@dsh-enhanced/assistant-policy 0.1.3

package/lib/ledger.js

@@ -0,0 +1,891 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { redactAuditValue } from './redaction.js';
+import { legacyApprovalIntentHash, openPolicyDatabase, PolicyDatabaseError } from './sqlite.js';
+export class PolicyLedgerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PolicyLedgerError';
+    }
+}
+/** Shared byte contract for Policy, Delivery, and channel approval rendering. */
+export const APPROVAL_DISPLAY_BUDGET = Object.freeze({
+    maxTextBytes: 64 * 1_024,
+    maxSummaryBytes: 120,
+    renderingReserveBytes: 4 * 1_024,
+    maxDiffBytes: 60 * 1_024,
+});
+const textLimits = Object.freeze({
+    id: 512,
+    action: 256,
+    resourceId: 4_096,
+    workspace: 4_096,
+    summary: APPROVAL_DISPLAY_BUDGET.maxSummaryBytes,
+    diff: APPROVAL_DISPLAY_BUDGET.maxDiffBytes,
+    reason: 2_048,
+});
+function requireText(value, field) {
+    if (value.trim() === '')
+        throw new PolicyLedgerError('invalid-input', `${field} must not be empty`);
+}
+function requireBoundedText(value, field, maxBytes, options = {}) {
+    if (!options.allowEmpty)
+        requireText(value, field);
+    if (Buffer.byteLength(value, 'utf8') > maxBytes) {
+        throw new PolicyLedgerError('invalid-input', `${field} must not exceed ${maxBytes} UTF-8 bytes`);
+    }
+}
+function dispatchPayloadHash(input) {
+    const canonicalPayload = JSON.stringify([
+        input.proposalId,
+        input.route.sourceId,
+        input.route.bindingId,
+        input.route.workspace,
+        input.route.principal,
+        input.requester,
+        input.action,
+        input.resourceKind,
+        input.resourceId,
+        input.summary,
+        input.diff,
+        input.diffHash,
+        input.expiresAt,
+        input.proposalVersion,
+    ]);
+    return createHash('sha256').update(canonicalPayload).digest('hex');
+}
+/**
+ * Canonical identity of an abandoned recovery attempt. The raw diff participates
+ * in the digest but is never persisted in a tombstone.
+ */
+function approvalRecoveryIntentHash(input) {
+    const dispatch = input.dispatch;
+    const canonicalIntent = JSON.stringify([
+        'approval-recovery-intent-v1',
+        input.idempotencyKey,
+        input.notAfter,
+        input.requester,
+        input.principal,
+        input.action,
+        input.resource.kind,
+        input.resource.id,
+        input.diff,
+        input.summary,
+        dispatch === undefined ? 0 : 1,
+        dispatch?.sourceId ?? null,
+        dispatch?.bindingId ?? null,
+        dispatch?.workspace ?? null,
+        dispatch?.principal ?? null,
+    ]);
+    return createHash('sha256').update(canonicalIntent).digest('hex');
+}
+function requirePositive(value, field) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new PolicyLedgerError('invalid-input', `${field} must be a positive finite number`);
+    }
+}
+function requirePeriod(value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new PolicyLedgerError('invalid-input', 'periodMs must be a positive safe integer');
+    }
+}
+export class PolicyLedger {
+    #database;
+    #now;
+    #closed = false;
+    constructor(options) {
+        this.#now = options.now ?? Date.now;
+        try {
+            this.#database = openPolicyDatabase(options.path);
+        }
+        catch (error) {
+            if (error instanceof PolicyDatabaseError) {
+                throw new PolicyLedgerError(error.code, error.message);
+            }
+            throw error;
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#database.close();
+    }
+    #transaction(operation) {
+        this.#database.exec('BEGIN IMMEDIATE');
+        try {
+            const value = operation();
+            this.#database.exec('COMMIT');
+            return value;
+        }
+        catch (error) {
+            this.#database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    #period(row) {
+        const period = this.#database.prepare(`
+      SELECT limit_amount, reserved_amount, spent_amount
+      FROM budget_periods
+      WHERE scope = ? AND metric = ? AND period_start = ? AND period_ms = ?
+    `).get(row.scope, row.metric, row.period_start, row.period_ms);
+        if (period === undefined)
+            throw new PolicyLedgerError('invalid-state', 'reservation budget period is missing');
+        return period;
+    }
+    #result(row, replayed) {
+        const period = this.#period(row);
+        return {
+            reservationId: row.id,
+            status: row.status,
+            periodStart: row.period_start,
+            remaining: period.limit_amount - period.reserved_amount - period.spent_amount,
+            replayed,
+        };
+    }
+    reserve(input) {
+        requireText(input.scope, 'scope');
+        requireText(input.metric, 'metric');
+        requireText(input.idempotencyKey, 'idempotencyKey');
+        requirePositive(input.limit, 'limit');
+        requirePositive(input.amount, 'amount');
+        requirePeriod(input.periodMs);
+        const now = this.#now();
+        const periodStart = Math.floor(now / input.periodMs) * input.periodMs;
+        return this.#transaction(() => {
+            const existing = this.#database.prepare(`
+        SELECT id, idempotency_key, scope, metric, period_start, period_ms,
+               amount, actual_amount, status
+        FROM budget_reservations WHERE idempotency_key = ?
+      `).get(input.idempotencyKey);
+            if (existing !== undefined) {
+                const sameInput = existing.scope === input.scope
+                    && existing.metric === input.metric
+                    && existing.period_ms === input.periodMs
+                    && existing.amount === input.amount;
+                if (!sameInput) {
+                    throw new PolicyLedgerError('idempotency-conflict', 'idempotency key was used for another reservation');
+                }
+                return this.#result(existing, true);
+            }
+            this.#database.prepare(`
+        INSERT INTO budget_periods(
+          scope, metric, period_start, period_ms, limit_amount, reserved_amount, spent_amount
+        ) VALUES (?, ?, ?, ?, ?, 0, 0)
+        ON CONFLICT(scope, metric, period_start, period_ms) DO NOTHING
+      `).run(input.scope, input.metric, periodStart, input.periodMs, input.limit);
+            const period = this.#database.prepare(`
+        SELECT limit_amount, reserved_amount, spent_amount
+        FROM budget_periods
+        WHERE scope = ? AND metric = ? AND period_start = ? AND period_ms = ?
+      `).get(input.scope, input.metric, periodStart, input.periodMs);
+            if (period.limit_amount !== input.limit) {
+                throw new PolicyLedgerError('idempotency-conflict', 'budget limit changed within an active period');
+            }
+            if (period.reserved_amount + period.spent_amount + input.amount > period.limit_amount) {
+                throw new PolicyLedgerError('budget-exhausted', 'hard budget is exhausted');
+            }
+            const id = randomUUID();
+            this.#database.prepare(`
+        INSERT INTO budget_reservations(
+          id, idempotency_key, scope, metric, period_start, period_ms,
+          amount, actual_amount, status, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, NULL, 'reserved', ?, ?)
+      `).run(id, input.idempotencyKey, input.scope, input.metric, periodStart, input.periodMs, input.amount, now, now);
+            this.#database.prepare(`
+        UPDATE budget_periods
+        SET reserved_amount = reserved_amount + ?, version = version + 1
+        WHERE scope = ? AND metric = ? AND period_start = ? AND period_ms = ?
+      `).run(input.amount, input.scope, input.metric, periodStart, input.periodMs);
+            return this.#result({
+                id,
+                idempotency_key: input.idempotencyKey,
+                scope: input.scope,
+                metric: input.metric,
+                period_start: periodStart,
+                period_ms: input.periodMs,
+                amount: input.amount,
+                actual_amount: null,
+                status: 'reserved',
+            }, false);
+        });
+    }
+    finalize(reservationId, actualAmount) {
+        requireText(reservationId, 'reservationId');
+        if (!Number.isFinite(actualAmount) || actualAmount < 0) {
+            throw new PolicyLedgerError('invalid-input', 'actualAmount must be a non-negative finite number');
+        }
+        return this.#transaction(() => {
+            const row = this.#reservation(reservationId);
+            if (row.status === 'finalized') {
+                if (row.actual_amount !== actualAmount) {
+                    throw new PolicyLedgerError('idempotency-conflict', 'reservation was finalized with another amount');
+                }
+                return this.#result(row, true);
+            }
+            if (row.status !== 'reserved') {
+                throw new PolicyLedgerError('invalid-state', `cannot finalize a ${row.status} reservation`);
+            }
+            if (actualAmount > row.amount) {
+                throw new PolicyLedgerError('invalid-input', 'actualAmount cannot exceed the reserved amount');
+            }
+            this.#database.prepare(`
+        UPDATE budget_periods
+        SET reserved_amount = reserved_amount - ?, spent_amount = spent_amount + ?, version = version + 1
+        WHERE scope = ? AND metric = ? AND period_start = ? AND period_ms = ?
+      `).run(row.amount, actualAmount, row.scope, row.metric, row.period_start, row.period_ms);
+            this.#database.prepare(`
+        UPDATE budget_reservations
+        SET status = 'finalized', actual_amount = ?, updated_at = ?, version = version + 1
+        WHERE id = ?
+      `).run(actualAmount, this.#now(), row.id);
+            return this.#result({ ...row, status: 'finalized', actual_amount: actualAmount }, false);
+        });
+    }
+    release(reservationId) {
+        requireText(reservationId, 'reservationId');
+        return this.#transaction(() => {
+            const row = this.#reservation(reservationId);
+            if (row.status === 'released')
+                return this.#result(row, true);
+            if (row.status !== 'reserved') {
+                throw new PolicyLedgerError('invalid-state', `cannot release a ${row.status} reservation`);
+            }
+            this.#database.prepare(`
+        UPDATE budget_periods
+        SET reserved_amount = reserved_amount - ?, version = version + 1
+        WHERE scope = ? AND metric = ? AND period_start = ? AND period_ms = ?
+      `).run(row.amount, row.scope, row.metric, row.period_start, row.period_ms);
+            this.#database.prepare(`
+        UPDATE budget_reservations
+        SET status = 'released', updated_at = ?, version = version + 1
+        WHERE id = ?
+      `).run(this.#now(), row.id);
+            return this.#result({ ...row, status: 'released' }, false);
+        });
+    }
+    #reservation(id) {
+        const row = this.#database.prepare(`
+      SELECT id, idempotency_key, scope, metric, period_start, period_ms,
+             amount, actual_amount, status
+      FROM budget_reservations WHERE id = ?
+    `).get(id);
+        if (row === undefined)
+            throw new PolicyLedgerError('not-found', 'budget reservation was not found');
+        return row;
+    }
+    getEmergencyStop() {
+        const row = this.#database.prepare(`
+      SELECT enabled, reason, actor, updated_at, version FROM emergency_state WHERE singleton = 1
+    `).get();
+        if (row === undefined) {
+            return { enabled: false, reason: undefined, actor: undefined, updatedAt: undefined, version: 0 };
+        }
+        return {
+            enabled: row.enabled === 1,
+            reason: row.reason,
+            actor: row.actor,
+            updatedAt: row.updated_at,
+            version: row.version,
+        };
+    }
+    setEmergencyStop(input) {
+        requireText(input.actor, 'actor');
+        requireText(input.reason, 'reason');
+        const now = this.#now();
+        this.#transaction(() => {
+            this.#database.prepare(`
+        INSERT INTO emergency_state(singleton, enabled, reason, actor, updated_at, version)
+        VALUES (1, ?, ?, ?, ?, 1)
+        ON CONFLICT(singleton) DO UPDATE SET
+          enabled = excluded.enabled,
+          reason = excluded.reason,
+          actor = excluded.actor,
+          updated_at = excluded.updated_at,
+          version = emergency_state.version + 1
+      `).run(input.enabled ? 1 : 0, input.reason, input.actor, now);
+        });
+        return this.getEmergencyStop();
+    }
+    #validateProposalContent(input) {
+        requireBoundedText(input.idempotencyKey, 'idempotencyKey', textLimits.id);
+        requireBoundedText(input.requester, 'requester', textLimits.id);
+        requireBoundedText(input.principal, 'principal', textLimits.id);
+        requireBoundedText(input.action, 'action', textLimits.action);
+        requireBoundedText(input.resource.kind, 'resource.kind', textLimits.action);
+        requireBoundedText(input.resource.id, 'resource.id', textLimits.resourceId);
+        requireBoundedText(input.summary, 'summary', textLimits.summary);
+        requireBoundedText(input.diff, 'diff', textLimits.diff, { allowEmpty: true });
+        if (input.dispatch !== undefined) {
+            requireBoundedText(input.dispatch.sourceId, 'dispatch.sourceId', textLimits.id);
+            requireBoundedText(input.dispatch.bindingId, 'dispatch.bindingId', textLimits.id);
+            requireBoundedText(input.dispatch.workspace, 'dispatch.workspace', textLimits.workspace);
+            requireBoundedText(input.dispatch.principal, 'dispatch.principal', textLimits.id);
+            if (!isAbsolute(input.dispatch.workspace)) {
+                throw new PolicyLedgerError('invalid-path', 'dispatch.workspace must be absolute');
+            }
+            if (input.dispatch.principal !== input.principal) {
+                throw new PolicyLedgerError('unauthorized', 'dispatch route is bound to another principal');
+            }
+        }
+        return createHash('sha256').update(input.diff).digest('hex');
+    }
+    #proposalByIdempotencyKey(idempotencyKey) {
+        return this.#database.prepare(`
+      SELECT id, idempotency_key, requester, principal, action, resource_kind,
+             resource_id, diff_hash, diff_text, summary, status, created_at, expires_at, decided_by,
+             decision_reason, version
+      FROM approval_proposals WHERE idempotency_key = ?
+    `).get(idempotencyKey);
+    }
+    #assertExistingProposalMatches(existing, input, diffHash, expiryMatches) {
+        const existingDispatch = this.#database.prepare(`
+      SELECT source_id, binding_id, workspace, principal, state, payload_hash, proposal_version
+      FROM approval_dispatches WHERE proposal_id = ?
+    `).get(existing.id);
+        const sameDispatch = input.dispatch === undefined
+            ? existingDispatch === undefined
+            : existingDispatch !== undefined
+                && existingDispatch.source_id === input.dispatch.sourceId
+                && existingDispatch.binding_id === input.dispatch.bindingId
+                && existingDispatch.workspace === input.dispatch.workspace
+                && existingDispatch.principal === input.dispatch.principal;
+        const sameDiff = input.dispatch === undefined
+            ? existingDispatch === undefined && existing.diff_hash === diffHash
+            : existingDispatch !== undefined
+                && existing.diff_hash === diffHash
+                && (existing.diff_text === null || existing.diff_text === input.diff)
+                && existingDispatch.payload_hash === dispatchPayloadHash({
+                    proposalId: existing.id,
+                    route: input.dispatch,
+                    requester: input.requester,
+                    action: input.action,
+                    resourceKind: input.resource.kind,
+                    resourceId: input.resource.id,
+                    summary: input.summary,
+                    diff: input.diff,
+                    diffHash,
+                    expiresAt: existing.expires_at,
+                    proposalVersion: existingDispatch.proposal_version,
+                });
+        const sameInput = existing.requester === input.requester
+            && existing.principal === input.principal
+            && existing.action === input.action
+            && existing.resource_kind === input.resource.kind
+            && existing.resource_id === input.resource.id
+            && sameDiff
+            && existing.summary === input.summary
+            && expiryMatches
+            && sameDispatch;
+        if (!sameInput) {
+            throw new PolicyLedgerError('idempotency-conflict', 'idempotency key was used for another proposal');
+        }
+    }
+    #insertProposal(input, diffHash, createdAt, expiresAt) {
+        const id = randomUUID();
+        this.#database.prepare(`
+      INSERT INTO approval_proposals(
+        id, idempotency_key, requester, principal, action, resource_kind,
+        resource_id, diff_hash, diff_text, summary, status, created_at, expires_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)
+    `).run(id, input.idempotencyKey, input.requester, input.principal, input.action, input.resource.kind, input.resource.id, diffHash, input.dispatch === undefined ? null : input.diff, input.summary, createdAt, expiresAt);
+        if (input.dispatch !== undefined) {
+            const payloadHash = dispatchPayloadHash({
+                proposalId: id,
+                route: input.dispatch,
+                requester: input.requester,
+                action: input.action,
+                resourceKind: input.resource.kind,
+                resourceId: input.resource.id,
+                summary: input.summary,
+                diff: input.diff,
+                diffHash,
+                expiresAt,
+                proposalVersion: 1,
+            });
+            this.#database.prepare(`
+        INSERT INTO approval_dispatches(
+          proposal_id, source_id, binding_id, workspace, principal,
+          state, payload_hash, created_at, proposal_version
+        ) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?, 1)
+      `).run(id, input.dispatch.sourceId, input.dispatch.bindingId, input.dispatch.workspace, input.dispatch.principal, payloadHash, createdAt);
+        }
+        return {
+            proposalId: id,
+            status: 'pending',
+            diffHash,
+            expiresAt,
+            version: 1,
+            replayed: false,
+        };
+    }
+    propose(input) {
+        const diffHash = this.#validateProposalContent(input);
+        requirePeriod(input.ttlMs);
+        const now = this.#now();
+        const expiresAt = now + input.ttlMs;
+        if (!Number.isSafeInteger(expiresAt)) {
+            throw new PolicyLedgerError('invalid-input', 'proposal expiry exceeds the safe timestamp range');
+        }
+        return this.#transaction(() => {
+            const tombstone = this.#database.prepare(`
+        SELECT idempotency_key FROM approval_idempotency_tombstones WHERE idempotency_key = ?
+      `).get(input.idempotencyKey);
+            if (tombstone !== undefined) {
+                throw new PolicyLedgerError('idempotency-conflict', 'proposal idempotency key was permanently abandoned');
+            }
+            const existing = this.#proposalByIdempotencyKey(input.idempotencyKey);
+            if (existing !== undefined) {
+                this.#assertExistingProposalMatches(existing, input, diffHash, existing.expires_at - existing.created_at === input.ttlMs);
+                return this.#proposalResult(existing, true);
+            }
+            return this.#insertProposal(input, diffHash, now, expiresAt);
+        });
+    }
+    /**
+     * Atomically recover an existing exact proposal, create it under an immutable
+     * absolute deadline, or permanently abandon the idempotency key after that
+     * deadline. `BEGIN IMMEDIATE` serializes this decision across Policy processes,
+     * closing the lookup-then-create orphan-card race.
+     */
+    recoverOrCreateProposal(input) {
+        const diffHash = this.#validateProposalContent(input);
+        if (!Number.isSafeInteger(input.notAfter) || input.notAfter < 0) {
+            throw new PolicyLedgerError('invalid-input', 'proposal notAfter must be a non-negative safe integer');
+        }
+        const intentHash = approvalRecoveryIntentHash(input);
+        return this.#transaction(() => {
+            const existing = this.#proposalByIdempotencyKey(input.idempotencyKey);
+            if (existing !== undefined) {
+                this.#assertExistingProposalMatches(existing, input, diffHash, existing.expires_at === input.notAfter);
+                return Object.freeze({
+                    kind: 'proposal',
+                    proposal: this.#proposalResult(existing, true),
+                });
+            }
+            const tombstone = this.#database.prepare(`
+        SELECT idempotency_key, not_after, abandoned_at, intent_hash
+        FROM approval_idempotency_tombstones WHERE idempotency_key = ?
+      `).get(input.idempotencyKey);
+            if (tombstone !== undefined) {
+                if (tombstone.intent_hash === legacyApprovalIntentHash || tombstone.intent_hash !== intentHash) {
+                    throw new PolicyLedgerError('idempotency-conflict', 'idempotency key was abandoned for another or unverifiable proposal intent');
+                }
+                return Object.freeze({
+                    kind: 'abandoned',
+                    idempotencyKey: tombstone.idempotency_key,
+                    notAfter: tombstone.not_after,
+                    abandonedAt: tombstone.abandoned_at,
+                    replayed: true,
+                });
+            }
+            // Sample only after BEGIN IMMEDIATE has acquired the write lock. A value
+            // read before lock acquisition could become stale while another Policy
+            // process holds the transaction across the absolute deadline.
+            const now = this.#now();
+            if (now >= input.notAfter) {
+                this.#database.prepare(`
+          INSERT INTO approval_idempotency_tombstones(
+            idempotency_key, not_after, abandoned_at, intent_hash
+          ) VALUES (?, ?, ?, ?)
+        `).run(input.idempotencyKey, input.notAfter, now, intentHash);
+                return Object.freeze({
+                    kind: 'abandoned',
+                    idempotencyKey: input.idempotencyKey,
+                    notAfter: input.notAfter,
+                    abandonedAt: now,
+                    replayed: false,
+                });
+            }
+            return Object.freeze({
+                kind: 'proposal',
+                proposal: this.#insertProposal(input, diffHash, now, input.notAfter),
+            });
+        });
+    }
+    decideProposal(input) {
+        requireBoundedText(input.proposalId, 'proposalId', textLimits.id);
+        requireBoundedText(input.principal, 'principal', textLimits.id);
+        requireBoundedText(input.reason, 'reason', textLimits.reason);
+        if (!Number.isSafeInteger(input.expectedVersion) || input.expectedVersion <= 0) {
+            throw new PolicyLedgerError('invalid-input', 'expectedVersion must be a positive safe integer');
+        }
+        return this.#transaction(() => {
+            const proposal = this.#proposal(input.proposalId);
+            if (proposal.principal !== input.principal) {
+                throw new PolicyLedgerError('unauthorized', 'proposal is bound to another principal');
+            }
+            if (proposal.status === input.decision) {
+                if (proposal.decided_by !== input.principal || proposal.decision_reason !== input.reason) {
+                    throw new PolicyLedgerError('idempotency-conflict', 'proposal already has a different decision');
+                }
+                return this.#proposalResult(proposal, true);
+            }
+            if (proposal.version !== input.expectedVersion) {
+                throw new PolicyLedgerError('version-conflict', 'proposal version changed');
+            }
+            if (proposal.status !== 'pending') {
+                throw new PolicyLedgerError('invalid-state', `proposal is already ${proposal.status}`);
+            }
+            const now = this.#now();
+            const status = now >= proposal.expires_at ? 'expired' : input.decision;
+            const decidedBy = status === 'expired' ? 'system:expiry' : input.principal;
+            const decisionReason = status === 'expired' ? 'expired' : input.reason;
+            this.#database.prepare(`
+        UPDATE approval_proposals
+        SET status = ?, decided_at = ?, decided_by = ?, decision_reason = ?,
+            diff_text = NULL, version = version + 1
+        WHERE id = ? AND version = ?
+      `).run(status, now, decidedBy, decisionReason, proposal.id, proposal.version);
+            return this.#proposalResult({
+                ...proposal,
+                status,
+                decided_by: decidedBy,
+                decision_reason: decisionReason,
+                version: proposal.version + 1,
+            }, false);
+        });
+    }
+    /**
+     * Read one proposal's current status without deciding it. A domain reconciler
+     * uses this to learn that its own pending operation was already approved or
+     * rejected elsewhere, then commits that outcome itself.
+     */
+    getProposal(proposalId) {
+        requireBoundedText(proposalId, 'proposalId', textLimits.id);
+        const row = this.#database.prepare(`
+      SELECT id, idempotency_key, requester, principal, action, resource_kind,
+             resource_id, diff_hash, diff_text, summary, status, created_at, expires_at, decided_by,
+             decision_reason, version
+      FROM approval_proposals WHERE id = ?
+    `).get(proposalId);
+        if (row === undefined)
+            return undefined;
+        return Object.freeze({
+            proposalId: row.id,
+            requester: row.requester,
+            principal: row.principal,
+            action: row.action,
+            resource: Object.freeze({ kind: row.resource_kind, id: row.resource_id }),
+            summary: row.summary,
+            status: row.status,
+            diffHash: row.diff_hash,
+            expiresAt: row.expires_at,
+            version: row.version,
+            decidedBy: row.decided_by ?? undefined,
+            decisionReason: row.decision_reason ?? undefined,
+        });
+    }
+    /**
+     * Recover an existing proposal by its immutable scoped idempotency identity.
+     * A mismatch is indistinguishable from absence; callers may subsequently try
+     * `propose`, whose normal idempotency conflict check remains fail-closed.
+     */
+    getProposalByIdempotencyKey(input) {
+        requireBoundedText(input.idempotencyKey, 'idempotencyKey', textLimits.id);
+        requireBoundedText(input.requester, 'requester', textLimits.id);
+        requireBoundedText(input.principal, 'principal', textLimits.id);
+        requireBoundedText(input.action, 'action', textLimits.action);
+        requireBoundedText(input.resource.kind, 'resource.kind', textLimits.action);
+        requireBoundedText(input.resource.id, 'resource.id', textLimits.resourceId);
+        const row = this.#database.prepare(`
+      SELECT id, idempotency_key, requester, principal, action, resource_kind,
+             resource_id, diff_hash, diff_text, summary, status, created_at, expires_at, decided_by,
+             decision_reason, version
+      FROM approval_proposals
+      WHERE idempotency_key = ? AND requester = ? AND principal = ? AND action = ?
+        AND resource_kind = ? AND resource_id = ?
+    `).get(input.idempotencyKey, input.requester, input.principal, input.action, input.resource.kind, input.resource.id);
+        if (row === undefined)
+            return undefined;
+        return Object.freeze({
+            proposalId: row.id,
+            requester: row.requester,
+            principal: row.principal,
+            action: row.action,
+            resource: Object.freeze({ kind: row.resource_kind, id: row.resource_id }),
+            summary: row.summary,
+            status: row.status,
+            diffHash: row.diff_hash,
+            expiresAt: row.expires_at,
+            version: row.version,
+            decidedBy: row.decided_by ?? undefined,
+            decisionReason: row.decision_reason ?? undefined,
+        });
+    }
+    listPendingApprovalDispatches(limit = 100, after) {
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+            throw new PolicyLedgerError('invalid-input', 'approval dispatch limit must be between 1 and 100');
+        }
+        if (after !== undefined) {
+            if (after === null || typeof after !== 'object' || Array.isArray(after)
+                || Object.keys(after).length !== 2
+                || !Object.hasOwn(after, 'createdAt') || !Object.hasOwn(after, 'proposalId')
+                || !Number.isSafeInteger(after.createdAt) || after.createdAt < 0
+                || typeof after.proposalId !== 'string') {
+                throw new PolicyLedgerError('invalid-input', 'approval dispatch cursor is invalid');
+            }
+            requireBoundedText(after.proposalId, 'approval dispatch cursor proposalId', textLimits.id);
+        }
+        const cursorCreatedAt = after?.createdAt ?? null;
+        const cursorProposalId = after?.proposalId ?? '';
+        const rows = this.#database.prepare(`
+      SELECT d.proposal_id, d.source_id, d.binding_id, d.workspace,
+             d.principal AS dispatch_principal, d.state, d.payload_hash,
+             d.created_at AS dispatch_created_at, d.enqueued_at,
+             d.version AS dispatch_version, d.proposal_version, p.requester,
+             p.principal AS proposal_principal, p.action, p.resource_kind,
+             p.resource_id, p.diff_hash, p.diff_text, p.summary, p.status,
+             p.expires_at, p.version AS current_proposal_version
+      FROM approval_dispatches d
+      JOIN approval_proposals p ON p.id = d.proposal_id
+      WHERE d.state = 'pending' AND p.status = 'pending' AND p.expires_at > ?
+        AND (? IS NULL OR d.created_at > ? OR (d.created_at = ? AND d.proposal_id > ?))
+      ORDER BY d.created_at ASC, d.proposal_id ASC
+      LIMIT ?
+    `).all(this.#now(), cursorCreatedAt, cursorCreatedAt, cursorCreatedAt, cursorProposalId, limit);
+        return rows.map(row => this.#dispatchSnapshot(row));
+    }
+    markApprovalDispatchEnqueued(proposalId, expectedVersion) {
+        requireBoundedText(proposalId, 'proposalId', textLimits.id);
+        if (!Number.isSafeInteger(expectedVersion) || expectedVersion <= 0) {
+            throw new PolicyLedgerError('invalid-input', 'expectedVersion must be a positive safe integer');
+        }
+        return this.#transaction(() => {
+            const dispatch = this.#dispatch(proposalId);
+            if (dispatch.state === 'enqueued') {
+                return this.#dispatchResult(dispatch, true);
+            }
+            if (dispatch.dispatch_version !== expectedVersion) {
+                throw new PolicyLedgerError('version-conflict', 'approval dispatch version changed');
+            }
+            const now = this.#now();
+            if (dispatch.status !== 'pending' || dispatch.expires_at <= now) {
+                throw new PolicyLedgerError('invalid-state', 'approval proposal is no longer pending');
+            }
+            this.#dispatchSnapshot(dispatch);
+            const result = this.#database.prepare(`
+        UPDATE approval_dispatches
+        SET state = 'enqueued', enqueued_at = ?, version = version + 1
+        WHERE proposal_id = ? AND state = 'pending' AND version = ?
+      `).run(now, proposalId, expectedVersion);
+            if (Number(result.changes) !== 1) {
+                throw new PolicyLedgerError('version-conflict', 'approval dispatch version changed');
+            }
+            const cleared = this.#database.prepare(`
+        UPDATE approval_proposals SET diff_text = NULL
+        WHERE id = ? AND status = 'pending' AND version = ? AND diff_text IS NOT NULL
+      `).run(proposalId, dispatch.proposal_version);
+            if (Number(cleared.changes) !== 1) {
+                throw new PolicyLedgerError('invalid-state', 'approval dispatch diff could not be cleared');
+            }
+            return this.#dispatchResult({
+                ...dispatch,
+                state: 'enqueued',
+                enqueued_at: now,
+                dispatch_version: dispatch.dispatch_version + 1,
+                diff_text: null,
+            }, false);
+        });
+    }
+    expireProposals(limit = 100) {
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 1_000) {
+            throw new PolicyLedgerError('invalid-input', 'proposal expiry limit must be between 1 and 1000');
+        }
+        const now = this.#now();
+        return this.#transaction(() => {
+            const rows = this.#database.prepare(`
+        SELECT id FROM approval_proposals
+        WHERE status = 'pending' AND expires_at <= ?
+        ORDER BY expires_at ASC, id ASC
+        LIMIT ?
+      `).all(now, limit);
+            const expire = this.#database.prepare(`
+        UPDATE approval_proposals
+        SET status = 'expired', decided_at = ?, decided_by = 'system:expiry',
+            decision_reason = 'expired', diff_text = NULL, version = version + 1
+        WHERE id = ? AND status = 'pending'
+      `);
+            let changed = 0;
+            for (const row of rows)
+                changed += Number(expire.run(now, row.id).changes);
+            return changed;
+        });
+    }
+    #proposal(id) {
+        const proposal = this.#database.prepare(`
+      SELECT id, idempotency_key, requester, principal, action, resource_kind,
+             resource_id, diff_hash, diff_text, summary, status, created_at, expires_at, decided_by,
+             decision_reason, version
+      FROM approval_proposals WHERE id = ?
+    `).get(id);
+        if (proposal === undefined)
+            throw new PolicyLedgerError('not-found', 'approval proposal was not found');
+        return proposal;
+    }
+    #dispatch(proposalId) {
+        const dispatch = this.#database.prepare(`
+      SELECT d.proposal_id, d.source_id, d.binding_id, d.workspace,
+             d.principal AS dispatch_principal, d.state, d.payload_hash,
+             d.created_at AS dispatch_created_at, d.enqueued_at,
+             d.version AS dispatch_version, d.proposal_version, p.requester,
+             p.principal AS proposal_principal, p.action, p.resource_kind,
+             p.resource_id, p.diff_hash, p.diff_text, p.summary, p.status,
+             p.expires_at, p.version AS current_proposal_version
+      FROM approval_dispatches d
+      JOIN approval_proposals p ON p.id = d.proposal_id
+      WHERE d.proposal_id = ?
+    `).get(proposalId);
+        if (dispatch === undefined) {
+            throw new PolicyLedgerError('not-found', 'approval dispatch was not found');
+        }
+        return dispatch;
+    }
+    #dispatchSnapshot(row) {
+        if (row.diff_text === null) {
+            throw new PolicyLedgerError('invalid-state', 'approval dispatch is missing its immutable diff');
+        }
+        if (row.dispatch_principal !== row.proposal_principal) {
+            throw new PolicyLedgerError('invalid-state', 'approval dispatch principal does not match proposal');
+        }
+        if (row.current_proposal_version !== row.proposal_version) {
+            throw new PolicyLedgerError('invalid-state', 'approval dispatch proposal version changed');
+        }
+        const expectedPayloadHash = dispatchPayloadHash({
+            proposalId: row.proposal_id,
+            route: {
+                sourceId: row.source_id,
+                bindingId: row.binding_id,
+                workspace: row.workspace,
+                principal: row.dispatch_principal,
+            },
+            requester: row.requester,
+            action: row.action,
+            resourceKind: row.resource_kind,
+            resourceId: row.resource_id,
+            summary: row.summary,
+            diff: row.diff_text,
+            diffHash: row.diff_hash,
+            expiresAt: row.expires_at,
+            proposalVersion: row.proposal_version,
+        });
+        if (row.payload_hash !== expectedPayloadHash) {
+            throw new PolicyLedgerError('invalid-state', 'approval dispatch payload hash does not match proposal');
+        }
+        return Object.freeze({
+            proposalId: row.proposal_id,
+            sourceId: row.source_id,
+            bindingId: row.binding_id,
+            workspace: row.workspace,
+            principal: row.proposal_principal,
+            requester: row.requester,
+            action: row.action,
+            resource: Object.freeze({ kind: row.resource_kind, id: row.resource_id }),
+            summary: row.summary,
+            diff: row.diff_text,
+            diffHash: row.diff_hash,
+            payloadHash: row.payload_hash,
+            expiresAt: row.expires_at,
+            proposalVersion: row.proposal_version,
+            state: row.state,
+            createdAt: row.dispatch_created_at,
+            enqueuedAt: row.enqueued_at ?? undefined,
+            version: row.dispatch_version,
+        });
+    }
+    #dispatchResult(row, replayed) {
+        if (row.state !== 'enqueued' || row.enqueued_at === null) {
+            throw new PolicyLedgerError('invalid-state', 'approval dispatch is not enqueued');
+        }
+        return Object.freeze({
+            proposalId: row.proposal_id,
+            state: 'enqueued',
+            payloadHash: row.payload_hash,
+            enqueuedAt: row.enqueued_at,
+            version: row.dispatch_version,
+            replayed,
+        });
+    }
+    #proposalResult(proposal, replayed) {
+        return {
+            proposalId: proposal.id,
+            status: proposal.status,
+            diffHash: proposal.diff_hash,
+            expiresAt: proposal.expires_at,
+            version: proposal.version,
+            replayed,
+        };
+    }
+    appendAudit(input) {
+        requireText(input.actor, 'actor');
+        requireText(input.action, 'action');
+        requireText(input.resource.kind, 'resource.kind');
+        requireText(input.resource.id, 'resource.id');
+        requireText(input.outcome, 'outcome');
+        requireText(input.reasonCode, 'reasonCode');
+        const resourceHash = createHash('sha256').update(input.resource.id).digest('hex');
+        const details = redactAuditValue(input.details);
+        let detailsJson;
+        try {
+            detailsJson = JSON.stringify(details);
+        }
+        catch {
+            throw new PolicyLedgerError('invalid-input', 'audit details must be JSON serializable');
+        }
+        const eventId = randomUUID();
+        const occurredAt = this.#now();
+        const result = this.#database.prepare(`
+      INSERT INTO audit_events(
+        event_id, occurred_at, actor, action, resource_kind, resource_hash,
+        outcome, reason_code, details_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(eventId, occurredAt, input.actor, input.action, input.resource.kind, resourceHash, input.outcome, input.reasonCode, detailsJson);
+        return {
+            sequence: Number(result.lastInsertRowid),
+            eventId,
+            occurredAt,
+            actor: input.actor,
+            action: input.action,
+            resourceKind: input.resource.kind,
+            resourceHash,
+            outcome: input.outcome,
+            reasonCode: input.reasonCode,
+            details,
+        };
+    }
+    queryAudit(options = {}) {
+        const afterSequence = options.afterSequence ?? 0;
+        const limit = options.limit ?? 50;
+        if (!Number.isSafeInteger(afterSequence) || afterSequence < 0) {
+            throw new PolicyLedgerError('invalid-input', 'afterSequence must be a non-negative safe integer');
+        }
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+            throw new PolicyLedgerError('invalid-input', 'audit limit must be between 1 and 100');
+        }
+        const rows = this.#database.prepare(`
+      SELECT sequence, event_id, occurred_at, actor, action, resource_kind,
+             resource_hash, outcome, reason_code, details_json
+      FROM audit_events WHERE sequence > ? ORDER BY sequence ASC LIMIT ?
+    `).all(afterSequence, limit);
+        return rows.map(row => ({
+            sequence: row.sequence,
+            eventId: row.event_id,
+            occurredAt: row.occurred_at,
+            actor: row.actor,
+            action: row.action,
+            resourceKind: row.resource_kind,
+            resourceHash: row.resource_hash,
+            outcome: row.outcome,
+            reasonCode: row.reason_code,
+            details: JSON.parse(row.details_json),
+        }));
+    }
+    health() {
+        const row = this.#database.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM audit_events')
+            .get();
+        return { lastAuditSequence: row.sequence };
+    }
+}
+//# sourceMappingURL=ledger.js.map