@connexum/ai-governance 1.0.0-beta.11

package/dist/governance/skip-api-empty-queue.js

@@ -0,0 +1,499 @@
+"use strict";
+/**
+ * SkipApiEmptyQueueEnforcer -- Pre-call gate that prevents LLM calls when
+ * the agent's work queue is empty.
+ *
+ * Problem: polling-style agents may issue an LLM call on every tick even
+ * when no work is pending, burning tokens for "nothing to do" responses.
+ * This gate asks the operator-supplied queue adapter: "is there work?"
+ * If the answer is no, it throws EmptyQueueSkipApiError and the caller
+ * skips the LLM call entirely.
+ *
+ * Operator opt-in:
+ *   Default: NOT enabled. Operators must call configure() for each agent.
+ *   Agents without a registered adapter pass through guardPreCall() as a
+ *   no-op. This is intentional -- some agents legitimately poll for events
+ *   that are not queue-shaped (cron triggers, health checks, etc.).
+ *
+ * Position in the hook chain:
+ *   VERY EARLY -- before cycle-token-budget, rate-limit, and RAG gates.
+ *   If the queue is empty, skip ALL downstream gates and avoid every
+ *   compute-heavy check.
+ *
+ * Fail-closed on adapter error:
+ *   If the adapter throws, guardPreCall() rethrows. It does NOT default to
+ *   "skip" (which would silently stop the agent) or "allow" (which would
+ *   bypass the gate). Both silent behaviours are dangerous. The caller must
+ *   handle the error explicitly.
+ *
+ * Adapter timeout:
+ *   Default 500 ms. Queue-state lookups should be fast. A slow queue adapter
+ *   is a sign of operator infrastructure issues that should NOT propagate to
+ *   LLM-call latency. Timeout is configurable per-agent.
+ *
+ * Build Plan Reference: docs/BUILD_PLAN_V3_FULL_LIFECYCLE.md line 274
+ * Budget-trio siblings: PR #12 (per-cycle), PR #30 (per-agent-daily)
+ *
+ * Compliance bindings:
+ *   - HIPAA 164.312(b): Audit Controls -- idle-agent calls appear as anomalies
+ *   - SOC 2 CC6.1: Resource control -- skip unnecessary inference spend
+ *   - EU AI Act Art. 9: Risk management -- bound agent action to intent
+ *   - ISO 42001 A.6.1.4: Resource management for AI systems
+ *
+ * @connexum/ai-governance
+ */
+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.SkipApiEmptyQueueEnforcer = exports.INCONSISTENCY_MIN_SAMPLES = exports.INCONSISTENCY_THRESHOLD = exports.DEFAULT_ADAPTER_TIMEOUT_MS = exports.ConfigurePermissionError = exports.EmptyQueuePackBindingError = exports.QueueAdapterTimeoutError = exports.EmptyQueueSkipApiError = void 0;
+const crypto = __importStar(require("node:crypto"));
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/**
+ * Thrown by guardPreCall() when the adapter reports hasWork: false.
+ * The caller should catch this and skip the LLM call entirely.
+ * It is NOT an error condition -- it is an expected, recoverable signal.
+ */
+class EmptyQueueSkipApiError extends Error {
+    orgId;
+    agentId;
+    packBinding;
+    constructor(opts) {
+        super(`Agent '${opts.agentId}' in org '${opts.orgId}' has no pending work. ` +
+            `LLM call skipped to preserve token budget.`);
+        this.name = 'EmptyQueueSkipApiError';
+        this.orgId = opts.orgId;
+        this.agentId = opts.agentId;
+        this.packBinding = opts.packBinding;
+    }
+}
+exports.EmptyQueueSkipApiError = EmptyQueueSkipApiError;
+/**
+ * Thrown by guardPreCall() when the adapter's peek() does not resolve within
+ * the configured timeout. Fails closed -- the LLM call is rejected until
+ * the operator fixes their adapter latency.
+ */
+class QueueAdapterTimeoutError extends Error {
+    orgId;
+    agentId;
+    timeoutMs;
+    packBinding;
+    constructor(opts) {
+        super(`Queue adapter for agent '${opts.agentId}' in org '${opts.orgId}' did not resolve ` +
+            `within ${opts.timeoutMs} ms. Queue-state lookups must be fast. ` +
+            `Slow adapters indicate operator infrastructure issues. LLM call rejected (fail-closed).`);
+        this.name = 'QueueAdapterTimeoutError';
+        this.orgId = opts.orgId;
+        this.agentId = opts.agentId;
+        this.timeoutMs = opts.timeoutMs;
+        this.packBinding = opts.packBinding;
+    }
+}
+exports.QueueAdapterTimeoutError = QueueAdapterTimeoutError;
+/**
+ * Thrown when configure() is called with an empty packBinding.
+ * Per pack-binding-primacy: every governance record must carry at least one
+ * compliance pack binding.
+ */
+class EmptyQueuePackBindingError extends Error {
+    operation;
+    constructor(operation) {
+        super(`Operation '${operation}' requires a non-empty packBinding. ` +
+            `Per the Connexum AI Governance pack-binding-primacy invariant, ` +
+            `every governance record must carry at least one compliance pack binding.`);
+        this.name = 'EmptyQueuePackBindingError';
+        this.operation = operation;
+    }
+}
+exports.EmptyQueuePackBindingError = EmptyQueuePackBindingError;
+/**
+ * Thrown when configure() is called by an identity that does not hold the
+ * 'governance.configure' permission (PT-SKIP-API-3: opt-in bypass prevention).
+ */
+class ConfigurePermissionError extends Error {
+    operatorId;
+    reason;
+    constructor(operatorId, reason) {
+        super(`configure() denied for identity '${operatorId}': ${reason}. ` +
+            `Only identities with governance.configure permission may register ` +
+            `a queue adapter. Agent-runtime identities are rejected.`);
+        this.name = 'ConfigurePermissionError';
+        this.operatorId = operatorId;
+        this.reason = reason;
+    }
+}
+exports.ConfigurePermissionError = ConfigurePermissionError;
+// ---------------------------------------------------------------------------
+// SkipApiEmptyQueueEnforcer
+// ---------------------------------------------------------------------------
+/** Default adapter timeout in milliseconds. */
+exports.DEFAULT_ADAPTER_TIMEOUT_MS = 500;
+/**
+ * Ratio threshold above which a QUEUE_PEEK_INCONSISTENT warning event is
+ * emitted. If peeksClaimingWork / actualLlmCalls > INCONSISTENCY_THRESHOLD,
+ * the adapter is reporting hasWork:true significantly more than LLM calls are
+ * actually occurring, which may indicate a compromised adapter always returning
+ * hasWork:true to keep the gate open. (PT-SKIP-API-1)
+ *
+ * Evaluated at every skip event (because a skip is direct evidence the adapter
+ * returned hasWork:false at least once, giving us a consistent baseline to
+ * compare against).
+ *
+ * Minimum sample size before firing: 10 peeks to avoid false positives on
+ * low-volume agents.
+ */
+exports.INCONSISTENCY_THRESHOLD = 5.0;
+exports.INCONSISTENCY_MIN_SAMPLES = 10;
+class SkipApiEmptyQueueEnforcer {
+    /** Per-agent registered adapters. Key: `${orgId}::${agentId}` */
+    agents = new Map();
+    /**
+     * Audit event callback. Wire to AuditIntegrity.append() in production.
+     */
+    onAudit;
+    /**
+     * SHA chain state for audit events. Simple in-memory chain for the
+     * enforcer's own events. In production wire to the external AuditIntegrity chain.
+     */
+    lastSha = '';
+    /**
+     * Optional permission check function injected by the operator.
+     * Signature mirrors OperatorRoles.checkPermission.
+     *
+     * If not provided, any caller can configure the gate -- appropriate for
+     * test environments. In production, inject OperatorRoles.checkPermission
+     * to enforce that only operators hold governance.configure.
+     */
+    checkPermission;
+    constructor(opts = {}) {
+        this.onAudit = opts.onAudit ?? (() => undefined);
+        this.checkPermission = opts.checkPermission;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Register a queue adapter for an agent.
+     *
+     * Must be called before guardPreCall() has any effect for this agent.
+     * If not called, guardPreCall() is a no-op pass-through (opt-in semantics).
+     *
+     * PT-SKIP-API-3: configure() checks the callerIdentity holds
+     * 'governance.configure' permission when a checkPermission function was
+     * injected. Agent-runtime identities (prefixed 'agent:' or 'runtime:') are
+     * always rejected, even without an injected checker.
+     *
+     * @param orgId           Tenant / organization ID.
+     * @param agentId         Agent identifier.
+     * @param callerIdentity  Identity of the operator performing configuration.
+     * @param queueAdapter    Operator-implemented adapter.
+     * @param packBinding     Non-empty compliance pack binding. (Pack-binding primacy.)
+     * @param adapterTimeoutMs  Timeout for peek() calls. Default 500 ms.
+     */
+    configure(orgId, agentId, callerIdentity, queueAdapter, packBinding, adapterTimeoutMs = exports.DEFAULT_ADAPTER_TIMEOUT_MS) {
+        if (!packBinding || packBinding.length === 0) {
+            throw new EmptyQueuePackBindingError('configure');
+        }
+        // PT-SKIP-API-3: reject agent-runtime identities unconditionally.
+        if (this.isAgentRuntimeIdentity(callerIdentity)) {
+            throw new ConfigurePermissionError(callerIdentity, 'agent-runtime identities (prefixed agent: or runtime:) may not register queue adapters. ' +
+                'Only operator identities with governance.configure permission are permitted.');
+        }
+        // PT-SKIP-API-3: check injected permission function if present.
+        if (this.checkPermission) {
+            const check = this.checkPermission(callerIdentity, 'governance.configure');
+            if (!check.allowed) {
+                throw new ConfigurePermissionError(callerIdentity, check.reason);
+            }
+        }
+        const key = this.key(orgId, agentId);
+        const existing = this.agents.get(key);
+        this.agents.set(key, {
+            adapter: queueAdapter,
+            packBinding,
+            adapterTimeoutMs,
+            skippedTotal: existing?.skippedTotal ?? 0,
+            skippedHourBucket: existing?.skippedHourBucket ?? 0,
+            hourBucketKey: existing?.hourBucketKey ?? this.currentHourBucket(),
+            lastSkipAt: existing?.lastSkipAt ?? null,
+            peeksClaimingWork: existing?.peeksClaimingWork ?? 0,
+            actualLlmCalls: existing?.actualLlmCalls ?? 0,
+        });
+        this.emit({
+            type: 'QUEUE_ADAPTER_CONFIGURED',
+            severity: 'NOTICE',
+            orgId,
+            agentId,
+            packBinding,
+            callerIdentity,
+            adapterTimeoutMs,
+        });
+    }
+    /**
+     * Pre-call gate. Call this BEFORE every LLM call.
+     *
+     * Behaviour:
+     *   - Agent NOT configured: no-op, returns { allowed: true }. No event emitted.
+     *     (Opt-in semantics. Agents without a registered adapter are unaffected.)
+     *   - Adapter reports hasWork: true: returns { allowed: true, workCount }.
+     *     Increments the actualLlmCalls counter for consistency tracking.
+     *   - Adapter reports hasWork: false: throws EmptyQueueSkipApiError.
+     *     Caller catches and skips the LLM call. recordSkippedCall() is called
+     *     internally to emit the audit event and update counters.
+     *   - Adapter throws: rethrows. Gate fails closed. NOT silently skipped or
+     *     silently allowed -- both silent paths are dangerous.
+     *   - Adapter does not resolve within adapterTimeoutMs: throws
+     *     QueueAdapterTimeoutError. Fails closed. (PT-SKIP-API-2)
+     *
+     * @param orgId     Tenant / organization ID.
+     * @param agentId   Agent identifier.
+     */
+    async guardPreCall(orgId, agentId) {
+        const key = this.key(orgId, agentId);
+        const state = this.agents.get(key);
+        // Not configured: no-op pass-through (opt-in semantics).
+        if (!state) {
+            return { allowed: true };
+        }
+        // Call adapter with timeout. (PT-SKIP-API-2)
+        let peekResult;
+        try {
+            peekResult = await this.peekWithTimeout(state.adapter, state.adapterTimeoutMs, orgId, agentId, state.packBinding);
+        }
+        catch (err) {
+            // Rethrow. Fail closed. Do NOT swallow adapter errors.
+            throw err;
+        }
+        if (!peekResult.hasWork) {
+            // Empty queue: skip the LLM call.
+            await this.recordSkippedCallInternal(state, orgId, agentId, 'queue-empty', peekResult);
+            throw new EmptyQueueSkipApiError({
+                orgId,
+                agentId,
+                packBinding: state.packBinding,
+            });
+        }
+        // Queue has work: allow. Track for consistency (PT-SKIP-API-1).
+        state.peeksClaimingWork += 1;
+        state.actualLlmCalls += 1;
+        return { allowed: true, workCount: peekResult.workCount };
+    }
+    /**
+     * Emit an audit record for a manually recorded skip.
+     *
+     * Operators may call this when they skip an LLM call outside the
+     * guardPreCall() path (e.g., in a wrapper that catches EmptyQueueSkipApiError
+     * and wants to add extra context). guardPreCall() calls this internally.
+     *
+     * @param orgId       Tenant / organization ID.
+     * @param agentId     Agent identifier.
+     * @param reason      Human-readable reason string.
+     * @param packBinding Non-empty compliance pack binding.
+     */
+    recordSkippedCall(orgId, agentId, reason, packBinding) {
+        if (!packBinding || packBinding.length === 0) {
+            throw new EmptyQueuePackBindingError('recordSkippedCall');
+        }
+        this.emit({
+            type: 'API_SKIPPED_EMPTY_QUEUE',
+            severity: 'NOTICE',
+            orgId,
+            agentId,
+            packBinding,
+            reason,
+        });
+    }
+    /**
+     * Return per-agent skip telemetry for operator dashboards.
+     *
+     * @param orgId     Tenant / organization ID.
+     * @param agentId   Agent identifier.
+     */
+    getStats(orgId, agentId) {
+        const key = this.key(orgId, agentId);
+        const state = this.agents.get(key);
+        if (!state) {
+            return {
+                skippedToday: 0,
+                skippedThisHour: 0,
+                lastSkipAt: null,
+                configured: false,
+            };
+        }
+        return {
+            skippedToday: state.skippedTotal,
+            skippedThisHour: this.resolveHourBucket(state),
+            lastSkipAt: state.lastSkipAt,
+            configured: true,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    key(orgId, agentId) {
+        return `${orgId}::${agentId}`;
+    }
+    currentHourBucket() {
+        return Math.floor(Date.now() / 3_600_000);
+    }
+    /**
+     * Resolve the skip count for the current hour bucket.
+     * Resets the bucket counter if we have moved to a new hour.
+     */
+    resolveHourBucket(state) {
+        const currentBucket = this.currentHourBucket();
+        if (state.hourBucketKey !== currentBucket) {
+            state.hourBucketKey = currentBucket;
+            state.skippedHourBucket = 0;
+        }
+        return state.skippedHourBucket;
+    }
+    /**
+     * Execute peek() with a timeout. (PT-SKIP-API-2)
+     * Fails closed: timeout throws QueueAdapterTimeoutError (not "skip" or "allow").
+     */
+    peekWithTimeout(adapter, timeoutMs, orgId, agentId, packBinding) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new QueueAdapterTimeoutError({ orgId, agentId, timeoutMs, packBinding }));
+            }, timeoutMs);
+            adapter.peek().then((result) => {
+                clearTimeout(timer);
+                resolve(result);
+            }, (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Internal skip recording. Updates counters and emits the audit event.
+     * Also runs the PT-SKIP-API-1 consistency check.
+     */
+    recordSkippedCallInternal(state, orgId, agentId, reason, peekResult) {
+        const currentBucket = this.currentHourBucket();
+        if (state.hourBucketKey !== currentBucket) {
+            state.hourBucketKey = currentBucket;
+            state.skippedHourBucket = 0;
+        }
+        state.skippedTotal += 1;
+        state.skippedHourBucket += 1;
+        state.lastSkipAt = process.hrtime.bigint();
+        this.emit({
+            type: 'API_SKIPPED_EMPTY_QUEUE',
+            severity: 'NOTICE',
+            orgId,
+            agentId,
+            packBinding: state.packBinding,
+            reason,
+            workCount: peekResult.workCount,
+            oldestPendingMs: peekResult.oldestPendingMs,
+            skippedTotal: state.skippedTotal,
+        });
+        // PT-SKIP-API-1: consistency check.
+        // A compromised adapter that always returns hasWork:true would never
+        // trigger this code path (since this runs only on hasWork:false).
+        // The check fires when a skip DOES occur but peeksClaimingWork is wildly
+        // high relative to actualLlmCalls, suggesting prior peek inflation.
+        this.checkPeekConsistency(state, orgId, agentId);
+    }
+    /**
+     * PT-SKIP-API-1: detect adapter peek inflation.
+     *
+     * If the ratio of peeks claiming work to actual LLM calls diverges beyond
+     * INCONSISTENCY_THRESHOLD (default 5x), the adapter may be compromised --
+     * always reporting hasWork:true to keep the gate open while the agent is
+     * actually calling the LLM far less frequently.
+     *
+     * This is a probabilistic signal, not a hard gate. A QUEUE_PEEK_INCONSISTENT
+     * warning is emitted for operator review.
+     *
+     * Minimum sample size: INCONSISTENCY_MIN_SAMPLES (default 10). Avoids
+     * false positives on low-volume or newly started agents.
+     */
+    checkPeekConsistency(state, orgId, agentId) {
+        if (state.peeksClaimingWork < exports.INCONSISTENCY_MIN_SAMPLES)
+            return;
+        if (state.actualLlmCalls === 0)
+            return;
+        const ratio = state.peeksClaimingWork / state.actualLlmCalls;
+        if (ratio > exports.INCONSISTENCY_THRESHOLD) {
+            this.emit({
+                type: 'QUEUE_PEEK_INCONSISTENT',
+                severity: 'WARNING',
+                orgId,
+                agentId,
+                packBinding: state.packBinding,
+                peeksClaimingWork: state.peeksClaimingWork,
+                actualLlmCalls: state.actualLlmCalls,
+                ratio,
+                threshold: exports.INCONSISTENCY_THRESHOLD,
+                detail: 'Adapter peeks claiming hasWork:true significantly exceed actual LLM calls. ' +
+                    'Possible compromised adapter always returning hasWork:true to keep the gate open. ' +
+                    'Review adapter implementation. (PT-SKIP-API-1)',
+            });
+        }
+    }
+    /**
+     * Determine if the given identity is an agent-runtime identity.
+     * Heuristic: agent-runtime IDs are prefixed with 'agent:' or 'runtime:'.
+     * In production, wire to OperatorRoles for a hard check.
+     */
+    isAgentRuntimeIdentity(identity) {
+        return identity.startsWith('agent:') || identity.startsWith('runtime:');
+    }
+    /**
+     * Emit an audit event with SHA-256 chaining.
+     * Swallows errors from the onAudit callback to avoid breaking the enforcement path.
+     */
+    emit(fields) {
+        const payload = {
+            ...fields,
+            timestamp: new Date().toISOString(),
+            prevSha: this.lastSha,
+        };
+        const entryStr = JSON.stringify(payload);
+        const sha = crypto.createHash('sha256').update(entryStr).digest('hex');
+        this.lastSha = sha;
+        try {
+            this.onAudit(payload);
+        }
+        catch {
+            // Swallow -- enforcement path must not fail due to audit callback errors.
+        }
+    }
+}
+exports.SkipApiEmptyQueueEnforcer = SkipApiEmptyQueueEnforcer;
+//# sourceMappingURL=skip-api-empty-queue.js.map

package/dist/governance/skip-api-empty-queue.js.map

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

package/dist/governance/state-manager.d.ts

@@ -0,0 +1,102 @@
+/**
+ * StateManager -- Centralized governance state coordination.
+ *
+ * Provides a single source of truth for governance state across
+ * all modules. Prevents duplicate initialization, manages module
+ * lifecycle, and coordinates shared resources.
+ *
+ * T-024: Shared state manager to prevent fragmented governance state.
+ *
+ * @connexum/ai-governance
+ */
+export interface StateManagerConfig {
+    /** Base directory for all governance state */
+    stateDir: string;
+    /** Unique agent identifier */
+    agentId: string;
+    /** Enable state file locking (default: true) */
+    useLocking?: boolean;
+    /** State save interval in ms (default: 30000) */
+    saveIntervalMs?: number;
+}
+export interface ModuleState {
+    name: string;
+    initialized: boolean;
+    lastActivity: string;
+    data: Record<string, unknown>;
+}
+export interface GovernanceSnapshot {
+    agentId: string;
+    version: number;
+    modules: Record<string, ModuleState>;
+    createdAt: string;
+    updatedAt: string;
+    checksum: string;
+}
+export declare class StateManager {
+    private config;
+    private modules;
+    private version;
+    private stateFile;
+    private lockFile;
+    private saveTimer;
+    private dirty;
+    constructor(config: StateManagerConfig);
+    /**
+     * Register a governance module.
+     */
+    registerModule(name: string, initialData?: Record<string, unknown>): void;
+    /**
+     * Update module state data.
+     */
+    updateModule(name: string, data: Record<string, unknown>): void;
+    /**
+     * Get module state.
+     */
+    getModule(name: string): ModuleState | undefined;
+    /**
+     * Get data from a specific module.
+     */
+    getModuleData<T = unknown>(name: string, key: string): T | undefined;
+    /**
+     * Check if a module is registered and initialized.
+     */
+    isModuleReady(name: string): boolean;
+    /**
+     * Deregister a module (cleanup).
+     */
+    deregisterModule(name: string): boolean;
+    /**
+     * Get a full snapshot of governance state.
+     */
+    getSnapshot(): GovernanceSnapshot;
+    /**
+     * Verify snapshot integrity.
+     */
+    verifySnapshot(snapshot: GovernanceSnapshot): boolean;
+    /**
+     * List all registered modules.
+     */
+    listModules(): string[];
+    /**
+     * Get module count.
+     */
+    getModuleCount(): number;
+    /**
+     * Save state to disk.
+     */
+    save(): void;
+    /**
+     * Start periodic auto-save.
+     */
+    startAutoSave(): void;
+    /**
+     * Stop auto-save and do a final save.
+     */
+    stop(): void;
+    private loadState;
+    private computeChecksum;
+    private acquireLock;
+    private releaseLock;
+}
+//# sourceMappingURL=state-manager.d.ts.map

package/dist/governance/state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../src/governance/state-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,KAAK,CAAkB;gBAEnB,MAAM,EAAE,kBAAkB;IAkBtC;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAkBzE;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAY/D;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIhD;;OAEG;IACH,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAMpE;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKpC;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IASvC;;OAEG;IACH,WAAW,IAAI,kBAAkB;IAmBjC;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO;IAMrD;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,IAAI,IAAI,IAAI;IAiBZ;;OAEG;IACH,aAAa,IAAI,IAAI;IAcrB;;OAEG;IACH,IAAI,IAAI,IAAI;IAaZ,OAAO,CAAC,SAAS;IAuBjB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,WAAW;CAOpB"}