looply-cli 0.0.0-stage → 0.3.0

package/dist/retention-apply-runtime.d.ts

@@ -0,0 +1,105 @@
+import { type ApplyIntent, type ApplyRecord, type ApplyRecordPhase, type Observed, type RemovalDecision, type RetentionPolicy, type Tombstone } from '@looply/core';
+/**
+ * THE FILESYSTEM HALF OF APPLYING A RETENTION PLAN.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `retention-apply.ts` in core decides; this observes, serialises, journals and
+ * removes. The split is the same one `candidate-replay` uses and for the same
+ * reason: every refusal in the decision can be tested without a real file, and
+ * every mechanic here can be tested against real ones without re-deciding
+ * anything.
+ *
+ * 🔴 NOTHING HERE DECIDES. This file must never contain a reason to remove
+ * something. It reads what is there, hands it to the fold, and does what the
+ * fold says. A condition written here would be one nothing in core's suite can
+ * see, which is how the second copy of a rule ends up disagreeing with the first.
+ */
+/** What the filesystem cannot tell us: provenance, pins and references. */
+export interface ArtifactFacts {
+    readonly owned?: boolean;
+    readonly pinned?: boolean;
+    readonly referenced?: boolean;
+    readonly class?: Observed['class'];
+}
+export interface ApplyRuntimeDeps {
+    readonly nowMs: () => number;
+    readonly policy: RetentionPolicy;
+    readonly maxPlanAgeMs?: number;
+    /** Ownership, pins and references for one artifact. Absent fields refuse. */
+    readonly facts: (id: string) => ArtifactFacts;
+    /** Append-only, two records per deletion. Created if absent. */
+    readonly journalPath: string;
+    /** Exclusive while an apply runs. See `withLock`. */
+    readonly lockPath: string;
+    readonly log?: (line: string) => void;
+}
+export interface ApplyOutcome {
+    readonly decisions: readonly RemovalDecision[];
+    readonly removed: readonly Tombstone[];
+    readonly refused: readonly {
+        id: string;
+        because: string;
+    }[];
+    readonly alreadyGone: readonly string[];
+    /** Entries a previous interrupted run left in flight, re-observed this time. */
+    readonly resumed: readonly string[];
+    /**
+     * Entries this intent had already finished, carried over rather than redone.
+     *
+     * 🔴 REPORTED, NOT SWALLOWED. A second run of the same plan decides nothing
+     * and removes nothing — which is the point — but a caller told only "removed
+     * 0, refused 0" would read a standing refusal as a clean result. The decision
+     * still stands; it was simply made earlier.
+     */
+    readonly settled: readonly {
+        id: string;
+        phase: ApplyRecordPhase;
+    }[];
+}
+/**
+ * What is actually at `path`, read without following anything.
+ *
+ * ⚠️ `lstat`, NEVER `stat`. `stat` follows a link and reports the TARGET, so a
+ * junction would be measured, aged and classified as whatever it points at —
+ * and then deleted as if it were that. `lstat` reports the link itself, which
+ * is the thing this is deciding about.
+ *
+ * Every failure produces a refusable observation rather than a throw: an
+ * unreadable artifact must reach the fold as unreadable, because the fold is
+ * where "unreadable is not permission" is written down.
+ */
+export declare function observe(id: string, path: string, facts: ArtifactFacts): Observed;
+export declare class LockHeld extends Error {
+    readonly by: string;
+    constructor(by: string);
+}
+/**
+ * Exclusive for the duration, or it does not run.
+ *
+ * `wx` is create-if-absent, and it is the whole mechanism: two processes racing
+ * it cannot both win, because the filesystem arbitrates. The holder writes who
+ * it is so the refusal can say so rather than "locked".
+ *
+ * ⚠️ A HELD LOCK IS A REFUSAL, NOT A WAIT. The charter requires serialising
+ * against writers and retention consumers; a timeout that gave up and proceeded
+ * would be exactly the thing it is serialising against.
+ */
+export declare function withLock<T>(lockPath: string, holder: string, body: () => T): T;
+export declare function readJournal(path: string): ApplyRecord[];
+/**
+ * Carry out an intent: observe, decide, journal, remove.
+ *
+ * The order per deletion is fixed and is the crash-survivable one:
+ *
+ *   1. observe what is there now
+ *   2. ask the fold
+ *   3. write `intended` BEFORE touching anything
+ *   4. remove
+ *   5. write `removed` with the tombstone
+ *
+ * A crash between 3 and 5 leaves an `intended` with no outcome, which is
+ * exactly the state `resumeApply` re-observes. It cannot be mistaken for a
+ * completed removal, and it cannot be mistaken for one that never started.
+ */
+export declare function applyRetention(intent: ApplyIntent, deps: ApplyRuntimeDeps): ApplyOutcome;
+//# sourceMappingURL=retention-apply-runtime.d.ts.map

