bareloop 0.5.1 → 0.6.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/clock.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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.
+ *
+ * @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 {(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 }} [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.
+ * @returns {Clock}
+ */
+export function createClock({ maxWallMs, closeStages, now }?: {
+    maxWallMs?: number | null;
+    closeStages?: number;
+    now?: () => 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";
+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;
+    /**
+     * one spine-safe shape carrying both numbers
+     */
+    report: (closeTimeoutMs: number) => object;
+};

package/types/index.d.ts

@@ -1,11 +1,9 @@
 export { makeSpine } from "./spine.js";
 export { runPlan } from "./planrun.js";
 export { runJob } from "./run.js";
-export { ralph, runClose, CLOSE_FAULTS } from "./ralph.js";
-export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
-export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
-export { validatePlan, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from "./plan.js";
+export { ralph, runClose, runStages, CLOSE_FAULTS } from "./ralph.js";
+export { globToPrefix, scanSecrets } from "./validate.js";
+export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
+export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from "./plan.js";
 export { snapshotScope, evalExits } from "./exits.js";
-export { interpret, STALL_REDS } from "./interpret.js";
-export { extractRules, MAX_RULES, MAX_RULE_CHARS } from "./extract.js";
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from "./ledger.js";

package/types/job.d.ts

@@ -17,9 +17,52 @@ export function validateJob(input: object | string, { shellCapUsd }?: {
     job: object | null;
 };
 /**
- * Content hash of a job spec — what an approval record binds to. Any edit to
- * the spec changes the hash, so an edited spec is unapproved by construction
- * (interview decision #1: human signs, always, once per spec VERSION).
+ * The staged close (PRD v1.28) — the close is an ORDERED LIST of named stages,
+ * and the check menu DERIVES from it. The principle: *the user authors the
+ * destination, never the road.* A user who cannot describe a workflow can still
+ * say what done looks like, and everything downstream of that is derived — which
+ * is why `checks[]` no longer exists as a field (hamr: *"there shouldn't be user
+ * authoring anywhere, that defies the point of bareloop"*).
+ *
+ * Two stage classes cannot be handed to the agent as a mid-build ruler, and F58
+ * measured both against a real close:
+ *  - a PRECONDITION ("the seed commit exists") is not a ruler for the work; run
+ *    as a check it passes instantly and teaches nothing. It sets `offer: false`.
+ *  - a stage that reads what an EARLIER stage built ("the public API matches the
+ *    emitted declarations") reds on its own for a reason that has nothing to do
+ *    with the worker's edit. It names `needs`, and picking it runs that chain first.
+ * Everything else is offerable: derivation gave job #5 SEVEN rulers where the
+ * operator had hand-carved three (F58) — removing the operator does not cost the
+ * agent rulers, it hands it more.
+ *
+ * The `needs` expansion is TRANSITIVE (fixed point, not one level): a
+ * prerequisite may itself name one, and running an incomplete chain reproduces
+ * the exact false-red `needs` exists to remove, one level deeper. The expanded
+ * chain is ordered by the CLOSE, never by the order names were typed —
+ * validateStagedClose forces `needs` to name EARLIER stages, so close order IS
+ * a topological order. A `needs` cycle is inexpressible in a validated close for
+ * that same reason; the walk is still cycle-safe by construction (each stage is
+ * collected at most once), because a pure exported helper must terminate on
+ * whatever it is handed rather than hang the runner before any token burns.
+ *
+ * @param {any[]} close the validated stage list
+ * @returns {{name: string, run: any[]}[]} offerable stages, each with the ordered
+ *   chain that must run for it (prerequisites first, the stage itself last)
+ */
+export function checkMenu(close: any[]): {
+    name: string;
+    run: any[];
+}[];
+/**
+ * Content hash of a job spec — what an approval record binds to. Any SEMANTIC
+ * edit changes the hash, so a spec whose meaning moved is unapproved by
+ * construction (interview decision #1: human signs, always, once per spec
+ * VERSION). Not every BYTE edit: the hash is taken over the RESOLVED spec
+ * (resolveSpec), so writing today's full TOOL_MENU into a spec that omitted
+ * `tools` is hash-neutral — the two spell the same ceiling, and that identity
+ * is the point of MED-1, since it is what pins WHICH menu the signature covers.
+ * The direction that matters still bites: the menu itself changing (or the
+ * explicit list changing) moves the resolved form, and the hash with it.
  * @param {object} job
  * @returns {string} sha256 hex
  */
@@ -35,8 +78,11 @@ export function jobSpecHash(job: object): string;
  */
 export function checkApproval(job: object, approvals: unknown): boolean;
 export const CLOSE_TYPES: readonly string[];
-export const CLASSES: readonly string[];
-/** the hierarchy: which verdict classes a close type may claim (PRD §7) */
+/** the hierarchy: which verdict classes a close type may claim (PRD §7). Read by
+ * the verdictType check — a declared verdict may not demand a class its close
+ * type cannot legally claim (green-on-rubric is laundering). The `CLASSES`
+ * vocabulary export went with steps[] (PRD v1.32): a class was a STEP field, and
+ * nothing declares one now. */
 export const CLASS_BY_CLOSE: Readonly<{
     predicate: readonly string[];
     gold: readonly string[];
@@ -44,8 +90,6 @@ export const CLASS_BY_CLOSE: Readonly<{
     hitl: readonly string[];
 }>;
 export const GOLD_COMPARE: readonly string[];
-/** step middle modes (2b): text = single-target artifact; tools = Gate-governed file tools */
-export const STEP_MODES: readonly string[];
 /** the tool grant menu (2b interview #1): read/grep/write, plus the two litectx
  * RETRIEVAL verbs (F19) — `run` stays locked-but-listed; a spec requesting it
  * reds, and that red IS the request-red evidence admission waits on (curation
@@ -65,8 +109,39 @@ export const STEP_MODES: readonly string[];
  * WRITE-class verb judged by the SAME writeScope fence as `write` (bareguard
  * action type 'edit'). Admitted because whole-file rewrite is measurably
  * unreliable at size (F31: 4 of 5 big-file whole-writes broke the tree) and
- * taxes output tokens ∝ file size. It admits no execution either. */
+ * taxes output tokens ∝ file size. It admits no execution either.
+ *
+ * P (design record 2026-07-28, hamr: full catalog) widened the menu to the four
+ * components — write · select · compress · isolate — every verb an EXISTING
+ * litectx implementation (menu-is-inventory). impact/related/recent/compress/
+ * peek are read-only like the retrieval pair; stash/remember/forget are
+ * STORE-writes (`.litectx`, never the tree — own gate action types, and the U
+ * runner deletes the store at reset so cold stays cold). None admits execution:
+ * the `run` lock is untouched. */
 export const TOOL_MENU: readonly string[];
+/** the write-class split the validator and the scout filter read: tree writes
+ * (writeScope fence) vs store writes (isolate) — NEITHER is read-capable. */
+export const WRITE_VERBS: readonly string[];
+export const STORE_VERBS: readonly string[];
+/**
+ * The floor for `maxWallMs`: one default close timeout (`runClose`'s 120_000).
+ * Addendum 1 MEASURED that a wall deadline can only be read BETWEEN rounds —
+ * `loop.stop()` does not cut an in-flight call (fired at 500ms, returned at
+ * 4,018ms) — so enforcement is `maxWallMs + closeStages × closeTimeoutMs` (W5: a
+ * staged close runs every stage under the FULL timeout, ralph.js `runStages`).
+ * Under this floor the overshoot exceeds the budget itself and the advertised
+ * number would be more wrong than right, which is the advertised-must-equal-
+ * enforced line.
+ *
+ * The VALUE is a one-stage, default-timeout floor and is deliberately left alone —
+ * a threshold is operator territory, not something this module re-derives from a
+ * spec's own stage count. It therefore bounds only the degenerate case; a job with
+ * many stages or a raised `closeTimeoutMs` can still sit far above it while its
+ * overshoot dwarfs its cap. The clock reports that honestly (`closeStages` and
+ * `enforcedMs` are both on the `wall-clock` record) rather than the floor pretending
+ * to prevent it.
+ */
+export const MIN_WALL_MS: 120000;
 /** locked-but-listed tools: real capabilities deliberately outside the grant
  * menu. Requesting one is a DISTINCT `request-red` (module 4) — the ledger
  * counts admission demand, and a generic invalid-value would bury it as a typo. */

package/types/ledger.d.ts

@@ -3,7 +3,9 @@
  * bareloop vocabulary). Deliberate exclusions — bare cap-halt (a budget story),
  * close-verdict reds and artifact-red (worker stories, the §5b line), gate-red
  * (governance working as intended), pr-red (operator environment, not a suite
- * lib), smoke-red escalations (already counted via primitive-smoke), hitl-close
+ * lib), smoke-red escalations (already counted via primitive-smoke), step-stalled
+ * (our own fuse firing on an ABSENCE of beats — no observed lib failure to file),
+ * hitl-close
  * and close-unsupported (by design) — classify to nothing.
  * @param {any[]} events one spine's parsed events, in seq order
  * @param {{spine?: string}} [opts] spine id stamped into samples