bareloop 0.5.1 → 0.7.0

package/src/validate.js

@@ -1,48 +1,16 @@
-// Workflow-config validator — a deterministic predicate that runs before any
-// tokens burn (PRD §4: schema-validated, config-red before tokens). Every
-// failure is a distinct named red { code, path, detail } so the spine can carry
-// `config-red: missing-required:gate.writeScope`. An invalid config is a red,
-// not a crash: this module never throws on bad input.
+// The shared validation primitives — the fence transform, containment, the
+// secret-shape inventory, and the small type guards. Both validators
+// (`validateJob`, `validatePlan`) go through this ONE module, because a scope
+// that validated under one transform and enforced under another is the F9
+// red-class: green at the gate, gate-red on every write.
 //
-// The verb vocabulary is BOUND from litectx (adaptlearn F1 — consume, don't
-// build; design law #10); this schema exposes the adaptlearn-proven 4-verb
-// subset. The close and the provider are deliberately not expressible here:
-// they arrive as unknown-field reds — the shell owns both (design law #1).
+// This file WAS the config-v1 workflow-config validator. config-v1 died in F22
+// (of its 7 knobs only `loop.shape` was ever live, on a never-green run) and
+// was DELETED with the operator-authored steps[] path on 2026-07-26 (PRD
+// v1.32). What remains is what the live path imports — the primitives were
+// housed here, they were never part of the dead schema.
 
-import { COMPRESS_LEVELS, KINDS, WRITE_KINDS } from 'litectx';
-
-export const LOOP_SHAPES = Object.freeze(['refine', 'plan']);
-export const SLOTS = Object.freeze(['before-attempt', 'after-red', 'on-green']);
-export const VERBS = Object.freeze(['recall', 'compress', 'stash', 'remember']);
-const TOP_FIELDS = ['schema', 'loop', 'memory', 'hooks', 'gate', 'escalation'];
-// Unknown-field guard, PER SECTION — not just at the top (F17). The arbiter
-// split is guarded "both directions by inexpressibility": the drafted config
-// must be UNABLE to say certain things. A guard that stops at the top level
-// does not deliver that — `gate: { judged: {...} }` (the close's own honesty
-// check) validated green, as would `gate.maxCostUsd`. Nothing consumed those
-// keys, so nothing broke; the guarantee is that nothing ever can. Hook ops are
-// guarded separately by VERB_PARAMS.
-const SECTION_FIELDS = Object.freeze({
-  loop: ['shape', 'maxIterations'],
-  memory: ['store', 'recall', 'compressLevel'],
-  'memory.recall': ['k', 'kinds'],
-  gate: ['budgetUsd', 'writeScope'],
-  escalation: ['mode'],
-});
-const MAX_OPS_PER_SLOT = 2;
-
-// per-verb parameter contracts: name → check(value) (op field itself excluded).
-// remember's kinds are NARROWER than recall's: bound from litectx WRITE_KINDS
-// (the set remember() itself validates against — adaptlearn F5's drift lesson:
-// the export you bind can be wider than the function you call), minus doc:
-// the doc/upload axis stays gated out deliberately.
-export const REMEMBER_KINDS = WRITE_KINDS.filter((k) => k !== 'doc'); // exported: the drafting prompt advertises THIS menu (one source, no drift)
-const VERB_PARAMS = {
-  recall: { k: (v) => Number.isInteger(v) && v >= 1 && v <= 20, kinds: isKinds },
-  compress: { level: (v) => COMPRESS_LEVELS.includes(v) },
-  stash: {},
-  remember: { kind: (v) => REMEMBER_KINDS.includes(v) },
-};
+import { redact } from 'bareguard';
 
 /**
  * Map a schema writeScope entry to its enforcement prefix. bareguard
@@ -94,31 +62,6 @@ export function scopeContained(s) {
   return prefix.split('/').every((seg) => seg !== '..');
 }
 
-/**
- * The per-entry write-scope legality law, one home for all three call sites
- * (workflow gate.writeScope, the job fence, the operator's job-v1 writeScope):
- * a non-empty string, no mid-path wildcard (enforcement is prefix-containment,
- * F9), contained under the run dir (law #1). The chains that need per-check
- * reds still spell the three steps; fenceOk uses this so a fence can never be
- * blessed that the job validator would reject.
- * @param {unknown} s
- */
-function legalScopeEntry(s) {
-  return isNonEmptyString(s) && !globToPrefix(s).includes('*') && scopeContained(s);
-}
-
-// Each verb is legal ONLY in the slot where it has effect: recall/compress
-// build the attempt context (consumed by before-attempt only), stash parks the
-// gap (which exists only after-red), remember is verdict-gated retention
-// (on-green only, design law #2). An op that validates green but is inert at
-// runtime would still emit hook-op events — a live-looking knob with zero
-// effect, polluting the contrast evidence the extractor attributes by
-// (design law #3; the F16 credit-loss class).
-const VERB_SLOT = { recall: 'before-attempt', compress: 'before-attempt', stash: 'after-red', remember: 'on-green' };
-
-function isKinds(v) {
-  return Array.isArray(v) && v.length > 0 && v.every((k) => KINDS.includes(k));
-}
 /** Shared with the job validator — one definition of "a JSON object" for both
  * documents (the sibling-validator drift class).
  * @param {unknown} v */