package/dist/retention-apply-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-apply-runtime.d.ts","sourceRoot":"","sources":["../src/retention-apply-runtime.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;GAcG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,aAAa,CAAC;IAC9C,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE,EAAE,CAAC;CACtE;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,CAmChF;AAgDD,qBAAa,QAAS,SAAQ,KAAK;aACL,EAAE,EAAE,MAAM;gBAAV,EAAE,EAAE,MAAM;CAGvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CA4B9E;AAID,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAevD;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,GAAG,YAAY,CA8ExF"}

package/dist/retention-apply-runtime.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LockHeld = void 0;
+exports.observe = observe;
+exports.withLock = withLock;
+exports.readJournal = readJournal;
+exports.applyRetention = applyRetention;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+/* ──────────────────────────────────────────────────────────── observing ── */
+/**
+ * What is actually at `path`, read without following anything.
+ *
+ * ⚠️ `lstat`, NEVER `stat`. `stat` follows a link and reports the TARGET, so a
+ * junction would be measured, aged and classified as whatever it points at —
+ * and then deleted as if it were that. `lstat` reports the link itself, which
+ * is the thing this is deciding about.
+ *
+ * Every failure produces a refusable observation rather than a throw: an
+ * unreadable artifact must reach the fold as unreadable, because the fold is
+ * where "unreadable is not permission" is written down.
+ */
+function observe(id, path, facts) {
+    const base = { id, ...facts };
+    let st;
+    try {
+        st = (0, node_fs_1.lstatSync)(path);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT') {
+            return { ...base, present: false, bytes: null, createdAtMs: null, realPath: null, isLink: false, containsLink: false };
+        }
+        // There but unreadable — the fold refuses this, and must be given the
+        // chance to. Reporting it absent would be a removal decided by an error.
+        return { ...base, present: true, bytes: null, createdAtMs: null, realPath: null, isLink: false };
+    }
+    const isLink = st.isSymbolicLink();
+    let realPath = null;
+    try {
+        realPath = node_fs_1.realpathSync.native(path);
+    }
+    catch {
+        /* null refuses */
+    }
+    const walked = walk(path, st.isDirectory());
+    return {
+        ...base,
+        present: true,
+        bytes: walked.bytes,
+        createdAtMs: walked.createdAtMs,
+        realPath,
+        isLink,
+        ...(walked.containsLink === undefined ? {} : { containsLink: walked.containsLink }),
+    };
+}
+/**
+ * Size, age and whether anything inside is a link.
+ *
+ * 🔴 THE LINK SEARCH IS THE POINT, not a side effect of measuring. A recursive
+ * delete walks a junction out of the tree, so an artifact directory holding one
+ * is an artifact that can delete somebody else's files. The walk uses `lstat`
+ * at every level and never descends THROUGH a link — it records it and stops.
+ *
+ * Any error at any level leaves `bytes`/`createdAtMs` null and `containsLink`
+ * undefined, all three of which the fold refuses. A partial walk is not a
+ * measurement.
+ */
+function walk(path, isDir) {
+    let bytes = 0;
+    let createdAtMs = null;
+    let containsLink = false;
+    const stack = [path];
+    let first = true;
+    try {
+        while (stack.length > 0) {
+            const at = stack.pop();
+            const st = (0, node_fs_1.lstatSync)(at);
+            if (st.isSymbolicLink()) {
+                // The top-level link is reported by `observe` through `isLink`; a nested
+                // one is what this flag exists for. Either way: do not descend.
+                if (!first)
+                    containsLink = true;
+                first = false;
+                continue;
+            }
+            first = false;
+            createdAtMs = createdAtMs === null ? st.mtimeMs : Math.min(createdAtMs, st.mtimeMs);
+            if (st.isDirectory()) {
+                for (const child of (0, node_fs_1.readdirSync)(at))
+                    stack.push((0, node_path_1.join)(at, child));
+            }
+            else {
+                bytes += st.size;
+            }
+        }
+    }
+    catch {
+        return { bytes: null, createdAtMs: null, containsLink: undefined };
+    }
+    if (!isDir && createdAtMs === null)
+        return { bytes: null, createdAtMs: null, containsLink: undefined };
+    return { bytes, createdAtMs, containsLink };
+}
+/* ─────────────────────────────────────────────────────────── the lock ── */
+class LockHeld extends Error {
+    by;
+    constructor(by) {
+        super(`another apply or retention consumer holds the lock: ${by}`);
+        this.by = by;
+    }
+}
+exports.LockHeld = LockHeld;
+/**
+ * Exclusive for the duration, or it does not run.
+ *
+ * `wx` is create-if-absent, and it is the whole mechanism: two processes racing
+ * it cannot both win, because the filesystem arbitrates. The holder writes who
+ * it is so the refusal can say so rather than "locked".
+ *
+ * ⚠️ A HELD LOCK IS A REFUSAL, NOT A WAIT. The charter requires serialising
+ * against writers and retention consumers; a timeout that gave up and proceeded
+ * would be exactly the thing it is serialising against.
+ */
+function withLock(lockPath, holder, body) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(lockPath), { recursive: true });
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(lockPath, 'wx');
+    }
+    catch (e) {
+        if (e.code === 'EEXIST') {
+            let by = 'unknown';
+            try {
+                by = (0, node_fs_1.readFileSync)(lockPath, 'utf8').trim() || 'unknown';
+            }
+            catch {
+                /* the message degrades; the refusal does not */
+            }
+            throw new LockHeld(by);
+        }
+        throw e;
+    }
+    try {
+        (0, node_fs_1.writeSync)(fd, holder);
+        (0, node_fs_1.closeSync)(fd);
+        return body();
+    }
+    finally {
+        try {
+            (0, node_fs_1.unlinkSync)(lockPath);
+        }
+        catch {
+            /* a lock that cannot be released is reported by the next run, not hidden here */
+        }
+    }
+}
+/* ──────────────────────────────────────────────────────────── journal ── */
+function readJournal(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return [];
+    const out = [];
+    for (const line of (0, node_fs_1.readFileSync)(path, 'utf8').split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A torn last line is what a crash mid-append looks like. Skipping it is
+            // correct: an unparseable record asserts nothing, and `resumeApply` reads
+            // an absent record as "never started", which re-decides rather than
+            // assumes.
+        }
+    }
+    return out;
+}
+function append(path, record) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.appendFileSync)(path, JSON.stringify(record) + '\n', 'utf8');
+}
+/* ───────────────────────────────────────────────────────────── applying ── */
+/**
+ * Carry out an intent: observe, decide, journal, remove.
+ *
+ * The order per deletion is fixed and is the crash-survivable one:
+ *
+ *   1. observe what is there now
+ *   2. ask the fold
+ *   3. write `intended` BEFORE touching anything
+ *   4. remove
+ *   5. write `removed` with the tombstone
+ *
+ * A crash between 3 and 5 leaves an `intended` with no outcome, which is
+ * exactly the state `resumeApply` re-observes. It cannot be mistaken for a
+ * completed removal, and it cannot be mistaken for one that never started.
+ */
+function applyRetention(intent, deps) {
+    const root = (0, node_path_1.resolve)(intent.root);
+    const log = deps.log ?? (() => { });
+    return withLock(deps.lockPath, `${process.pid} applying ${intent.intentId}`, () => {
+        const actions = (0, core_1.resumeApply)(intent, readJournal(deps.journalPath));
+        const byId = new Map(intent.deletions.map((d) => [d.id, d]));
+        const decisions = [];
+        const removed = [];
+        const refused = [];
+        const alreadyGone = [];
+        const resumed = [];
+        const settled = [];
+        for (const action of actions) {
+            const planned = byId.get(action.id);
+            if (planned === undefined)
+                continue;
+            if (action.kind === 'settled') {
+                settled.push({ id: action.id, phase: action.phase });
+                log(`${action.id}: already ${action.phase}`);
+                continue;
+            }
+            if (action.kind === 're-observe') {
+                resumed.push(action.id);
+                log(`${action.id}: ${action.because} — looking again`);
+            }
+            const observed = observe(action.id, planned.path, deps.facts(action.id));
+            const verdict = (0, core_1.decideRemoval)(planned, observed, { ...intent, root }, {
+                nowMs: deps.nowMs(),
+                policy: deps.policy,
+                ...(deps.maxPlanAgeMs === undefined ? {} : { maxPlanAgeMs: deps.maxPlanAgeMs }),
+            });
+            decisions.push({ id: action.id, path: planned.path, verdict });
+            if (verdict.kind === 'refuse') {
+                append(deps.journalPath, { intentId: intent.intentId, id: action.id, phase: 'refused', atMs: deps.nowMs(), because: verdict.because });
+                refused.push({ id: action.id, because: verdict.because });
+                log(`${action.id}: refused — ${verdict.because}`);
+                continue;
+            }
+            if (verdict.kind === 'already-gone') {
+                const stone = (0, core_1.tombstoneFor)(planned, verdict.because, deps.nowMs());
+                append(deps.journalPath, { intentId: intent.intentId, id: action.id, phase: 'removed', atMs: deps.nowMs(), tombstone: stone, because: verdict.because });
+                alreadyGone.push(action.id);
+                log(`${action.id}: already gone`);
+                continue;
+            }
+            // 🔴 THE INTENT IS ON DISK BEFORE THE REMOVAL, NOT AFTER.
+            append(deps.journalPath, { intentId: intent.intentId, id: action.id, phase: 'intended', atMs: deps.nowMs(), because: verdict.because });
+            /**
+             * ⚠️ ONE LAST BOUNDARY CHECK, IMMEDIATELY BEFORE THE CALL THAT DELETES.
+             * The fold checked it, and this checks it again against the resolved path
+             * it is about to hand to `rmSync`. It is the cheapest possible guard on
+             * the only line in this package that can destroy something, and the cost
+             * of the duplication is one comparison.
+             */
+            const target = observed.realPath ?? planned.path;
+            if (!(0, core_1.insideRoot)(root, target)) {
+                const because = `refusing at the last step: ${target} is outside ${root}`;
+                append(deps.journalPath, { intentId: intent.intentId, id: action.id, phase: 'refused', atMs: deps.nowMs(), because });
+                refused.push({ id: action.id, because });
+                continue;
+            }
+            (0, node_fs_1.rmSync)(planned.path, { recursive: true, force: false });
+            const stone = (0, core_1.tombstoneFor)(planned, verdict.because, deps.nowMs());
+            append(deps.journalPath, { intentId: intent.intentId, id: action.id, phase: 'removed', atMs: deps.nowMs(), tombstone: stone, because: verdict.because });
+            removed.push(stone);
+            log(`${action.id}: removed — ${verdict.because}`);
+        }
+        return { decisions, removed, refused, alreadyGone, resumed, settled };
+    });
+}
+//# sourceMappingURL=retention-apply-runtime.js.map

