@deftai/directive-core 0.104.0 → 0.106.0

package/dist/scope-provenance/mint-artifacts.js

@@ -0,0 +1,425 @@
+/**
+ * One mint writes record + preimage + both digests (#3376 R7 / #3385).
+ * Dest publish is two-phase under a per-plan lock: both dests land as
+ * `.next` first, then dests are copied from that pair. A crash leaves
+ * `.next` and/or a bak journal; recover finishes the flip or restores
+ * the prior pair (or neither dest) without waiting for a remint.
+ * Caught write failures still restore or clear dests.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { ContainedWriteError, ContainedWriteErrorCode, containedRemove, containedWrite, } from "../fs/contained-write.js";
+import { approvedScopeDir, approvedScopeIntentPath, approvedScopeRecordPath, buildApprovedScopeRecord, } from "./digest.js";
+import { extractIntentFromRaw, } from "./extract-intent.js";
+import { computeIntentDigest, INTENT_DIGEST_ALGO } from "./intent-digest.js";
+export { approvedScopeIntentPath, approvedScopeRecordPath };
+export class MintPairRollbackError extends Error {
+    writeError;
+    restoreError;
+    clearError;
+    constructor(writeError, restoreError, clearError) {
+        const writeMsg = errorMessage(writeError);
+        const restoreMsg = errorMessage(restoreError);
+        const clearSuffix = clearError === undefined
+            ? "; leftover dests were cleared"
+            : `; leftover dests could not be cleared (${errorMessage(clearError)})`;
+        super(`Mint dest publish failed (${writeMsg}); rollback also failed (${restoreMsg})${clearSuffix}. Do not commit a partial approved-scope pair.`);
+        this.name = "MintPairRollbackError";
+        this.writeError = writeError;
+        this.restoreError = restoreError;
+        this.clearError = clearError;
+        this.cause = writeError;
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function snapshotText(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf8");
+}
+function restoreText(root, path, snapshot) {
+    rmSync(path, { force: true, recursive: true });
+    if (snapshot === null)
+        return;
+    containedWrite({
+        root,
+        target: path,
+        data: snapshot,
+        mode: "replace",
+    });
+}
+function writeTempPayload(root, target, data) {
+    containedWrite({
+        root,
+        target,
+        data,
+        mode: "create",
+    });
+}
+function restoreDestDefault(input) {
+    restoreText(input.root, input.target, input.snapshot);
+}
+function removeDestDefault(input) {
+    rmSync(input.target, { force: true });
+}
+function pairStem(recordPath) {
+    return basename(recordPath).replace(/\.json$/i, "");
+}
+export function approvedScopePairLockPath(dir, recordPath) {
+    return join(dir, `.${pairStem(recordPath)}.pair.lock.tmp`);
+}
+export function approvedScopePairJournalPaths(dir, intentPath, recordPath) {
+    return {
+        publishing: join(dir, `.${pairStem(recordPath)}.publishing.bak`),
+        intentBak: join(dir, `${basename(intentPath)}.bak`),
+        recordBak: join(dir, `${basename(recordPath)}.bak`),
+    };
+}
+export function approvedScopePairNextPaths(dir, intentPath, recordPath) {
+    return {
+        intentNext: join(dir, `${basename(intentPath)}.next.tmp`),
+        recordNext: join(dir, `${basename(recordPath)}.next.tmp`),
+    };
+}
+function publishFromNext(root, next, dest) {
+    if (!existsSync(next)) {
+        throw new Error(`mint pair next payload missing: ${basename(next)}`);
+    }
+    containedWrite({
+        root,
+        target: dest,
+        data: readFileSync(next, "utf8"),
+        mode: "replace",
+    });
+}
+function writeBak(root, src, bak) {
+    if (!existsSync(src)) {
+        rmSync(bak, { force: true });
+        return;
+    }
+    containedWrite({
+        root,
+        target: bak,
+        data: readFileSync(src, "utf8"),
+        mode: "replace",
+    });
+}
+function clearJournal(paths) {
+    rmSync(paths.publishing, { force: true });
+    rmSync(paths.intentBak, { force: true });
+    rmSync(paths.recordBak, { force: true });
+}
+function pairStemFromPublishingName(name) {
+    const match = name.match(/^\.(.+)\.publishing\.bak$/i);
+    return match?.[1] ?? null;
+}
+function pairStemFromNextName(name) {
+    if (!name.endsWith(".next.tmp"))
+        return null;
+    const base = name.slice(0, -".next.tmp".length);
+    if (base.endsWith(".intent.json"))
+        return base.slice(0, -".intent.json".length);
+    if (base.endsWith(".json"))
+        return base.slice(0, -".json".length);
+    return null;
+}
+/**
+ * Finish a staged dest flip from `.next`, or restore the bak pair / clear dests.
+ * Does not wait for a remint.
+ */
+export function recoverIncompleteApprovedScopePair(input) {
+    const root = resolve(input.projectRoot);
+    const dir = approvedScopeDir(input.projectRoot);
+    const journal = approvedScopePairJournalPaths(dir, input.intentPath, input.recordPath);
+    const next = approvedScopePairNextPaths(dir, input.intentPath, input.recordPath);
+    const intentNext = snapshotText(next.intentNext);
+    const recordNext = snapshotText(next.recordNext);
+    if (intentNext !== null && recordNext !== null) {
+        restoreText(root, input.intentPath, intentNext);
+        restoreText(root, input.recordPath, recordNext);
+        rmSync(next.intentNext, { force: true });
+        rmSync(next.recordNext, { force: true });
+        clearJournal(journal);
+        return true;
+    }
+    if (!existsSync(journal.publishing)) {
+        const leftover = intentNext !== null || recordNext !== null;
+        rmSync(next.intentNext, { force: true });
+        rmSync(next.recordNext, { force: true });
+        return leftover;
+    }
+    const intentBak = snapshotText(journal.intentBak);
+    const recordBak = snapshotText(journal.recordBak);
+    if (intentBak !== null || recordBak !== null) {
+        restoreText(root, input.intentPath, intentBak);
+        restoreText(root, input.recordPath, recordBak);
+    }
+    else {
+        rmSync(input.intentPath, { force: true });
+        rmSync(input.recordPath, { force: true });
+    }
+    rmSync(next.intentNext, { force: true });
+    rmSync(next.recordNext, { force: true });
+    clearJournal(journal);
+    return true;
+}
+/** Recover every incomplete pair under `.deft/approved-scope/`. */
+export function recoverApprovedScopePairs(projectRoot) {
+    const dir = approvedScopeDir(projectRoot);
+    if (!existsSync(dir))
+        return 0;
+    const stems = new Set();
+    for (const name of readdirSync(dir)) {
+        const fromPub = pairStemFromPublishingName(name);
+        if (fromPub !== null)
+            stems.add(fromPub);
+        const fromNext = pairStemFromNextName(name);
+        if (fromNext !== null)
+            stems.add(fromNext);
+    }
+    let recovered = 0;
+    for (const stem of stems) {
+        const did = recoverIncompleteApprovedScopePair({
+            projectRoot,
+            intentPath: join(dir, `${stem}.intent.json`),
+            recordPath: join(dir, `${stem}.json`),
+        });
+        if (did)
+            recovered += 1;
+    }
+    return recovered;
+}
+function ownerPidAlive(lockPath) {
+    try {
+        const owner = Number(readFileSync(lockPath, "utf8").trim());
+        if (!Number.isInteger(owner) || owner <= 0)
+            return true;
+        process.kill(owner, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        return code !== "ESRCH";
+    }
+}
+function reclaimDeadPairLock(lockPath) {
+    const stale = `${lockPath}.stale`;
+    try {
+        renameSync(lockPath, stale);
+    }
+    catch {
+        return;
+    }
+    rmSync(stale, { force: true });
+}
+function isCreateExistsError(err) {
+    return err instanceof ContainedWriteError && err.code === ContainedWriteErrorCode.EXISTS;
+}
+function withPairLock(root, lockPath, waitMs, fn) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + waitMs;
+    let held = false;
+    while (!held) {
+        try {
+            containedWrite({
+                root,
+                target: lockPath,
+                data: `${process.pid}\n`,
+                mode: "create",
+                mutation: false,
+            });
+            held = true;
+        }
+        catch (err) {
+            if (!isCreateExistsError(err))
+                throw err;
+            if (!ownerPidAlive(lockPath)) {
+                reclaimDeadPairLock(lockPath);
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`timed out acquiring mint pair lock for ${basename(lockPath)}`);
+            }
+            const spinEnd = Date.now() + 20;
+            while (Date.now() < spinEnd) {
+                /* spin */
+            }
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            containedRemove({ root, target: lockPath, mutation: false });
+        }
+        catch {
+            rmSync(lockPath, { force: true });
+        }
+    }
+}
+function restorePair(restore, dests) {
+    const failures = [];
+    for (const dest of dests) {
+        try {
+            restore(dest);
+        }
+        catch (err) {
+            failures.push(`${basename(dest.target)}: ${errorMessage(err)}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new Error(failures.join("; "));
+    }
+}
+function clearDestPair(input) {
+    const dests = [
+        { root: input.root, target: input.intentPath, snapshot: input.prevIntent },
+        { root: input.root, target: input.recordPath, snapshot: input.prevRecord },
+    ];
+    const removed = [];
+    const failures = [];
+    for (const dest of dests) {
+        try {
+            input.remove({ root: dest.root, target: dest.target });
+            removed.push(dest);
+        }
+        catch (err) {
+            failures.push(`${basename(dest.target)}: ${errorMessage(err)}`);
+        }
+    }
+    if (failures.length === 0)
+        return;
+    const putBackFailures = [];
+    for (const dest of removed) {
+        try {
+            restoreDestDefault(dest);
+        }
+        catch (err) {
+            putBackFailures.push(`${basename(dest.target)}: ${errorMessage(err)}`);
+        }
+    }
+    const putBackSuffix = putBackFailures.length > 0
+        ? `; removed dests could not be put back (${putBackFailures.join("; ")})`
+        : "";
+    throw new Error(`${failures.join("; ")}${putBackSuffix}`);
+}
+/**
+ * Write record + preimage as one fail-closed pair.
+ * Phase 1 writes both dests to `.next`. Phase 2 copies dests from that pair.
+ * Recover finishes the flip or restores the bak pair without a remint.
+ */
+export function writeApprovedScopePair(input) {
+    const root = resolve(input.projectRoot);
+    const dir = approvedScopeDir(input.projectRoot);
+    mkdirSync(dir, { recursive: true });
+    const lockPath = approvedScopePairLockPath(dir, input.recordPath);
+    const journal = approvedScopePairJournalPaths(dir, input.intentPath, input.recordPath);
+    const restore = input.restoreDest ?? restoreDestDefault;
+    const remove = input.removeDest ?? removeDestDefault;
+    const customPublish = input.publishDest;
+    const next = approvedScopePairNextPaths(dir, input.intentPath, input.recordPath);
+    withPairLock(root, lockPath, input.lockWaitMs ?? 30_000, () => {
+        recoverIncompleteApprovedScopePair({
+            projectRoot: input.projectRoot,
+            intentPath: input.intentPath,
+            recordPath: input.recordPath,
+        });
+        const prevIntent = snapshotText(input.intentPath);
+        const prevRecord = snapshotText(input.recordPath);
+        const dests = [
+            { root, target: input.intentPath, snapshot: prevIntent },
+            { root, target: input.recordPath, snapshot: prevRecord },
+        ];
+        let destPublished = false;
+        try {
+            writeTempPayload(root, next.intentNext, input.intentData);
+            writeTempPayload(root, next.recordNext, input.recordData);
+            writeBak(root, input.intentPath, journal.intentBak);
+            writeBak(root, input.recordPath, journal.recordBak);
+            containedWrite({
+                root,
+                target: journal.publishing,
+                data: "publishing\n",
+                mode: "replace",
+            });
+            destPublished = true;
+            if (customPublish) {
+                customPublish({ root, target: input.intentPath, data: input.intentData });
+                customPublish({ root, target: input.recordPath, data: input.recordData });
+            }
+            else {
+                publishFromNext(root, next.intentNext, input.intentPath);
+                publishFromNext(root, next.recordNext, input.recordPath);
+            }
+            clearJournal(journal);
+        }
+        catch (err) {
+            if (destPublished) {
+                try {
+                    restorePair(restore, dests);
+                    clearJournal(journal);
+                }
+                catch (restoreErr) {
+                    try {
+                        clearDestPair({
+                            root,
+                            intentPath: input.intentPath,
+                            recordPath: input.recordPath,
+                            prevIntent,
+                            prevRecord,
+                            remove,
+                        });
+                        clearJournal(journal);
+                    }
+                    catch (clearErr) {
+                        throw new MintPairRollbackError(err, restoreErr, clearErr);
+                    }
+                    throw new MintPairRollbackError(err, restoreErr);
+                }
+            }
+            throw err;
+        }
+        finally {
+            rmSync(next.intentNext, { force: true });
+            rmSync(next.recordNext, { force: true });
+        }
+    });
+}
+export function mintApprovedScopeArtifacts(input) {
+    const extracted = extractIntentFromRaw(input.rawText, {
+        projectRoot: input.projectRoot,
+        ...input.extract,
+    });
+    if (!extracted.ok) {
+        throw new Error(extracted.error);
+    }
+    const intentDigest = computeIntentDigest(extracted.preimage);
+    const record = {
+        ...buildApprovedScopeRecord({
+            xbriefRelPath: input.xbriefRelPath,
+            payload: input.payload,
+            approvedAt: input.approvedAt,
+            humanApproval: input.humanApproval,
+        }),
+        intentDigest,
+        digestAlgo: INTENT_DIGEST_ALGO,
+    };
+    const intentPath = approvedScopeIntentPath(input.projectRoot, record.planId);
+    const recordPath = approvedScopeRecordPath(input.projectRoot, record.planId);
+    writeApprovedScopePair({
+        projectRoot: input.projectRoot,
+        intentPath,
+        recordPath,
+        intentData: `${JSON.stringify(extracted.preimage, null, 2)}\n`,
+        recordData: `${JSON.stringify(record, null, 2)}\n`,
+        publishDest: input.publishDest,
+        restoreDest: input.restoreDest,
+        removeDest: input.removeDest,
+        lockWaitMs: input.lockWaitMs,
+    });
+    return { record, preimage: extracted.preimage, recordPath, intentPath };
+}
+//# sourceMappingURL=mint-artifacts.js.map

package/dist/session/ac-pass-banking.d.ts

@@ -38,6 +38,8 @@ export interface AcPassBankRecord {
     readonly scopeId: string;
     readonly bankedAt: string;
     readonly headSha: string | null;
+    /** Product+acceptance digest; missing/empty is stale for #3387 reuse. */
+    readonly productStateHash?: string | null;
     readonly remainingTurns: number | null;
     readonly remainingBudget: number | null;
     readonly maxTurns: number | null;
@@ -75,6 +77,7 @@ export interface BankAcPassInput {
     readonly surplus: SurplusEvaluation;
     readonly nextAction: Exclude<AcPassNextAction, "still_open">;
     readonly headSha?: string | null;
+    readonly productStateHash?: string | null;
     readonly now?: string;
     readonly environ?: Readonly<Record<string, string | undefined>>;
 }
@@ -130,42 +133,6 @@ export declare function readAcPassBank(projectRoot: string, scopeId: string): Ac
  * Append a post-bank finding to an existing bank record (report/chase/fix).
  */
 export declare function recordPostBankFinding(projectRoot: string, scopeId: string, finding: PostBankFinding): AcPassBankRecord | null;
-export interface BankEventPayload {
-    readonly type: "ac_pass_bank" | "ac_pass_post_bank_finding" | "ac_pass_deepening_skipped";
-    readonly schemaVersion: number;
-    readonly scopeId?: string;
-    readonly bankedAt?: string;
-    readonly nextAction?: string;
-    readonly hadSurplus?: boolean;
-    readonly surplusThreshold?: number;
-    readonly remainingFraction?: number | null;
-    readonly remainingTurns?: number | null;
-    readonly remainingBudget?: number | null;
-    readonly maxTurns?: number | null;
-    readonly maxBudget?: number | null;
-    readonly headSha?: string | null;
-    readonly path?: string;
-    readonly finding?: PostBankFinding;
-    readonly note?: string;
-    readonly [key: string]: unknown;
-}
-/**
- * Format one JSONL bank-event line for run-summary telemetry (#3285 / #3282).
- */
-export declare function formatBankEventLine(event: BankEventPayload): string;
-/**
- * Append bank event to DEFT_RUN_SUMMARY_PATH when set.
- * Unset = silent. `-` = stdout. Failures warn once to stderr (fail-open).
- */
-export declare function appendBankEventToRunSummary(input: {
-    readonly environ?: Readonly<Record<string, string | undefined>>;
-    readonly event: BankEventPayload;
-    readonly writeLine?: (path: string, line: string) => void;
-    readonly warn?: (message: string) => void;
-}): {
-    written: boolean;
-    path: string | null;
-};
 /**
  * Simulated run used by the surplus-insufficient acceptance test (#3285):
  * AC passes → bank → extra checks would exceed budget → ship + report finding.
@@ -205,6 +172,12 @@ export interface MaybeBankOnAcPassInput {
      */
     readonly executableRuns: number;
     readonly quiet?: boolean;
+    readonly productStateHash?: string | null;
+    /**
+     * Bank a verified-pass walk even when no shell runs were recorded (#3558).
+     * Soft/advisory empty passes still skip via executableRuns === 0.
+     */
+    readonly verifiedPass?: boolean;
 }
 export interface MaybeBankOnAcPassResult {
     readonly banked: boolean;

package/dist/session/ac-pass-banking.js

@@ -12,10 +12,12 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { DEFAULT_SURPLUS_THRESHOLD, resolveAcPassBanking, } from "../policy/ac-pass-banking.js";
+import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { detectHardEffortBudget, formatDeepeningSkippedNote, recommendVerificationDepth, } from "./effort-budget.js";
+import { gitHead } from "./git.js";
 /** Durable bank ledger directory (gitignored under `.deft/`). */
 export const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
 export const AC_PASS_BANK_SCHEMA_VERSION = 1;
@@ -320,6 +322,7 @@ export function bankAcPass(input) {
         scopeId: input.scopeId,
         bankedAt,
         headSha: input.headSha ?? null,
+        productStateHash: input.productStateHash ?? prior?.productStateHash ?? null,
         remainingTurns: input.budget.remainingTurns,
         remainingBudget: input.budget.remainingBudget,
         maxTurns: input.budget.maxTurns,
@@ -358,25 +361,31 @@ export function bankAcPass(input) {
             durablePath = tmpPath;
         }
     }
-    appendBankEventToRunSummary({
-        environ: input.environ ?? process.env,
-        event: {
-            type: "ac_pass_bank",
-            schemaVersion: AC_PASS_BANK_SCHEMA_VERSION,
-            scopeId: record.scopeId,
-            bankedAt: record.bankedAt,
-            nextAction: record.nextAction,
-            hadSurplus: record.hadSurplus,
-            surplusThreshold: record.surplusThreshold,
-            remainingFraction: input.surplus.remainingFraction,
-            remainingTurns: record.remainingTurns,
-            remainingBudget: record.remainingBudget,
-            maxTurns: record.maxTurns,
-            maxBudget: record.maxBudget,
-            headSha: record.headSha,
+    try {
+        const env = { ...(input.environ ?? process.env) };
+        const emitter = new RunSummaryEmitter({
+            projectRoot: root,
+            env,
+            component: "ac-pass-banking",
+        });
+        emitter.emitAcPassBank({
+            scope_id: record.scopeId,
+            banked_at: record.bankedAt,
+            next_action: record.nextAction,
+            had_surplus: record.hadSurplus,
+            surplus_threshold: record.surplusThreshold,
+            remaining_fraction: input.surplus.remainingFraction,
+            remaining_turns: record.remainingTurns,
+            remaining_budget: record.remainingBudget,
+            max_turns: record.maxTurns,
+            max_budget: record.maxBudget,
+            head_sha: record.headSha,
             path: durablePath,
-        },
-    });
+        });
+    }
+    catch {
+        // fail-open
+    }
     return record;
 }
 /**
@@ -487,6 +496,7 @@ function recoveredStubRecord(scopeId, findings) {
         // valid primary ledger (#3285 Greptile residual).
         bankedAt: "1970-01-01T00:00:00Z",
         headSha: null,
+        productStateHash: null,
         remainingTurns: null,
         remainingBudget: null,
         maxTurns: null,
@@ -616,63 +626,6 @@ export function recordPostBankFinding(projectRoot, scopeId, finding) {
     }
     return updated;
 }
-/**
- * Format one JSONL bank-event line for run-summary telemetry (#3285 / #3282).
- */
-export function formatBankEventLine(event) {
-    return JSON.stringify({
-        ...event,
-        ts: typeof event.bankedAt === "string" ? event.bankedAt : utcIso(),
-        source: "ac-pass-banking",
-        issue: 3285,
-    });
-}
-/**
- * Append bank event to DEFT_RUN_SUMMARY_PATH when set.
- * Unset = silent. `-` = stdout. Failures warn once to stderr (fail-open).
- */
-export function appendBankEventToRunSummary(input) {
-    const environ = input.environ ?? process.env;
-    const raw = (environ[ENV_RUN_SUMMARY_PATH] ?? "").trim();
-    if (!raw) {
-        return { written: false, path: null };
-    }
-    const line = `${formatBankEventLine(input.event)}\n`;
-    if (raw === "-") {
-        process.stdout.write(line);
-        return { written: true, path: "-" };
-    }
-    try {
-        if (input.writeLine) {
-            input.writeLine(raw, line);
-        }
-        else {
-            const abs = resolve(raw);
-            const parent = dirname(abs);
-            if (!existsSync(parent)) {
-                mkdirSync(parent, { recursive: true });
-            }
-            // Contain under the parent directory of the summary file.
-            containedWrite({
-                root: parent,
-                target: abs,
-                data: line,
-                mode: "append",
-            });
-        }
-        return { written: true, path: raw };
-    }
-    catch (err) {
-        const msg = err instanceof ContainedWriteError
-            ? err.message
-            : err instanceof Error
-                ? err.message
-                : String(err);
-        const warn = input.warn ?? ((m) => process.stderr.write(`${m}\n`));
-        warn(`[deft ac-pass-banking] run-summary write failed path=${raw}: ${msg} (#3285)`);
-        return { written: false, path: raw };
-    }
-}
 /**
  * Simulated run used by the surplus-insufficient acceptance test (#3285):
  * AC passes → bank → extra checks would exceed budget → ship + report finding.
@@ -730,7 +683,7 @@ export function resolveBankingConfigForRoot(projectRoot, environ) {
  * Throws on I/O failure so verify:ac can fail closed (checkpoint mandatory).
  */
 export function maybeBankOnAcPass(input) {
-    if (input.executableRuns <= 0) {
+    if (input.executableRuns <= 0 && input.verifiedPass !== true) {
         return { banked: false, decision: null, bank: null, notes: [] };
     }
     const budget = input.budget ?? detectHardEffortBudget({ environ: input.environ ?? process.env });
@@ -747,7 +700,8 @@ export function maybeBankOnAcPass(input) {
         budget,
         surplus: decision.surplus,
         nextAction,
-        headSha: input.headSha ?? null,
+        headSha: input.headSha !== undefined ? input.headSha : gitHead(input.projectRoot).head,
+        productStateHash: input.productStateHash ?? null,
         now: input.now,
         environ: input.environ,
     });