@a5c-ai/agent-platform 5.0.1-staging.b436b3b3e611

package/dist/governance/authority.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * GAP-SEC: Authority Chain system.
+ *
+ * Models delegation chains from human principals through agent principals,
+ * with monotonically narrowing scope at each hop.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthorityChain = createAuthorityChain;
+exports.validateAuthorityChain = validateAuthorityChain;
+exports.attenuateScope = attenuateScope;
+exports.traceAuthorityToHuman = traceAuthorityToHuman;
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Create an authority chain from an ordered list of grants.
+ * Computes the effective scope as the intersection of all grant scopes.
+ */
+function createAuthorityChain(grants) {
+    if (grants.length === 0) {
+        throw new Error('Authority chain requires at least one grant');
+    }
+    const rootPrincipal = grants[0].from;
+    // Compute effective scope as intersection of all grant scopes
+    let effectiveScope = { ...grants[0].scope, allowedEffectKinds: [...grants[0].scope.allowedEffectKinds] };
+    for (let i = 1; i < grants.length; i++) {
+        effectiveScope = attenuateScope(effectiveScope, grants[i].scope);
+    }
+    return {
+        grants: [...grants],
+        rootPrincipal,
+        effectiveScope,
+    };
+}
+/**
+ * Validate an authority chain. Checks:
+ * 1. Root must be a human principal.
+ * 2. No revoked links.
+ * 3. No expired links.
+ * 4. Scopes monotonically narrow (no expansion).
+ */
+function validateAuthorityChain(chain) {
+    // 1. Root must be human
+    if (chain.rootPrincipal.kind !== 'human') {
+        return { valid: false, reason: 'Authority chain must be rooted in a human principal' };
+    }
+    const now = Date.now();
+    for (let i = 0; i < chain.grants.length; i++) {
+        const grant = chain.grants[i];
+        // 2. No revoked links
+        if (grant.revokedAt) {
+            return { valid: false, reason: `Grant at index ${i} has been revoked` };
+        }
+        // 3. No expired links
+        if (grant.expiresAt && new Date(grant.expiresAt).getTime() <= now) {
+            return { valid: false, reason: `Grant at index ${i} has expired` };
+        }
+        // 4. Scope must not expand beyond previous grant
+        if (i > 0) {
+            const parentScope = chain.grants[i - 1].scope;
+            const childScope = grant.scope;
+            if (!isScopeSubsetOrEqual(parentScope, childScope)) {
+                return { valid: false, reason: `Grant at index ${i} expands scope beyond parent` };
+            }
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Check if childScope is a subset of or equal to parentScope.
+ */
+function isScopeSubsetOrEqual(parent, child) {
+    // Check effect kinds
+    const parentWildcard = parent.allowedEffectKinds.length === 1 && parent.allowedEffectKinds[0] === '*';
+    if (!parentWildcard) {
+        for (const kind of child.allowedEffectKinds) {
+            if (kind === '*') {
+                return false; // wildcard child cannot escape non-wildcard parent
+            }
+            if (!parent.allowedEffectKinds.includes(kind)) {
+                return false;
+            }
+        }
+    }
+    // Check numeric limits
+    if (child.maxIterations > parent.maxIterations)
+        return false;
+    if (child.maxConcurrentTasks > parent.maxConcurrentTasks)
+        return false;
+    if (child.timeoutMs > parent.timeoutMs)
+        return false;
+    return true;
+}
+/**
+ * Attenuate (intersect) two scopes. The result is never wider than either input.
+ * Pure function.
+ */
+function attenuateScope(parent, child) {
+    const parentWildcard = parent.allowedEffectKinds.length === 1 && parent.allowedEffectKinds[0] === '*';
+    const childWildcard = child.allowedEffectKinds.length === 1 && child.allowedEffectKinds[0] === '*';
+    let allowedEffectKinds;
+    if (parentWildcard && childWildcard) {
+        allowedEffectKinds = ['*'];
+    }
+    else if (parentWildcard) {
+        allowedEffectKinds = [...child.allowedEffectKinds];
+    }
+    else if (childWildcard) {
+        allowedEffectKinds = [...parent.allowedEffectKinds];
+    }
+    else {
+        allowedEffectKinds = parent.allowedEffectKinds.filter(k => child.allowedEffectKinds.includes(k));
+    }
+    return {
+        allowedEffectKinds,
+        maxIterations: Math.min(parent.maxIterations, child.maxIterations),
+        maxConcurrentTasks: Math.min(parent.maxConcurrentTasks, child.maxConcurrentTasks),
+        timeoutMs: Math.min(parent.timeoutMs, child.timeoutMs),
+    };
+}
+/**
+ * Trace authority back to the human root, returning the human principal,
+ * hop count, and full principal path.
+ */
+function traceAuthorityToHuman(chain) {
+    const principalPath = [chain.grants[0].from.id];
+    for (const grant of chain.grants) {
+        principalPath.push(grant.to.id);
+    }
+    return {
+        humanPrincipal: chain.rootPrincipal,
+        hopCount: chain.grants.length,
+        principalPath,
+    };
+}

package/dist/governance/bridge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bridge from existing breakpoint rules to governance policies (GAP-SEC-001).
+ * Converts BreakpointRule[] into PolicyRule[] for unified evaluation.
+ */
+import type { BreakpointRule } from "@a5c-ai/babysitter-sdk";
+import type { PolicyRule } from './types';
+/**
+ * Convert breakpoint auto-approval rules into governance policy rules.
+ *
+ * Mapping:
+ * - "auto-approve" → allow policy (permission kind)
+ * - "never-auto-approve" → deny policy (permission kind)
+ *
+ * The breakpoint pattern is mapped to a "matches" condition on the taskId field.
+ */
+export declare function breakpointRulesToPolicies(rules: BreakpointRule[]): PolicyRule[];
+//# sourceMappingURL=bridge.d.ts.map

package/dist/governance/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/governance/bridge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,UAAU,EAAE,CAkB/E"}

package/dist/governance/bridge.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Bridge from existing breakpoint rules to governance policies (GAP-SEC-001).
+ * Converts BreakpointRule[] into PolicyRule[] for unified evaluation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.breakpointRulesToPolicies = breakpointRulesToPolicies;
+/**
+ * Convert breakpoint auto-approval rules into governance policy rules.
+ *
+ * Mapping:
+ * - "auto-approve" → allow policy (permission kind)
+ * - "never-auto-approve" → deny policy (permission kind)
+ *
+ * The breakpoint pattern is mapped to a "matches" condition on the taskId field.
+ */
+function breakpointRulesToPolicies(rules) {
+    return rules.map(rule => ({
+        id: `bp-bridge:${rule.id}`,
+        kind: 'permission',
+        condition: {
+            field: 'taskId',
+            op: 'matches',
+            value: globToRegex(rule.pattern),
+        },
+        action: rule.action === 'auto-approve' ? 'allow' : 'deny',
+        priority: rule.action === 'never-auto-approve' ? 100 : 50,
+        metadata: {
+            source: 'breakpoint-bridge',
+            originalPattern: rule.pattern,
+            createdBy: rule.createdBy,
+            ...(rule.note ? { note: rule.note } : {}),
+        },
+    }));
+}
+/**
+ * Convert a simple glob pattern to a regex string.
+ * Supports * (any chars) and ? (single char).
+ */
+function globToRegex(glob) {
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.');
+    return `^${escaped}$`;
+}

package/dist/governance/builtins.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Built-in governance policy rules (GAP-SEC-001).
+ * Ready-to-use policy factories for common constraints.
+ */
+import type { PolicyRule, StatefulPolicyRule } from './types';
+/**
+ * Deny effects when the iteration count exceeds a limit.
+ */
+export declare function maxIterationsPolicy(limit: number): PolicyRule;
+/**
+ * Deny effects whose effectKind is not in the allowed list.
+ * Implemented as a deny rule that matches effectKinds NOT in the list.
+ *
+ * Since condition ops are single-value, this creates one deny rule per
+ * disallowed kind by using a special "neq" with a runtime check.
+ * For simplicity, we use a "matches" regex that rejects non-matching kinds.
+ */
+export declare function taskKindPolicy(allowedKinds: string[]): PolicyRule;
+/**
+ * Deny effects when the rate exceeds maxCount within windowMs.
+ * Uses an in-memory sliding window counter via StatefulPolicyRule.
+ * Note: counter resets on process restart (in-memory only).
+ */
+export declare function rateLimitPolicy(windowMs: number, maxCount: number): StatefulPolicyRule;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/governance/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/governance/builtins.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAA2B,MAAM,SAAS,CAAC;AAEvF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,UAAU,CAUjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAqBtF"}

package/dist/governance/builtins.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Built-in governance policy rules (GAP-SEC-001).
+ * Ready-to-use policy factories for common constraints.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maxIterationsPolicy = maxIterationsPolicy;
+exports.taskKindPolicy = taskKindPolicy;
+exports.rateLimitPolicy = rateLimitPolicy;
+/**
+ * Deny effects when the iteration count exceeds a limit.
+ */
+function maxIterationsPolicy(limit) {
+    return {
+        id: `builtin:max-iterations:${limit}`,
+        kind: 'resource-limit',
+        condition: { field: 'iteration', op: 'gt', value: String(limit) },
+        action: 'deny',
+        priority: 90,
+        metadata: { description: `Deny when iteration exceeds ${limit}` },
+    };
+}
+/**
+ * Deny effects whose effectKind is not in the allowed list.
+ * Implemented as a deny rule that matches effectKinds NOT in the list.
+ *
+ * Since condition ops are single-value, this creates one deny rule per
+ * disallowed kind by using a special "neq" with a runtime check.
+ * For simplicity, we use a "matches" regex that rejects non-matching kinds.
+ */
+function taskKindPolicy(allowedKinds) {
+    const pattern = `^(?!${allowedKinds.map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')}$)`;
+    return {
+        id: `builtin:task-kind:${allowedKinds.join(',')}`,
+        kind: 'permission',
+        condition: { field: 'effectKind', op: 'matches', value: pattern },
+        action: 'deny',
+        priority: 80,
+        metadata: { description: `Only allow effect kinds: ${allowedKinds.join(', ')}` },
+    };
+}
+/**
+ * Deny effects when the rate exceeds maxCount within windowMs.
+ * Uses an in-memory sliding window counter via StatefulPolicyRule.
+ * Note: counter resets on process restart (in-memory only).
+ */
+function rateLimitPolicy(windowMs, maxCount) {
+    let timestamps = [];
+    return {
+        id: `builtin:rate-limit:${maxCount}per${windowMs}ms`,
+        kind: 'rate-limit',
+        // Declarative condition is a no-op placeholder; shouldMatch does the real work
+        condition: { field: '__rate_limit__', op: 'eq', value: '__stateful__' },
+        action: 'deny',
+        priority: 95,
+        metadata: {
+            description: `Rate limit: ${maxCount} per ${windowMs}ms`,
+        },
+        shouldMatch(_context) {
+            const now = Date.now();
+            // Evict expired timestamps with filter (O(n) but no shift overhead)
+            timestamps = timestamps.filter(t => t > now - windowMs);
+            timestamps.push(now);
+            return timestamps.length > maxCount;
+        },
+    };
+}

package/dist/governance/categories.d.ts

@@ -0,0 +1,58 @@
+/**
+ * GAP-SEC: Deterministic Policy Categories.
+ *
+ * Categorizes policy rules into A/B/C/D tiers with distinct enforcement
+ * behaviors and wraps the base policy engine with category-aware evaluation.
+ */
+import type { PolicyRule, PolicyEvaluationContext, PolicyDecision } from './types';
+/** Policy category identifiers. */
+export type PolicyCategory = 'A' | 'B' | 'C' | 'D';
+/** A PolicyRule annotated with a category. */
+export interface CategorizedPolicyRule extends PolicyRule {
+    category?: PolicyCategory;
+}
+/** Enforcement behavior per category. */
+export interface CategoryEnforcementBehavior {
+    category: PolicyCategory;
+    description: string;
+    immutable: boolean;
+    requiresClassification: boolean;
+    isFallback: boolean;
+}
+/** Extended decision with category metadata. */
+export interface CategorizedPolicyDecision extends PolicyDecision {
+    requiresClassification?: boolean;
+    usedFallback?: boolean;
+}
+/** Categorized engine interface. */
+export interface CategorizedPolicyEngine {
+    readonly rules: readonly CategorizedPolicyRule[];
+    evaluate(context: PolicyEvaluationContext): CategorizedPolicyDecision;
+}
+/**
+ * Wrap a plain PolicyRule with a category annotation.
+ */
+export declare function categorizePolicyRule(rule: PolicyRule, category: PolicyCategory): CategorizedPolicyRule;
+/**
+ * Infer a category for a rule that lacks one.
+ *
+ * Heuristic:
+ * - rate-limit + deny -> A (critical)
+ * - permission + deny -> C (needs classification)
+ * - trust-level       -> D (fallback)
+ * - everything else   -> B (advisory)
+ */
+export declare function inferPolicyCategory(rule: PolicyRule): PolicyCategory;
+/**
+ * Create a categorized policy engine that evaluates rules with
+ * category-aware precedence:
+ *
+ * 1. Category A (immutable) - evaluated first, cannot be overridden
+ * 2. Category B (advisory)  - warnings / normal evaluation
+ * 3. Category C (classification-required) - denials flagged
+ * 4. Category D (fallback)  - posture-based fallback
+ *
+ * Accepts CategorizedPolicyRule[] (rules without a category are auto-inferred).
+ */
+export declare function createCategorizedEngine(rules: CategorizedPolicyRule[]): CategorizedPolicyEngine;
+//# sourceMappingURL=categories.d.ts.map

package/dist/governance/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../src/governance/categories.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAMnF,mCAAmC;AACnC,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEnD,8CAA8C;AAC9C,MAAM,WAAW,qBAAsB,SAAQ,UAAU;IACvD,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,yCAAyC;AACzC,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,sBAAsB,EAAE,OAAO,CAAC;IAChC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,oCAAoC;AACpC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,uBAAuB,GAAG,yBAAyB,CAAC;CACvE;AAiBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,GAAG,qBAAqB,CAEtG;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAKpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,EAAE,GAAG,uBAAuB,CAuE/F"}

package/dist/governance/categories.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * GAP-SEC: Deterministic Policy Categories.
+ *
+ * Categorizes policy rules into A/B/C/D tiers with distinct enforcement
+ * behaviors and wraps the base policy engine with category-aware evaluation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.categorizePolicyRule = categorizePolicyRule;
+exports.inferPolicyCategory = inferPolicyCategory;
+exports.createCategorizedEngine = createCategorizedEngine;
+const engine_1 = require("./engine");
+// ---------------------------------------------------------------------------
+// Category behaviours
+// ---------------------------------------------------------------------------
+const _CATEGORY_BEHAVIORS = {
+    A: { category: 'A', description: 'Immutable critical rules', immutable: true, requiresClassification: false, isFallback: false },
+    B: { category: 'B', description: 'Advisory rules', immutable: false, requiresClassification: false, isFallback: false },
+    C: { category: 'C', description: 'Classification-required rules', immutable: false, requiresClassification: true, isFallback: false },
+    D: { category: 'D', description: 'Fallback posture-based rules', immutable: false, requiresClassification: false, isFallback: true },
+};
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a plain PolicyRule with a category annotation.
+ */
+function categorizePolicyRule(rule, category) {
+    return { ...rule, category };
+}
+/**
+ * Infer a category for a rule that lacks one.
+ *
+ * Heuristic:
+ * - rate-limit + deny -> A (critical)
+ * - permission + deny -> C (needs classification)
+ * - trust-level       -> D (fallback)
+ * - everything else   -> B (advisory)
+ */
+function inferPolicyCategory(rule) {
+    if (rule.kind === 'rate-limit' && rule.action === 'deny')
+        return 'A';
+    if (rule.kind === 'permission' && rule.action === 'deny')
+        return 'C';
+    if (rule.kind === 'trust-level')
+        return 'D';
+    return 'B';
+}
+/**
+ * Create a categorized policy engine that evaluates rules with
+ * category-aware precedence:
+ *
+ * 1. Category A (immutable) - evaluated first, cannot be overridden
+ * 2. Category B (advisory)  - warnings / normal evaluation
+ * 3. Category C (classification-required) - denials flagged
+ * 4. Category D (fallback)  - posture-based fallback
+ *
+ * Accepts CategorizedPolicyRule[] (rules without a category are auto-inferred).
+ */
+function createCategorizedEngine(rules) {
+    // Ensure every rule has a category
+    const categorized = rules.map(r => r.category ? r : { ...r, category: inferPolicyCategory(r) });
+    // Partition by category
+    const byCategory = { A: [], B: [], C: [], D: [] };
+    for (const rule of categorized) {
+        byCategory[rule.category].push(rule);
+    }
+    // Build per-category engines
+    const engineA = (0, engine_1.createPolicyEngine)(byCategory.A);
+    const engineB = (0, engine_1.createPolicyEngine)(byCategory.B);
+    const engineC = (0, engine_1.createPolicyEngine)(byCategory.C);
+    const engineD = (0, engine_1.createPolicyEngine)(byCategory.D);
+    return {
+        rules: Object.freeze([...categorized]),
+        evaluate(context) {
+            const allWarnings = [];
+            // 1. Category A - immutable, first match wins
+            if (byCategory.A.length > 0) {
+                const decisionA = engineA.evaluate(context);
+                allWarnings.push(...decisionA.warnings);
+                if (!decisionA.allowed) {
+                    return { ...decisionA, warnings: allWarnings };
+                }
+                // If A explicitly allows, still continue to collect warnings from B
+                // but A deny is final.
+            }
+            // 2. Category B - advisory (collect warnings)
+            if (byCategory.B.length > 0) {
+                const decisionB = engineB.evaluate(context);
+                allWarnings.push(...decisionB.warnings);
+                // B deny/allow also applies if no A deny
+                if (!decisionB.allowed) {
+                    return { ...decisionB, warnings: allWarnings };
+                }
+            }
+            // 3. Category C - requires classification
+            if (byCategory.C.length > 0) {
+                const decisionC = engineC.evaluate(context);
+                allWarnings.push(...decisionC.warnings);
+                if (!decisionC.allowed) {
+                    return { ...decisionC, warnings: allWarnings, requiresClassification: true };
+                }
+            }
+            // 4. Category D - fallback
+            if (byCategory.D.length > 0) {
+                const decisionD = engineD.evaluate(context);
+                allWarnings.push(...decisionD.warnings);
+                if (decisionD.rule) {
+                    return { ...decisionD, warnings: allWarnings, usedFallback: true };
+                }
+            }
+            // Default allow
+            return {
+                allowed: true,
+                reason: 'Allowed by default policy',
+                warnings: allWarnings,
+            };
+        },
+    };
+}

package/dist/governance/decisionTrail.d.ts

@@ -0,0 +1,60 @@
+/**
+ * GAP-OBS-004: Policy Decision Trail.
+ *
+ * Audit trail for governance policy decisions. Records which policies
+ * were evaluated, their results, and the final decision for each
+ * effect dispatch.
+ */
+import type { PolicyRule, PolicyDecision } from "./types";
+/** Record of a single policy's evaluation against an effect. */
+export interface PolicyEvalRecord {
+    ruleId: string;
+    ruleKind: string;
+    action: string;
+    matched: boolean;
+    priority: number;
+}
+/** Full audit entry for one effect dispatch decision. */
+export interface DecisionTrailEntry {
+    effectId: string;
+    effectKind: string;
+    evaluatedAt: string;
+    policies: PolicyEvalRecord[];
+    finalOutcome: "allow" | "deny";
+    decidingRuleId: string | undefined;
+    reason: string;
+    warnings: string[];
+    runId?: string;
+    stepId?: string;
+}
+/** Options to build a decision trail entry. */
+export interface DecisionTrailOptions {
+    effectId: string;
+    effectKind: string;
+    rulesEvaluated: PolicyRule[];
+    finalDecision: PolicyDecision;
+    matchedRuleId?: string;
+    runId?: string;
+    stepId?: string;
+}
+/** Summary statistics for a set of decision trail entries. */
+export interface DecisionTrailSummary {
+    totalEffects: number;
+    allowCount: number;
+    denyCount: number;
+    topDecidingRules: Array<{
+        ruleId: string;
+        count: number;
+    }>;
+}
+/**
+ * Build a DecisionTrailEntry from evaluation options.
+ * Pure function — no I/O.
+ */
+export declare function buildDecisionTrailEntry(options: DecisionTrailOptions): DecisionTrailEntry;
+/**
+ * Summarize a collection of decision trail entries.
+ * Pure function — no I/O.
+ */
+export declare function summarizeDecisionTrail(entries: DecisionTrailEntry[]): DecisionTrailSummary;
+//# sourceMappingURL=decisionTrail.d.ts.map

package/dist/governance/decisionTrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisionTrail.d.ts","sourceRoot":"","sources":["../../src/governance/decisionTrail.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAM1D,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,aAAa,EAAE,cAAc,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5D;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,oBAAoB,GAC5B,kBAAkB,CAqBpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,kBAAkB,EAAE,GAC5B,oBAAoB,CA8BtB"}

package/dist/governance/decisionTrail.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * GAP-OBS-004: Policy Decision Trail.
+ *
+ * Audit trail for governance policy decisions. Records which policies
+ * were evaluated, their results, and the final decision for each
+ * effect dispatch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDecisionTrailEntry = buildDecisionTrailEntry;
+exports.summarizeDecisionTrail = summarizeDecisionTrail;
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Build a DecisionTrailEntry from evaluation options.
+ * Pure function — no I/O.
+ */
+function buildDecisionTrailEntry(options) {
+    const policies = options.rulesEvaluated.map((rule) => ({
+        ruleId: rule.id,
+        ruleKind: rule.kind,
+        action: rule.action,
+        matched: rule.id === options.matchedRuleId,
+        priority: rule.priority,
+    }));
+    return {
+        effectId: options.effectId,
+        effectKind: options.effectKind,
+        evaluatedAt: new Date().toISOString(),
+        policies,
+        finalOutcome: options.finalDecision.allowed ? "allow" : "deny",
+        decidingRuleId: options.matchedRuleId,
+        reason: options.finalDecision.reason,
+        warnings: options.finalDecision.warnings,
+        runId: options.runId,
+        stepId: options.stepId,
+    };
+}
+/**
+ * Summarize a collection of decision trail entries.
+ * Pure function — no I/O.
+ */
+function summarizeDecisionTrail(entries) {
+    let allowCount = 0;
+    let denyCount = 0;
+    const ruleFreq = new Map();
+    for (const entry of entries) {
+        if (entry.finalOutcome === "allow") {
+            allowCount++;
+        }
+        else {
+            denyCount++;
+        }
+        if (entry.decidingRuleId) {
+            ruleFreq.set(entry.decidingRuleId, (ruleFreq.get(entry.decidingRuleId) ?? 0) + 1);
+        }
+    }
+    const topDecidingRules = [...ruleFreq.entries()]
+        .map(([ruleId, count]) => ({ ruleId, count }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        totalEffects: entries.length,
+        allowCount,
+        denyCount,
+        topDecidingRules,
+    };
+}

package/dist/governance/engine.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Governance Policy Engine (GAP-SEC-001).
+ * Evaluates declarative policy rules with precedence: deny > warn > allow > default-allow.
+ */
+import type { PolicyRule, PolicyCondition, PolicyEvaluationContext, PolicyEngine } from './types';
+/**
+ * Evaluate a single condition against the evaluation context.
+ */
+export declare function matchCondition(condition: PolicyCondition, context: PolicyEvaluationContext): boolean;
+/**
+ * Create a policy engine from a set of rules.
+ *
+ * Evaluation precedence:
+ * 1. Deny rules (sorted by priority desc) — first match blocks
+ * 2. Warn rules (all matching collected as warnings)
+ * 3. Allow rules (sorted by priority desc) — first match allows explicitly
+ * 4. Default: allow
+ */
+export declare function createPolicyEngine(rules: PolicyRule[]): PolicyEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/governance/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/governance/engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,uBAAuB,EAEvB,YAAY,EACb,MAAM,SAAS,CAAC;AAiBjB;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAwCpG;AAaD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,YAAY,CAmDpE"}