package/dist/retention-apply-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-apply-runtime.js","sourceRoot":"","sources":["../src/retention-apply-runtime.ts"],"names":[],"mappings":";;;AAqFA,0BAmCC;AAiED,4BA4BC;AAID,kCAeC;AAwBD,wCA8EC;AA9UD,qCAAwK;AACxK,yCAAmD;AACnD,uCAYsB;AAyDtB,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,SAAgB,OAAO,CAAC,EAAU,EAAE,IAAY,EAAE,KAAoB;IACpE,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC;IAE9B,IAAI,EAAE,CAAC;IACP,IAAI,CAAC;QACH,EAAE,GAAG,IAAA,mBAAS,EAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,GAAI,CAA2B,CAAC,IAAI,CAAC;QAC/C,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;QACzH,CAAC;QACD,sEAAsE;QACtE,yEAAyE;QACzE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACnG,CAAC;IAED,MAAM,MAAM,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC;IAEnC,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,QAAQ,GAAG,sBAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5C,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ;QACR,MAAM;QACN,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;KACpF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,IAAI,CAAC,IAAY,EAAE,KAAc;IACxC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;IACrB,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,EAAY,CAAC;YACjC,MAAM,EAAE,GAAG,IAAA,mBAAS,EAAC,EAAE,CAAC,CAAC;YACzB,IAAI,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC;gBACxB,yEAAyE;gBACzE,gEAAgE;gBAChE,IAAI,CAAC,KAAK;oBAAE,YAAY,GAAG,IAAI,CAAC;gBAChC,KAAK,GAAG,KAAK,CAAC;gBACd,SAAS;YACX,CAAC;YACD,KAAK,GAAG,KAAK,CAAC;YACd,WAAW,GAAG,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;YACpF,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;gBACrB,KAAK,MAAM,KAAK,IAAI,IAAA,qBAAW,EAAC,EAAE,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,IAAA,gBAAI,EAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;YACnE,CAAC;iBAAM,CAAC;gBACN,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,KAAK,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IACvG,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;AAC9C,CAAC;AAED,6EAA6E;AAE7E,MAAa,QAAS,SAAQ,KAAK;IACL;IAA5B,YAA4B,EAAU;QACpC,KAAK,CAAC,uDAAuD,EAAE,EAAE,CAAC,CAAC;QADzC,OAAE,GAAF,EAAE,CAAQ;IAEtC,CAAC;CACF;AAJD,4BAIC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,QAAQ,CAAI,QAAgB,EAAE,MAAc,EAAE,IAAa;IACzE,IAAA,mBAAS,EAAC,IAAA,mBAAO,EAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,IAAI,EAAU,CAAC;IACf,IAAI,CAAC;QACH,EAAE,GAAG,IAAA,kBAAQ,EAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnD,IAAI,EAAE,GAAG,SAAS,CAAC;YACnB,IAAI,CAAC;gBACH,EAAE,GAAG,IAAA,sBAAY,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;YAC1D,CAAC;YAAC,MAAM,CAAC;gBACP,gDAAgD;YAClD,CAAC;YACD,MAAM,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;IACD,IAAI,CAAC;QACH,IAAA,mBAAS,EAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACtB,IAAA,mBAAS,EAAC,EAAE,CAAC,CAAC;QACd,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,IAAA,oBAAU,EAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,iFAAiF;QACnF,CAAC;IACH,CAAC;AACH,CAAC;AAED,6EAA6E;AAE7E,SAAgB,WAAW,CAAC,IAAY;IACtC,IAAI,CAAC,IAAA,oBAAU,EAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,IAAA,sBAAY,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QACjC,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAgB,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,0EAA0E;YAC1E,oEAAoE;YACpE,WAAW;QACb,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,MAAmB;IAC/C,IAAA,mBAAS,EAAC,IAAA,mBAAO,EAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,IAAA,wBAAc,EAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC;AAED,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,SAAgB,cAAc,CAAC,MAAmB,EAAE,IAAsB;IACxE,MAAM,IAAI,GAAG,IAAA,mBAAO,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAS,EAAE,GAAE,CAAC,CAAC,CAAC;IAEzC,OAAO,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,OAAO,CAAC,GAAG,aAAa,MAAM,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE;QAChF,MAAM,OAAO,GAAG,IAAA,kBAAW,EAAC,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;QACnE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;QAEtE,MAAM,SAAS,GAAsB,EAAE,CAAC;QACxC,MAAM,OAAO,GAAgB,EAAE,CAAC;QAChC,MAAM,OAAO,GAAsC,EAAE,CAAC;QACtD,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,OAAO,GAA8C,EAAE,CAAC;QAE9D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACpC,IAAI,OAAO,KAAK,SAAS;gBAAE,SAAS;YAEpC,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC9B,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;gBACrD,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,aAAa,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC7C,SAAS;YACX,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACxB,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;YACzD,CAAC;YAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YACzE,MAAM,OAAO,GAAG,IAAA,oBAAa,EAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,EAAE;gBACpE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;gBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;aAChF,CAAC,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YAE/D,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gBACvI,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC1D,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,eAAe,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gBAClD,SAAS;YACX,CAAC;YACD,IAAI,OAAO,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;gBACpC,MAAM,KAAK,GAAG,IAAA,mBAAY,EAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;gBACnE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;gBACzJ,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAC5B,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC;gBAClC,SAAS;YACX,CAAC;YAED,0DAA0D;YAC1D,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YAExI;;;;;;eAMG;YACH,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YACjD,IAAI,CAAC,IAAA,iBAAU,EAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;gBAC9B,MAAM,OAAO,GAAG,8BAA8B,MAAM,eAAe,IAAI,EAAE,CAAC;gBAC1E,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;gBACtH,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;gBACzC,SAAS;YACX,CAAC;YAED,IAAA,gBAAM,EAAC,OAAO,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;YACxD,MAAM,KAAK,GAAG,IAAA,mBAAY,EAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YACnE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACzJ,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,eAAe,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/reverify.d.ts

