@peac/control 0.9.18

package/README.md

@@ -0,0 +1,23 @@
+# @peac/control
+
+PEAC Protocol Control - control engine interfaces and validation
+
+## Installation
+
+```bash
+pnpm add @peac/control
+```
+
+## Documentation
+
+See [peacprotocol.org](https://peacprotocol.org) for full documentation.
+
+## License
+
+Apache-2.0
+
+---
+
+PEAC Protocol is an open source project stewarded by Originary and community contributors.
+
+[Originary](https://www.originary.xyz) | [Docs](https://peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac)

package/dist/adapter.d.ts

@@ -0,0 +1,143 @@
+/**
+ * PEAC Control Engine Adapter Interface
+ *
+ * Minimal, vendor-neutral interface for control engine implementations.
+ * Control engines evaluate authorization policies and return allow/deny decisions.
+ *
+ * @packageDocumentation
+ */
+import type { ControlStep } from '@peac/schema';
+/**
+ * Context provided to control engine for evaluation
+ *
+ * This is the minimal context needed for most control engines.
+ * Engines may require additional context via the `policy` field.
+ */
+export interface ControlEvaluationContext {
+    /** Resource being accessed (e.g., "https://api.example.com/v1/chat") */
+    resource: string;
+    /** HTTP method or operation (e.g., "POST", "read", "write") */
+    method: string;
+    /** Requested payment amount (smallest currency unit), if applicable */
+    amount?: number;
+    /** Currency (ISO 4217), if applicable */
+    currency?: string;
+    /** Subject identifier (e.g., agent ID, user ID) */
+    subject?: string;
+    /** Policy document fetched from policy_uri (engine-specific structure) */
+    policy: unknown;
+    /** Current timestamp (Unix seconds) for temporal checks */
+    timestamp?: number;
+    /** Additional context (engine-specific) */
+    [key: string]: unknown;
+}
+/**
+ * Control Engine Adapter
+ *
+ * Minimal interface that all control engines must implement.
+ *
+ * **Design principles**:
+ * - Vendor-neutral: No hardcoded engine names or vendor-specific types
+ * - Stateless: Engine is responsible for fetching its own state if needed
+ * - Async: Allows engines to make network calls (fetch policies, check quotas)
+ * - Opaque: Policy structure is engine-specific (unknown type)
+ *
+ * **Examples of engines**:
+ * - Spend control: Per-transaction, daily, monthly limits
+ * - Risk scoring: Fraud detection, anomaly detection
+ * - Mandate enforcement: Enterprise approval chains
+ * - Rate limiting: Request quotas, throttling
+ *
+ * **Usage**:
+ * ```typescript
+ * const engine: ControlEngineAdapter = new MyControlEngine();
+ * const step = await engine.evaluate({
+ *   resource: "https://api.example.com/v1/chat",
+ *   method: "POST",
+ *   amount: 250,
+ *   currency: "USD",
+ *   policy: { ... }  // Fetched from policy_uri
+ * });
+ * ```
+ */
+export interface ControlEngineAdapter {
+    /**
+     * Engine identifier (vendor-neutral)
+     *
+     * Examples:
+     * - "spend-control-service"
+     * - "risk-engine"
+     * - "mandate-service"
+     *
+     * See docs/specs/registries.json for common identifiers.
+     */
+    readonly engineId: string;
+    /**
+     * Engine version (optional, for tracking)
+     *
+     * Format: Semantic versioning (e.g., "1.2.3")
+     */
+    readonly version?: string;
+    /**
+     * Evaluate authorization policy and return control decision
+     *
+     * @param context - Evaluation context (resource, method, amount, policy, etc.)
+     * @returns Control step with decision (allow/deny) and optional limits_snapshot
+     * @throws Error if evaluation fails (network error, invalid policy, etc.)
+     *
+     * **Requirements**:
+     * - MUST return a valid ControlStep with result: "allow" | "deny" | "review"
+     * - SHOULD populate reason if result is "deny" or "review"
+     * - MAY populate limits_snapshot with engine-specific state
+     * - MAY populate evidence_ref with URL to detailed evidence
+     * - MUST NOT throw on normal deny decisions (only throw on errors)
+     */
+    evaluate(context: ControlEvaluationContext): Promise<ControlStep>;
+}
+/**
+ * Control Engine Registry
+ *
+ * Optional helper for managing multiple control engines.
+ *
+ * **Usage**:
+ * ```typescript
+ * const registry = new ControlEngineRegistry();
+ * registry.register(new SpendControlEngine());
+ * registry.register(new RiskEngine());
+ *
+ * const engine = registry.get("spend-control-service");
+ * const step = await engine.evaluate(context);
+ * ```
+ */
+export declare class ControlEngineRegistry {
+    private engines;
+    /**
+     * Register a control engine
+     *
+     * @param engine - Control engine adapter
+     * @throws Error if engine with same ID already registered
+     */
+    register(engine: ControlEngineAdapter): void;
+    /**
+     * Get control engine by ID
+     *
+     * @param engineId - Engine identifier
+     * @returns Control engine adapter
+     * @throws Error if engine not found
+     */
+    get(engineId: string): ControlEngineAdapter;
+    /**
+     * Check if engine is registered
+     *
+     * @param engineId - Engine identifier
+     * @returns True if engine is registered
+     */
+    has(engineId: string): boolean;
+    /**
+     * Get all registered engine IDs
+     *
+     * @returns Array of engine IDs
+     */
+    list(): string[];
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IAEjB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IAEf,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAEhB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,OAAO,CAA2C;IAE1D;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAO5C;;;;;;OAMG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB;IAQ3C;;;;;OAKG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;OAIG;IACH,IAAI,IAAI,MAAM,EAAE;CAGjB"}

package/dist/adapter.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * PEAC Control Engine Adapter Interface
+ *
+ * Minimal, vendor-neutral interface for control engine implementations.
+ * Control engines evaluate authorization policies and return allow/deny decisions.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlEngineRegistry = void 0;
+/**
+ * Control Engine Registry
+ *
+ * Optional helper for managing multiple control engines.
+ *
+ * **Usage**:
+ * ```typescript
+ * const registry = new ControlEngineRegistry();
+ * registry.register(new SpendControlEngine());
+ * registry.register(new RiskEngine());
+ *
+ * const engine = registry.get("spend-control-service");
+ * const step = await engine.evaluate(context);
+ * ```
+ */
+class ControlEngineRegistry {
+    engines = new Map();
+    /**
+     * Register a control engine
+     *
+     * @param engine - Control engine adapter
+     * @throws Error if engine with same ID already registered
+     */
+    register(engine) {
+        if (this.engines.has(engine.engineId)) {
+            throw new Error(`Control engine already registered: ${engine.engineId}`);
+        }
+        this.engines.set(engine.engineId, engine);
+    }
+    /**
+     * Get control engine by ID
+     *
+     * @param engineId - Engine identifier
+     * @returns Control engine adapter
+     * @throws Error if engine not found
+     */
+    get(engineId) {
+        const engine = this.engines.get(engineId);
+        if (!engine) {
+            throw new Error(`Control engine not found: ${engineId}`);
+        }
+        return engine;
+    }
+    /**
+     * Check if engine is registered
+     *
+     * @param engineId - Engine identifier
+     * @returns True if engine is registered
+     */
+    has(engineId) {
+        return this.engines.has(engineId);
+    }
+    /**
+     * Get all registered engine IDs
+     *
+     * @returns Array of engine IDs
+     */
+    list() {
+        return Array.from(this.engines.keys());
+    }
+}
+exports.ControlEngineRegistry = ControlEngineRegistry;
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAsGH;;;;;;;;;;;;;;GAcG;AACH,MAAa,qBAAqB;IACxB,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAE1D;;;;;OAKG;IACH,QAAQ,CAAC,MAA4B;QACnC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,sCAAsC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,QAAgB;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,QAAgB;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;CACF;AAjDD,sDAiDC"}

package/dist/constraints.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Generic Control Constraint Types
+ *
+ * These are informational helper types that control engines MAY use
+ * in their limits_snapshot fields. They are NOT part of the normative
+ * wire format.
+ *
+ * Control engines are free to use custom constraint models.
+ * These types provide common patterns (temporal, usage, budget)
+ * that many engines need.
+ */
+/**
+ * Constraint type identifiers
+ */
+export type ConstraintType = 'temporal' | 'usage' | 'budget' | 'combined';
+/**
+ * Temporal constraint - time-based access control
+ *
+ * Common use cases:
+ * - Access only during business hours
+ * - Time-limited API keys
+ * - Temporary elevated permissions
+ */
+export interface TemporalConstraint {
+    /** Constraint type */
+    type: 'temporal';
+    /** Access granted from (Unix timestamp seconds) */
+    valid_from?: number;
+    /** Access expires at (Unix timestamp seconds) */
+    valid_until?: number;
+    /** Maximum duration in seconds */
+    duration?: number;
+}
+/**
+ * Usage constraint - count-based restrictions
+ *
+ * Common use cases:
+ * - Rate limiting (N requests per window)
+ * - Quota management (N API calls per month)
+ * - One-time use tokens
+ */
+export interface UsageConstraint {
+    /** Constraint type */
+    type: 'usage';
+    /** Maximum number of uses allowed */
+    max_uses: number;
+    /** Current usage count (tracked by issuer) */
+    current_uses?: number;
+    /** Usage window in seconds (optional) */
+    window?: number;
+}
+/**
+ * Budget constraint - amount-based restrictions
+ *
+ * Common use cases:
+ * - Spending limits (per transaction, daily, monthly)
+ * - Credit limits
+ * - Expense controls
+ */
+export interface BudgetConstraint {
+    /** Constraint type */
+    type: 'budget';
+    /** Maximum amount allowed (smallest currency unit) */
+    max_amount: number;
+    /** Current spent amount (tracked by issuer) */
+    current_amount?: number;
+    /** Budget window in seconds (optional) */
+    window?: number;
+    /** Currency (ISO 4217) */
+    currency: string;
+}
+/**
+ * Combined constraint - multiple restrictions
+ *
+ * Combines temporal, usage, and budget constraints.
+ * All specified constraints must be satisfied.
+ */
+export interface CombinedConstraint {
+    /** Constraint type */
+    type: 'combined';
+    /** Temporal restrictions */
+    temporal?: Omit<TemporalConstraint, 'type'>;
+    /** Usage restrictions */
+    usage?: Omit<UsageConstraint, 'type'>;
+    /** Budget restrictions */
+    budget?: Omit<BudgetConstraint, 'type'>;
+}
+/**
+ * Constraint union type
+ */
+export type Constraint = TemporalConstraint | UsageConstraint | BudgetConstraint | CombinedConstraint;
+/**
+ * Enforcement result from evaluating a constraint
+ */
+export interface ConstraintEnforcementResult {
+    /** Whether the constraint is satisfied */
+    allowed: boolean;
+    /** Reason if not allowed */
+    reason?: string;
+    /** Remaining quota information */
+    remaining?: {
+        uses?: number;
+        amount?: number;
+        seconds?: number;
+    };
+}
+//# sourceMappingURL=constraints.d.ts.map

package/dist/constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../src/constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,CAAC;AAEf;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,IAAI,EAAE,UAAU,CAAC;IAEjB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,IAAI,EAAE,OAAO,CAAC;IAEd,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IAEjB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,IAAI,EAAE,QAAQ,CAAC;IAEf,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IAEnB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,IAAI,EAAE,UAAU,CAAC;IAEjB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAE5C,yBAAyB;IACzB,KAAK,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAEtC,0BAA0B;IAC1B,MAAM,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,kBAAkB,GAClB,eAAe,GACf,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IAEjB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,kCAAkC;IAClC,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH"}

package/dist/constraints.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Generic Control Constraint Types
+ *
+ * These are informational helper types that control engines MAY use
+ * in their limits_snapshot fields. They are NOT part of the normative
+ * wire format.
+ *
+ * Control engines are free to use custom constraint models.
+ * These types provide common patterns (temporal, usage, budget)
+ * that many engines need.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=constraints.js.map

package/dist/constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.js","sourceRoot":"","sources":["../src/constraints.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}

package/dist/enforcement.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PEAC Control Abstraction Layer (CAL) Enforcement
+ *
+ * Enforcement logic for mandates and control blocks.
+ */
+import type { Constraint, ControlState, ConstraintEnforcementResult, TemporalConstraint, UsageConstraint, BudgetConstraint, CombinedConstraint } from './types';
+type EnforcementResult = ConstraintEnforcementResult;
+/**
+ * Enforce temporal mandate
+ */
+export declare function enforceTemporalConstraint(mandate: TemporalConstraint, currentTime?: number): EnforcementResult;
+/**
+ * Enforce usage mandate
+ */
+export declare function enforceUsageConstraint(mandate: UsageConstraint, state?: ControlState): EnforcementResult;
+/**
+ * Enforce budget mandate
+ */
+export declare function enforceBudgetConstraint(mandate: BudgetConstraint, state?: ControlState, requestedAmount?: number): EnforcementResult;
+/**
+ * Enforce combined mandate
+ */
+export declare function enforceCombinedConstraint(mandate: CombinedConstraint, state?: ControlState, requestedAmount?: number, currentTime?: number): EnforcementResult;
+/**
+ * Enforce mandate (dispatcher)
+ */
+export declare function enforceConstraint(mandate: Constraint, state?: ControlState, requestedAmount?: number, currentTime?: number): EnforcementResult;
+/**
+ * Enforce control block
+ *
+ * @deprecated Use enforceConstraint directly. This function is maintained for backward compatibility.
+ */
+export declare function enforceControlBlock(constraint: Constraint, state?: ControlState, requestedAmount?: number, currentTime?: number): EnforcementResult;
+export {};
+//# sourceMappingURL=enforcement.d.ts.map

package/dist/enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforcement.d.ts","sourceRoot":"","sources":["../src/enforcement.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,2BAA2B,EAC3B,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,KAAK,iBAAiB,GAAG,2BAA2B,CAAC;AAErD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,GAAE,MAAsC,GAClD,iBAAiB,CAiCnB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,YAAY,GACnB,iBAAiB,CAgCnB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,gBAAgB,EACzB,KAAK,CAAC,EAAE,YAAY,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,iBAAiB,CA4CnB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,CAAC,EAAE,YAAY,EACpB,eAAe,CAAC,EAAE,MAAM,EACxB,WAAW,CAAC,EAAE,MAAM,GACnB,iBAAiB,CAmDnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,UAAU,EACnB,KAAK,CAAC,EAAE,YAAY,EACpB,eAAe,CAAC,EAAE,MAAM,EACxB,WAAW,CAAC,EAAE,MAAM,GACnB,iBAAiB,CAsBnB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,UAAU,EACtB,KAAK,CAAC,EAAE,YAAY,EACpB,eAAe,CAAC,EAAE,MAAM,EACxB,WAAW,CAAC,EAAE,MAAM,GACnB,iBAAiB,CAEnB"}

package/dist/enforcement.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * PEAC Control Abstraction Layer (CAL) Enforcement
+ *
+ * Enforcement logic for mandates and control blocks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceTemporalConstraint = enforceTemporalConstraint;
+exports.enforceUsageConstraint = enforceUsageConstraint;
+exports.enforceBudgetConstraint = enforceBudgetConstraint;
+exports.enforceCombinedConstraint = enforceCombinedConstraint;
+exports.enforceConstraint = enforceConstraint;
+exports.enforceControlBlock = enforceControlBlock;
+/**
+ * Enforce temporal mandate
+ */
+function enforceTemporalConstraint(mandate, currentTime = Math.floor(Date.now() / 1000)) {
+    // Check valid_from
+    if (mandate.valid_from !== undefined && currentTime < mandate.valid_from) {
+        const remaining = mandate.valid_from - currentTime;
+        return {
+            allowed: false,
+            reason: `Access not yet valid (starts in ${remaining}s)`,
+            remaining: { seconds: remaining },
+        };
+    }
+    // Check valid_until
+    if (mandate.valid_until !== undefined && currentTime > mandate.valid_until) {
+        return {
+            allowed: false,
+            reason: 'Access has expired',
+            remaining: { seconds: 0 },
+        };
+    }
+    // Calculate remaining time
+    let remainingSeconds;
+    if (mandate.valid_until !== undefined) {
+        remainingSeconds = mandate.valid_until - currentTime;
+    }
+    else if (mandate.duration !== undefined && mandate.valid_from !== undefined) {
+        const expiresAt = mandate.valid_from + mandate.duration;
+        remainingSeconds = expiresAt - currentTime;
+    }
+    return {
+        allowed: true,
+        remaining: remainingSeconds !== undefined ? { seconds: remainingSeconds } : undefined,
+    };
+}
+/**
+ * Enforce usage mandate
+ */
+function enforceUsageConstraint(mandate, state) {
+    const currentUses = state?.usage_count ?? mandate.current_uses ?? 0;
+    // Check if max uses exceeded
+    if (currentUses >= mandate.max_uses) {
+        return {
+            allowed: false,
+            reason: `Usage limit exceeded (${currentUses}/${mandate.max_uses})`,
+            remaining: { uses: 0 },
+        };
+    }
+    // Check usage window if specified
+    if (mandate.window !== undefined && state?.first_use !== undefined) {
+        const currentTime = Math.floor(Date.now() / 1000);
+        const windowExpiry = state.first_use + mandate.window;
+        if (currentTime > windowExpiry) {
+            return {
+                allowed: false,
+                reason: 'Usage window expired',
+                remaining: { uses: 0 },
+            };
+        }
+    }
+    const remainingUses = mandate.max_uses - currentUses;
+    return {
+        allowed: true,
+        remaining: { uses: remainingUses },
+    };
+}
+/**
+ * Enforce budget mandate
+ */
+function enforceBudgetConstraint(mandate, state, requestedAmount) {
+    const currentAmount = state?.spent_amount ?? mandate.current_amount ?? 0;
+    // Check if budget exceeded
+    if (currentAmount >= mandate.max_amount) {
+        return {
+            allowed: false,
+            reason: `Budget limit exceeded (${currentAmount}/${mandate.max_amount} ${mandate.currency})`,
+            remaining: { amount: 0 },
+        };
+    }
+    // Check if requested amount would exceed budget
+    if (requestedAmount !== undefined) {
+        if (currentAmount + requestedAmount > mandate.max_amount) {
+            const remaining = mandate.max_amount - currentAmount;
+            return {
+                allowed: false,
+                reason: `Requested amount would exceed budget (${requestedAmount} > ${remaining} ${mandate.currency} remaining)`,
+                remaining: { amount: remaining },
+            };
+        }
+    }
+    // Check budget window if specified
+    if (mandate.window !== undefined && state?.first_use !== undefined) {
+        const currentTime = Math.floor(Date.now() / 1000);
+        const windowExpiry = state.first_use + mandate.window;
+        if (currentTime > windowExpiry) {
+            return {
+                allowed: false,
+                reason: 'Budget window expired',
+                remaining: { amount: 0 },
+            };
+        }
+    }
+    const remainingAmount = mandate.max_amount - currentAmount;
+    return {
+        allowed: true,
+        remaining: { amount: remainingAmount },
+    };
+}
+/**
+ * Enforce combined mandate
+ */
+function enforceCombinedConstraint(mandate, state, requestedAmount, currentTime) {
+    const results = [];
+    // Check temporal constraints
+    if (mandate.temporal !== undefined) {
+        const temporalConstraint = {
+            type: 'temporal',
+            ...mandate.temporal,
+        };
+        const result = enforceTemporalConstraint(temporalConstraint, currentTime);
+        results.push(result);
+    }
+    // Check usage constraints
+    if (mandate.usage !== undefined) {
+        const usageConstraint = {
+            type: 'usage',
+            ...mandate.usage,
+        };
+        const result = enforceUsageConstraint(usageConstraint, state);
+        results.push(result);
+    }
+    // Check budget constraints
+    if (mandate.budget !== undefined) {
+        const budgetConstraint = {
+            type: 'budget',
+            ...mandate.budget,
+        };
+        const result = enforceBudgetConstraint(budgetConstraint, state, requestedAmount);
+        results.push(result);
+    }
+    // All constraints must be satisfied
+    const failedResult = results.find((r) => !r.allowed);
+    if (failedResult) {
+        return failedResult;
+    }
+    // Merge remaining information
+    const remaining = {};
+    for (const result of results) {
+        if (result.remaining) {
+            Object.assign(remaining, result.remaining);
+        }
+    }
+    return {
+        allowed: true,
+        remaining: Object.keys(remaining).length > 0 ? remaining : undefined,
+    };
+}
+/**
+ * Enforce mandate (dispatcher)
+ */
+function enforceConstraint(mandate, state, requestedAmount, currentTime) {
+    switch (mandate.type) {
+        case 'temporal':
+            return enforceTemporalConstraint(mandate, currentTime);
+        case 'usage':
+            return enforceUsageConstraint(mandate, state);
+        case 'budget':
+            return enforceBudgetConstraint(mandate, state, requestedAmount);
+        case 'combined':
+            return enforceCombinedConstraint(mandate, state, requestedAmount, currentTime);
+        default:
+            // TypeScript exhaustiveness check
+            const _exhaustive = mandate;
+            return {
+                allowed: false,
+                reason: `Unknown mandate type: ${_exhaustive.type}`,
+            };
+    }
+}
+/**
+ * Enforce control block
+ *
+ * @deprecated Use enforceConstraint directly. This function is maintained for backward compatibility.
+ */
+function enforceControlBlock(constraint, state, requestedAmount, currentTime) {
+    return enforceConstraint(constraint, state, requestedAmount, currentTime);
+}
+//# sourceMappingURL=enforcement.js.map

package/dist/enforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforcement.js","sourceRoot":"","sources":["../src/enforcement.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * PEAC Control
+ *
+ * Control engine interfaces, generic constraint helpers, and validation.
+ *
+ * @packageDocumentation
+ */
+export type { ControlEngineAdapter, ControlEvaluationContext } from './adapter';
+export { ControlEngineRegistry } from './adapter';
+export type { ControlBlock, ControlStep, ControlDecision, ControlValidationResult, ControlPurpose, ControlLicensingMode, } from './types';
+export type { ConstraintType, TemporalConstraint, UsageConstraint, BudgetConstraint, CombinedConstraint, Constraint, ConstraintEnforcementResult, } from './constraints';
+export type { MandateType, TemporalMandate, UsageMandate, BudgetMandate, CombinedMandate, Mandate, EnforcementResult, ControlState, } from './types';
+export { TemporalConstraintSchema, UsageConstraintSchema, BudgetConstraintSchema, CombinedConstraintSchema, ConstraintSchema, ControlBlockSchema, ControlStateSchema, ControlPurposeSchema, ControlLicensingModeSchema, ControlDecisionSchema, ControlStepSchema, ChainControlBlockSchema, } from './validators';
+export { TemporalConstraintSchema as TemporalMandateSchema, UsageConstraintSchema as UsageMandateSchema, BudgetConstraintSchema as BudgetMandateSchema, CombinedConstraintSchema as CombinedMandateSchema, ConstraintSchema as MandateSchema, } from './validators';
+export { enforceTemporalConstraint, enforceUsageConstraint, enforceBudgetConstraint, enforceCombinedConstraint, enforceConstraint, enforceControlBlock, } from './enforcement';
+export { enforceTemporalConstraint as enforceTemporalMandate, enforceUsageConstraint as enforceUsageMandate, enforceBudgetConstraint as enforceBudgetMandate, enforceCombinedConstraint as enforceCombinedMandate, enforceConstraint as enforceMandate, } from './enforcement';
+export { createControlState, updateStateAfterUse, isStateExpired, resetState, getStateSummary, } from './state';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAGlD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,uBAAuB,EAEvB,cAAc,EACd,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AAGvB,YAAY,EACV,WAAW,EACX,eAAe,EACf,YAAY,EACZ,aAAa,EACb,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAElB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,wBAAwB,IAAI,qBAAqB,EACjD,qBAAqB,IAAI,kBAAkB,EAC3C,sBAAsB,IAAI,mBAAmB,EAC7C,wBAAwB,IAAI,qBAAqB,EACjD,gBAAgB,IAAI,aAAa,GAClC,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,yBAAyB,IAAI,sBAAsB,EACnD,sBAAsB,IAAI,mBAAmB,EAC7C,uBAAuB,IAAI,oBAAoB,EAC/C,yBAAyB,IAAI,sBAAsB,EACnD,iBAAiB,IAAI,cAAc,GACpC,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,eAAe,GAChB,MAAM,SAAS,CAAC"}