looply-cli 0.0.0-stage → 0.2.0

package/dist/doctor.d.ts

@@ -0,0 +1,91 @@
+import type { AbortResult, CommandRunner } from './gate';
+import type { LooplyConfig } from './config';
+import type { ContainmentProbe } from './untrusted-exec';
+/**
+ * `looply doctor` — the interlocks and one full gate pass with **no agent call**
+ * (DESIGN §5.2), so a wrong `tsc` command is found in ninety seconds rather than
+ * at round 1 of an overnight run.
+ *
+ * This is deliberately not `runGate`. The gate skips `when:`-filtered steps
+ * against the diff and stops at the first red because later steps are
+ * uninformative about *this round*. Doctor answers a different question — does
+ * every configured command exist and run? — so every step runs (there is no
+ * diff to filter on) and a failure does not stop the pass: one doctor run
+ * should name every broken command, not the first one per invocation.
+ */
+export interface DoctorStepReport {
+    step: string;
+    run: string;
+    ok: boolean;
+    ms: number;
+    timedOut?: boolean;
+    /**
+     * The step NEVER RAN — the environment could not start it (`CommandResult.unavailable`).
+     * Not a verdict about the code, and a reader that needs one must not take `ok: false` for one.
+     */
+    unavailable?: boolean;
+    /** Command output, kept only on failure — that is when someone reads it. */
+    output?: string;
+}
+export interface DoctorReport {
+    /** Non-null when an interlock tripped; no step has run in that case. */
+    abort: AbortResult | null;
+    steps: DoctorStepReport[];
+    ok: boolean;
+    /**
+     * Whether this machine can contain untrusted execution at all, or null when
+     * nothing asked.
+     *
+     * 🔴 REPORTED, NOT ENFORCED — and it is reported because it was previously
+     * knowable and unknown. `AppContainerBackend.probe()` existed, was correct,
+     * and had NO CALLER anywhere: the one function that answers "is there a
+     * boundary on this machine" was never asked. A person on a platform with no
+     * AppContainer learned it from a gate step failing mid-run, if at all.
+     *
+     * It does not gate the doctor pass. A machine without containment cannot run
+     * a gate step at all — `run()` refuses rather than degrading — so the step
+     * failures below already say so loudly. What this adds is the REASON, before
+     * the failures, in one line.
+     */
+    containment: ContainmentProbe | null;
+}
+export interface DoctorDeps {
+    runner: CommandRunner;
+    /**
+     * Ask whether untrusted execution can be contained here.
+     *
+     * Optional so every existing caller and fixture keeps working, and absent
+     * means "nobody asked" rather than "no boundary" — two different facts, and
+     * only one of them is a finding.
+     */
+    probeContainment?: () => Promise<ContainmentProbe>;
+    /** Contents of an env file, or null when it does not exist (not an error). */
+    readEnvFile(path: string): string | null;
+    /** The live environment; values are matched against `rails.prod_patterns`. */
+    env: Readonly<Record<string, string | undefined>>;
+}
+export declare function runDoctorGate(cfg: LooplyConfig, deps: DoctorDeps): Promise<DoctorReport>;
+/**
+ * THE INTEGRATION REF, ASKED BEFORE A START IS SPENT FINDING OUT (M6-12).
+ *
+ * With `run.integration` on — by hand, or by the umbrella, which turns it on
+ * for every project under `machine.programme: { on: true }` — a run checks
+ * after each round that its base is still current against
+ * `looply/integration`. When that ref does not exist the check cannot answer
+ * and the run halts `aborted` after its first round (run-cmd's `baseStale`;
+ * `baseFreshness` → `uninitialised`). Correct — and found live in M6-11 by a
+ * placed run that spent its round to learn it, with doctor having said "all
+ * gate steps pass" moments before. Doctor now says it first.
+ *
+ * A WARNING, NOT A GATE FAILURE: creating the ref is the owner's act
+ * (`looply integrate --init <ref>`), and a project that has not chosen its
+ * base yet is not broken — its runs simply cannot converge until it does.
+ * `null` when integration is off, when nobody supplied a git to ask (the
+ * lane's candidate check has no business asking), or when the ref exists.
+ * A git that cannot answer is said out loud rather than read as "exists".
+ */
+export interface IntegrationRefGit {
+    refExists(ref: string): Promise<boolean>;
+}
+export declare function integrationRefWarning(cfg: LooplyConfig, git: IntegrationRefGit | undefined): Promise<string | null>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ;;;;;;;;;;;;;;OAcG;IACH,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnD,8EAA8E;IAC9E,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACzC,8EAA8E;IAC9E,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACnD;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CA6C9F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,iBAAiB,GAAG,SAAS,GACjC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB"}

