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

package/dist/governance/engine.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Governance Policy Engine (GAP-SEC-001).
+ * Evaluates declarative policy rules with precedence: deny > warn > allow > default-allow.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchCondition = matchCondition;
+exports.createPolicyEngine = createPolicyEngine;
+const types_1 = require("./types");
+/**
+ * Resolve a dot-notation field path against the evaluation context.
+ * Returns undefined if any segment is missing.
+ */
+function resolveField(context, fieldPath) {
+    const parts = fieldPath.split('.');
+    let current = context;
+    for (const part of parts) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Evaluate a single condition against the evaluation context.
+ */
+function matchCondition(condition, context) {
+    const fieldValue = resolveField(context, condition.field);
+    if (fieldValue === undefined || fieldValue === null)
+        return false;
+    switch (condition.op) {
+        case 'eq':
+            return String(fieldValue) === condition.value;
+        case 'neq':
+            return String(fieldValue) !== condition.value;
+        case 'gt':
+            return typeof fieldValue === 'number' && fieldValue > Number(condition.value);
+        case 'lt':
+            return typeof fieldValue === 'number' && fieldValue < Number(condition.value);
+        case 'gte':
+            return typeof fieldValue === 'number' && fieldValue >= Number(condition.value);
+        case 'lte':
+            return typeof fieldValue === 'number' && fieldValue <= Number(condition.value);
+        case 'contains':
+            if (Array.isArray(fieldValue)) {
+                return fieldValue.includes(condition.value);
+            }
+            return String(fieldValue).includes(condition.value);
+        case 'matches':
+            try {
+                return new RegExp(condition.value).test(String(fieldValue));
+            }
+            catch {
+                return false;
+            }
+        default:
+            return false;
+    }
+}
+/**
+ * Check whether a rule matches the given context.
+ * Uses the stateful shouldMatch callback if present, otherwise declarative matchCondition.
+ */
+function ruleMatches(rule, context) {
+    if ((0, types_1.isStatefulRule)(rule)) {
+        return rule.shouldMatch(context);
+    }
+    return matchCondition(rule.condition, context);
+}
+/**
+ * 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
+ */
+function createPolicyEngine(rules) {
+    // Pre-sort rules by action group, then priority descending
+    const denyRules = rules.filter(r => r.action === 'deny').sort((a, b) => b.priority - a.priority);
+    const warnRules = rules.filter(r => r.action === 'warn').sort((a, b) => b.priority - a.priority);
+    const allowRules = rules.filter(r => r.action === 'allow').sort((a, b) => b.priority - a.priority);
+    return {
+        rules: Object.freeze([...rules]),
+        evaluate(context) {
+            const warnings = [];
+            // 1. Deny rules — first match blocks
+            for (const rule of denyRules) {
+                if (ruleMatches(rule, context)) {
+                    return {
+                        allowed: false,
+                        rule,
+                        reason: `Denied by rule ${rule.id}`,
+                        warnings,
+                    };
+                }
+            }
+            // 2. Warn rules — collect all matching
+            for (const rule of warnRules) {
+                if (ruleMatches(rule, context)) {
+                    warnings.push(`Warning from rule ${rule.id}: ${rule.metadata?.reason ?? rule.kind}`);
+                }
+            }
+            // 3. Allow rules — first match allows explicitly
+            for (const rule of allowRules) {
+                if (ruleMatches(rule, context)) {
+                    return {
+                        allowed: true,
+                        rule,
+                        reason: `Allowed by rule ${rule.id}`,
+                        warnings,
+                    };
+                }
+            }
+            // 4. Default: allow
+            return {
+                allowed: true,
+                reason: 'Allowed by default policy',
+                warnings,
+            };
+        },
+    };
+}

package/dist/governance/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Governance Policy Layer module (GAP-SEC-001).
+ * Centralized policy engine for evaluating security rules at effect dispatch.
+ */
+export type { PolicyRuleKind, PolicyConditionOp, PolicyAction, PolicyCondition, PolicyRule, StatefulPolicyRule, PolicyEvaluationContext, PolicyDecision, PolicyDecisionLog, PolicyEngine, } from './types';
+export { isStatefulRule } from './types';
+export { createPolicyEngine, matchCondition } from './engine';
+export { maxIterationsPolicy, taskKindPolicy, rateLimitPolicy } from './builtins';
+export { logPolicyDecision, readPolicyDecisionLog } from './logging';
+export { breakpointRulesToPolicies } from './bridge';
+export { buildDecisionTrailEntry, summarizeDecisionTrail, type DecisionTrailEntry, type DecisionTrailOptions, type DecisionTrailSummary, type PolicyEvalRecord, } from './decisionTrail';
+export { createMandate, activateMandate, revokeMandate, deriveMandate, validateMandateForContext, mandateToPolicy, type ExecutionMandate, type MandateScope, type MandateLifecycle, type MandateProvenance, type MandateValidationResult, } from './mandate';
+export { createAuthorityChain, validateAuthorityChain, attenuateScope, traceAuthorityToHuman, type AuthorityPrincipal, type AuthorityGrant, type AuthorityChain, type AuthorityChainLink, type AuthorityTrace, type AuthorityChainValidationResult, } from './authority';
+export { categorizePolicyRule, createCategorizedEngine, inferPolicyCategory, type PolicyCategory, type CategorizedPolicyRule, type CategoryEnforcementBehavior, type CategorizedPolicyDecision, type CategorizedPolicyEngine, } from './categories';
+export { postureToPolicyRules, allPosturesToPolicies, } from './postureBridge';
+export { evaluateSandboxAccess, matchesPattern, composeSandboxPolicies, attenuateSandboxPolicy, type SandboxOperationKind, type SandboxRule, type SandboxPolicy, type SandboxDecision, type SandboxOperation, } from './sandboxPolicy';
+export { sandboxDecisionToInteraction, buildSandboxEvent, inheritSandboxPolicy, type SandboxEvent, } from './sandboxBridge';
+export { createPermissionEvent, aggregateChainEvents, filterEvents, type PermissionEvent, type PermissionEventSource, type CreatePermissionEventOptions, type FilterCriteria, } from './permissionEvents';
+export { formatPermissionForTui, formatPermissionForJsonStream, formatPermissionForCli, createPropagationConfig, shouldPropagate, type PropagationTarget, type PropagationConfig, } from './permissionPropagation';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/governance/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGzC,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlF,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAGrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAGrD,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,aAAa,EACb,eAAe,EACf,aAAa,EACb,aAAa,EACb,yBAAyB,EACzB,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,8BAA8B,GACpC,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,yBAAyB,CAAC"}

package/dist/governance/index.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Governance Policy Layer module (GAP-SEC-001).
+ * Centralized policy engine for evaluating security rules at effect dispatch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldPropagate = exports.createPropagationConfig = exports.formatPermissionForCli = exports.formatPermissionForJsonStream = exports.formatPermissionForTui = exports.filterEvents = exports.aggregateChainEvents = exports.createPermissionEvent = exports.inheritSandboxPolicy = exports.buildSandboxEvent = exports.sandboxDecisionToInteraction = exports.attenuateSandboxPolicy = exports.composeSandboxPolicies = exports.matchesPattern = exports.evaluateSandboxAccess = exports.allPosturesToPolicies = exports.postureToPolicyRules = exports.inferPolicyCategory = exports.createCategorizedEngine = exports.categorizePolicyRule = exports.traceAuthorityToHuman = exports.attenuateScope = exports.validateAuthorityChain = exports.createAuthorityChain = exports.mandateToPolicy = exports.validateMandateForContext = exports.deriveMandate = exports.revokeMandate = exports.activateMandate = exports.createMandate = exports.summarizeDecisionTrail = exports.buildDecisionTrailEntry = exports.breakpointRulesToPolicies = exports.readPolicyDecisionLog = exports.logPolicyDecision = exports.rateLimitPolicy = exports.taskKindPolicy = exports.maxIterationsPolicy = exports.matchCondition = exports.createPolicyEngine = exports.isStatefulRule = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "isStatefulRule", { enumerable: true, get: function () { return types_1.isStatefulRule; } });
+// Engine
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "createPolicyEngine", { enumerable: true, get: function () { return engine_1.createPolicyEngine; } });
+Object.defineProperty(exports, "matchCondition", { enumerable: true, get: function () { return engine_1.matchCondition; } });
+// Built-in policies
+var builtins_1 = require("./builtins");
+Object.defineProperty(exports, "maxIterationsPolicy", { enumerable: true, get: function () { return builtins_1.maxIterationsPolicy; } });
+Object.defineProperty(exports, "taskKindPolicy", { enumerable: true, get: function () { return builtins_1.taskKindPolicy; } });
+Object.defineProperty(exports, "rateLimitPolicy", { enumerable: true, get: function () { return builtins_1.rateLimitPolicy; } });
+// Audit logging
+var logging_1 = require("./logging");
+Object.defineProperty(exports, "logPolicyDecision", { enumerable: true, get: function () { return logging_1.logPolicyDecision; } });
+Object.defineProperty(exports, "readPolicyDecisionLog", { enumerable: true, get: function () { return logging_1.readPolicyDecisionLog; } });
+// Breakpoint bridge
+var bridge_1 = require("./bridge");
+Object.defineProperty(exports, "breakpointRulesToPolicies", { enumerable: true, get: function () { return bridge_1.breakpointRulesToPolicies; } });
+// Decision trail (GAP-OBS-004)
+var decisionTrail_1 = require("./decisionTrail");
+Object.defineProperty(exports, "buildDecisionTrailEntry", { enumerable: true, get: function () { return decisionTrail_1.buildDecisionTrailEntry; } });
+Object.defineProperty(exports, "summarizeDecisionTrail", { enumerable: true, get: function () { return decisionTrail_1.summarizeDecisionTrail; } });
+// Mandate system
+var mandate_1 = require("./mandate");
+Object.defineProperty(exports, "createMandate", { enumerable: true, get: function () { return mandate_1.createMandate; } });
+Object.defineProperty(exports, "activateMandate", { enumerable: true, get: function () { return mandate_1.activateMandate; } });
+Object.defineProperty(exports, "revokeMandate", { enumerable: true, get: function () { return mandate_1.revokeMandate; } });
+Object.defineProperty(exports, "deriveMandate", { enumerable: true, get: function () { return mandate_1.deriveMandate; } });
+Object.defineProperty(exports, "validateMandateForContext", { enumerable: true, get: function () { return mandate_1.validateMandateForContext; } });
+Object.defineProperty(exports, "mandateToPolicy", { enumerable: true, get: function () { return mandate_1.mandateToPolicy; } });
+// Authority chain
+var authority_1 = require("./authority");
+Object.defineProperty(exports, "createAuthorityChain", { enumerable: true, get: function () { return authority_1.createAuthorityChain; } });
+Object.defineProperty(exports, "validateAuthorityChain", { enumerable: true, get: function () { return authority_1.validateAuthorityChain; } });
+Object.defineProperty(exports, "attenuateScope", { enumerable: true, get: function () { return authority_1.attenuateScope; } });
+Object.defineProperty(exports, "traceAuthorityToHuman", { enumerable: true, get: function () { return authority_1.traceAuthorityToHuman; } });
+// Categorized policy engine
+var categories_1 = require("./categories");
+Object.defineProperty(exports, "categorizePolicyRule", { enumerable: true, get: function () { return categories_1.categorizePolicyRule; } });
+Object.defineProperty(exports, "createCategorizedEngine", { enumerable: true, get: function () { return categories_1.createCategorizedEngine; } });
+Object.defineProperty(exports, "inferPolicyCategory", { enumerable: true, get: function () { return categories_1.inferPolicyCategory; } });
+// Posture-to-policy bridge
+var postureBridge_1 = require("./postureBridge");
+Object.defineProperty(exports, "postureToPolicyRules", { enumerable: true, get: function () { return postureBridge_1.postureToPolicyRules; } });
+Object.defineProperty(exports, "allPosturesToPolicies", { enumerable: true, get: function () { return postureBridge_1.allPosturesToPolicies; } });
+// Sandbox policy (GAP-SEC-002)
+var sandboxPolicy_1 = require("./sandboxPolicy");
+Object.defineProperty(exports, "evaluateSandboxAccess", { enumerable: true, get: function () { return sandboxPolicy_1.evaluateSandboxAccess; } });
+Object.defineProperty(exports, "matchesPattern", { enumerable: true, get: function () { return sandboxPolicy_1.matchesPattern; } });
+Object.defineProperty(exports, "composeSandboxPolicies", { enumerable: true, get: function () { return sandboxPolicy_1.composeSandboxPolicies; } });
+Object.defineProperty(exports, "attenuateSandboxPolicy", { enumerable: true, get: function () { return sandboxPolicy_1.attenuateSandboxPolicy; } });
+// Sandbox bridge (GAP-SEC-002)
+var sandboxBridge_1 = require("./sandboxBridge");
+Object.defineProperty(exports, "sandboxDecisionToInteraction", { enumerable: true, get: function () { return sandboxBridge_1.sandboxDecisionToInteraction; } });
+Object.defineProperty(exports, "buildSandboxEvent", { enumerable: true, get: function () { return sandboxBridge_1.buildSandboxEvent; } });
+Object.defineProperty(exports, "inheritSandboxPolicy", { enumerable: true, get: function () { return sandboxBridge_1.inheritSandboxPolicy; } });
+// Permission events
+var permissionEvents_1 = require("./permissionEvents");
+Object.defineProperty(exports, "createPermissionEvent", { enumerable: true, get: function () { return permissionEvents_1.createPermissionEvent; } });
+Object.defineProperty(exports, "aggregateChainEvents", { enumerable: true, get: function () { return permissionEvents_1.aggregateChainEvents; } });
+Object.defineProperty(exports, "filterEvents", { enumerable: true, get: function () { return permissionEvents_1.filterEvents; } });
+// Permission propagation
+var permissionPropagation_1 = require("./permissionPropagation");
+Object.defineProperty(exports, "formatPermissionForTui", { enumerable: true, get: function () { return permissionPropagation_1.formatPermissionForTui; } });
+Object.defineProperty(exports, "formatPermissionForJsonStream", { enumerable: true, get: function () { return permissionPropagation_1.formatPermissionForJsonStream; } });
+Object.defineProperty(exports, "formatPermissionForCli", { enumerable: true, get: function () { return permissionPropagation_1.formatPermissionForCli; } });
+Object.defineProperty(exports, "createPropagationConfig", { enumerable: true, get: function () { return permissionPropagation_1.createPropagationConfig; } });
+Object.defineProperty(exports, "shouldPropagate", { enumerable: true, get: function () { return permissionPropagation_1.shouldPropagate; } });