@@ -152,8 +95,13 @@ const SECRET_RE = new RegExp(SECRET_PATTERNS.map((r) => r.source).join('|'));
  * Scan a RAW text stream (a spine file, a close's output, a transcript) for
  * known secret shapes and return the literal matches. The ONE spelling of the
  * text-side scan, for the same reason SECRET_PATTERNS is the ONE inventory: a
- * hand-rolled copy that misses a shape is a leak on the very output it guards
- * (seven copies of this expression lived in scripts/ before it landed here).
+ * hand-rolled copy that misses a shape is a leak on the very output it guards.
+ * The dedup is now COMPLETE and the count is grepped, not remembered: all 11
+ * call sites in scripts/ go through this function, and zero hand-rolled copies
+ * of the expression remain anywhere in the repo. (F40 landed the helper and
+ * converted 2 of 7 sites; the 5 it left alone plus 4 that accreted afterwards
+ * were converted in one sweep, byte-identical behaviour — measured equivalent
+ * on 900 spiked real spines, 0 divergences.)
  * `sweepSecretLiterals` is the config-tree twin — same shapes, tree walk.
  * Never throws; returns [] for a missing stream.
  * @param {unknown} raw
@@ -166,6 +114,23 @@ export function scanSecrets(raw) {
   return SECRET_PATTERNS.flatMap((re) => text.match(new RegExp(re.source, `${re.flags.replace('g', '')}g`)) ?? []);
 }
 
+/**
+ * Mask known secret shapes in a text. The REDACTION twin of `scanSecrets` and
+ * the ONE spelling of it: detection and redaction read the same inventory, so a
+ * shape the validator reds can never be a shape the redactor passes (a divergence
+ * there is a leak on the very output the validator was guarding). Housed beside
+ * the inventory rather than at each consumer for the same reason `scanSecrets`
+ * is — a hand-rolled copy is how the two drift.
+ * Consumers: the plan flow's spine/close/prompt `scrub`, and the isolate verbs,
+ * which write model-authored text into `<workdir>/.litectx` — a file INSIDE the
+ * tree that outlives the run and reads back through ctx_recall.
+ * @param {unknown} raw
+ * @returns {string}
+ */
+export function redactSecrets(raw) {
+  return redact(String(raw ?? ''), { patterns: SECRET_PATTERNS });
+}
+
 /**
  * Red every string in a config tree that carries a known secret-token shape.
  * @param {any} root
@@ -190,183 +155,3 @@ export function sweepSecretLiterals(root, red) {
     }
   })(root, '');
 }
-
-/**
- * Validate a workflow config against schema v1. Returns the parsed config on
- * ok (single parse — callers never re-parse; null on any red).
- * @param {object|string} input parsed config, or raw JSON text (parse failures are a red)
- * @param {{ shellCapUsd?: number, jobWriteScope?: string[] }} [opts] the shell's
- *   ceilings — a config may tighten either, never exceed. `shellCapUsd`: at N2+
- *   the shell passes min(shell cap, job budgetUsd) — the ceiling chain
- *   workflow ≤ job ≤ shell. `jobWriteScope`: the job spec's outer fence
- *   (operator law, job-v1) — every workflow scope must fit inside it.
- * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}>, config: object|null }}
- */
-export function validateConfig(input, { shellCapUsd = 2, jobWriteScope } = {}) {
-  /** @type {Array<{code: string, path: string, detail?: string}>} */
-  const reds = [];
-  /** @type {(code: string, path: string, detail?: string) => void} */
-  const red = (code, path, detail) => { reds.push(detail ? { code, path, detail } : { code, path }); };
-
-  let c = input;
-  if (typeof c === 'string') {
-    try { c = JSON.parse(c); } catch (e) {
-      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }], config: null };
-    }
-  }
-  if (!isObj(c)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'config must be a JSON object' }], config: null };
-
-  // 1. shape — unknown top-level fields red here (smuggled close/provider included)
-  for (const key of Object.keys(c)) {
-    if (!TOP_FIELDS.includes(key)) red('unknown-field', key);
-  }
-  if (c.schema === undefined) red('missing-required', 'schema');
-  else if (c.schema !== 'v1') red('invalid-value', 'schema', `expected "v1", got ${JSON.stringify(c.schema)}`);
-
-  // 2. required bindings + 3. bounds, section by section
-  const loop = isObj(c.loop) ? c.loop : {};
-  if (loop.shape === undefined) red('missing-required', 'loop.shape');
-  else if (!LOOP_SHAPES.includes(loop.shape)) red('invalid-value', 'loop.shape', `menu: ${LOOP_SHAPES.join('|')}`);
-  if (loop.maxIterations !== undefined
-      && !(Number.isInteger(loop.maxIterations) && loop.maxIterations >= 1 && loop.maxIterations <= 8)) {
-    red('bounds', 'loop.maxIterations', '1..8');
-  }
-
-  const memory = isObj(c.memory) ? c.memory : {};
-  if (memory.store === undefined) red('missing-required', 'memory.store');
-  else if (memory.store !== 'litectx') red('invalid-value', 'memory.store', 'v1 binds "litectx"');
-  if (isObj(memory.recall)) {
-    const { k, kinds } = memory.recall;
-    if (k !== undefined && !(Number.isInteger(k) && k >= 1 && k <= 20)) red('bounds', 'memory.recall.k', '1..20');
-    if (kinds !== undefined && !isKinds(kinds)) red('invalid-value', 'memory.recall.kinds', `subset of ${KINDS.join('|')}`);
-  }
-  if (memory.compressLevel !== undefined && !COMPRESS_LEVELS.includes(memory.compressLevel)) {
-    red('invalid-value', 'memory.compressLevel', COMPRESS_LEVELS.join('|'));
-  }
-
-  const gate = isObj(c.gate) ? c.gate : {};
-  if (gate.budgetUsd === undefined) red('missing-required', 'gate.budgetUsd');
-  else if (!(typeof gate.budgetUsd === 'number' && gate.budgetUsd > 0 && gate.budgetUsd <= shellCapUsd)) {
-    red('bounds', 'gate.budgetUsd', `0 < budget <= shell cap ${shellCapUsd}`);
-  }
-  if (gate.writeScope === undefined) red('missing-required', 'gate.writeScope');
-  else if (!(Array.isArray(gate.writeScope) && gate.writeScope.length > 0
-             && gate.writeScope.every(isNonEmptyString))) {
-    red('invalid-value', 'gate.writeScope', 'non-empty array of glob strings');
-  } else if (!gate.writeScope.every((s) => !globToPrefix(s).includes('*'))) {
-    // adaptlearn F9: enforcement (bareguard fs.writeScope) is prefix-containment — a wildcard
-    // anywhere but a trailing /** or /* is inexpressible there, so it would validate green
-    // and then gate-red EVERY write at runtime. Reds-before-tokens means rejecting it here.
-    red('invalid-value', 'gate.writeScope', 'wildcards only as a trailing "/**" or "/*" (enforcement is prefix-containment, adaptlearn F9)');
-  } else if (!gate.writeScope.every(scopeContained)) {
-    // A scope that can reach the arbiter's inputs is the config-level
-    // fit-to-pass surface (design law #1). Reds-before-tokens.
-    red('invalid-value', 'gate.writeScope', 'must be a proper subdirectory of the run directory — no absolute paths, no ".." segments, not the run dir itself (design law #1)');
-  } else if (jobWriteScope !== undefined && jobWriteScope !== null) {
-    // Two-layer fence: the job spec's writeScope is operator law; the authored
-    // config may tighten it, never exceed it (the budget pattern, on paths).
-    // null/undefined are the legitimate "no fence" spellings (job optional at
-    // N2, and the only forms that survive JSON transit) — the layer is skipped,
-    // never a deadlock. A PRESENT-but-malformed fence fails CLOSED with its own
-    // red, attributed to jobWriteScope (NOT the innocent workflow field — the
-    // ledger's contrast attribution must not charge the agent's config for the
-    // operator's broken spec).
-    const fenceOk = Array.isArray(jobWriteScope) && jobWriteScope.length > 0 && jobWriteScope.every(legalScopeEntry);
-    if (!fenceOk) {
-      const shown = JSON.stringify(jobWriteScope).slice(0, 200); // bound: a malformed fence is untrusted caller input, and this rides the append-only spine (ralph's 2000-char precedent)
-      red('fence-invalid', 'jobWriteScope', `not a validateJob-green fence (${shown}) — validate the job spec before threading its fence`);
-    } else {
-      // Boundary-aware: "src2" is not inside "src" — prefix means PATH prefix.
-      const fence = jobWriteScope.map(globToPrefix);
-      const inside = (/** @type {string} */ p) => fence.some((f) => p === f || p.startsWith(f + '/'));
-      gate.writeScope.forEach((/** @type {string} */ s, /** @type {number} */ i) => {
-        if (!inside(globToPrefix(s))) {
-          red('scope-escape', `gate.writeScope.${i}`, `"${s}" is outside the job's fence [${jobWriteScope.join(', ')}] — the workflow may tighten the operator's bound, never exceed it`);
-        }
-      });
-    }
-  }
-
-  const escalation = isObj(c.escalation) ? c.escalation : {};
-  if (escalation.mode === undefined) red('missing-required', 'escalation.mode');
-  else if (escalation.mode !== 'decision-ready') red('invalid-value', 'escalation.mode', 'must be "decision-ready"');
-
-  // 4. verb legality inside the slots
-  if (c.hooks !== undefined) {
-    const hooks = isObj(c.hooks) ? c.hooks : {};
-    if (!isObj(c.hooks)) red('invalid-value', 'hooks', 'must be an object of slots');
-    for (const [slot, ops] of Object.entries(hooks)) {
-      const at = `hooks.${slot}`;
-      if (!SLOTS.includes(slot)) { red('unknown-field', at); continue; }
-      if (!Array.isArray(ops)) { red('invalid-value', at, 'must be an array of ops'); continue; }
-      if (ops.length > MAX_OPS_PER_SLOT) { red('slot-overflow', at, `max ${MAX_OPS_PER_SLOT} ops`); continue; }
-      ops.forEach((op, i) => {
-        const opAt = `${at}.${i}`;
-        if (!isObj(op) || !VERBS.includes(op.op)) { red('verb-illegal', opAt, `verbs: ${VERBS.join('|')}`); return; }
-        if (VERB_SLOT[op.op] !== slot) {
-          red('verb-placement', opAt, `${op.op} is legal only in ${VERB_SLOT[op.op]} — the one slot where it has effect (an inert op is a fake knob in the contrast evidence)`);
-          return;
-        }
-        const params = VERB_PARAMS[op.op];
-        for (const [key, value] of Object.entries(op)) {
-          if (key === 'op') continue;
-          // Object.hasOwn, not `in`: params named after Object.prototype members
-          // ("constructor", "toString") must not smuggle past the unknown-param red.
-          if (!Object.hasOwn(params, key)) red('verb-params', `${opAt}.${key}`, `unknown param for ${op.op}`);
-          else if (!params[key](value)) red('verb-params', `${opAt}.${key}`, `invalid value for ${op.op}.${key}`);
-        }
-      });
-    }
-  }
-
-  // 4b. inexpressibility, at every depth the arbiter can be reached from
-  for (const [section, allowed] of Object.entries(SECTION_FIELDS)) {
-    const obj = section === 'memory.recall' ? memory.recall : c[section];
-    if (!isObj(obj)) continue;
-    for (const key of Object.keys(obj)) {
-      if (!allowed.includes(key)) red('unknown-field', `${section}.${key}`);
-    }
-  }
-
-  // 5. secrets sweep — same guard as the job spec (the agent-authored document
-  // is the riskier one; a green config is a ledger fact and inherits forever)
-  sweepSecretLiterals(c, red);
-
-  return { ok: reds.length === 0, reds, config: reds.length === 0 ? c : null };
-}
-
-/**
- * Changed JSON paths between two configs — the one-knob mutation checker
- * (a legal mutant has exactly one). A subtree present on only one side counts
- * as ONE path (its root), so "add an op to a slot" is one knob, not two params.
- * @param {object} a
- * @param {object} b
- * @returns {string[]} sorted changed paths, dot-notation with array indices
- */
-export function diffPaths(a, b) {
-  /** @type {string[]} */
-  const paths = [];
-  walk(a, b, '');
-  return paths.sort();
-
-  /**
-   * @param {any} x
-   * @param {any} y
-   * @param {string} at
-   */
-  function walk(x, y, at) {
-    if (x === y) return;
-    const bothObj = isObj(x) && isObj(y);
-    const bothArr = Array.isArray(x) && Array.isArray(y);
-    if (!bothObj && !bothArr) {
-      if (JSON.stringify(x) !== JSON.stringify(y)) paths.push(at || '$');
-      return;
-    }
-    const keys = new Set([...Object.keys(x), ...Object.keys(y)]);
-    for (const key of keys) {
-      const p = at ? `${at}.${key}` : key;
-      if (!(key in x) || !(key in y)) paths.push(p); // added/removed subtree = one knob
-      else walk(x[key], y[key], p);
-    }
-  }
-}