package/dist/doctor.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctorGate = runDoctorGate;
+exports.integrationRefWarning = integrationRefWarning;
+const gate_1 = require("./gate");
+const integration_1 = require("./integration");
+async function runDoctorGate(cfg, deps) {
+    const envValues = [];
+    for (const file of cfg.rails.prodEnvFiles) {
+        const text = deps.readEnvFile(file);
+        if (text !== null)
+            envValues.push(text);
+    }
+    for (const value of Object.values(deps.env)) {
+        if (value)
+            envValues.push(value);
+    }
+    // Same interlock the run uses, with an empty diff: doctor proves the prod
+    // check itself, and a reachable production database must stop everything
+    // before a single command runs — exactly as it would mid-run.
+    /**
+     * Asked BEFORE the interlocks, so the answer survives an abort. A machine
+     * with no boundary is worth saying so on the way out, not only on the happy
+     * path — and a probe that failed would otherwise be reported as nothing.
+     */
+    const containment = deps.probeContainment
+        ? await deps.probeContainment().catch((e) => ({
+            available: false,
+            backend: 'unknown',
+            because: `the probe itself failed: ${e?.message ?? String(e)}`,
+        }))
+        : null;
+    const abort = (0, gate_1.checkInterlocks)({ changedPaths: [], rails: cfg.rails, envValues });
+    if (abort)
+        return { abort, steps: [], ok: false, containment };
+    const steps = [];
+    for (const step of cfg.gates) {
+        // The step's own timeout, identical to the gate's: a doctor pass that used
+        // a different budget would prove a run the real gate never executes.
+        const timeoutMs = (step.timeoutS ?? gate_1.DEFAULT_TIMEOUT_S) * 1000;
+        const r = await deps.runner(step.run, timeoutMs);
+        const report = { step: step.name, run: step.run, ok: r.ok, ms: r.ms };
+        if (r.timedOut)
+            report.timedOut = true;
+        if (r.unavailable === true)
+            report.unavailable = true;
+        if (!r.ok && r.output)
+            report.output = r.output;
+        steps.push(report);
+    }
+    return { abort: null, steps, ok: steps.every((s) => s.ok), containment };
+}
+async function integrationRefWarning(cfg, git) {
+    if (cfg.run.integration !== true)
+        return null;
+    if (git === undefined)
+        return null;
+    let exists;
+    try {
+        exists = await git.refExists(integration_1.INTEGRATION_BRANCH);
+    }
+    catch (e) {
+        return (`could not tell whether ${integration_1.INTEGRATION_BRANCH} exists (${e?.message ?? String(e)}) — ` +
+            'with run.integration on, a run that cannot tell will end aborted after its first round');
+    }
+    if (exists)
+        return null;
+    return (`run.integration is on and ${integration_1.INTEGRATION_BRANCH} does not exist — every run will end aborted after its ` +
+        'first round until it is created (looply integrate --init <ref>)');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/edge-approval.d.ts

@@ -0,0 +1,105 @@
+import { buildActionRequest, type ActionRequest, type DependsVerdict, type ProposedDependency, type TrustedActionContext } from '@looply/core';
+/**
+ * TURNING A JUDGED EDGE INTO A QUESTION FOR A PERSON.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE ONLY VERDICT THAT MAY BE FILED IS `accepted`, AND THAT IS THE FENCE'S
+ * ENTIRE PURPOSE.
+ *
+ * A stale edge, a refused one, or one nothing could be established about must
+ * never reach somebody's phone. The fence exists so a person is asked about
+ * edges that passed every check a machine can make — asking about the others
+ * would spend the one resource this system cannot replace, which is somebody's
+ * willingness to read the next question carefully.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE IDEMPOTENCY KEY IS THE FINGERPRINT, NOT A COUNTER OR A CLOCK.
+ *
+ * The same edge, at the same goal versions, read from the same source, is the
+ * same request — and must become at most one approval however many cadences
+ * propose it. A key derived from time would file a new question every tick for
+ * as long as the brain kept suggesting it, which is how an approval queue
+ * becomes something a person scrolls past.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⚠️ HOW MANY OF THESE CAN ARRIVE IS BOUNDED UPSTREAM, AND IT IS WORTH SAYING
+ * WHERE. `MAX_ASKS_PER_TICK` is 1: one NEW question to the brain per cadence,
+ * so at most one new edge proposal per cadence can exist to file. Nothing here
+ * needs its own throttle, and if that constant ever moves, this is the sentence
+ * that should be read again.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 FILING IS NOT APPROVING. Nothing in this module decides anything. It
+ * builds a request, hands it to the approvals surface, and stops.
+ */
+/** What this needs from the server, and nothing wider. */
+export interface EdgeApprovalCapability {
+    createApproval(projectId: string, input: {
+        clientRef: string;
+        actionRequest: unknown;
+        context?: {
+            goalId: string;
+            goalVersion: number;
+        };
+        validForMs?: number;
+    }): Promise<{
+        deduplicated: boolean;
+    }>;
+}
+export type FiledEdge = 
+/** A question is on record for a person. */
+{
+    readonly kind: 'filed';
+    readonly clientRef: string;
+    readonly display: string;
+    readonly deduplicated: boolean;
+}
+/** It was not `accepted`, so it is not something to ask anybody about. */
+ | {
+    readonly kind: 'not-asked';
+    readonly because: string;
+}
+/**
+ * 🔴 THE REQUEST COULD NOT EVEN BE BUILT. Distinct from `not-asked`: that one
+ * is a judgement about the edge, and this is a shape the action registry
+ * refuses. A caller that reported them alike would tell somebody their
+ * proposal was stale when the truth is that it was malformed.
+ */
+ | {
+    readonly kind: 'unbuildable';
+    readonly because: string;
+}
+/** The surface could not be reached. Nothing was established, and nothing filed. */
+ | {
+    readonly kind: 'unreachable';
+    readonly because: string;
+};
+/**
+ * The action an accepted edge becomes.
+ *
+ * ⚠️ `requestedBy` IS THE CALLER'S, AND A MACHINE IS RECORDED AS A MACHINE.
+ * This is the two-key rule's first key: a machine raises the request and a
+ * person turns the second. Passing a person's actor here would be a machine
+ * signing somebody else's name on the thing they are about to be asked to
+ * approve.
+ */
+export declare function edgeActionFor(edge: ProposedDependency, ctx: TrustedActionContext): ReturnType<typeof buildActionRequest>;
+/**
+ * ⚠️ DERIVED FROM THE FINGERPRINT, WHICH ALREADY CONTAINS EVERY FIELD THAT
+ * MATTERS — both goals, both versions, the source and its hash. Re-deriving a
+ * key from those fields by hand would be a second definition of "the same
+ * request" that could drift from the first.
+ */
+export declare function edgeClientRef(request: ActionRequest): string;
+/**
+ * File one judged edge, if it is one anybody should be asked about.
+ */
+export declare function fileEdge(edge: ProposedDependency, verdict: DependsVerdict, ctx: TrustedActionContext, approvals: EdgeApprovalCapability): Promise<FiledEdge>;
+/**
+ * One line for a person.
+ *
+ * 🔴 A FILED EDGE SAYS IT IS WAITING, NOT THAT IT HAPPENED. The word "approval"
+ * on its own reads to a tired person as a thing that was approved.
+ */
+export declare function describeFiled(filed: FiledEdge): string;
+//# sourceMappingURL=edge-approval.d.ts.map

package/dist/edge-approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-approval.d.ts","sourceRoot":"","sources":["../src/edge-approval.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAElB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,OAAO,CAAC;QACvB,OAAO,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;QAClD,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GACA,OAAO,CAAC;QAAE,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,SAAS;AACnB,4CAA4C;AAC1C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAAE;AAClH,0EAA0E;GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC1D;;;;;GAKG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC5D,oFAAoF;GAClF;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,oBAAoB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAmBxH;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,oBAAoB,EACzB,SAAS,EAAE,sBAAsB,GAChC,OAAO,CAAC,SAAS,CAAC,CAmCpB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAatD"}

package/dist/edge-approval.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.edgeActionFor = edgeActionFor;
+exports.edgeClientRef = edgeClientRef;
+exports.fileEdge = fileEdge;
+exports.describeFiled = describeFiled;
+const core_1 = require("@looply/core");
+/**
+ * The action an accepted edge becomes.
+ *
+ * ⚠️ `requestedBy` IS THE CALLER'S, AND A MACHINE IS RECORDED AS A MACHINE.
+ * This is the two-key rule's first key: a machine raises the request and a
+ * person turns the second. Passing a person's actor here would be a machine
+ * signing somebody else's name on the thing they are about to be asked to
+ * approve.
+ */
+function edgeActionFor(edge, ctx) {
+    return (0, core_1.buildActionRequest)('goal.depends', {
+        goalId: edge.goalId,
+        dependsOnId: edge.dependsOnId,
+        goalVersion: edge.readAt.goalVersion,
+        dependsOnVersion: edge.readAt.dependsOnVersion,
+        sourceId: edge.readAt.sourceId,
+        sourceSha: edge.readAt.sourceSha,
+    }, ctx, 
+    /**
+     * ⚠️ THE MODEL'S SENTENCE TRAVELS AS A NOTE, WHICH CARRIES NO WEIGHT. It is
+     * outside the fingerprint by the action registry's design: approving means
+     * approving the action, not the wording of its excuse.
+     */
+    edge.because);
+}
+/**
+ * ⚠️ DERIVED FROM THE FINGERPRINT, WHICH ALREADY CONTAINS EVERY FIELD THAT
+ * MATTERS — both goals, both versions, the source and its hash. Re-deriving a
+ * key from those fields by hand would be a second definition of "the same
+ * request" that could drift from the first.
+ */
+function edgeClientRef(request) {
+    return `edge-${request.fingerprint.slice(0, 32)}`;
+}
+/**
+ * File one judged edge, if it is one anybody should be asked about.
+ */
+async function fileEdge(edge, verdict, ctx, approvals) {
+    if (verdict.kind !== 'accepted') {
+        return {
+            kind: 'not-asked',
+            because: verdict.kind === 'unmeasurable'
+                ? `nothing was established about it (${verdict.because})`
+                : `it is ${verdict.kind}: ${verdict.because}`,
+        };
+    }
+    const built = edgeActionFor(edge, ctx);
+    if (!built.ok)
+        return { kind: 'unbuildable', because: `${built.code}: ${built.because}` };
+    const clientRef = edgeClientRef(built.request);
+    try {
+        /**
+         * 🔴 FILED UNDER THE GOAL THAT WILL WAIT, OR NOTHING CAN EVER CARRY IT OUT.
+         * Runs find their approvals by goal@version; an edge filed with no pursuit
+         * was approved and then claimed by nobody, for ever. The pursuit is the
+         * action's own goal@version — the server accepts it without a run for
+         * `goal.depends` only, and only when it is exactly that (F12). It also
+         * HOLDS that goal while the question is open: a pursuit with a pending
+         * approval is waiting on a person, so it does not start work that the
+         * edge might be about to make premature.
+         */
+        const r = await approvals.createApproval(ctx.projectId, {
+            clientRef,
+            actionRequest: built.request,
+            context: { goalId: edge.goalId, goalVersion: edge.readAt.goalVersion },
+        });
+        return { kind: 'filed', clientRef, display: (0, core_1.displayAction)(built.request), deduplicated: r.deduplicated };
+    }
+    catch (e) {
+        return { kind: 'unreachable', because: `the approvals surface could not be reached (${e.message})` };
+    }
+}
+/**
+ * One line for a person.
+ *
+ * 🔴 A FILED EDGE SAYS IT IS WAITING, NOT THAT IT HAPPENED. The word "approval"
+ * on its own reads to a tired person as a thing that was approved.
+ */
+function describeFiled(filed) {
+    switch (filed.kind) {
+        case 'filed':
+            return filed.deduplicated
+                ? `already waiting for a decision: ${filed.display}`
+                : `waiting for your decision: ${filed.display}`;
+        case 'not-asked':
+            return `not put to anybody: ${filed.because}`;
+        case 'unbuildable':
+            return `could not be made into a request: ${filed.because}`;
+        case 'unreachable':
+            return `${filed.because}. Nothing was filed, and nothing was decided.`;
+    }
+}
+//# sourceMappingURL=edge-approval.js.map

package/dist/edge-approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-approval.js","sourceRoot":"","sources":["../src/edge-approval.ts"],"names":[],"mappings":"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"}

package/dist/evidence-cache.d.ts

@@ -0,0 +1,45 @@
+import type { Evidence } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+export type EvidenceLookup = 
+/** Recorded at exactly this HEAD — safe to put in the implementation prompt. */
+{
+    kind: 'hit';
+    evidence: Evidence[];
+}
+/** Recorded at another HEAD; the caller owns the reuse-or-reverify decision. */
+ | {
+    kind: 'moved';
+    cachedHead: string;
+    evidence: Evidence[];
+} | {
+    kind: 'miss';
+};
+export declare class EvidenceCache {
+    private readonly stateDir;
+    private readonly fs;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private entries;
+    private opened;
+    constructor(stateDir: string, fs: LedgerFs);
+    private get cachePath();
+    /**
+     * Load whatever is on disk. Missing file → empty cache (first run); corrupt
+     * file → loud failure, same rationale as the queue store: the file only ever
+     * lands whole, so corrupt means something else touched it, and starting empty
+     * would throw away a night of verification the next persist makes permanent.
+     */
+    open(): Promise<void>;
+    /**
+     * Record a confirmed item's evidence at the HEAD it was verified against.
+     * One entry per item: a re-verify at a new HEAD replaces the old claim —
+     * keeping both would let a later lookup "hit" on a tree that no longer exists.
+     */
+    put(itemId: string, head: string, evidence: readonly Evidence[]): Promise<void>;
+    lookup(itemId: string, head: string): EvidenceLookup;
+    /** Drop an item's entry. §12 case 19: a discard always invalidates — the round may have mangled the very paths the evidence points at. */
+    invalidate(itemId: string): Promise<void>;
+    private assertOpened;
+    private persist;
+}
+//# sourceMappingURL=evidence-cache.d.ts.map

package/dist/evidence-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../src/evidence-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA6B/C,MAAM,MAAM,cAAc;AACxB,gFAAgF;AAC9E;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;CAAE;AACvC,gFAAgF;GAC9E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,qBAAa,aAAa;IAQtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IARrB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,MAAM,CAAS;gBAGJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ;IAG/B,OAAO,KAAK,SAAS,GAEpB;IAED;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc;IASpD,0IAA0I;IACpI,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,OAAO,CAAC,YAAY;YAMN,OAAO;CAWtB"}

package/dist/evidence-cache.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCache = void 0;
+class EvidenceCache {
+    stateDir;
+    fs;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    entries = new Map();
+    opened = false;
+    constructor(stateDir, fs) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+    }
+    get cachePath() {
+        return `${this.stateDir}/evidence.json`;
+    }
+    /**
+     * Load whatever is on disk. Missing file → empty cache (first run); corrupt
+     * file → loud failure, same rationale as the queue store: the file only ever
+     * lands whole, so corrupt means something else touched it, and starting empty
+     * would throw away a night of verification the next persist makes permanent.
+     */
+    async open() {
+        await this.fs.mkdir(this.stateDir);
+        const text = await this.fs.readFile(this.cachePath);
+        if (text !== null) {
+            const parsed = JSON.parse(text);
+            this.entries = new Map(Object.entries(parsed));
+        }
+        this.opened = true;
+    }
+    /**
+     * Record a confirmed item's evidence at the HEAD it was verified against.
+     * One entry per item: a re-verify at a new HEAD replaces the old claim —
+     * keeping both would let a later lookup "hit" on a tree that no longer exists.
+     */
+    async put(itemId, head, evidence) {
+        this.assertOpened();
+        if (itemId === '' || head === '') {
+            // An empty half of the key would silently collide every caller that
+            // forgot to thread it — better to fail at the write than mix items up.
+            throw new Error('evidence cache: itemId and head must be non-empty');
+        }
+        this.entries.set(itemId, { head, evidence: copyEvidence(evidence) });
+        await this.persist();
+    }
+    lookup(itemId, head) {
+        const entry = this.entries.get(itemId);
+        if (entry === undefined)
+            return { kind: 'miss' };
+        if (entry.head !== head) {
+            return { kind: 'moved', cachedHead: entry.head, evidence: copyEvidence(entry.evidence) };
+        }
+        return { kind: 'hit', evidence: copyEvidence(entry.evidence) };
+    }
+    /** Drop an item's entry. §12 case 19: a discard always invalidates — the round may have mangled the very paths the evidence points at. */
+    async invalidate(itemId) {
+        this.assertOpened();
+        if (this.entries.delete(itemId)) {
+            await this.persist();
+        }
+    }
+    assertOpened() {
+        if (!this.opened) {
+            throw new Error('evidence cache: write before open() — would overwrite the cache on disk');
+        }
+    }
+    async persist() {
+        // Temp-then-rename, same contract as status.json and queue.json.
+        // The temp name is PRIVATE TO THIS WRITER. A shared `evidence.json.tmp` is
+        // two processes writing one path: the second truncates and rewrites what
+        // the first is midway through, and then both rename it into place. The
+        // rename is atomic and the file it renames is a splice of two writes, and
+        // nothing downstream can tell.
+        const tmp = `${this.cachePath}.${process.pid}.${(EvidenceCache.writes += 1)}.tmp`;
+        await this.fs.writeFile(tmp, JSON.stringify(Object.fromEntries(this.entries), null, 2) + '\n');
+        await this.fs.rename(tmp, this.cachePath);
+    }
+}
+exports.EvidenceCache = EvidenceCache;
+/**
+ * Copies on the way in and out: the cache holds a *record* of what verify saw,
+ * and a caller mutating the array it handed over (or got back) must not be able
+ * to rewrite that record without going through `put`.
+ */
+function copyEvidence(evidence) {
+    return evidence.map((e) => ({ ...e }));
+}
+//# sourceMappingURL=evidence-cache.js.map

package/dist/evidence-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-cache.js","sourceRoot":"","sources":["../src/evidence-cache.ts"],"names":[],"mappings":"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"}