@dzhechkov/harness-core 0.4.5 → 0.5.1

package/src/loop-render.ts

@@ -34,6 +34,7 @@ import {
   type LoopStep,
 } from './loop-plan.js';
 import { BLOBS, type LoopBlob } from './loop-blobs.generated.js';
+import { computeBudgetTotal, stepContractLines } from './loop-run-semantics.js';
 
 export const LOOP_RENDER_GENERATOR = 'loop-render/1';
 
@@ -76,6 +77,12 @@ function sha256(s: string): string {
 /** Which blobs a plan pulls in (opt-in subsystems + auto rules + requires closure). */
 export function selectBlobs(plan: LoopPlan): LoopBlob[] {
   const names = new Set<string>();
+  // The ENACTMENT-DECISION blob is UNCONDITIONAL (ADR-001 W4): the base runtime aliases
+  // errText/errSnap/classifyFailure in every script, so there is no plan that does not need it.
+  // gateVerdict/joinRegion are inert function declarations in a plan with no gate/fanout — the
+  // alternative (a conditional roster) would make the exec fingerprint's `tools` axis depend on
+  // plan shape twice, and would let a semantics-carrying script exist without the semantics.
+  names.add('loop-semantics');
   const sub = plan.subsystems ?? {};
   if (plan.checkpointing?.enabled === true || sub.checkpoints === true) names.add('checkpoints');
   // AM-9: training pairs are injected ONLY on an explicit opt-in — never by default (PHI lesson).
@@ -189,26 +196,22 @@ function stepUserLines(s: LoopStep): string[] {
 function stepPromptAssembly(s: LoopStep, plan: LoopPlan): string[] {
   const id = s.stepId;
   const lines: string[] = [];
-  const reads = s.artifacts?.reads ?? [];
-  const writes = s.artifacts?.writes ?? [];
   const gateCfg = s.kind === 'gate' ? (plan.gates ?? []).find((g) => g.stepId === id) : undefined;
   lines.push(`const P_${ident(id)} = [`);
   lines.push(`  USER_PROMPT_${ident(id)},`);
-  if (reads.length > 0) lines.push(`  ${jsString('declared inputs (plan artifacts.reads): ' + reads.join(', '))},`);
-  if (writes.length > 0) {
-    const fileNote = (s.deliverable ?? 'return-value') === 'file' ? '; your deliverable is the written file(s), not your reply' : '';
-    lines.push(`  ${jsString('declared outputs (plan artifacts.writes): ' + writes.join(', ') + ' — write them' + fileNote + '. The loop verifies they land.')},`);
-  }
-  // ENACTS LoopStep.tools (cfr-pipeline ADR-002): the declared perimeter is COMMUNICATED to the
-  // agent in FIXED wording, so its presence is greppable by a layer-1 test. The second sentence is
-  // not decoration — it is the honesty clause the whole feature rests on: a declaration is not
-  // enforcement, and every environment this ships into today serves the tools as labeled stubs.
-  const tools = s.tools ?? [];
-  if (tools.length > 0) {
-    lines.push(`  ${jsString('declared MCP tool allowlist (plan tools): ' + tools.join(', ') + ' — use NOTHING outside it. In this environment every one of these is a labeled STUB, not a live integration; enforcement lives at the MCP server, not here.')},`);
-  }
-  if (s.kind === 'gate') {
-    lines.push(`  ${jsString('GATE PROTOCOL (kind: ' + (gateCfg?.kind ?? 'gate') + '): end your reply with exactly one line "GATE: PASS" or "GATE: FAIL" — the loop PARSES this verdict and never synthesizes one.')},`);
+  // The contract lines themselves come from ONE function shared with the dz runner
+  // (loop-run-semantics.stepContractLines, ADR-001 Confirmation-5) — the render's only remaining
+  // job is JS-quoting them. ENACTS artifacts.reads/writes/deliverable, LoopStep.tools and the gate
+  // protocol: the plan's declarations are COMMUNICATED to the agent in FIXED wording, so their
+  // presence is greppable by a layer-1 test and IDENTICAL under both enactors.
+  for (const line of stepContractLines({
+    reads: s.artifacts?.reads ?? [],
+    writes: s.artifacts?.writes ?? [],
+    deliverable: s.deliverable ?? 'return-value',
+    tools: s.tools ?? [],
+    gate: s.kind === 'gate' ? { kind: gateCfg?.kind ?? 'gate' } : null,
+  })) {
+    lines.push(`  ${jsString(line)},`);
   }
   lines.push(`].join('\\n')`);
   return lines;
@@ -477,15 +480,10 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
   const traceOn = plan.trace?.emit === true;
   const ckptOn = plan.checkpointing?.enabled === true || plan.subsystems?.checkpoints === true;
   // budget: declared per-step budgets PLUS the declared gate-redo allowance (QE round-3 B1 — a
-  // plan-declared redo must be affordable; an undeclared one still hits the guard loudly).
-  const stepBudget = plan.steps.reduce((n, s) => n + (s.budget?.maxAgents ?? 1), 0);
-  const byIdB = new Map(plan.steps.map((s) => [s.stepId, s]));
-  const gateRedoBudget = (plan.gates ?? []).reduce((n, g) => {
-    const redos = typeof g.maxRedos === 'number' && Number.isFinite(g.maxRedos) && g.maxRedos > 0 ? Math.floor(g.maxRedos) : 0;
-    if (redos === 0 || typeof g.failRoute !== 'string' || g.failRoute.startsWith('terminal:')) return n;
-    return n + redos * ((byIdB.get(g.failRoute)?.budget?.maxAgents ?? 1) + (byIdB.get(g.stepId)?.budget?.maxAgents ?? 1));
-  }, 0);
-  const budgetTotal = stepBudget + gateRedoBudget;
+  // plan-declared redo must be affordable; an undeclared one still hits the guard loudly). The
+  // FORMULA lives in loop-run-semantics (ADR-004 Confirmation-2) so the dz runner reserves against
+  // the same ceiling this script spends against — one formula, two enactors.
+  const budgetTotal = computeBudgetTotal(plan);
   const lines: string[] = [];
   lines.push(G('runtime'));
   lines.push(`const A = typeof args === 'string' ? JSON.parse(args) : (args || {})`);
@@ -518,82 +516,15 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
   lines.push(`function __settleSeqOf(stepId, itemKey, occ) { const v = __settled[__settleKey(stepId, itemKey, occ)]; return typeof v === 'number' ? v : -1 }`);
   lines.push(`let __invocationN = 0`);
   lines.push(`let __seqFallback = 0 // used only when the trace blob is opted out (hooks are no-ops)`);
-  lines.push(`// __errText — TOTAL error-to-text (QE round-3 B3, the ha-consilium 5b totality lesson): the`);
-  lines.push(`// writer's own settle event must survive a hostile error object. String(err) throws on a`);
-  lines.push(`// null-prototype object and a throwing .message getter throws on access — both are caught here,`);
-  lines.push(`// so rendering a message can never replace the original failure or lose the settle. The`);
-  lines.push(`// .message property is read ONCE into a local (round-5 B3: a one-shot getter answered the`);
-  lines.push(`// typeof probe and vanished on the value read — snapshot-once defeats it).`);
-  lines.push(`function __errText(err) {`);
-  lines.push(`  try {`);
-  lines.push(`    if (err !== null && typeof err === 'object') { const m = err.message; if (typeof m === 'string') return m }`);
-  lines.push(`    return String(err)`);
-  lines.push(`  } catch (_e) {`);
-  lines.push(`    try { return Object.prototype.toString.call(err) } catch (_e2) { return '[unrenderable error]' }`);
-  lines.push(`  }`);
-  lines.push(`}`);
-  lines.push(`// failure classification (G4, hardened in QE round-3 B3, round-4: cause-chain + word bounds) —`);
-  lines.push(`// the CLOSED enum from loop-plan/1 (timeout | transport | malformed-output | policy-refusal).`);
-  lines.push(`// The err.cause CHAIN is traversed (bounded depth 5, cycle-safe, getter-safe): the standard`);
-  lines.push(`// Node fetch shape TypeError('fetch failed', {cause:{code:'ECONNRESET'}}) is TRANSPORT.`);
-  lines.push(`// THREE TIERS over the whole chain, strongest first:`);
-  lines.push(`//   1. error CODE (works on non-Error shapes like {code:'ECONNRESET'}; never message-dependent;`);
-  lines.push(`//      ETIMEDOUT is a TRANSPORT code — round-2's message regex captured it as 'timeout' first);`);
-  lines.push(`//   2. error NAME (SyntaxError = parsing model output failed → malformed-output);`);
-  lines.push(`//   3. message patterns, DISJOINT by precedence transport > policy-refusal > malformed-output >`);
-  lines.push(`//      timeout — every alternative WORD-BOUNDED (round-4 B3: 'rate.?limit' unbounded matched`);
-  lines.push(`//      'delibeRATE LIMITation'/'corpoRATE LIMITation' — a substring can never smuggle a class).`);
-  lines.push(`// An UNCLASSIFIABLE failure returns null and is NEVER retried (closed enum, fail-closed).`);
-  lines.push(`function __causeChain(err) {`);
-  lines.push(`  const chain = []`);
-  lines.push(`  let cur = err`);
-  lines.push(`  for (let d = 0; d < 5; d++) {`);
-  lines.push(`    if (cur === null || cur === undefined) break`);
-  lines.push(`    if (chain.indexOf(cur) !== -1) break // cycle-safe`);
-  lines.push(`    chain.push(cur)`);
-  lines.push(`    try { cur = typeof cur === 'object' ? cur.cause : undefined } catch (_e) { cur = undefined } // getter-safe`);
-  lines.push(`  }`);
-  lines.push(`  return chain.length > 0 ? chain : [err]`);
-  lines.push(`}`);
-  lines.push(`// __errSnap — ONE snapshot PER FAILURE (round-6 B3; Codex round-5: .message was snapshot once`);
-  lines.push(`// per __errText INVOCATION, not once per failure — logging read it, classification read it`);
-  lines.push(`// AGAIN, so a one-shot .message getter answered the log and defeated classification: 2 getter`);
-  lines.push(`// reads, 1 attempt MEASURED). The catch site builds this snapshot ONCE; the log line and the`);
-  lines.push(`// classifier both consume the SNAPSHOT — .code/.name/.message are each read exactly once per`);
-  lines.push(`// failure, getter-safe, over the whole cause chain.`);
-  lines.push(`function __errSnap(err) {`);
-  lines.push(`  const chain = __causeChain(err)`);
-  lines.push(`  const snap = []`);
-  lines.push(`  for (let ci = 0; ci < chain.length; ci++) {`);
-  lines.push(`    let code = null`);
-  lines.push(`    try { const c = chain[ci] !== null && typeof chain[ci] === 'object' ? chain[ci].code : null; code = typeof c === 'string' ? c.toUpperCase() : null } catch (_e) { code = null }`);
-  lines.push(`    let name = null`);
-  lines.push(`    try { const n = chain[ci] !== null && typeof chain[ci] === 'object' ? chain[ci].name : null; name = typeof n === 'string' ? n : null } catch (_e) { name = null }`);
-  lines.push(`    snap.push({ code: code, name: name, text: __errText(chain[ci]) })`);
-  lines.push(`  }`);
-  lines.push(`  return snap`);
-  lines.push(`}`);
-  lines.push(`function __classifyFailure(outcome, snap) {`);
-  lines.push(`  if (outcome === 'null') return 'transport' // a dead/empty agent is a delivery failure — the "agent died" case is retryable ONLY under retryOn: ['transport']`);
-  lines.push(`  const links = Array.isArray(snap) ? snap : []`);
-  lines.push(`  for (let ci = 0; ci < links.length; ci++) {`);
-  lines.push(`    const code = links[ci].code`);
-  lines.push(`    if (code === 'ETIMEDOUT' || code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EPIPE' || code === 'ECONNABORTED' || code === 'EAI_AGAIN') return 'transport'`);
-  lines.push(`  }`);
-  lines.push(`  for (let ci = 0; ci < links.length; ci++) {`);
-  lines.push(`    if (links[ci].name === 'SyntaxError') return 'malformed-output'`);
-  lines.push(`  }`);
-  lines.push(`  let msg = ''`);
-  lines.push(`  for (let ci = 0; ci < links.length; ci++) { msg += (ci > 0 ? '\\n' : '') + links[ci].text }`);
-  lines.push(`  msg = msg.toLowerCase()`);
-  lines.push(`  // rate[ -]?limit(ed|ing|s)? is RIGHT-BOUNDED (round-5 B3: the open 'rate.?limit' matched`);
-  lines.push(`  // 'rate limitation: invalid JSON' as transport — a malformed-output failure smuggled a class)`);
-  lines.push(`  if (/\\btransport\\b|\\beconnreset\\b|\\beconnrefused\\b|\\benotfound\\b|\\bepipe\\b|\\betimedout\\b|\\bsocket hang up\\b|\\bnetwork error\\b|\\brate[ -]?limit(ed|ing|s)?\\b|\\boverloaded\\b|\\bhttp 5[0-9][0-9]\\b/.test(msg)) return 'transport'`);
-  lines.push(`  if (/\\bpolicy\\b|\\brefus(e|ed|es|al|ing)\\b|\\bdeclin(e|ed|es|ing)\\b|\\bcontent filter\\b|\\bsafety block\\b/.test(msg)) return 'policy-refusal'`);
-  lines.push(`  if (/\\bmalformed\\b|\\bunparseable\\b|\\bparse error\\b|\\binvalid json\\b|\\bunexpected token\\b|\\bunexpected end of json\\b|\\bschema mismatch\\b/.test(msg)) return 'malformed-output'`);
-  lines.push(`  if (/\\btimeout\\b|\\btimed out\\b/.test(msg)) return 'timeout'`);
-  lines.push(`  return null`);
-  lines.push(`}`);
+  lines.push(`// The enactment DECISIONS below are ALIASES onto the always-on \`loop-semantics\` blob`);
+  lines.push(`// (ADR-001 W4): errText/causeChain/errSnap/classifyFailure/gateVerdict/joinRegion have ONE`);
+  lines.push(`// implementation, sliced into this script from harness-core/src/loop-run-semantics.ts and`);
+  lines.push(`// IMPORTED (not copied) by the dz runner. The __-prefixed names are kept so every call site`);
+  lines.push(`// in this runtime reads exactly as it did when the bodies lived here.`);
+  lines.push(`const __errText = errText`);
+  lines.push(`const __causeChain = causeChain`);
+  lines.push(`const __errSnap = errSnap`);
+  lines.push(`const __classifyFailure = classifyFailure`);
   lines.push(`// __settleStep — THE single terminal exit of every step path (QE round-5 B3 class-kill;`);
   lines.push(`// round-6: SUCCESS-PATH PARITY — Codex round-5 showed __settleStep({outcome:'ok'}) returned`);
   lines.push(`// BEFORE flushing, leaving success durability on a naked phase-boundary await whose rejection`);
@@ -684,17 +615,8 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
   lines.push(`  if (lastErr !== null) throw lastErr`);
   lines.push(`  return null`);
   lines.push(`}`);
-  lines.push(`// join helper — explicit policy from the closed set; a dispatched branch is never skippable`);
-  lines.push(`function joinRegion(results, o) {`);
-  lines.push(`  const policy = o && o.policy ? o.policy : 'all-activated'`);
-  lines.push(`  const failures = []`);
-  lines.push(`  for (let i = 0; i < results.length; i++) { if (results[i] === null || results[i] === undefined) failures.push(i) }`);
-  lines.push(`  if (policy === 'any') { if (failures.length === results.length) { throw new Error('join ' + o.region + ': every branch failed (policy any)') } return { ok: true, values: results, failures: failures } }`);
-  lines.push(`  const quorum = /^quorum:([1-9][0-9]*)$/.exec(policy)`);
-  lines.push(`  if (quorum) { const okN = results.length - failures.length; if (okN < Number(quorum[1])) { throw new Error('join ' + o.region + ': quorum ' + quorum[1] + ' not met (' + okN + ' ok)') } return { ok: true, values: results, failures: failures } }`);
-  lines.push(`  if (failures.length > 0) { throw new Error('join ' + o.region + ': ' + failures.length + ' dispatched branch(es) failed under policy ' + policy + ' — a dispatched branch is never skippable') }`);
-  lines.push(`  return { ok: true, values: results, failures: [] }`);
-  lines.push(`}`);
+  lines.push(`// join helper — explicit policy from the closed set; a dispatched branch is never skippable.`);
+  lines.push(`// The DECISION lives in the loop-semantics blob above (\`joinRegion\`), called directly here.`);
   if (plan.steps.some((s) => s.kind === 'fanout')) {
     // ── QUIESCENCE (QE round-7 B3, the round-6 reviewer's FOURTH CLASS: structured-concurrency /
     // quiescence ownership). MEASURED by Codex on the previous shape: the region awaited a
@@ -871,20 +793,8 @@ function renderRuntime(plan: LoopPlan, planDig: string, execFp: string, blobs: L
     lines.push(`// must be the ONLY anchored verdict line. Embedded mid-reply "GATE: PASS" text never counts,`);
     lines.push(`// "GATE: PASS" followed by trailing prose is invalid, and "GATE: FAIL … GATE: PASS" is an`);
     lines.push(`// INVALID verdict (never a success) — routed like a failure (redo/fail route), never a pass.`);
-    lines.push(`function __gateVerdict(r) {`);
-    lines.push(`  if (typeof r !== 'string') return 'invalid'`);
-    lines.push(`  const vLines = r.split('\\n')`);
-    lines.push(`  const vRe = /^\\s*GATE:\\s*(PASS|FAIL)\\s*$/`);
-    lines.push(`  let vCount = 0`);
-    lines.push(`  let vLast = ''`);
-    lines.push(`  for (let i = 0; i < vLines.length; i++) {`);
-    lines.push(`    if (vRe.test(vLines[i])) { vCount++ }`);
-    lines.push(`    if (vLines[i].trim() !== '') { vLast = vLines[i] }`);
-    lines.push(`  }`);
-    lines.push(`  const vEnd = vRe.exec(vLast)`);
-    lines.push(`  if (vCount !== 1 || vEnd === null) return 'invalid'`);
-    lines.push(`  return vEnd[1] === 'PASS' ? 'pass' : 'fail'`);
-    lines.push(`}`);
+    lines.push(`// The grammar itself lives in the loop-semantics blob, shared with the dz runner.`);
+    lines.push(`const __gateVerdict = gateVerdict`);
   }
   lines.push(GE('runtime'));
   return lines.join('\n');

package/src/loop-run-semantics.ts

@@ -0,0 +1,278 @@
+/**
+ * `loop-run-semantics` — the ONE home of loop-designer's ENACTMENT DECISIONS (feature
+ * dz-workflow-run, ADR-001 W4).
+ *
+ * Before this module these semantics existed ONLY as template strings inside
+ * `loop-render.ts:renderRuntime` — readable by the generated Claude-host script and by nobody
+ * else. A second enactor (`dz workflow run`) would have had to COPY them, and two copies of a
+ * gate-verdict grammar is exactly how a runner comes to synthesize a pass the render would have
+ * refused. So the decisions move here once and are consumed twice:
+ *   • the generated script gets them as a BLOB (`scripts/gen-loop-blobs.mjs`, blob `loop-semantics`,
+ *     always on — the base runtime references errText/classifyFailure in every script);
+ *   • the dz runner imports them directly.
+ * "Imported, not copied" stops being an intention and becomes a fact a test can check.
+ *
+ * SCOPE, honestly (ADR-001 names it): what moves is DECISION semantics. `__drainAll`,
+ * `runStep` and `__settleStep` do NOT move — they are HOST-STRUCTURAL (they wrap the sandbox's
+ * `parallel()`/`agent()` and its settle discipline); the runner has its own structured concurrency
+ * and its own settle path.
+ *
+ * BLOB-SOURCE DISCIPLINE (same rule as `loop-trace.ts`): this module has NO RUNTIME IMPORT — its
+ * single `import type` is erased at compile time, so the generator can slice declarations out of it
+ * with no import to resolve. The generator's INV-12 output ban (fs / clock / randomness / process)
+ * holds here by construction: every function below is pure.
+ *
+ * One consequence of that discipline is visible in the signatures: the six BLOB-EXPORTED functions
+ * may not mention an IMPORTED type by bare name (the slicer would see an unresolvable cross-file
+ * reference and fail closed), so `classifyFailure` spells its return type as the inline import type
+ * `import('./loop-plan.js').FailureClass`. It is the SAME closed enum — one domain, not a restated
+ * copy — written in the one form the slicer can carry.
+ */
+
+import type { Deliverable, LoopPlan } from './loop-plan.js';
+
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs. */
+export const LOOP_RUN_SEMANTICS_BLOB_VERSION = '1.0.0';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BLOB EXPORTS — sliced verbatim into every rendered script AND imported by the runner.
+// Byte-semantics preserved from the template originals (loop-render.ts, pre-extraction):
+//   errText ← __errText · causeChain ← __causeChain · errSnap ← __errSnap
+//   classifyFailure ← __classifyFailure · gateVerdict ← __gateVerdict · joinRegion ← joinRegion
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ErrSnapLink {
+  code: string | null;
+  name: string | null;
+  text: string;
+}
+
+/**
+ * TOTAL error-to-text (the ha-consilium 5b totality lesson): the writer's own settle event must
+ * survive a hostile error object. `String(err)` throws on a null-prototype object and a throwing
+ * `.message` getter throws on access — both are caught here, so rendering a message can never
+ * replace the original failure or lose the settle. `.message` is read ONCE into a local (a one-shot
+ * getter answered the `typeof` probe and vanished on the value read — snapshot-once defeats it).
+ */
+export function errText(err: unknown): string {
+  try {
+    if (err !== null && typeof err === 'object') {
+      const m = (err as { message?: unknown }).message;
+      if (typeof m === 'string') return m;
+    }
+    return String(err);
+  } catch (_e) {
+    try {
+      return Object.prototype.toString.call(err);
+    } catch (_e2) {
+      return '[unrenderable error]';
+    }
+  }
+}
+
+/**
+ * The `err.cause` chain, bounded (depth 5), cycle-safe and getter-safe. The standard Node fetch
+ * shape `TypeError('fetch failed', { cause: { code: 'ECONNRESET' } })` hides its real class one
+ * link down, so classification must see the whole chain, not the outermost error.
+ */
+export function causeChain(err: unknown): unknown[] {
+  const chain: unknown[] = [];
+  let cur: unknown = err;
+  for (let d = 0; d < 5; d++) {
+    if (cur === null || cur === undefined) break;
+    if (chain.indexOf(cur) !== -1) break; // cycle-safe
+    chain.push(cur);
+    try {
+      cur = typeof cur === 'object' ? (cur as { cause?: unknown }).cause : undefined;
+    } catch (_e) {
+      cur = undefined; // getter-safe
+    }
+  }
+  return chain.length > 0 ? chain : [err];
+}
+
+/**
+ * ONE snapshot PER FAILURE. The earlier shape snapshotted `.message` once per `errText` CALL, not
+ * once per failure — so logging read it, classification read it AGAIN, and a one-shot `.message`
+ * getter answered the log and defeated the classifier (2 getter reads, 1 attempt, MEASURED). The
+ * catch site builds this snapshot once; the log line and the classifier both consume the SNAPSHOT,
+ * so `.code` / `.name` / `.message` are each read exactly once per failure, over the whole chain.
+ */
+export function errSnap(err: unknown): ErrSnapLink[] {
+  const chain = causeChain(err);
+  const snap: ErrSnapLink[] = [];
+  for (let ci = 0; ci < chain.length; ci++) {
+    let code: string | null = null;
+    try {
+      const c = chain[ci] !== null && typeof chain[ci] === 'object' ? (chain[ci] as { code?: unknown }).code : null;
+      code = typeof c === 'string' ? c.toUpperCase() : null;
+    } catch (_e) {
+      code = null;
+    }
+    let name: string | null = null;
+    try {
+      const n = chain[ci] !== null && typeof chain[ci] === 'object' ? (chain[ci] as { name?: unknown }).name : null;
+      name = typeof n === 'string' ? n : null;
+    } catch (_e) {
+      name = null;
+    }
+    snap.push({ code: code, name: name, text: errText(chain[ci]) });
+  }
+  return snap;
+}
+
+/**
+ * The CLOSED failure classification of `loop-plan/1` (timeout | transport | malformed-output |
+ * policy-refusal). THREE TIERS over the whole cause chain, strongest first:
+ *   1. error CODE — works on non-Error shapes like `{code:'ECONNRESET'}`, never message-dependent
+ *      (`ETIMEDOUT` is a TRANSPORT code; an earlier message regex captured it as 'timeout' first);
+ *   2. error NAME — `SyntaxError` = parsing the model's output failed → malformed-output;
+ *   3. message patterns, DISJOINT by precedence transport > policy-refusal > malformed-output >
+ *      timeout, every alternative WORD-BOUNDED (an unbounded `rate.?limit` matched
+ *      'delibeRATE LIMITation' — a substring must never smuggle a class).
+ * `outcome: 'null'` (a dead/empty agent) is a delivery failure ⇒ `transport`, retryable ONLY under
+ * `retryOn: ['transport']`. An UNCLASSIFIABLE failure returns null and is NEVER retried.
+ */
+export function classifyFailure(
+  outcome: 'null' | 'error',
+  snap: ErrSnapLink[],
+): import('./loop-plan.js').FailureClass | null {
+  if (outcome === 'null') return 'transport';
+  const links = Array.isArray(snap) ? snap : [];
+  for (let ci = 0; ci < links.length; ci++) {
+    const code = (links[ci] as ErrSnapLink).code;
+    if (code === 'ETIMEDOUT' || code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EPIPE' || code === 'ECONNABORTED' || code === 'EAI_AGAIN') return 'transport';
+  }
+  for (let ci = 0; ci < links.length; ci++) {
+    if ((links[ci] as ErrSnapLink).name === 'SyntaxError') return 'malformed-output';
+  }
+  let msg = '';
+  for (let ci = 0; ci < links.length; ci++) msg += (ci > 0 ? '\n' : '') + (links[ci] as ErrSnapLink).text;
+  msg = msg.toLowerCase();
+  // rate[ -]?limit(ed|ing|s)? is RIGHT-BOUNDED: the open 'rate.?limit' matched
+  // 'rate limitation: invalid JSON' as transport — a malformed-output failure smuggled a class.
+  if (/\btransport\b|\beconnreset\b|\beconnrefused\b|\benotfound\b|\bepipe\b|\betimedout\b|\bsocket hang up\b|\bnetwork error\b|\brate[ -]?limit(ed|ing|s)?\b|\boverloaded\b|\bhttp 5[0-9][0-9]\b/.test(msg)) return 'transport';
+  if (/\bpolicy\b|\brefus(e|ed|es|al|ing)\b|\bdeclin(e|ed|es|ing)\b|\bcontent filter\b|\bsafety block\b/.test(msg)) return 'policy-refusal';
+  if (/\bmalformed\b|\bunparseable\b|\bparse error\b|\binvalid json\b|\bunexpected token\b|\bunexpected end of json\b|\bschema mismatch\b/.test(msg)) return 'malformed-output';
+  if (/\btimeout\b|\btimed out\b/.test(msg)) return 'timeout';
+  return null;
+}
+
+export type GateVerdict = 'pass' | 'fail' | 'invalid';
+
+/**
+ * Gate verdict parsing — parse-NEVER-synthesize, with the EXACTLY-ONE-ENDING-LINE protocol
+ * enforced: the verdict must be an ANCHORED line ("GATE: PASS" or "GATE: FAIL" alone on its line),
+ * it must be the LAST non-empty line of the reply, and it must be the ONLY anchored verdict line.
+ * Embedded mid-reply "GATE: PASS" text never counts, "GATE: PASS" followed by trailing prose is
+ * invalid, and "GATE: FAIL … GATE: PASS" is an INVALID verdict (never a success) — routed like a
+ * failure (redo / fail route), never a pass.
+ */
+export function gateVerdict(reply: unknown): GateVerdict {
+  if (typeof reply !== 'string') return 'invalid';
+  const vLines = reply.split('\n');
+  const vRe = /^\s*GATE:\s*(PASS|FAIL)\s*$/;
+  let vCount = 0;
+  let vLast = '';
+  for (let i = 0; i < vLines.length; i++) {
+    if (vRe.test(vLines[i] as string)) vCount++;
+    if ((vLines[i] as string).trim() !== '') vLast = vLines[i] as string;
+  }
+  const vEnd = vRe.exec(vLast);
+  if (vCount !== 1 || vEnd === null) return 'invalid';
+  return vEnd[1] === 'PASS' ? 'pass' : 'fail';
+}
+
+export interface JoinOutcome {
+  ok: true;
+  values: unknown[];
+  failures: number[];
+}
+
+/**
+ * The join decision — explicit policy from the closed set; a dispatched branch is never skippable.
+ * `any` fails only when EVERY branch failed; `quorum:<n>` needs n non-failing branches; every other
+ * policy (the `all-*` family) fails on the first failing branch. Throws with a NAMED message, which
+ * the caller settles through its own single terminal exit.
+ */
+export function joinRegion(results: unknown[], o: { policy: string; onInvalid: string; region: string }): JoinOutcome {
+  const policy = o && o.policy ? o.policy : 'all-activated';
+  const failures: number[] = [];
+  for (let i = 0; i < results.length; i++) {
+    if (results[i] === null || results[i] === undefined) failures.push(i);
+  }
+  if (policy === 'any') {
+    if (failures.length === results.length) throw new Error('join ' + o.region + ': every branch failed (policy any)');
+    return { ok: true, values: results, failures: failures };
+  }
+  const quorum = /^quorum:([1-9][0-9]*)$/.exec(policy);
+  if (quorum) {
+    const okN = results.length - failures.length;
+    if (okN < Number(quorum[1])) throw new Error('join ' + o.region + ': quorum ' + quorum[1] + ' not met (' + okN + ' ok)');
+    return { ok: true, values: results, failures: failures };
+  }
+  if (failures.length > 0) throw new Error('join ' + o.region + ': ' + failures.length + ' dispatched branch(es) failed under policy ' + policy + ' — a dispatched branch is never skippable');
+  return { ok: true, values: results, failures: [] };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NON-BLOB EXPORTS — shared by loop-render.ts and workflow-run.ts, never injected into a script
+// (the rendered script receives the RESULT of these as literal text / a literal number).
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ContractInputs {
+  reads: string[];
+  writes: string[];
+  deliverable: Deliverable;
+  tools: string[];
+  gate: { kind: string } | null;
+}
+
+/**
+ * THE agent-visible contract TEXT lines (ADR-001 Confirmation-5) — byte-for-byte the strings the
+ * render splices after a step's USER prompt, minus the JS quoting. Both enactors assemble a step's
+ * prompt from the SAME function, so a dz-hosted step and a Claude-hosted step communicate the plan's
+ * declarations identically; a value-pinned wiring test compares the rendered USER-region contract
+ * lines against the runner-assembled ones.
+ *
+ * The tools line's second sentence is not decoration — it is the honesty clause the whole feature
+ * rests on: a declaration is not enforcement.
+ */
+export function stepContractLines(c: ContractInputs): string[] {
+  const lines: string[] = [];
+  const reads = c.reads ?? [];
+  const writes = c.writes ?? [];
+  const tools = c.tools ?? [];
+  if (reads.length > 0) lines.push('declared inputs (plan artifacts.reads): ' + reads.join(', '));
+  if (writes.length > 0) {
+    const fileNote = (c.deliverable ?? 'return-value') === 'file' ? '; your deliverable is the written file(s), not your reply' : '';
+    lines.push('declared outputs (plan artifacts.writes): ' + writes.join(', ') + ' — write them' + fileNote + '. The loop verifies they land.');
+  }
+  if (tools.length > 0) {
+    lines.push('declared MCP tool allowlist (plan tools): ' + tools.join(', ') + ' — use NOTHING outside it. In this environment every one of these is a labeled STUB, not a live integration; enforcement lives at the MCP server, not here.');
+  }
+  if (c.gate !== null && c.gate !== undefined) {
+    lines.push('GATE PROTOCOL (kind: ' + (c.gate.kind ?? 'gate') + '): end your reply with exactly one line "GATE: PASS" or "GATE: FAIL" — the loop PARSES this verdict and never synthesizes one.');
+  }
+  return lines;
+}
+
+/**
+ * THE budget ceiling formula (ADR-004 Confirmation-2): declared per-step budgets PLUS the declared
+ * gate-redo allowance — a plan-declared redo must be AFFORDABLE (an undeclared one still hits the
+ * guard loudly). A gate whose failRoute is a `terminal:` route reserves nothing: a terminal route
+ * ends the run, it does not re-run anything.
+ *
+ * This is the number the rendered script carries as `const __budget = { left: N }`; the runner reads
+ * it from HERE, so the two enactors cannot drift into two ceilings.
+ */
+export function computeBudgetTotal(plan: LoopPlan): number {
+  const stepBudget = plan.steps.reduce((n, s) => n + (s.budget?.maxAgents ?? 1), 0);
+  const byId = new Map(plan.steps.map((s) => [s.stepId, s]));
+  const gateRedoBudget = (plan.gates ?? []).reduce((n, g) => {
+    const redos = typeof g.maxRedos === 'number' && Number.isFinite(g.maxRedos) && g.maxRedos > 0 ? Math.floor(g.maxRedos) : 0;
+    if (redos === 0 || typeof g.failRoute !== 'string' || g.failRoute.startsWith('terminal:')) return n;
+    return n + redos * ((byId.get(g.failRoute)?.budget?.maxAgents ?? 1) + (byId.get(g.stepId)?.budget?.maxAgents ?? 1));
+  }, 0);
+  return stepBudget + gateRedoBudget;
+}

package/src/loop-trace.ts

@@ -211,6 +211,19 @@ export function traceFlushCmd(state: TraceState, traceFileAbs: string): string |
   return 'mkdir -p ' + dir + ' && ' + printfs;
 }
 
+/**
+ * Drain the buffered, already-VALIDATED lines — the runner's flush primitive (W17/T0.1). The
+ * fs-less Claude host turns the same buffer into a shell command (`traceFlushCmd`); a host that
+ * HAS fs (the `dz workflow run` scheduler) appends exactly these lines itself. One buffer, two
+ * drains, zero second line-shape: a line this returns has already passed `traceValidateEvent`,
+ * because nothing else can enter the buffer. Empty buffer ⇒ `[]` (never a repeat of the last
+ * batch).
+ */
+export function traceDrain(state: TraceState): string[] {
+  if (state.buffer.length === 0) return [];
+  return state.buffer.splice(0, state.buffer.length);
+}
+
 /**
  * Build the feature-ADR live-panel telemetry leg. Totality comes from the caller's grouped splice:
  * returning the bare command lets that splice preserve the trace flush's exit status while
@@ -303,12 +316,31 @@ export interface TraceRun {
   parseErrors: string[];
 }
 
-/** Parse a trace.jsonl text. Tolerant of a missing run.closed (incomplete: true); a DUPLICATE
- * settle for one invocation is a PARSE ERROR, never a silent merge (INV-15). */
+/**
+ * Parse a trace.jsonl text. Tolerant of a missing run.closed (incomplete: true); a DUPLICATE
+ * settle for one invocation is a PARSE ERROR, never a silent merge (INV-15).
+ *
+ * W17 / AM-12 — `run.events` is CANONICALIZED by ascending `seq` after the line scan. The host's
+ * batched racing flush agents legitimately append out of seq order (MEASURED on the committed
+ * `pkg-audit-1` run: lines 1-2 are settles seq 7 and 6, ahead of `run.opened` seq 1), and the
+ * reader used to inherit that file order — so `invocations()` DROPPED every settle that preceded
+ * its own dispatch in the file, and a complete, successful run read as three FAIL verdicts. seq is
+ * the authoritative order (it is allocated synchronously at the lifecycle transition); file order
+ * is a durability artifact the flush design already blesses, and it stays recoverable only from the
+ * raw text.
+ *
+ * Order of the two bookkeeping passes is load-bearing:
+ *   • LINE-SHAPE errors (unparseable / invalid event) are recorded in FILE order — they describe
+ *     the bytes, and quoting them in file order is what lets a human find the line.
+ *   • The duplicate-dispatch and duplicate-settle checks run AFTER canonicalization, so "which
+ *     settle is the duplicate" is decided by seq, not by which flush batch happened to land first
+ *     (before this, reversing the flush order changed WHICH event INV-15 refused).
+ * The sort is stable, so two events sharing one seq keep their file order relative to each other —
+ * the only ordering the file can still testify to. INV-14 fails such a trace on uniqueness anyway.
+ */
 export function parseTrace(text: string): TraceRun {
   const run: TraceRun = { runId: null, planDigest: null, execFp: null, events: [], incomplete: true, parseErrors: [] };
-  const settledSeen = new Set<string>();
-  const dispatchSeen = new Set<string>();
+  const scanned: TraceEvent[] = [];
   for (const line of String(text ?? '').split('\n')) {
     const t = line.trim();
     if (t === '') continue;
@@ -324,7 +356,13 @@ export function parseTrace(text: string): TraceRun {
       run.parseErrors.push('invalid event (' + err + '): ' + t.slice(0, 120));
       continue;
     }
-    const ev = e as TraceEvent;
+    scanned.push(e as TraceEvent);
+  }
+  // CANONICALIZATION (the W17 fix): ascending seq, stable.
+  scanned.sort((a, b) => a.seq - b.seq);
+  const settledSeen = new Set<string>();
+  const dispatchSeen = new Set<string>();
+  for (const ev of scanned) {
     if (ev.event === 'run.opened') {
       run.runId = ev.runId;
       run.planDigest = ev.planDigest;
@@ -395,13 +433,49 @@ export function runInvariants(projection: TraceProjection, run: TraceRun): Invar
   const out: InvariantVerdict[] = [];
   const invs = invocations(run);
 
-  // INV-14: seq unique + strictly increasing in event order.
+  // INV-14 (RESTATED, W17/AM-12 — verdict id UNCHANGED: `seq-monotonic` is the consumer contract,
+  // keyed on by the fitness suite and every `dz workflow-trace` reader, so only the SEMANTICS and
+  // the message restate). `parseTrace` now canonicalizes by seq, so "strictly increasing in event
+  // order" became tautological — it tested the reader's own sort. The property that still has
+  // teeth is the SINGLE-ALLOCATOR witness:
+  //   • seq values are UNIQUE (two writers, or one writer allocating twice, collide) — always;
+  //   • on a COMPLETE trace they are exactly contiguous 1..maxSeq (a closed run that skips a
+  //     number lost an event or had a second allocator);
+  //   • on an INCOMPLETE trace a gap is INCONCLUSIVE, never a pass — the window is truncated, so
+  //     a missing number is indistinguishable from an unflushed one.
+  // Residue accepted and named in AM-12: a writer allocating unique + contiguous seq in a
+  // non-monotonic ORDER is no longer detectable. Allocation order was only ever observable through
+  // the racy append that this fix (correctly) stopped trusting.
   {
     const seqs = run.events.map((e) => e.seq);
-    const dup = seqs.some((s, i) => seqs.indexOf(s) !== i);
-    const decreasing = seqs.some((s, i) => i > 0 && s <= (seqs[i - 1] as number));
-    if (dup || decreasing) out.push({ id: 'seq-monotonic', status: 'fail', message: 'seq is not unique/strictly-increasing — the single serialized writer property is broken' });
-    else out.push({ id: 'seq-monotonic', status: 'pass', message: 'seq unique and strictly increasing (' + seqs.length + ' events)' });
+    const dupes = [...new Set(seqs.filter((s, i) => seqs.indexOf(s) !== i))].sort((a, b) => a - b);
+    if (dupes.length > 0) {
+      out.push({
+        id: 'seq-monotonic',
+        status: 'fail',
+        message: 'duplicate seq value(s) ' + dupes.join(', ') + ' — the single-ALLOCATOR property is broken (seq must be unique across the whole run)',
+      });
+    } else {
+      const maxSeq = seqs.length === 0 ? 0 : Math.max(...seqs);
+      const missing: number[] = [];
+      const present = new Set(seqs);
+      for (let s = 1; s <= maxSeq && missing.length < 8; s++) if (!present.has(s)) missing.push(s);
+      if (missing.length === 0) {
+        out.push({ id: 'seq-monotonic', status: 'pass', message: 'seq unique and contiguous 1..' + maxSeq + ' (' + seqs.length + ' events)' });
+      } else if (run.incomplete) {
+        out.push({
+          id: 'seq-monotonic',
+          status: 'inconclusive',
+          message: 'seq unique but NOT contiguous (missing ' + missing.join(', ') + ' of 1..' + maxSeq + ') on an INCOMPLETE trace — a truncated window is indistinguishable from a lost event',
+        });
+      } else {
+        out.push({
+          id: 'seq-monotonic',
+          status: 'fail',
+          message: 'seq is not contiguous 1..' + maxSeq + ' on a COMPLETE trace — missing ' + missing.join(', ') + ' (a closed run that skips a number lost an event or had a second allocator)',
+        });
+      }
+    }
   }
 
   // INV-15: pairing (a dangling dispatch is only conclusive on a complete trace).