@@ -0,0 +1,41 @@
+import type { Evidence } from '@looply/core';
+import type { EvidenceLookup } from './evidence-cache';
+/**
+ * Re-verification triggers (DESIGN §7, §12 case 19).
+ *
+ * Cached evidence is a claim about one tree. DESIGN names exactly two things
+ * that age it: HEAD moving past more than N commits that touch the paths the
+ * evidence points at, and a discard. This module owns the first trigger as a
+ * pure decision over the cache's lookup result; the discard trigger lives in
+ * the round runner, which invalidates the cache entry so the next lookup here
+ * is a `miss`. Both funnel into the same answer: hand the implementer the
+ * cached file:line, or send the item back through verify first.
+ *
+ * The decision takes counting as an injected function (the real backend is
+ * `GitDriver.countCommitsTouching`), so every branch is testable without a
+ * repository.
+ */
+/**
+ * How many commits touching the evidence paths HEAD may move past before the
+ * evidence must be re-checked. DESIGN fixes the trigger but is silent on N; a
+ * constant rather than config, same reasoning as the zero-rejection alert
+ * threshold — a tunable staleness bound is how stale evidence gets tolerated.
+ * §12 case 19's forty-commit example must fire, so N stays well under 40 (the
+ * spec asserts this).
+ */
+export declare const REVERIFY_AFTER_COMMITS = 20;
+/** Count of commits in `fromSha..toSha` that touch any of `paths`. */
+export type CountCommitsTouching = (fromSha: string, toSha: string, paths: readonly string[]) => Promise<number>;
+export type ReverifyDecision = 
+/** The cached evidence is still trustworthy — put it in the implementation prompt. */
+{
+    kind: 'reuse';
+    evidence: Evidence[];
+}
+/** The item must go back through verify before it is picked. */
+ | {
+    kind: 'reverify';
+    reason: string;
+};
+export declare function decideReverify(lookup: EvidenceLookup, head: string, countCommitsTouching: CountCommitsTouching, threshold?: number): Promise<ReverifyDecision>;
+//# sourceMappingURL=reverify.d.ts.map