package/dist/governance/logging.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Governance policy decision audit logging (GAP-SEC-001).
+ * Appends decisions to a JSONL file for audit trail.
+ * Uses async handle-based I/O with fsync for crash safety.
+ */
+import type { PolicyDecisionLog } from './types';
+/**
+ * Append a policy decision to the audit log.
+ * Uses handle-based async I/O with fsync for crash safety.
+ */
+export declare function logPolicyDecision(logDir: string, entry: PolicyDecisionLog): Promise<void>;
+/**
+ * Read all policy decisions from the audit log.
+ * Returns empty array if the file does not exist.
+ * Throws on permission errors or other unexpected failures.
+ */
+export declare function readPolicyDecisionLog(logDir: string): Promise<PolicyDecisionLog[]>;
+//# sourceMappingURL=logging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/governance/logging.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAIjD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAaxF"}

package/dist/governance/logging.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Governance policy decision audit logging (GAP-SEC-001).
+ * Appends decisions to a JSONL file for audit trail.
+ * Uses async handle-based I/O with fsync for crash safety.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logPolicyDecision = logPolicyDecision;
+exports.readPolicyDecisionLog = readPolicyDecisionLog;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const LOG_FILENAME = 'governance-decisions.jsonl';
+/**
+ * Append a policy decision to the audit log.
+ * Uses handle-based async I/O with fsync for crash safety.
+ */
+async function logPolicyDecision(logDir, entry) {
+    await node_fs_1.promises.mkdir(logDir, { recursive: true });
+    const logPath = path.join(logDir, LOG_FILENAME);
+    const line = JSON.stringify(entry) + '\n';
+    const handle = await node_fs_1.promises.open(logPath, 'a');
+    try {
+        await handle.writeFile(line, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Read all policy decisions from the audit log.
+ * Returns empty array if the file does not exist.
+ * Throws on permission errors or other unexpected failures.
+ */
+async function readPolicyDecisionLog(logDir) {
+    const logPath = path.join(logDir, LOG_FILENAME);
+    try {
+        const content = await node_fs_1.promises.readFile(logPath, 'utf8');
+        return content
+            .split('\n')
+            .filter(line => line.trim())
+            .map(line => JSON.parse(line));
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}

package/dist/governance/mandate.d.ts

@@ -0,0 +1,83 @@
+/**
+ * GAP-SEC: Execution Mandate system.
+ *
+ * Mandates are scoped, lifecycle-managed authority grants that can be
+ * derived (attenuated) and converted to PolicyRule[] for engine evaluation.
+ */
+import type { PolicyRule, PolicyEvaluationContext } from './types';
+/** The set of permissions / limits a mandate grants. */
+export interface MandateScope {
+    /** Effect kinds allowed. Array of strings, or ['*'] for wildcard. */
+    allowedEffectKinds: string[];
+    /** Maximum iterations permitted. */
+    maxIterations: number;
+    /** Maximum concurrent tasks permitted. */
+    maxConcurrentTasks: number;
+    /** Timeout in milliseconds. */
+    timeoutMs: number;
+}
+/** Lifecycle states of a mandate. */
+export type MandateLifecycle = 'created' | 'active' | 'revoked';
+/** Where this mandate came from. */
+export interface MandateProvenance {
+    /** The root mandate ID (self-referential for root mandates). */
+    rootMandateId: string;
+    /** Chain of mandate IDs from root to parent. */
+    derivationChain: string[];
+}
+/** An execution mandate. */
+export interface ExecutionMandate {
+    mandateId: string;
+    scope: MandateScope;
+    grantedBy: string;
+    lifecycle: MandateLifecycle;
+    provenance: MandateProvenance;
+    createdAt: string;
+    activatedAt?: string;
+    /** High-resolution activation mark (performance.now()) for precise expiry checks. */
+    activatedMark?: number;
+    revokedAt?: string;
+    revokedBy?: string;
+}
+export interface CreateMandateOptions {
+    scope: MandateScope;
+    grantedBy: string;
+}
+export interface RevokeMandateOptions {
+    revokedBy: string;
+    reason: string;
+}
+export interface DeriveMandateOptions {
+    scope: MandateScope;
+    grantedBy: string;
+}
+export interface MandateValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Create a new mandate in the 'created' lifecycle state.
+ */
+export declare function createMandate(options: CreateMandateOptions): ExecutionMandate;
+/**
+ * Transition a mandate from 'created' to 'active'.
+ */
+export declare function activateMandate(mandate: ExecutionMandate): ExecutionMandate;
+/**
+ * Revoke a mandate. Only active mandates can be revoked.
+ */
+export declare function revokeMandate(mandate: ExecutionMandate, options: RevokeMandateOptions): ExecutionMandate;
+/**
+ * Derive a child mandate from an active parent. The child scope must be
+ * equal to or narrower than the parent scope (intersection semantics).
+ */
+export declare function deriveMandate(parent: ExecutionMandate, options: DeriveMandateOptions): ExecutionMandate;
+/**
+ * Validate whether a mandate permits the given evaluation context.
+ */
+export declare function validateMandateForContext(mandate: ExecutionMandate, ctx: PolicyEvaluationContext): MandateValidationResult;
+/**
+ * Convert a mandate's scope into PolicyRule[] for governance engine evaluation.
+ */
+export declare function mandateToPolicy(mandate: ExecutionMandate): PolicyRule[];
+//# sourceMappingURL=mandate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mandate.d.ts","sourceRoot":"","sources":["../../src/governance/mandate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAMnE,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qCAAqC;AACrC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,4BAA4B;AAC5B,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CAa7E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAa3E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CAWxG;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CA2CvG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,uBAAuB,GAC3B,uBAAuB,CA8BzB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,EAAE,CAkCvE"}

package/dist/governance/mandate.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * GAP-SEC: Execution Mandate system.
+ *
+ * Mandates are scoped, lifecycle-managed authority grants that can be
+ * derived (attenuated) and converted to PolicyRule[] for engine evaluation.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMandate = createMandate;
+exports.activateMandate = activateMandate;
+exports.revokeMandate = revokeMandate;
+exports.deriveMandate = deriveMandate;
+exports.validateMandateForContext = validateMandateForContext;
+exports.mandateToPolicy = mandateToPolicy;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Create a new mandate in the 'created' lifecycle state.
+ */
+function createMandate(options) {
+    const mandateId = node_crypto_1.default.randomUUID();
+    return {
+        mandateId,
+        scope: { ...options.scope, allowedEffectKinds: [...options.scope.allowedEffectKinds] },
+        grantedBy: options.grantedBy,
+        lifecycle: 'created',
+        provenance: {
+            rootMandateId: mandateId,
+            derivationChain: [],
+        },
+        createdAt: new Date().toISOString(),
+    };
+}
+/**
+ * Transition a mandate from 'created' to 'active'.
+ */
+function activateMandate(mandate) {
+    if (mandate.lifecycle !== 'created') {
+        throw new Error(`Cannot activate mandate in '${mandate.lifecycle}' state; must be 'created'`);
+    }
+    const now = Date.now();
+    const result = {
+        ...mandate,
+        scope: { ...mandate.scope, allowedEffectKinds: [...mandate.scope.allowedEffectKinds] },
+        lifecycle: 'active',
+        activatedAt: new Date(now).toISOString(),
+    };
+    result.activatedMark = performance.now();
+    return result;
+}
+/**
+ * Revoke a mandate. Only active mandates can be revoked.
+ */
+function revokeMandate(mandate, options) {
+    if (mandate.lifecycle === 'revoked') {
+        throw new Error('Cannot revoke an already-revoked mandate');
+    }
+    return {
+        ...mandate,
+        scope: { ...mandate.scope, allowedEffectKinds: [...mandate.scope.allowedEffectKinds] },
+        lifecycle: 'revoked',
+        revokedAt: new Date().toISOString(),
+        revokedBy: options.revokedBy,
+    };
+}
+/**
+ * Derive a child mandate from an active parent. The child scope must be
+ * equal to or narrower than the parent scope (intersection semantics).
+ */
+function deriveMandate(parent, options) {
+    if (parent.lifecycle !== 'active') {
+        throw new Error(`Cannot derive from mandate in '${parent.lifecycle}' state; must be 'active'`);
+    }
+    // Validate scope is not wider than parent
+    const parentKinds = parent.scope.allowedEffectKinds;
+    const isParentWildcard = parentKinds.length === 1 && parentKinds[0] === '*';
+    const childKinds = options.scope.allowedEffectKinds;
+    if (!isParentWildcard) {
+        for (const kind of childKinds) {
+            if (kind === '*') {
+                throw new Error('Child scope expands beyond parent: wildcard child not allowed when parent has explicit effect kinds');
+            }
+            if (!parentKinds.includes(kind)) {
+                throw new Error(`Child scope expands beyond parent: effect kind '${kind}' not in parent scope`);
+            }
+        }
+    }
+    if (options.scope.maxIterations > parent.scope.maxIterations) {
+        throw new Error(`Child scope expands beyond parent: maxIterations ${options.scope.maxIterations} > ${parent.scope.maxIterations}`);
+    }
+    if (options.scope.maxConcurrentTasks > parent.scope.maxConcurrentTasks) {
+        throw new Error(`Child scope expands beyond parent: maxConcurrentTasks ${options.scope.maxConcurrentTasks} > ${parent.scope.maxConcurrentTasks}`);
+    }
+    if (options.scope.timeoutMs > parent.scope.timeoutMs) {
+        throw new Error(`Child scope expands beyond parent: timeoutMs ${options.scope.timeoutMs} > ${parent.scope.timeoutMs}`);
+    }
+    const mandateId = node_crypto_1.default.randomUUID();
+    return {
+        mandateId,
+        scope: { ...options.scope, allowedEffectKinds: [...options.scope.allowedEffectKinds] },
+        grantedBy: options.grantedBy,
+        lifecycle: 'created',
+        provenance: {
+            rootMandateId: parent.provenance.rootMandateId,
+            derivationChain: [...parent.provenance.derivationChain, parent.mandateId],
+        },
+        createdAt: new Date().toISOString(),
+    };
+}
+/**
+ * Validate whether a mandate permits the given evaluation context.
+ */
+function validateMandateForContext(mandate, ctx) {
+    // Check lifecycle
+    if (mandate.lifecycle === 'revoked') {
+        return { valid: false, reason: 'Mandate has been revoked' };
+    }
+    if (mandate.lifecycle !== 'active') {
+        return { valid: false, reason: `Mandate is in '${mandate.lifecycle}' state, not active` };
+    }
+    // Check expiration (activatedAt + timeoutMs)
+    if (mandate.activatedAt) {
+        let elapsedMs;
+        if (mandate.activatedMark != null) {
+            elapsedMs = performance.now() - mandate.activatedMark;
+        }
+        else {
+            elapsedMs = Date.now() - new Date(mandate.activatedAt).getTime();
+        }
+        if (elapsedMs >= mandate.scope.timeoutMs) {
+            return { valid: false, reason: 'Mandate has expired' };
+        }
+    }
+    // Check effect kind
+    const kinds = mandate.scope.allowedEffectKinds;
+    const isWildcard = kinds.length === 1 && kinds[0] === '*';
+    if (!isWildcard && !kinds.includes(ctx.effectKind)) {
+        return { valid: false, reason: `Effect kind '${ctx.effectKind}' is not allowed by mandate scope` };
+    }
+    return { valid: true };
+}
+/**
+ * Convert a mandate's scope into PolicyRule[] for governance engine evaluation.
+ */
+function mandateToPolicy(mandate) {
+    const rules = [];
+    const prefix = `mandate:${mandate.mandateId.slice(0, 8)}`;
+    // 1. Deny rule for out-of-scope effect kinds (if not wildcard)
+    const kinds = mandate.scope.allowedEffectKinds;
+    const isWildcard = kinds.length === 1 && kinds[0] === '*';
+    if (!isWildcard) {
+        // Create a deny rule that matches any effectKind NOT in the allowed list.
+        // We use a regex negative lookahead.
+        const escaped = kinds.map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        const pattern = `^(?!${escaped.join('|')}$)`;
+        rules.push({
+            id: `${prefix}:deny-out-of-scope`,
+            kind: 'permission',
+            condition: { field: 'effectKind', op: 'matches', value: pattern },
+            action: 'deny',
+            priority: 200,
+            metadata: { source: 'mandate', mandateId: mandate.mandateId },
+        });
+    }
+    // 2. Iteration limit rule
+    rules.push({
+        id: `${prefix}:max-iterations`,
+        kind: 'rate-limit',
+        condition: { field: 'iteration', op: 'gt', value: String(mandate.scope.maxIterations) },
+        action: 'deny',
+        priority: 150,
+        metadata: { source: 'mandate', mandateId: mandate.mandateId },
+    });
+    return rules;
+}

package/dist/governance/permissionEvents.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Permission event creation, aggregation, and filtering for the governance layer.
+ */
+export type PermissionEventSource = 'harness' | 'subagent' | 'sandbox' | 'policy-engine';
+export interface PermissionEvent {
+    kind: string;
+    operation: {
+        kind: string;
+        target: string;
+        [key: string]: unknown;
+    };
+    decision: {
+        action: string;
+        reason: string;
+        [key: string]: unknown;
+    };
+    timestamp: string;
+    source: PermissionEventSource;
+    mandateId?: string;
+    chainId?: string;
+}
+export interface CreatePermissionEventOptions {
+    kind: string;
+    operation: {
+        kind: string;
+        target: string;
+        [key: string]: unknown;
+    };
+    decision: {
+        action: string;
+        reason: string;
+        [key: string]: unknown;
+    };
+    source: PermissionEventSource;
+    timestamp?: string;
+    mandateId?: string;
+    chainId?: string;
+}
+export declare function createPermissionEvent(options: CreatePermissionEventOptions): PermissionEvent;
+/**
+ * Flatten multiple event arrays (from parent/child runs), filter by chainId,
+ * and sort chronologically.
+ */
+export declare function aggregateChainEvents(chainId: string, eventArrays: PermissionEvent[][]): PermissionEvent[];
+export interface FilterCriteria {
+    source?: PermissionEventSource;
+    action?: string;
+    kind?: string;
+}
+export declare function filterEvents(events: PermissionEvent[], criteria: FilterCriteria): PermissionEvent[];
+//# sourceMappingURL=permissionEvents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permissionEvents.d.ts","sourceRoot":"","sources":["../../src/governance/permissionEvents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,eAAe,CAAC;AAEzF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACpE,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACpE,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACrE,MAAM,EAAE,qBAAqB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,eAAe,CAU5F;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,eAAe,EAAE,EAAE,GAC/B,eAAe,EAAE,CAWnB;AAMD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,QAAQ,EAAE,cAAc,GAAG,eAAe,EAAE,CAOnG"}