package/types/bridges.d.ts

@@ -0,0 +1,198 @@
+/**
+ * D6's status ladder, walked in history order. Pure, total, and never throws —
+ * it is called on whatever a file happens to contain.
+ *
+ * - **candidate** — at least one green.
+ * - **proven** — greens on ≥2 DISTINCT patients (R2: the same SHAPE on a second
+ *   instance; two greens on ONE patient is a lookup table, which the memorization
+ *   audit kills).
+ * - a **red** on a PROVEN entry drops it to candidate, and re-promotion then needs
+ *   greens on two distinct patients AGAIN — that is what "until a new green on a
+ *   second distinct patient re-proves" means, so the demoting red clears the
+ *   distinct-patient set rather than leaving the old count standing to re-promote
+ *   the entry on the first repeat green.
+ * - a red on a CANDIDATE changes nothing: there is nothing below the entry bar, and
+ *   the entry stays in the record with the red beside it.
+ * - a **CASUALTY is not a red.** Only the literal outcome `'red'` demotes; every
+ *   other non-green outcome (`provider-red`, `wall-halt`, `close-crashed`, …) is a
+ *   casualty, and casualties are never evidence in either direction.
+ *
+ * @param {unknown} history the bridge's per-run rows, oldest first
+ * @returns {'candidate'|'proven'|null} null = below the entry bar (no green yet)
+ */
+export function deriveStatus(history: unknown): "candidate" | "proven" | null;
+/**
+ * Validate a bridge entry (`schema: "bridge-v1"`). Never throws on JSON text or
+ * plain parsed data — the same ingest contract both config validators hold; every
+ * failure is a named red. Returns the parsed entry on ok, null on any red.
+ * @param {object|string|unknown} input parsed entry, or raw JSON text
+ * @returns {{ ok: boolean, reds: Red[], bridge: any }}
+ */
+export function validateBridge(input: object | string | unknown): {
+    ok: boolean;
+    reds: Red[];
+    bridge: any;
+};
+/**
+ * FIRST GREEN MINTS: build a new registry entry from one green. The entry bar is
+ * a green (D6) — there is deliberately no way to create an entry without one, so
+ * a failed plan cannot enter the registry even by accident.
+ * @param {unknown} meta `{ name, goal, specHash, closeStageNames, toolsUsed }` —
+ *   `specHash` may be an explicit null (one probe-era bridge on disk has none), and
+ *   the KEY is required so an unknown hash has to be said rather than omitted.
+ * @param {unknown} record `{ runid, patient, at, plan, costUsd, spendComplete, wallMs, rounds, specHash? }`
+ * @returns {{ ok: boolean, reds: Red[], bridge: any }}
+ */
+export function mintBridge(meta: unknown, record: unknown): {
+    ok: boolean;
+    reds: Red[];
+    bridge: any;
+};
+/**
+ * A green on an EXISTING bridge: the plan AS EXECUTED becomes its next version,
+ * and the run gets a history row. Pure — returns a NEW entry; the input is never
+ * mutated, so a caller that reds still holds the bridge it read from disk.
+ * @param {unknown} bridge a validated bridge entry
+ * @param {unknown} record `{ runid, patient, at, plan, costUsd, spendComplete, wallMs, rounds, specHash? }`
+ * @returns {{ ok: boolean, reds: Red[], bridge: any }}
+ */
+export function appendGreen(bridge: unknown, record: unknown): {
+    ok: boolean;
+    reds: Red[];
+    bridge: any;
+};
+/**
+ * A red (or a casualty): a history row ONLY. R1 — the bridge file is never edited
+ * in place by a red; the recipe that greened stays exactly as it greened, and the
+ * status derivation reads the demotion off the history.
+ * @param {unknown} bridge a validated bridge entry
+ * @param {unknown} record `{ runid, patient, at, outcome, failingStage, costUsd, spendComplete, wallMs, rounds }`
+ * @returns {{ ok: boolean, reds: Red[], bridge: any }}
+ */
+export function appendRed(bridge: unknown, record: unknown): {
+    ok: boolean;
+    reds: Red[];
+    bridge: any;
+};
+/**
+ * One row of D3's listing: what the user (and the selecting LLM) sees per bridge —
+ * name, the job sentence it greened, status, greens/reds, and the cost/time BAND of
+ * its greens. Deliberately no score (D6).
+ *
+ * The cost band SKIPS unknowns and says how many it skipped: an aggregate that
+ * treats a null as 0 reports a floor that reads as exact, which is F6 in an honest
+ * coat. With no priced green at all, every bound is null — never 0.
+ *
+ * Total and never throws: the listing is a display surface, and one malformed
+ * entry must not take the whole listing down (loadRegistry already reports it).
+ * @param {unknown} bridge
+ * @returns {{name: string|null, goal: string|null, status: 'candidate'|'proven'|null, greens: number, reds: number, lastOutcome: string|null, greenCost: {minUsd: number|null, maxUsd: number|null, minWallMs: number|null, maxWallMs: number|null, unpricedCount: number, untimedCount: number}}}
+ */
+export function listingRow(bridge: unknown): {
+    name: string | null;
+    goal: string | null;
+    status: "candidate" | "proven" | null;
+    greens: number;
+    reds: number;
+    lastOutcome: string | null;
+    greenCost: {
+        minUsd: number | null;
+        maxUsd: number | null;
+        minWallMs: number | null;
+        maxWallMs: number | null;
+        unpricedCount: number;
+        untimedCount: number;
+    };
+};
+/**
+ * D2's LOAD-TIME gate, as SPLIT by the 2026-08-01 addendum. Exactly three checks —
+ * *"is this the right KIND of recipe?"*, asked at the box:
+ *
+ *  1. **verdict type matches.** v1 admits `green` only, and a bridge only ever
+ *     exists because a green minted it, so the bridge side is `green` by
+ *     construction and the check reads the JOB's declared type. **The day a second
+ *     verdict class is admitted, the bridge entry must carry its own verdictType
+ *     and this becomes a two-sided comparison** — recorded here so it cannot be
+ *     quietly assumed to already be one.
+ *  2. **close-stage KINDS match.** v1 simplification: the same stage NAMES in the
+ *     same ORDER is the definition of the same kinds. The probes' R2-legal pair
+ *     matched on four identical stage names over different patients, which is the
+ *     material this rule was ruled on; a real kind-comparison (what each stage
+ *     INSPECTS, independent of what it was named) is a later rung's problem and is
+ *     not pretended here.
+ *  3. **every stored verb fits THIS job's signed menu.** An omitted `tools` means
+ *     the concrete current TOOL_MENU — the same predicate `resolveSpec` and
+ *     `validatePlan` read (MED-1), so what the gate judges is what was signed.
+ *
+ * **NOTHING about paths, scopes or targets.** Those are instance-bound and are
+ * EXPECTED to red: every recipe from a different day names yesterday's bricks, and
+ * that is what a recipe IS, not a flaw. The pre-probe measured the drafter
+ * replacing them unaided (3/3 legal after tweak), while the gate as originally
+ * frozen would have refused all six of them at the door. The full `validatePlan`
+ * still judges the TWEAKED draft at draft time — nothing executes unvalidated, and
+ * no second, looser path exists for an inherited plan (D4).
+ *
+ * A failing gate is the **recipe-stale / wrong-kind** OUTCOME — a distinct result
+ * with cold drafting offered, never a throw.
+ * @param {unknown} bridge
+ * @param {unknown} job the validateJob-green spec this run is signed against
+ * @returns {{ ok: boolean, reds: Red[] }}
+ */
+export function loadGate(bridge: unknown, job: unknown): {
+    ok: boolean;
+    reds: Red[];
+};
+/**
+ * Read one bridge file. Never throws — a missing/unreadable file and a malformed
+ * one are both named reds, because the registry is read at selection time and one
+ * bad file must not take the run down.
+ * @param {string} file
+ * @returns {{ ok: boolean, reds: Red[], bridge: any }}
+ */
+export function loadBridge(file: string): {
+    ok: boolean;
+    reds: Red[];
+    bridge: any;
+};
+/**
+ * Read a whole registry directory. A malformed entry is SKIPPED AND REPORTED —
+ * one red per bad file, the good entries still returned, sorted by name for a
+ * stable listing. `ok` is false when anything was skipped, so a caller can surface
+ * the skip instead of silently listing fewer workflows than exist on disk.
+ * @param {string} dir the operator-supplied registry path (no default location)
+ * @returns {{ ok: boolean, reds: Red[], bridges: any[] }}
+ */
+export function loadRegistry(dir: string): {
+    ok: boolean;
+    reds: Red[];
+    bridges: any[];
+};
+/**
+ * Write one bridge entry, ATOMICALLY (temp + rename): a registry read concurrent
+ * with a write must see the old entry or the new one, never a half-written file
+ * that then reads as a malformed skip. An INVALID entry is refused before anything
+ * touches the disk — the registry never holds a file its own validator rejects.
+ * @param {string} dir the operator-supplied registry directory (must exist)
+ * @param {unknown} bridge
+ * @returns {{ ok: boolean, reds: Red[], file: string|null }}
+ */
+export function saveBridge(dir: string, bridge: unknown): {
+    ok: boolean;
+    reds: Red[];
+    file: string | null;
+};
+/**
+ * Create a registry directory. Separate from `saveBridge` ON PURPOSE: saving must
+ * never conjure a registry from a typo'd path, so making one is an explicit act.
+ * @param {string} dir
+ * @returns {string} the directory
+ */
+export function makeRegistry(dir: string): string;
+/** @param {string} dir @returns {boolean} does a registry directory exist */
+export function registryExists(dir: string): boolean;
+export const BRIDGE_SCHEMA: "bridge-v1";
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};