package/dist/reverify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reverify.d.ts","sourceRoot":"","sources":["../src/reverify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,KACrB,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,MAAM,MAAM,gBAAgB;AAC1B,sFAAsF;AACpF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;CAAE;AACzC,gEAAgE;GAC9D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,MAAM,EACZ,oBAAoB,EAAE,oBAAoB,EAC1C,SAAS,GAAE,MAA+B,GACzC,OAAO,CAAC,gBAAgB,CAAC,CAyC3B"}

package/dist/reverify.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVERIFY_AFTER_COMMITS = void 0;
+exports.decideReverify = decideReverify;
+/**
+ * Re-verification triggers (DESIGN §7, §12 case 19).
+ *
+ * Cached evidence is a claim about one tree. DESIGN names exactly two things
+ * that age it: HEAD moving past more than N commits that touch the paths the
+ * evidence points at, and a discard. This module owns the first trigger as a
+ * pure decision over the cache's lookup result; the discard trigger lives in
+ * the round runner, which invalidates the cache entry so the next lookup here
+ * is a `miss`. Both funnel into the same answer: hand the implementer the
+ * cached file:line, or send the item back through verify first.
+ *
+ * The decision takes counting as an injected function (the real backend is
+ * `GitDriver.countCommitsTouching`), so every branch is testable without a
+ * repository.
+ */
+/**
+ * How many commits touching the evidence paths HEAD may move past before the
+ * evidence must be re-checked. DESIGN fixes the trigger but is silent on N; a
+ * constant rather than config, same reasoning as the zero-rejection alert
+ * threshold — a tunable staleness bound is how stale evidence gets tolerated.
+ * §12 case 19's forty-commit example must fire, so N stays well under 40 (the
+ * spec asserts this).
+ */
+exports.REVERIFY_AFTER_COMMITS = 20;
+async function decideReverify(lookup, head, countCommitsTouching, threshold = exports.REVERIFY_AFTER_COMMITS) {
+    if (lookup.kind === 'hit') {
+        // Recorded at exactly this HEAD — nothing can have touched anything since.
+        return { kind: 'reuse', evidence: lookup.evidence };
+    }
+    if (lookup.kind === 'miss') {
+        return {
+            kind: 'reverify',
+            reason: 'no cached evidence — the item has not been verified (or a discard invalidated it)',
+        };
+    }
+    const paths = [...new Set(lookup.evidence.map((e) => e.path))];
+    if (paths.length === 0) {
+        // No paths means no commit can touch them, so the moved-HEAD trigger cannot
+        // fire by definition — an evidence-free confirmation ages only through the
+        // discard trigger. (This also keeps an empty pathspec away from rev-list,
+        // where it would count every commit — the opposite of the question.)
+        return { kind: 'reuse', evidence: lookup.evidence };
+    }
+    let touched;
+    try {
+        touched = await countCommitsTouching(lookup.cachedHead, head, paths);
+    }
+    catch (e) {
+        // The cached HEAD may no longer resolve — rebased away, gc'd, or a
+        // different clone. Freshness cannot be established, so fail toward
+        // re-checking, never toward handing over line numbers of unknown age.
+        return {
+            kind: 'reverify',
+            reason: `cannot count commits since ${lookup.cachedHead}: ${e.message}`,
+        };
+    }
+    if (touched > threshold) {
+        return {
+            kind: 'reverify',
+            reason: `${touched} commits since ${lookup.cachedHead} touched the evidence paths (threshold ${threshold})`,
+        };
+    }
+    return { kind: 'reuse', evidence: lookup.evidence };
+}
+//# sourceMappingURL=reverify.js.map

