@aiwg/cli 2026.9.20 → 2026.9.24

package/dist/src/decision/review/recovery-adapters.js

@@ -0,0 +1,252 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { link, mkdir, open, readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { importDiscoveryManifest } from '../../sessions/batch-import.js';
+import { assertReviewProjection, ReviewConflictError, reviewDigest } from './validate.js';
+/** Caller supplies an authorized, exact-workspace refresh; never discovers provider roots implicitly. */
+export class WorkspaceReviewSessionAudit {
+    repository;
+    refresh;
+    locate;
+    covered = new Set();
+    constructor(repository, refresh, locate) {
+        this.repository = repository;
+        this.refresh = refresh;
+        this.locate = locate;
+    }
+    exactCoverage(workspaceId, previousSessionId) {
+        const coverage = this.repository.getCoverage(workspaceId);
+        if (coverage.status === 'stale')
+            return 'stale';
+        const session = this.repository.getSession(previousSessionId, workspaceId);
+        if (!session)
+            return 'unavailable';
+        if (!coverage.manifestId || session.consistency === 'provisional')
+            return 'partial';
+        const run = this.repository.getBatchImportRunForManifest(coverage.manifestId, workspaceId);
+        const source = run?.sources.find(item => item.sourceId === session.sourceId && item.provider === session.provider);
+        // Other providers may legitimately require a separate export. Global
+        // workspace coverage can be partial while this exact committed source is
+        // covered. No session from an uncommitted/rejected source is accepted.
+        return source && ['committed', 'previously-committed', 'duplicate'].includes(source.status) &&
+            ['complete', 'partial'].includes(run.status) ? 'covered' : 'partial';
+    }
+    async hydrate(workspaceId, previousSessionId) {
+        this.covered.delete(`${workspaceId}\0${previousSessionId}`);
+        await this.refresh(workspaceId, previousSessionId);
+        const status = this.exactCoverage(workspaceId, previousSessionId);
+        if (status === 'covered')
+            this.covered.add(`${workspaceId}\0${previousSessionId}`);
+        return { workspaceId, previousSessionId, coverage: status };
+    }
+    async findAttempt(query) {
+        if (!this.covered.has(`${query.workspaceId}\0${query.previousSessionId}`) ||
+            this.exactCoverage(query.workspaceId, query.previousSessionId) !== 'covered')
+            return null;
+        const matches = this.repository.listEvents(query.previousSessionId, query.workspaceId)
+            .filter(event => {
+            if (event.origin !== 'tool-control' || event.consistency !== 'complete')
+                return false;
+            const marker = this.locate(event);
+            return marker?.reviewId === query.reviewId && marker.effectId === query.effectId;
+        });
+        // An ambiguous marker never attests a specific attempt. Transcript text is
+        // not a completion receipt; the independent executor ledger is mandatory.
+        return matches.length === 1 ? { workspaceId: query.workspaceId, sessionId: query.previousSessionId,
+            reviewId: query.reviewId, effectId: query.effectId } : null;
+    }
+}
+/** Import only a previously reviewed manifest after fresh workspace/session authorization. */
+export function authorizedReviewCatalogRefresh(input) {
+    return async (workspaceId, previousSessionId) => {
+        if (workspaceId !== input.manifest.workspaceId || !previousSessionId ||
+            !await input.authorize(workspaceId, previousSessionId, input.manifest)) {
+            throw new Error('Review catalog refresh denied');
+        }
+        await importDiscoveryManifest({ manifest: input.manifest, repository: input.repository });
+    };
+}
+/**
+ * Wrap the effectful executor so the journal records an `intent` BEFORE the
+ * effect and a verified `completed` after it.
+ *
+ * - A known completed receipt is returned without re-executing.
+ * - An earlier intent without an outcome (a stale lease) is reconciled through
+ *   the kind verifier: `present` returns the recovered result; `absent` stays
+ *   uncertain unless the target is declared idempotent on the effect ID;
+ *   `unknown` never replays. Both refusals leave the review in `resuming`.
+ * - A journal without `recordIntent` (the deprecated HMAC journal) keeps its
+ *   post-execution journaling only.
+ */
+export function journaledReviewExecutor(input) {
+    return async (effectId, action) => {
+        if (effectId !== reviewDigest({ reviewId: input.reviewId, continuationId: input.continuationId,
+            proposalVersion: input.proposalVersion }))
+            throw new Error('Executor effect identity mismatch');
+        const query = { tenantId: input.scope.tenantId, projectId: input.scope.projectId, reviewId: input.reviewId, effectId };
+        const known = (receipt) => {
+            if (receipt.continuationId !== input.continuationId || receipt.proposalVersion !== input.proposalVersion) {
+                throw new Error('Executor receipt identity mismatch');
+            }
+            return receipt.result;
+        };
+        const existing = await input.ledger.completedReceipt(query);
+        if (existing)
+            return known(existing);
+        if (input.ledger.recordIntent) {
+            const identity = { tenantId: query.tenantId, projectId: query.projectId, reviewId: input.reviewId,
+                continuationId: input.continuationId, proposalVersion: input.proposalVersion };
+            const state = await input.ledger.recordIntent(identity, reviewDigest(action), input.links);
+            if (state === 'pending') {
+                const settled = input.ledger.reconcileReceipt
+                    ? await input.ledger.reconcileReceipt(query, { identity: { continuationId: input.continuationId, proposalVersion: input.proposalVersion } })
+                    : { result: 'unknown', receipt: null };
+                if (settled.result === 'present' && settled.receipt)
+                    return known(settled.receipt);
+                if (settled.result !== 'absent' || !input.idempotentTarget) {
+                    throw new ReviewConflictError(settled.result === 'absent' ? 'Effect outcome remains uncertain' : 'Effect outcome remains unknown');
+                }
+            }
+        }
+        const result = await input.executeEffect(effectId, structuredClone(action));
+        await input.ledger.recordCompleted(query, { effectId, continuationId: input.continuationId,
+            proposalVersion: input.proposalVersion, completedAtEpochMs: input.now(), result });
+        return result;
+    };
+}
+/**
+ * HMAC-only executor receipt journal.
+ *
+ * @deprecated Compatibility shim. Use the effect-ledger adapter
+ * (`LedgerReviewEffectJournal` / `openReviewEffectLedger`), which records a
+ * signed intent before the effect. Migrate existing receipts with
+ * `LedgerReviewEffectJournal.importLegacyReceipts`; see docs/decision/review.md.
+ * Keep its key separate from review-store and session-index keys.
+ */
+export class FileVerifiedReviewEffectLedger {
+    directory;
+    integrityKey;
+    constructor(directory, integrityKey, options = {}) {
+        this.directory = directory;
+        this.integrityKey = integrityKey;
+        if (integrityKey.length < 32)
+            throw new Error('Executor ledger integrity key must be at least 32 bytes');
+        for (const other of options.independentOf ?? []) {
+            if (other.length === integrityKey.length && timingSafeEqual(Buffer.from(other), Buffer.from(integrityKey))) {
+                throw new Error('Executor ledger key must be independent of review-store and session-index keys');
+            }
+        }
+    }
+    scope(query) {
+        const { tenantId, projectId, reviewId, effectId } = query;
+        if (![tenantId, projectId, reviewId, effectId].every(value => typeof value === 'string' && value.length > 0))
+            throw new Error('Invalid executor ledger scope');
+        return { tenantId, projectId, reviewId, effectId };
+    }
+    path(query) {
+        const digest = createHash('sha256').update(canonicalJson(this.scope(query))).digest('hex');
+        return join(this.directory, `${digest}.json`);
+    }
+    mac(record) { return createHmac('sha256', this.integrityKey).update(canonicalJson(record)).digest('hex'); }
+    /** Only the effectful executor calls this after independently verifying completion. */
+    async recordCompleted(query, receipt) {
+        if (receipt.effectId !== query.effectId || !receipt.continuationId || !Number.isSafeInteger(receipt.proposalVersion) || receipt.proposalVersion < 1 ||
+            !Number.isSafeInteger(receipt.completedAtEpochMs) || receipt.completedAtEpochMs < 0)
+            throw new Error('Invalid executor completion receipt');
+        assertReviewProjection(receipt.result);
+        const record = { query: this.scope(query), receipt };
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const destination = this.path(query);
+        const temporary = `${destination}.${randomUUID()}.tmp`;
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(`${JSON.stringify({ record, mac: this.mac(record) })}\n`);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        try {
+            await link(temporary, destination);
+            const dir = await open(this.directory, 'r');
+            try {
+                await dir.sync();
+            }
+            finally {
+                await dir.close();
+            }
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                const existing = await this.completedReceipt(query);
+                if (existing && canonicalJson(existing) === canonicalJson(receipt))
+                    return false;
+                throw new Error('Conflicting executor completion receipt');
+            }
+            throw error;
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async completedReceipt(query) {
+        let raw;
+        try {
+            raw = await readFile(this.path(query), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        return this.verifyEntry(raw, query);
+    }
+    /** Every verified receipt in the journal, for migration to the effect ledger. Any invalid entry fails the listing. */
+    async listReceipts() {
+        let names;
+        try {
+            names = (await readdir(this.directory)).filter(name => /^[a-f0-9]{64}\.json$/.test(name)).sort();
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const out = [];
+        for (const name of names) {
+            const raw = await readFile(join(this.directory, name), 'utf8');
+            let query;
+            try {
+                query = this.scope(JSON.parse(raw).record.query);
+            }
+            catch {
+                throw new Error('Invalid executor ledger entry');
+            }
+            if (this.path(query) !== join(this.directory, name))
+                throw new Error('Invalid executor ledger entry');
+            out.push({ query, receipt: this.verifyEntry(raw, query) });
+        }
+        return out;
+    }
+    verifyEntry(raw, query) {
+        try {
+            const envelope = JSON.parse(raw);
+            const expected = Buffer.from(this.mac(envelope.record), 'hex');
+            const actual = Buffer.from(envelope.mac ?? '', 'hex');
+            if (actual.length !== expected.length || !timingSafeEqual(actual, expected) ||
+                canonicalJson(envelope.record.query) !== canonicalJson(this.scope(query)) || envelope.record.receipt.effectId !== query.effectId ||
+                !envelope.record.receipt.continuationId || !Number.isSafeInteger(envelope.record.receipt.proposalVersion) ||
+                envelope.record.receipt.proposalVersion < 1 || !Number.isSafeInteger(envelope.record.receipt.completedAtEpochMs) ||
+                envelope.record.receipt.completedAtEpochMs < 0)
+                throw new Error('Invalid executor ledger entry');
+            assertReviewProjection(envelope.record.receipt.result);
+            return structuredClone(envelope.record.receipt);
+        }
+        catch {
+            throw new Error('Invalid executor ledger entry');
+        }
+    }
+}
+//# sourceMappingURL=recovery-adapters.js.map

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

@@ -0,0 +1,33 @@
+import { ReviewConflictError } from './validate.js';
+/**
+ * Opt-in recovery adapter for DecisionReviewService.resume's reconcile callback.
+ * Missing, stale, conflicting, or unauthenticated evidence returns null; the
+ * service will keep the old effect uncertain and will not dispatch it again.
+ */
+export function auditedReviewReconciler(input) {
+    return async (effectId) => {
+        const coverage = await input.catalog.hydrate(input.workspaceId, input.previousSessionId);
+        if (coverage.workspaceId !== input.workspaceId || coverage.previousSessionId !== input.previousSessionId || coverage.coverage !== 'covered')
+            return null;
+        const attempt = await input.catalog.findAttempt({ workspaceId: input.workspaceId, previousSessionId: input.previousSessionId, reviewId: input.reviewId, effectId });
+        if (!attempt || attempt.workspaceId !== input.workspaceId || attempt.sessionId !== input.previousSessionId ||
+            attempt.reviewId !== input.reviewId || attempt.effectId !== effectId)
+            return null;
+        const query = { tenantId: input.scope.tenantId, projectId: input.scope.projectId, reviewId: input.reviewId, effectId };
+        let receipt = await input.ledger.completedReceipt(query);
+        if (!receipt && input.verifier) {
+            const settled = await input.verifier.reconcileReceipt(query);
+            // `absent` never authorizes a replay and `unknown` settles nothing.
+            if (settled.result !== 'present')
+                return null;
+            receipt = settled.receipt;
+        }
+        if (!receipt || receipt.effectId !== effectId || !Number.isSafeInteger(receipt.completedAtEpochMs) || receipt.completedAtEpochMs < 0)
+            return null;
+        if (input.expected && (receipt.continuationId !== input.expected.continuationId || receipt.proposalVersion !== input.expected.proposalVersion)) {
+            throw new ReviewConflictError('Reconciliation receipt mismatch');
+        }
+        return receipt;
+    };
+}
+//# sourceMappingURL=recovery.js.map