package/types/clock.d.ts

@@ -0,0 +1,131 @@
+/**
+ * F64 — is this throw the run's OWN deadline coming back dressed as a provider
+ * error? `callTimeoutMs()` hands the provider a bound derived from the wall, so
+ * when the wall is what shrank that bound, the resulting `TimeoutError` is a
+ * GOVERNANCE stop, not a casualty. Filing it as `provider-red` would discard it
+ * (a casualty is never evidence, F45/F48) and attach the F44
+ * `spendComplete:false` floor to a run that simply ran out of time.
+ *
+ * The discriminator is the wall itself, not the derived number: on a bounded
+ * clock a trip can only precede expiry when the bound came from the provider's
+ * own default (`remainingMs() > PROVIDER_TIMEOUT_MS`), and that case is transport
+ * by construction. So "already expired" IS the wall-derived set. An unbounded run
+ * can never produce one, and needs no separate `bounded` term to say so —
+ * `expired()` is false by construction with no cap. (A mutation run proved the
+ * extra term inert; the unbounded case is guarded by its own test instead, which
+ * is where that invariant belongs.)
+ *
+ * A genuine dead socket on a run whose wall has ALSO passed reads as a wall-halt.
+ * That is deliberate and honest: the run is out of time either way, the remedy is
+ * the same (raise `maxWallMs`), and the alternative — calling a governance stop
+ * transport on the chance that it was — is the failure this closes.
+ *
+ * BOTH derived bounds land here, because both are derived from the same wall:
+ * BA-18's idle timeout (`callTimeoutMs`) and BA-19's total-duration deadline
+ * (`callDeadlineMs`). Adding the second CODE does not widen the rule — the
+ * discriminator is still `clock.expired()`, never the code. That matters for the
+ * deadline specifically: a provider someone else constructed with its own
+ * `deadlineMs` could throw this code on a run with time left, and that is transport,
+ * exactly as it was before.
+ *
+ * @param {any} err the throw as caught
+ * @param {Clock} clock the run's clock
+ * @returns {boolean}
+ */
+export function isWallTimeout(err: any, clock: Clock): boolean;
+/**
+ * @typedef {object} Clock
+ * @property {boolean} bounded whether the operator set a cap at all
+ * @property {number|null} requestedMs the operator's number; `null` when unbounded
+ * @property {number} closeStages how many close stages one verdict can pay for (W5)
+ * @property {() => number} elapsedMs wall time since the clock was created
+ * @property {() => number} remainingMs what is left, floored at 0; `Infinity` when unbounded
+ * @property {() => boolean} expired whether the deadline has passed (always false when unbounded)
+ * @property {(closeTimeoutMs: number) => number|null} enforcedMs the HONEST worst case
+ * @property {(providerDefaultMs?: number) => number} callTimeoutMs the derived per-call bound
+ * @property {() => number|null} callDeadlineMs the derived per-call TOTAL-duration ceiling; `null` when unbounded
+ * @property {(closeTimeoutMs: number) => object} report one spine-safe shape carrying both numbers
+ */
+/**
+ * Start a wall clock for one run.
+ * @param {{ maxWallMs?: number|null, closeStages?: number, now?: () => number, priorElapsedMs?: number }} [opts]
+ *   `maxWallMs`: the signed operator cap, or absent/null for an honestly unbounded
+ *   run. `closeStages`: how many stages the job's close runs (W5) — each one gets
+ *   the FULL `closeTimeoutMs`, so this is the multiplier on the overshoot, not a
+ *   decoration. Defaults to 1, the single-predicate close. `now`: injected for
+ *   tests — the default is the real clock. `priorElapsedMs`: time this attempt's
+ *   PREDECESSOR already consumed (see below).
+ * @returns {Clock}
+ */
+export function createClock({ maxWallMs, closeStages, now, priorElapsedMs }?: {
+    maxWallMs?: number | null;
+    closeStages?: number;
+    now?: () => number;
+    priorElapsedMs?: number;
+}): Clock;
+/** BA-18's default request/idle timeout (`AnthropicProvider.timeoutMs`), the
+ * ceiling every derived per-call timeout starts from. Kept in sync deliberately:
+ * a value ABOVE the provider's own default would be inert. */
+export const PROVIDER_TIMEOUT_MS: 600000;
+/**
+ * The floor for a derived per-call timeout. Below this a call cannot plausibly
+ * succeed, and a timeout that is certain to trip manufactures a `provider-red`
+ * out of a time budget — a transport CASUALTY, which is never evidence
+ * (F45/F48). The deadline check is what must stop a run out of time; the per-call
+ * timeout exists to bound a HANG, not to enforce the budget's last second.
+ */
+export const MIN_CALL_TIMEOUT_MS: 30000;
+/** bare-agent's rejection code when its request/idle timeout trips (BA-18,
+ * `provider-http.js` → `TimeoutError`). The error carries a `code` and NO
+ * `category`, so every consumer that defaults an uncategorised throw would file
+ * it as transport. */
+export const TIMEOUT_CODE: "ETIMEDOUT";
+/** bare-agent's rejection code when its TOTAL-duration deadline trips (BA-19,
+ * `provider-http.js` → `applyRequestDeadline`). A DIFFERENT code from the idle
+ * bound's on purpose — upstream splits them precisely so a consumer routing
+ * governance stops apart from transport casualties can tell which timer fired. Like
+ * `TIMEOUT_CODE` it carries no `category`, so every default-to-transport catch site
+ * would file it as a casualty. */
+export const DEADLINE_CODE: "EDEADLINE";
+export type Clock = {
+    /**
+     * whether the operator set a cap at all
+     */
+    bounded: boolean;
+    /**
+     * the operator's number; `null` when unbounded
+     */
+    requestedMs: number | null;
+    /**
+     * how many close stages one verdict can pay for (W5)
+     */
+    closeStages: number;
+    /**
+     * wall time since the clock was created
+     */
+    elapsedMs: () => number;
+    /**
+     * what is left, floored at 0; `Infinity` when unbounded
+     */
+    remainingMs: () => number;
+    /**
+     * whether the deadline has passed (always false when unbounded)
+     */
+    expired: () => boolean;
+    /**
+     * the HONEST worst case
+     */
+    enforcedMs: (closeTimeoutMs: number) => number | null;
+    /**
+     * the derived per-call bound
+     */
+    callTimeoutMs: (providerDefaultMs?: number) => number;
+    /**
+     * the derived per-call TOTAL-duration ceiling; `null` when unbounded
+     */
+    callDeadlineMs: () => number | null;
+    /**
+     * one spine-safe shape carrying both numbers
+     */
+    report: (closeTimeoutMs: number) => object;
+};