package/dist/reverify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reverify.js","sourceRoot":"","sources":["../src/reverify.ts"],"names":[],"mappings":";;;AA0CA,wCA8CC;AArFD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACU,QAAA,sBAAsB,GAAG,EAAE,CAAC;AAelC,KAAK,UAAU,cAAc,CAClC,MAAsB,EACtB,IAAY,EACZ,oBAA0C,EAC1C,YAAoB,8BAAsB;IAE1C,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAC1B,2EAA2E;QAC3E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACtD,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,mFAAmF;SAC5F,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,4EAA4E;QAC5E,2EAA2E;QAC3E,0EAA0E;QAC1E,qEAAqE;QACrE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACtD,CAAC;IAED,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,mEAAmE;QACnE,mEAAmE;QACnE,sEAAsE;QACtE,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,8BAA8B,MAAM,CAAC,UAAU,KAAM,CAAW,CAAC,OAAO,EAAE;SACnF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,GAAG,SAAS,EAAE,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,GAAG,OAAO,kBAAkB,MAAM,CAAC,UAAU,0CAA0C,SAAS,GAAG;SAC5G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;AACtD,CAAC"}

package/dist/round-records.d.ts

@@ -0,0 +1,65 @@
+import { type GateStepResult, type GateVerdict, type RoundOutcome } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+/**
+ * WHAT A ROUND ACTUALLY DID, read back out of the ledger.
+ *
+ * The ledger has always been write-only from this side: `LedgerStore` appends
+ * and projects a status, and nothing asked it what happened in a particular
+ * round. Phase 6C needs to, because the only honest machine-held answer to
+ * "was this goal delivered" is the round record itself — which item, which
+ * outcome, which commit, and which gate steps passed.
+ *
+ * READ-ONLY, and deliberately not a method on `LedgerStore`. That class is the
+ * only writer of `events.jsonl` in the repository and its own comment says so;
+ * adding a reader to it invites a future reader that also writes. This takes a
+ * filesystem and a path and returns data.
+ *
+ * Damage-tolerant for the same reason every other reader here is: a process
+ * killed mid-append leaves a partial final line, and discarding a whole history
+ * because its last line is short would be absurd.
+ *
+ * SAFE TO READ WHILE A RUN IS APPENDING. `events.jsonl` is append-only with a
+ * single writer, and rotation or compaction would already have broken
+ * `makeLedgerReplay`'s byte-count guard — so a read sees a prefix of the truth,
+ * never a rewritten one. A prefix can only make this answer "not yet", which is
+ * the safe direction.
+ */
+/** One round, joined from the two events that describe it. */
+export interface RoundRecord {
+    runId: string;
+    round: number;
+    itemId: string;
+    outcome: RoundOutcome;
+    /** The commit, when the round committed. Absent on a discarded or abandoned round. */
+    sha?: string;
+    /**
+     * The gate that permitted it, when one was recorded.
+     *
+     * Absent is NOT a pass. A round whose gate never reached the ledger proves
+     * nothing about what ran, and the caller treats it as unproven.
+     */
+    gate?: {
+        verdict: GateVerdict;
+        steps: GateStepResult[];
+    };
+}
+export type RoundRecordsOutcome = {
+    ok: true;
+    rounds: RoundRecord[];
+}
+/**
+ * The ledger could not be read. NOT the same as "it holds no rounds".
+ *
+ * Both once returned an empty list, on the reasoning that either way nothing
+ * could be proven. That was true while a failed proof was retryable; it stopped
+ * being true when a KEY 2 refusal became TERMINAL, because a file that was
+ * momentarily busy would then be laundered into "no round delivered any of
+ * this plan" — a sentence about the work, told to a person, on the strength
+ * of a read that never happened.
+ */
+ | {
+    ok: false;
+    because: string;
+};
+export declare function readRoundRecords(stateDir: string, fs: Pick<LedgerFs, 'readFile'>): Promise<RoundRecordsOutcome>;
+//# sourceMappingURL=round-records.d.ts.map

