@eir-labs/coltrane 0.4.1 → 0.5.1

package/dist/src/reuse.js

@@ -0,0 +1,215 @@
+// Reuse a sealed output instead of re-deriving it.
+//
+// ONE idea, two ranges. A gig CHECKPOINT lets a failed run restart from the phase it died
+// on instead of from zero (reuse across attempts at the same gig); a chair-level REUSE CACHE
+// lets a chair be served from a prior gig's sealed output instead of invoking the model
+// (reuse across gigs). Both answer the same question — "is there an existing sealed output
+// that stands in for the one I am about to pay to derive?" — and both live or die on the
+// same discipline: an exact, defensible key, and a refusal to serve anything that would not
+// pass the seal boundary today.
+//
+// WHY THIS IS NOT MERELY AN OPTIMISATION. Substituting a sealed output means the artifact an
+// operator acts on was produced under conditions that are no longer visible in the run. If
+// the genome moved between the two, the provenance chain silently splices two different
+// systems together: sealed outputs from run A consumed by chairs from genome B, with nothing
+// in `input_shas`, `genome_hash` or `run_fingerprint` recording that it happened. So every
+// substitution here is gated on a stated IDENTITY, and every substitution that happens is
+// REPORTED. A silent saving is indistinguishable from a bug.
+//
+// THE GOVERNING ASYMMETRY (borrowed, deliberately, from the downstream precedent in
+// grant-writing-coltrane's `dashboard/src/lib/requirements-cache.ts`): a MISS IS FREE — it
+// costs the cold run that would have happened anyway. A WRONG HIT IS NOT. Every ambiguous
+// case below therefore resolves to "do the work".
+//
+// PURITY. Key derivation and entry validation are pure functions of their arguments — no
+// clock, no filesystem, no registry handle. The file-backed stores at the bottom are the only
+// I/O. That split is what makes the correctness half exhaustively testable.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeFileAtomic } from "./fs_atomic.js";
+import { sha256Hex, canonJson } from "./canonical_form.js";
+/**
+ * Bump when the key LAYOUT changes (a new component, a different framing). Old keys then
+ * simply stop being addressable, which is the correct outcome: a key computed under a
+ * different layout is not a weaker match, it is a different question.
+ */
+export const REUSE_KEY_VERSION = "cr1";
+/** Bump when the on-disk checkpoint shape changes. A checkpoint of another version is refused. */
+export const CHECKPOINT_SCHEMA_VERSION = 1;
+/** Bump when the on-disk reuse-entry shape changes. An entry of another version is a miss. */
+export const REUSE_SCHEMA_VERSION = 1;
+export class ReuseStoreError extends Error {
+}
+/**
+ * Fingerprint one type definition: its core, its required list, and its whole schema.
+ *
+ * Deliberately OVER-SENSITIVE — any edit to the type, including a nested one, invalidates
+ * every entry sealed under the old shape. Type edits are rare; a miss costs one cold
+ * invocation; serving an object the current seal validator would reject costs a run that
+ * dies at the terminal phase. The trade is not close.
+ */
+export function typeShapeFingerprint(def) {
+    return sha256Hex(canonJson({
+        extends: def.extends,
+        required: [...(def.required_fields ?? [])].sort(),
+        schema: def.schema ?? null,
+    }));
+}
+/**
+ * Fold every producer definition a run depends on into one hash.
+ *
+ * Whole agent definitions, plus each resolved skill's verified `code_hash` — not the slug,
+ * which is precisely what an edit-under-a-stable-slug leaves unchanged.
+ */
+export function producersSha(input) {
+    return sha256Hex(canonJson({
+        agents: input.agents,
+        skills: [...(input.skills ?? [])]
+            .map((s) => ({ slug: s.slug, code_hash: s.code_hash }))
+            .sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0)),
+    }));
+}
+export function runIdentityMismatch(a, b) {
+    const out = [];
+    for (const k of Object.keys(a)) {
+        if (a[k] !== b[k])
+            out.push(`${k}: checkpoint="${a[k]}" current="${b[k]}"`);
+    }
+    return out;
+}
+/**
+ * The cache key. Length-prefixed framing so no component can forge a delimiter and
+ * masquerade as a different key layout.
+ *
+ * NOT in the key: the TYPE FINGERPRINTS of the sealed outputs. Those ride on the ENTRY and
+ * are re-checked on read. Putting them in the key (as the downstream precedent does) would
+ * make a stale entry unaddressable — safe, but a SILENT miss, indistinguishable from
+ * never-cached. This engine has spent a lot of effort making refusals say why they happened,
+ * and the entry-side check gives a stale entry a name (`type-fingerprint-mismatch`) instead
+ * of a shrug. It is equally safe here because, unlike that precedent, every injection also
+ * crosses the real seal boundary before anything becomes durable.
+ */
+export function reuseCacheKey(input) {
+    const frame = (...parts) => parts.map((p) => `${p.length}:${p}`).join("|");
+    return sha256Hex(frame(REUSE_KEY_VERSION, input.canonical_form_version, input.standard_slug, input.phase, canonJson(input.chair), canonJson(input.agent ?? null), canonJson(input.skill_provenance ?? null), canonJson([...input.skills].map((s) => [s.slug, s.version, s.code_hash]).sort()), canonJson([...input.input_shas].sort()), input.gig_input_sha, input.model_version, input.depth, canonJson([...input.output_types].sort())));
+}
+/**
+ * Is this entry still safe to serve — on the evidence available WITHOUT touching the store?
+ *
+ * This is the cheap half of the guard. The authoritative half is that every injected output
+ * is re-validated through `OutputStore.validateWrite` and then re-sealed through
+ * `OutputStore.write`, so it crosses exactly the boundary a fresh output crosses: the #263
+ * core-agreement check, the registry schema, and the #227/#228 core substance floor. Nothing
+ * is injected that a fresh seal would have refused.
+ *
+ * Both halves exist because they fail in different directions. The fingerprint catches a
+ * genome edit BEFORE any data is touched and can name it. The seal catches everything else —
+ * a hand-edited entry, an entry written by an older engine whose substance floor was looser,
+ * a registry that resolves the type to a different core than it did. Neither subsumes the
+ * other, and the expensive one is the one that must not be skipped.
+ */
+export function checkReuseEntry(entry, fingerprintOf) {
+    if (entry.schema_version !== REUSE_SCHEMA_VERSION) {
+        return { ok: false, reason: "schema-version", detail: `entry is v${entry.schema_version}, engine reads v${REUSE_SCHEMA_VERSION}` };
+    }
+    if (!Array.isArray(entry.outputs) || entry.outputs.length === 0) {
+        // A chair that sealed nothing is legal (#243, every promised type optional) but it is not
+        // cacheable: "sealed nothing" and "was never cached" are the same bytes, so serving it
+        // would be asserting a fact the entry cannot carry.
+        return { ok: false, reason: "empty-entry", detail: "entry records no sealed outputs" };
+    }
+    for (const o of entry.outputs) {
+        const now = fingerprintOf(o.domain_type);
+        if (now === "") {
+            // A cache that cannot check its entries must not serve them.
+            return { ok: false, reason: "type-unfingerprintable", detail: `the registry cannot describe "${o.domain_type}"` };
+        }
+        if (now !== o.type_fingerprint) {
+            return { ok: false, reason: "type-fingerprint-mismatch", detail: `"${o.domain_type}" has changed shape since this entry was sealed` };
+        }
+    }
+    return { ok: true };
+}
+// ───────────────────────────────────────────────────────────────────────────────
+// File-backed stores
+// ───────────────────────────────────────────────────────────────────────────────
+// Write-then-rename. A torn checkpoint would be read as damage and refuse a resume that was,
+// in fact, resumable — the failure mode a partial `appendFileSync` would introduce.
+//
+// Shared with the genome writer (src/fs_atomic.ts), which needed the same guarantee and did not
+// have it. Two implementations of one concern, one documented and one absent, is how the two
+// identity gates in this file came to disagree.
+const writeAtomic = writeFileAtomic;
+function readJsonFile(file) {
+    if (!fs.existsSync(file))
+        return undefined;
+    const text = fs.readFileSync(file, "utf8");
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw new ReuseStoreError(`"${file}" is unreadable: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** Checkpoints under `<dir>/checkpoints/<gig_id>.json`, alongside `outputs/` and `refs/`. */
+export function createCheckpointStore(persistDir) {
+    const dir = path.join(persistDir, "checkpoints");
+    return {
+        read(gig_id) {
+            // A gig id reaches this from a caller's argument; it must not be able to name a path.
+            if (!/^[A-Za-z0-9._-]+$/.test(gig_id))
+                return undefined;
+            return readJsonFile(path.join(dir, `${gig_id}.json`));
+        },
+        write(cp) {
+            writeAtomic(path.join(dir, `${cp.gig_id}.json`), JSON.stringify(cp));
+        },
+        remove(gig_id) {
+            // Same path guard as read(): a gig id arrives from a caller's argument and must not be
+            // able to name a path. Doubly so here, where the operation DELETES.
+            if (!/^[A-Za-z0-9._-]+$/.test(gig_id))
+                return;
+            try {
+                fs.rmSync(path.join(dir, `${gig_id}.json`), { force: true });
+            }
+            catch { /* best-effort */ }
+        },
+    };
+}
+/** Reuse entries under `<dir>/reuse/<cache_key>.json`. Keys are sha256 hex — flat is fine. */
+export function createReuseStore(persistDir) {
+    const dir = path.join(persistDir, "reuse");
+    return {
+        get(cache_key) {
+            if (!/^[0-9a-f]{64}$/.test(cache_key))
+                return undefined;
+            return readJsonFile(path.join(dir, `${cache_key}.json`));
+        },
+        put(entry) {
+            writeAtomic(path.join(dir, `${entry.cache_key}.json`), JSON.stringify(entry));
+        },
+    };
+}
+/** An in-memory pair for tests and for a caller that wants reuse within one process. */
+export function createMemoryCheckpointStore() {
+    const m = new Map();
+    return {
+        read: (id) => {
+            const raw = m.get(id);
+            return raw === undefined ? undefined : JSON.parse(raw);
+        },
+        write: (cp) => void m.set(cp.gig_id, JSON.stringify(cp)),
+        remove: (id) => void m.delete(id),
+    };
+}
+export function createMemoryReuseStore() {
+    const m = new Map();
+    return {
+        get: (k) => {
+            const raw = m.get(k);
+            return raw === undefined ? undefined : JSON.parse(raw);
+        },
+        put: (e) => void m.set(e.cache_key, JSON.stringify(e)),
+    };
+}
+//# sourceMappingURL=reuse.js.map

package/dist/src/reuse.js.map

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

package/dist/src/runtime.d.ts

@@ -1,4 +1,5 @@
 import type { Standard, Agent, Chair } from "./composition.js";
+import { type CheckpointStore, type ReuseStore } from "./reuse.js";
 import type { OutputStore, OutputRecord } from "./outputs.js";
 import { type Ledger, type GigUsage } from "./ledger.js";
 import type { Depth } from "./pricing.js";
@@ -62,6 +63,29 @@ export type GigProgressEvent = {
     phase: string;
     role: string;
     event: AgentStreamEvent;
+} | {
+    type: "gig_resumed";
+    from_gig_id: string;
+    roles: string[];
+    outputs: number;
+} | {
+    type: "chair_skipped";
+    phase: string;
+    role: string;
+    /** "resume" — restored from this gig's own checkpoint. "reuse" — a prior gig's output. */
+    reason: "resume" | "reuse";
+    source_gig_id: string;
+    output_types: string[];
+    cache_key?: string;
+}
+/** A cache entry was FOUND and refused. A silent refusal is as opaque as a silent hit. */
+ | {
+    type: "reuse_rejected";
+    phase: string;
+    role: string;
+    cache_key: string;
+    reason: string;
+    detail?: string;
 } | {
     type: "gig_complete";
     outputs: number;
@@ -118,10 +142,10 @@ export interface RunDeps {
      * signal is threaded into every AgentInvocationContext, so an invoker that wires it to its
      * subprocess also stops the in-flight chair. Absent = an uncancellable run (the v0 shape).
      *
-     * Known bound: a SKILL-backed chair runs `spawnSync` (src/skill_subprocess.ts), which
-     * blocks the event loop, so an abort delivered while one is executing is not even RECEIVED
-     * until it returns. Skill chairs are therefore a hard uncancellable window of up to their
-     * declared `meta.timeout_ms` (default 120s). Deliberate for now — see #253.
+     * Skill chairs are cancellable too (#253). They used to run `spawnSync`, which blocks the
+     * event loop, so an abort delivered during one was not even RECEIVED until it returned —
+     * a hard uncancellable window of up to the skill's `meta.timeout_ms`, 120s by default.
+     * `executeSkillAsync` spawns without blocking and SIGKILLs on the signal.
      */
     signal?: AbortSignal | undefined;
     /**
@@ -129,6 +153,49 @@ export interface RunDeps {
      * the thing that actually spends. Absent = each agent's own `depth_profile` stands.
      */
     depth?: Depth | undefined;
+    /**
+     * Durable per-gig checkpoints. When wired, the runtime records each completed chair's sealed
+     * outputs (id + content_sha + type fingerprint) after every dispatch batch, so a run that
+     * dies at phase 5 can later be resumed instead of restarting from zero.
+     *
+     * WRITING is automatic; ACTING on it is not. That asymmetry is deliberate and it is the only
+     * one that works: a checkpoint you have to opt into BEFORE the failure is a checkpoint you
+     * never have. Recording a fact changes no behaviour; `resume_from` is what changes behaviour,
+     * and it is explicit.
+     *
+     * Absent = no checkpoints written, and `resume_from` is refused.
+     */
+    checkpoints?: CheckpointStore | undefined;
+    /**
+     * Resume the named gig. The run CONTINUES that gig — same `gig_id` — rather than minting a
+     * new one, because the outputs it restores already carry that id and `OutputStore.trace`
+     * scopes the provenance walk to a single gig. A fresh id would truncate every restored
+     * ancestor out of the chain, which is the opposite of what a resume is for.
+     *
+     * FAILURE POSTURE: a resume that cannot be honoured THROWS `ResumeRefused` and spends
+     * nothing. It never quietly falls back to a cold run. `resume_from` is a claim about a
+     * specific prior run; if the claim is false the caller is wrong about the world and needs to
+     * be told. And the "harmless" alternative is not harmless: a silent cold run charges the
+     * full price and returns a reply indistinguishable from a resume that worked, so the cost
+     * surprise is also an UNOBSERVABLE one. Dropping the flag and re-dispatching is one call
+     * away; noticing a silent $6 is not.
+     */
+    resume_from?: string | undefined;
+    /**
+     * The chair-level reuse cache. Presence IS the opt-in — the runtime never constructs one —
+     * and it enables BOTH reads and writes.
+     *
+     * Writes are gated by the same flag on purpose. This store is cross-gig by construction, so
+     * populating it is itself the decision that run A's sealed outputs may stand in for run B's
+     * work. That is a decision, not a side effect of having run something. The cost is that the
+     * first opted-in run only populates; the second one hits.
+     *
+     * FAILURE POSTURE, and it differs from resume's: a found-but-unusable entry is REPORTED and
+     * the chair does the work. `reuse` names no specific prior run — "no valid entry" is a
+     * normal outcome of a lookup, not a falsified premise — so the honest response is a miss,
+     * loudly recorded in `GigResult.reuse.rejected`, not a dead run.
+     */
+    reuse?: ReuseStore | undefined;
 }
 /**
  * Per-gig cost-budget input. Honors budget-state.json schema (PR #56). Only
@@ -202,6 +269,63 @@ export interface BudgetState {
      */
     settled_usd: number;
 }
+/** One chair that did not run, and what stood in for it. */
+export interface SkippedChair {
+    phase: string;
+    role: string;
+    reason: "resume" | "reuse";
+    /** The gig whose sealed output was used. Equal to this gig's id for a resume. */
+    source_gig_id: string;
+    output_types: string[];
+    /** The content_shas served. Identical to what a fresh derivation would have sealed. */
+    content_shas: string[];
+    /** reuse only — the key that matched, so an operator can reason about WHY it matched. */
+    cache_key?: string;
+}
+export interface GigResumeReport {
+    from_gig_id: string;
+    /** When the checkpoint this resume read was last written. */
+    checkpoint_at: string;
+    roles: Array<{
+        phase: string;
+        role: string;
+        output_types: string[];
+    }>;
+    outputs_restored: number;
+    /**
+     * What the earlier attempt(s) had spent when the checkpoint was written. Deliberately kept
+     * OUT of `GigResult.usage`: #235/#236 made `usage` mean "what THIS run actually captured",
+     * and widening it to "what the gig cost across attempts" would undo that. Two numbers, both
+     * true, reported separately. Absent when the earlier attempt captured no usage.
+     */
+    prior_usage?: unknown;
+}
+export interface GigReuseReport {
+    /** Chairs served from a prior gig's sealed output. */
+    hits: Array<{
+        phase: string;
+        role: string;
+        cache_key: string;
+        source_gig_id: string;
+        output_types: string[];
+    }>;
+    /** Entries that were FOUND and refused. Never a silent miss — a stale entry gets a name. */
+    rejected: Array<{
+        phase: string;
+        role: string;
+        cache_key: string;
+        reason: string;
+        detail?: string;
+    }>;
+    /** Entries written this run. */
+    writes: number;
+    /** Entries that could not be written. Not fatal — the run is unaffected — but not silent. */
+    write_errors: Array<{
+        phase: string;
+        role: string;
+        reason: string;
+    }>;
+}
 export interface GigResult {
     gig_id: string;
     standard_slug: string;
@@ -235,6 +359,22 @@ export interface GigResult {
     budget_state?: BudgetState;
     /** Settled model spend (#195). Present when ≥1 real model invocation ran this gig. */
     usage?: GigUsage;
+    /**
+     * Chairs that did not run because a sealed output stood in for them. Present only when
+     * something was actually skipped — so its ABSENCE means every chair ran, and its presence
+     * is the run stating plainly that part of this manifest was recalled rather than derived.
+     */
+    skipped?: readonly SkippedChair[];
+    /** Present when this run resumed a prior attempt at the same gig. */
+    resumed_from?: GigResumeReport;
+    /** Present when the reuse cache was wired, whether or not anything hit. */
+    reuse?: GigReuseReport;
+    /**
+     * The checkpoint store was wired and could not be written. The run is unaffected and
+     * complete — but it is NOT resumable, and an operator who believes otherwise will find out
+     * at the worst possible moment.
+     */
+    checkpoint_error?: string;
 }
 /**
  * #236 — settled spend used to be discarded on every failed gig: `usage` was written only on
@@ -247,6 +387,19 @@ export declare function partialGigUsage(e: unknown): GigUsage | undefined;
 export declare function partialBudgetState(e: unknown): BudgetState | undefined;
 export declare class RuntimeError extends Error {
 }
+/**
+ * A resume was requested and cannot be honoured. Thrown BEFORE any chair is prepared, so a
+ * refused resume costs nothing.
+ *
+ * Distinct from RuntimeError because it is not a crash and not a composition defect — it is
+ * the engine declining to splice two runs together. `drift` names exactly which identity
+ * fields disagree, so "it refused" is never the whole answer an operator gets.
+ */
+export declare class ResumeRefused extends Error {
+    readonly gig_id: string;
+    readonly drift: readonly string[];
+    constructor(gig_id: string, why: string, drift?: readonly string[]);
+}
 /**
  * Raised when a gig is cancelled through `RunDeps.signal` (#249). Distinct from RuntimeError
  * so a caller can tell "an operator stopped this" from "this crashed" — #251's point that a