@aiwg/cli 2026.9.20 → 2026.9.24

package/dist/src/decision/review/effect-ledger-adapter.js

@@ -0,0 +1,321 @@
+/**
+ * D13 adoption of the AIWG effect ledger (#2721, answers #2677).
+ *
+ * `LedgerReviewEffectJournal` implements `VerifiedReviewEffectLedger` (and the
+ * `ReviewEffectJournal` write port used by `journaledReviewExecutor`) over the
+ * signed effect ledger in `src/effects`. It keeps D13's effect identity exactly:
+ * the `d13.review/v1` derivation is `reviewDigest({reviewId, continuationId,
+ * proposalVersion})`, so reviews persisted before the ledger stay valid.
+ *
+ * Target systems remain the authorities. The ledger records a signed `intent`
+ * before the effect and `completed` only after the `decision.review.continuation`
+ * verifier reports `present`; `absent` and `unknown` never authorize a replay.
+ *
+ * @see docs/decision/review.md "Effect ledger"
+ * @see docs/contracts/effect-ledger.v1.md
+ */
+import { createHash, createPrivateKey, createPublicKey } from 'node:crypto';
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { publishExclusive } from '../../storage/protected-files.js';
+import { EffectLedger, createBuiltinVerifierRegistry, createVerifierRegistry, effectId as deriveEffectId, effectSha256Digest, evidenceDigest, isValidEffectId, lookupEffect, reconcileEffect, recordIntent, reviewContinuationTarget, } from '../../effects/index.js';
+import { readWriterSegment } from '../../effects/reader.js';
+import { assertReviewProjection, reviewDigest, reviewOperatorEventId } from './validate.js';
+export const REVIEW_EFFECT_KIND = 'decision.review.continuation';
+export const REVIEW_EFFECT_DERIVATION = 'd13.review/v1';
+/** `result` of a receipt rebuilt from ledger records when the receipt body was never archived. */
+export const REVIEW_EFFECT_REFERENCE_SCHEMA = 'aiwg.review-effect-reference/v1';
+const ARCHIVE_SCHEMA = 'aiwg.review-effect-receipt/v1';
+/** Version of the one-shot verifier that imports legacy HMAC receipts (`method: legacy-hmac`). */
+export const LEGACY_HMAC_IMPORT_VERIFIER_VERSION = '0.2.0';
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+const sha256Hex = (value) => createHash('sha256').update(value).digest('hex');
+const invalidEntry = () => new Error('Invalid executor ledger entry');
+/** The ledger intent (kind, target, context) for one review continuation. */
+export function reviewEffectIntent(identity) {
+    return {
+        kind: REVIEW_EFFECT_KIND,
+        target: reviewContinuationTarget(identity.tenantId, identity.projectId, identity.reviewId),
+        context: { reviewId: identity.reviewId, continuationId: identity.continuationId, proposalVersion: identity.proposalVersion },
+        derivation: REVIEW_EFFECT_DERIVATION,
+    };
+}
+/** The ledger effect ID for a review continuation; equal to D13's `reviewDigest` identity. */
+export function reviewEffectId(identity) {
+    const intent = reviewEffectIntent(identity);
+    return deriveEffectId({ scope: { tenant: identity.tenantId, project: identity.projectId, subsystem: 'review' },
+        kind: intent.kind, target: intent.target, context: intent.context }, REVIEW_EFFECT_DERIVATION);
+}
+/**
+ * #1567 links for a review continuation: the operator decision event of the
+ * approval of `proposalVersion` (its ID is `reviewOperatorEventId`), plus its
+ * audit `record_hash` when the caller has it. Empty when no approval exists.
+ */
+export function reviewApprovalLinks(review, proposalVersion, operatorDecisionRecordHash) {
+    const approval = [...review.events].reverse().find(event => event.type === 'approved' && event.proposalVersion === proposalVersion);
+    if (!approval)
+        return {};
+    return {
+        operatorDecisionEventId: approval.operatorDecisionEventId ?? reviewOperatorEventId(review.reviewId, approval.sequence),
+        ...(operatorDecisionRecordHash ? { operatorDecisionRecordHash } : {}),
+    };
+}
+/** Ed25519 key ID the first 32 bytes of `material` would produce as a ledger seed. */
+function seedKeyid(material) {
+    if (material.length < 32)
+        return null;
+    try {
+        const key = createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(material.subarray(0, 32))]), format: 'der', type: 'pkcs8' });
+        return effectSha256Digest(createPublicKey(key).export({ format: 'der', type: 'spki' }));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `VerifiedReviewEffectLedger` backed by the effect ledger. Scope: the ledger's
+ * `{tenant, project}` are the review's `{tenantId, projectId}`, subsystem `review`.
+ */
+export class LedgerReviewEffectJournal {
+    ledger;
+    options;
+    keysChecked = false;
+    constructor(ledger, options = {}) {
+        this.ledger = ledger;
+        this.options = options;
+        if (ledger.scope.subsystem !== 'review')
+            throw new Error('Review effect ledger must use the review subsystem');
+    }
+    inScope(query) {
+        return query.tenantId === this.ledger.scope.tenant && query.projectId === this.ledger.scope.project;
+    }
+    async assertIndependentKey() {
+        if (this.keysChecked)
+            return;
+        const { keyid } = await this.ledger.signingKey();
+        for (const material of this.options.independentOf ?? []) {
+            if (seedKeyid(material) === keyid)
+                throw new Error('Effect ledger key must be independent of review-store and session-index keys');
+        }
+        this.keysChecked = true;
+    }
+    archivePath(effectId) {
+        const directory = join(this.ledger.paths().root, 'receipts');
+        return { directory, file: join(directory, `${sha256Hex(effectId)}.json`) };
+    }
+    /** The verified intent identity behind a lookup; throws on any mismatch. */
+    async intentIdentity(lookup) {
+        const intent = lookup.records.find(record => record.phase === 'intent');
+        if (!intent)
+            throw invalidEntry();
+        const segment = await readWriterSegment(this.ledger.paths(), intent.writer);
+        const decoded = segment?.lines[intent.seq]?.decoded;
+        if (!decoded || decoded.line.recordHash !== intent.recordHash)
+            throw invalidEntry();
+        const predicate = decoded.statement.predicate;
+        const context = predicate.context ?? {};
+        const identity = {
+            tenantId: this.ledger.scope.tenant, projectId: this.ledger.scope.project, reviewId: context.reviewId,
+            continuationId: context.continuationId, proposalVersion: context.proposalVersion,
+        };
+        if (predicate.kind !== REVIEW_EFFECT_KIND || predicate.idDerivation !== REVIEW_EFFECT_DERIVATION
+            || predicate.effectId !== lookup.effectId || reviewEffectId(identity) !== lookup.effectId)
+            throw invalidEntry();
+        return identity;
+    }
+    async archived(effectId, completed, identity) {
+        let raw;
+        try {
+            raw = await readFile(this.archivePath(effectId).file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        try {
+            const value = JSON.parse(raw);
+            const receipt = value.receipt;
+            if (value.schema !== ARCHIVE_SCHEMA || value.effectId !== effectId || value.recordHash !== completed.recordHash
+                || evidenceDigest(value.evidence) !== completed.verification?.evidenceDigest
+                || value.evidence.expectedDigest !== reviewDigest(receipt)
+                || receipt.effectId !== effectId || receipt.continuationId !== identity.continuationId
+                || receipt.proposalVersion !== identity.proposalVersion
+                || !Number.isSafeInteger(receipt.completedAtEpochMs) || receipt.completedAtEpochMs < 0)
+                throw invalidEntry();
+            assertReviewProjection(receipt.result);
+            return structuredClone(receipt);
+        }
+        catch {
+            throw invalidEntry();
+        }
+    }
+    /** Receipt for a signed `completed` record; the archived body when present, else a digest reference. */
+    async completedReceipt(query) {
+        if (!this.inScope(query) || !isValidEffectId(query.effectId, REVIEW_EFFECT_DERIVATION))
+            return null;
+        const lookup = await lookupEffect(this.ledger, query.effectId);
+        const completed = lookup.records.find(record => record.phase === 'completed');
+        if (!completed)
+            return null;
+        const identity = await this.intentIdentity(lookup);
+        if (identity.reviewId !== query.reviewId)
+            return null;
+        const body = await this.archived(query.effectId, completed, identity);
+        if (body)
+            return body;
+        const completedAtEpochMs = Date.parse(completed.recordedAt);
+        if (!Number.isSafeInteger(completedAtEpochMs))
+            throw invalidEntry();
+        return {
+            effectId: query.effectId, continuationId: identity.continuationId, proposalVersion: identity.proposalVersion, completedAtEpochMs,
+            result: { effectLedger: { schema: REVIEW_EFFECT_REFERENCE_SCHEMA, recordHash: completed.recordHash, keyid: completed.keyid,
+                    evidenceDigest: completed.verification?.evidenceDigest ?? null } },
+        };
+    }
+    /** Append the signed intent before the effect. `pending`: an earlier intent has no outcome yet. */
+    async recordIntent(identity, actionDigest, links) {
+        if (!this.inScope(identity))
+            throw new Error('Invalid executor ledger scope');
+        await this.assertIndependentKey();
+        const intent = reviewEffectIntent(identity);
+        const receipt = await recordIntent(this.ledger, { ...intent, payloadDigest: actionDigest, ...(links ? { links } : {}) });
+        if (receipt.effectId !== reviewDigest({ reviewId: identity.reviewId, continuationId: identity.continuationId,
+            proposalVersion: identity.proposalVersion }))
+            throw invalidEntry();
+        return receipt.idempotent ? 'pending' : 'recorded';
+    }
+    /**
+     * Reconcile through the kind verifier; every call appends one signed
+     * `reconciled` record and `present` also records `completed`. With no intent
+     * the effect is `unknown` unless the caller supplies the identity and action
+     * digest, in which case the intent is recorded first (a crash before intent).
+     */
+    async reconcileReceipt(query, options = {}) {
+        const unknown = { result: 'unknown', receipt: null };
+        if (!this.inScope(query) || !isValidEffectId(query.effectId, REVIEW_EFFECT_DERIVATION))
+            return unknown;
+        const lookup = await lookupEffect(this.ledger, query.effectId);
+        if (!lookup.records.some(record => record.phase === 'intent')) {
+            if (!options.identity || !options.actionDigest)
+                return unknown;
+            const identity = { tenantId: query.tenantId, projectId: query.projectId, reviewId: query.reviewId, ...options.identity };
+            if (reviewEffectId(identity) !== query.effectId)
+                return unknown;
+            await this.recordIntent(identity, options.actionDigest);
+        }
+        else if ((await this.intentIdentity(lookup)).reviewId !== query.reviewId)
+            return unknown;
+        await this.assertIndependentKey();
+        const expectedDigest = options.receipt ? reviewDigest(options.receipt) : undefined;
+        const outcome = await reconcileEffect(this.ledger, query.effectId, {
+            verifiers: this.options.verifiers, timeoutMs: this.options.timeoutMs, expected: expectedDigest ? { digest: expectedDigest } : {},
+        });
+        const result = outcome.result.verification.result;
+        if (result !== 'present')
+            return { result, receipt: null };
+        if (options.receipt && outcome.completed && !outcome.completed.idempotent && outcome.evidence) {
+            assertReviewProjection(options.receipt.result);
+            const { directory, file } = this.archivePath(query.effectId);
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            const archived = { schema: ARCHIVE_SCHEMA, effectId: query.effectId, recordHash: outcome.completed.recordHash,
+                receipt: structuredClone(options.receipt), evidence: outcome.evidence };
+            await publishExclusive(directory, file, `${canonicalJson(archived)}\n`, 'receipt');
+        }
+        const receipt = await this.completedReceipt(query);
+        return receipt ? { result: 'present', receipt } : unknown;
+    }
+    /** Called by the executor after the effect: verify, then record `completed` only on `present`. */
+    async recordCompleted(query, receipt) {
+        if (receipt.effectId !== query.effectId)
+            throw new Error('Invalid executor completion receipt');
+        assertReviewProjection(receipt.result);
+        return (await this.reconcileReceipt(query, { receipt })).result === 'present';
+    }
+    /**
+     * Import receipts from the deprecated HMAC journal as `completed` records.
+     * Each is verified by a one-shot `legacy-hmac` verifier over the legacy
+     * journal (evidence `method: legacy-hmac`), and its body is archived so the
+     * same receipt is returned afterwards. Receipts already completed are skipped.
+     */
+    async importLegacyReceipts(legacy) {
+        let imported = 0;
+        let skipped = 0;
+        for (const { query, receipt } of await legacy.listReceipts()) {
+            if (!this.inScope(query) || await this.completedReceipt(query)) {
+                skipped += 1;
+                continue;
+            }
+            const identity = { tenantId: query.tenantId, projectId: query.projectId, reviewId: query.reviewId,
+                continuationId: receipt.continuationId, proposalVersion: receipt.proposalVersion };
+            if (reviewEffectId(identity) !== query.effectId) {
+                skipped += 1;
+                continue;
+            }
+            await this.recordIntent(identity, reviewDigest({ legacyReceipt: reviewDigest(receipt) }));
+            const importer = new LedgerReviewEffectJournal(this.ledger, {
+                ...this.options, verifiers: createVerifierRegistry([legacyHmacImportVerifier(legacy)]),
+            });
+            const settled = await importer.reconcileReceipt(query, { receipt });
+            if (settled.result === 'present')
+                imported += 1;
+            else
+                skipped += 1;
+        }
+        return { imported, skipped };
+    }
+}
+/** One-shot importer verifier: `present` only when the legacy HMAC journal holds the exact expected receipt. */
+function legacyHmacImportVerifier(legacy) {
+    return {
+        kind: REVIEW_EFFECT_KIND, version: LEGACY_HMAC_IMPORT_VERIFIER_VERSION, canReportAbsent: false,
+        async verify(request) {
+            const { reviewId } = request.context;
+            const expected = request.expected.digest ?? null;
+            const found = await legacy.completedReceipt({ tenantId: request.scope.tenant, projectId: request.scope.project,
+                reviewId: String(reviewId), effectId: request.effectId }).catch(() => null);
+            const actual = found ? reviewDigest(found) : null;
+            const evidence = { source: 'd13-legacy-journal', method: 'legacy-hmac', expectedDigest: expected, receiptDigest: actual };
+            return actual && actual === expected
+                ? { result: 'present', reason: 'digest-match', complete: true, evidence }
+                : { result: 'unknown', reason: 'evidence-conflict', complete: false, evidence };
+        },
+    };
+}
+/** Factory form of the ledger-backed `VerifiedReviewEffectLedger`. */
+export function ledgerVerifiedReviewEffectLedger(ledger, options = {}) {
+    return new LedgerReviewEffectJournal(ledger, options);
+}
+/** Production wiring: a `review` ledger with the built-in verifiers and the review-store verifier. */
+export function openReviewEffectLedger(options) {
+    const verifiers = createBuiltinVerifierRegistry({ review: { store: options.store, execution: options.execution } }, options.extensions ?? []);
+    const ledger = new EffectLedger({
+        projectDir: options.projectDir, scope: { tenant: options.tenantId, project: options.projectId, subsystem: 'review' },
+        writer: options.writer, keyProvider: options.keyProvider, verifiers, sink: options.sink, clock: options.clock,
+    });
+    return new LedgerReviewEffectJournal(ledger, { verifiers, independentOf: options.independentOf, timeoutMs: options.timeoutMs });
+}
+/**
+ * Production `reconcile(effectId)` for `DecisionReviewService.resume`. It
+ * returns a receipt only for a signed `completed` record or a `present`
+ * verifier result under the exact D13 identity; `absent` and `unknown` return
+ * `null`, so the stale continuation stays uncertain and is never replayed.
+ */
+export function ledgerReviewReconciler(input) {
+    return async (effectId) => {
+        if (effectId !== reviewDigest({ reviewId: input.reviewId, continuationId: input.continuationId, proposalVersion: input.proposalVersion }))
+            return null;
+        const query = { tenantId: input.scope.tenantId, projectId: input.scope.projectId, reviewId: input.reviewId, effectId };
+        const known = await input.journal.completedReceipt(query);
+        if (known)
+            return known.effectId === effectId ? known : null;
+        if (!input.journal.reconcileReceipt)
+            return null;
+        const settled = await input.journal.reconcileReceipt(query, {
+            identity: { continuationId: input.continuationId, proposalVersion: input.proposalVersion }, actionDigest: input.actionDigest,
+        });
+        return settled.result === 'present' && settled.receipt?.effectId === effectId ? settled.receipt : null;
+    };
+}
+//# sourceMappingURL=effect-ledger-adapter.js.map

package/dist/src/decision/review/index.js

@@ -0,0 +1,12 @@
+export * from './types.js';
+export * from './validate.js';
+export * from './store.js';
+export * from './service.js';
+export * from './migrate.js';
+export * from './recovery.js';
+export * from './recovery-adapters.js';
+export * from './effect-ledger-adapter.js';
+export * from './authorization.js';
+export * from './operator-audit.js';
+export { JsonlOperatorDecisionStore, verifyDecisionChain } from '../../audit/operator-decision.js';
+//# sourceMappingURL=index.js.map

package/dist/src/decision/review/migrate.js

@@ -0,0 +1,34 @@
+import { reviewDigest } from './validate.js';
+/** Explicit opt-in bridge; receiving a review result never creates durable state. */
+export function durableReviewInputFromRuleset(result, options) {
+    if (!options.enabled)
+        return null;
+    if (result.spec.status !== 'review')
+        throw new Error('Only a review RulesetResult may enter durable review');
+    if (result.spec.outcome === undefined)
+        throw new Error('Durable review requires a proposed outcome');
+    if (!options.reviewId || !options.continuationId || !options.resumeToken || !options.rationale
+        || !options.riskTier || !options.reasonCodes.length) {
+        throw new Error('Durable review migration requires explicit identity, rationale, risk, reason, and continuation data');
+    }
+    const evidencePins = Object.values(result.spec.evaluations)
+        .map(evaluation => evaluation.spec.decision)
+        .sort((left, right) => left.id.localeCompare(right.id) || left.version.localeCompare(right.version));
+    return {
+        reviewId: options.reviewId,
+        sourceReceipt: { id: result.spec.invocationId, digest: reviewDigest(result) },
+        evidencePins,
+        policyPins: [result.spec.ruleset, result.spec.binding],
+        reasonCodes: [...options.reasonCodes],
+        riskTier: options.riskTier,
+        presentation: structuredClone(options.presentation ?? {}),
+        action: structuredClone(result.spec.outcome),
+        rationale: options.rationale,
+        expiresAtEpochMs: options.expiresAtEpochMs,
+        ...(options.escalationAtEpochMs === undefined ? {} : { escalationAtEpochMs: options.escalationAtEpochMs }),
+        ...(options.quorum === undefined ? {} : { quorum: options.quorum }),
+        continuationId: options.continuationId,
+        resumeToken: options.resumeToken,
+    };
+}
+//# sourceMappingURL=migrate.js.map

package/dist/src/decision/review/operator-audit.js

@@ -0,0 +1,59 @@
+import { digestDecisionContext, verifyDecisionChain, } from '../../audit/operator-decision.js';
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { ReviewIntegrityError, reviewOperatorEventId, validateReview } from './validate.js';
+/** #1567 record mapping: review event ID is the operator audit event ID, not a parallel identity. */
+export function reviewOperatorDecisionInput(review, event, correlation, classification) {
+    const outcome = { approved: ['approval', 'approved'], rejected: ['denial', 'denied'],
+        escalated: ['escalation', 'escalated'], 'authorization-denied': ['denial', 'denied'] }[event.type];
+    if (!outcome)
+        return null;
+    if (event.operatorDecisionEventId && event.operatorDecisionEventId !== reviewOperatorEventId(review.reviewId, event.sequence)) {
+        throw new ReviewIntegrityError('Operator audit identity mismatch');
+    }
+    const proposal = review.proposals.find(item => item.version === event.proposalVersion);
+    if (!proposal)
+        throw new ReviewIntegrityError('Operator audit proposal mismatch');
+    return {
+        kind: outcome[0], outcome: outcome[1],
+        event_id: event.operatorDecisionEventId ?? reviewOperatorEventId(review.reviewId, event.sequence),
+        timestamp: new Date(event.atEpochMs).toISOString(),
+        actor: { id: event.actor.id, type: 'human', authentication: event.actor.authorityContext, roles: event.actor.roles },
+        reason: event.rationale, classification, correlation,
+        policy_ref: review.policyPins.map(pin => `${pin.id}@${pin.version}`).join(',') || undefined,
+        context: { reviewId: review.reviewId, sourceReceipt: review.sourceReceipt,
+            proposalVersion: event.proposalVersion, actionDigest: proposal.actionDigest },
+    };
+}
+/**
+ * Recover missing #1567 audit records after a crash using the durable review
+ * event IDs. Caller must serialize writers to the operator JSONL audit store.
+ */
+export async function replayReviewOperatorAudit(review, store, correlation, classification) {
+    validateReview(review);
+    const prior = await store.read();
+    if (!verifyDecisionChain(prior).ok)
+        throw new ReviewIntegrityError('Operator audit chain is invalid');
+    const matched = [];
+    for (const event of review.events) {
+        const input = reviewOperatorDecisionInput(review, event, correlation, classification);
+        if (!input)
+            continue;
+        const existing = prior.find(record => record.event_id === input.event_id);
+        if (existing) {
+            if (existing.kind !== input.kind || existing.outcome !== input.outcome || existing.actor.id !== input.actor.id ||
+                existing.context_digest !== digestDecisionContext(input.context) ||
+                canonicalJson(existing.correlation) !== canonicalJson(input.correlation) ||
+                existing.reason !== input.reason || existing.policy_ref !== input.policy_ref) {
+                throw new ReviewIntegrityError('Conflicting operator audit record');
+            }
+            matched.push(existing);
+        }
+        else {
+            const created = await store.append(input);
+            prior.push(created);
+            matched.push(created);
+        }
+    }
+    return matched;
+}
+//# sourceMappingURL=operator-audit.js.map