package/dist/round-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-records.d.ts","sourceRoot":"","sources":["../src/round-records.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;CAC1D;AAYD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,WAAW,EAAE,CAAA;CAAE;AACrC;;;;;;;;;GASG;GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CA+C9B"}

package/dist/round-records.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRoundRecords = readRoundRecords;
+const core_1 = require("@looply/core");
+/**
+ * `(runId, round)` — rounds are numbered per run, so neither half is a key alone.
+ *
+ * `#` because a run id is `run_` plus base32 and a round is a number, so neither
+ * can contain it and no two distinct pairs can collide on the joined string.
+ */
+function roundKey(runId, round) {
+    return `${runId}#${round}`;
+}
+async function readRoundRecords(stateDir, fs) {
+    let text;
+    try {
+        text = await fs.readFile(`${stateDir}/events.jsonl`);
+    }
+    catch (e) {
+        return { ok: false, because: `the run ledger could not be read (${e.message})` };
+    }
+    // Genuinely absent, or genuinely empty. Nothing has happened here yet, which
+    // IS an answer: no round delivered anything.
+    if (text === null || text.length === 0)
+        return { ok: true, rounds: [] };
+    const { events } = (0, core_1.parseLines)(text);
+    const gates = new Map();
+    const ended = new Map();
+    for (const e of events) {
+        if (e.kind === 'gate.result') {
+            const d = e.data;
+            gates.set(roundKey(e.runId, d.round), { verdict: d.verdict, steps: d.steps });
+            continue;
+        }
+        if (e.kind === 'round.ended') {
+            const d = e.data;
+            const record = {
+                runId: e.runId,
+                round: d.round,
+                itemId: d.itemId,
+                outcome: d.outcome,
+            };
+            if (d.sha !== undefined)
+                record.sha = d.sha;
+            // Last write wins on a duplicate `(runId, round)`, which the ledger's own
+            // contract says cannot happen — but a duplicated DELIVERY can, and taking
+            // the later copy of an identical event is the same answer either way.
+            ended.set(roundKey(e.runId, d.round), record);
+        }
+    }
+    // Joined after the walk rather than during it, because `gate.result` and
+    // `round.ended` are appended in that order for a committing round but the
+    // reader must not depend on having seen one before the other.
+    const out = [];
+    for (const [key, record] of ended) {
+        const gate = gates.get(key);
+        out.push(gate === undefined ? record : { ...record, gate });
+    }
+    return { ok: true, rounds: out };
+}
+//# sourceMappingURL=round-records.js.map

package/dist/round-records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"round-records.js","sourceRoot":"","sources":["../src/round-records.ts"],"names":[],"mappings":";;AAqEA,4CAkDC;AAvHD,uCAAoG;AA6CpG;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,KAAa,EAAE,KAAa;IAC5C,OAAO,GAAG,KAAK,IAAI,KAAK,EAAE,CAAC;AAC7B,CAAC;AAgBM,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,EAA8B;IAE9B,IAAI,IAAmB,CAAC;IACxB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,QAAQ,eAAe,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,qCAAsC,CAAW,CAAC,OAAO,GAAG,EAAE,CAAC;IAC9F,CAAC;IACD,6EAA6E;IAC7E,6CAA6C;IAC7C,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAExE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAA,iBAAU,EAAC,IAAI,CAAC,CAAC;IAEpC,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6D,CAAC;IACnF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE7C,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACjB,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YAC9E,SAAS;QACX,CAAC;QACD,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACjB,MAAM,MAAM,GAAgB;gBAC1B,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAC;YACF,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS;gBAAE,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;YAC5C,0EAA0E;YAC1E,0EAA0E;YAC1E,sEAAsE;YACtE,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,8DAA8D;IAC9D,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACnC,CAAC"}