@dzhechkov/harness-core 0.3.150 → 0.4.2

package/src/loop-trace.ts

@@ -0,0 +1,727 @@
+/**
+ * `loop-trace/1` — the trace plane of loop-designer (ADR-003: THE loop is its own sequencer).
+ *
+ * The host runtime's journal.jsonl has neither `seq` nor `ts` (MEASURED, K3) and is not repo code,
+ * so ordering can never come from it. Instead, the GENERATED loop emits its own trace events:
+ * `seq` is allocated by ONE module-level counter incremented SYNCHRONOUSLY at the lifecycle
+ * transition — immediately before `agent()`/`parallel()` is called (`dispatched`) and synchronously
+ * in the continuation after the `await` settles (`settled`). The sandbox runs a single-threaded JS
+ * context, so the counter is by construction unique and strictly increasing within a run (INV-14),
+ * and the allocation can never be separated from the call by an async write (AM-2 — the seq-at-
+ * write-time trap). `wallTime` is written shell-side by the flush command and is DIAGNOSTIC ONLY
+ * (INV-16 — never an operand of an invariant).
+ *
+ * EMITTER HALF (top of file, sandbox-safe — the `trace` blob is generated from these exports by
+ * scripts/gen-loop-blobs.mjs; no fs/Date/random/process here, ever).
+ *
+ * IMPORTS (QE round-7, stated precisely): this module has NO RUNTIME IMPORT. Its single `import
+ * type { TraceProjection } from './loop-plan.js'` is type-only and is erased at compile time, so
+ * there is no runtime cycle with loop-plan and the generated blob carries no import at all. (The
+ * ItemKey domain travels the other way — loop-plan imports `TRACE_KEY_RE` from here and re-exports
+ * it as `ITEM_KEY_RE`, one object shared by both layers.) "Import-free" would be the WRONG word.
+ * READER HALF (below) — parseTrace / assembleTimeline / runInvariants / renderTimelineHtml,
+ * consumed by `dz workflow-trace` and by the fitness suite (same runInvariants, two call sites).
+ */
+
+import type { TraceProjection } from './loop-plan.js';
+
+/** Blob version stamp for the emitter half (read by scripts/gen-loop-blobs.mjs). */
+export const LOOP_TRACE_BLOB_VERSION = '1.1.0';
+
+export const LOOP_TRACE_SCHEMA_VERSION = 1;
+
+/** runId VO: shell-inert, short. */
+export const TRACE_RUNID_RE = /^[a-z0-9-]{1,40}$/;
+/** stepId/itemKey VO: a stated, shell-inert superset of runId's alphabet (dots/underscores/colons
+ * for fanout-registry keys; quotes, $, backticks, newlines, spaces all excluded). */
+export const TRACE_KEY_RE = /^[a-z0-9_.:-]{1,64}$/i;
+
+export interface TraceDispatchEvent {
+  v: 1;
+  runId: string;
+  seq: number;
+  event: 'dispatched';
+  invocationId: string;
+  stepId: string;
+  itemKey: string | null;
+  attempt: number;
+  phase: string;
+  model: string | null;
+  causedBy: number[];
+}
+
+export interface TraceSettleEvent {
+  v: 1;
+  runId: string;
+  seq: number;
+  event: 'settled';
+  invocationId: string;
+  outcome: 'ok' | 'null' | 'error';
+  wallTime?: string | null;
+}
+
+export interface TraceRunOpened {
+  v: 1;
+  runId: string;
+  seq: number;
+  event: 'run.opened';
+  planDigest: string;
+  execFp: string;
+}
+
+export interface TraceRunClosed {
+  v: 1;
+  runId: string;
+  seq: number;
+  event: 'run.closed';
+  counts: { dispatched: number; settled: number };
+}
+
+export type TraceEvent = TraceDispatchEvent | TraceSettleEvent | TraceRunOpened | TraceRunClosed;
+
+export interface TraceState {
+  runId: string;
+  seq: number;
+  dispatched: number;
+  settled: number;
+  /** Buffered, validated event lines awaiting the next flush. */
+  buffer: string[];
+}
+
+/** shq twin, private to the trace plane (kept self-named so the trace blob never collides with the
+ * checkpoints blob's shellQuote when both are included in one script). */
+export function traceShellQuote(s: string): string {
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Validate one event BEFORE it is buffered (the injection discipline): trace.jsonl is the
+ * AUTHORITATIVE ordering source, so a non-conforming or injected event is a HARD ERROR at buffer
+ * time — never a line repaired later. Returns an error string or null.
+ */
+export function traceValidateEvent(e: unknown): string | null {
+  if (typeof e !== 'object' || e === null || Array.isArray(e)) return 'event must be an object';
+  const ev = e as Record<string, unknown>;
+  if (ev['v'] !== 1) return 'v must be 1';
+  if (typeof ev['runId'] !== 'string' || !TRACE_RUNID_RE.test(ev['runId'])) return 'runId fails its VO regex';
+  if (typeof ev['seq'] !== 'number' || !Number.isInteger(ev['seq']) || ev['seq'] < 1) return 'seq must be a positive integer';
+  const kind = ev['event'];
+  if (kind === 'dispatched') {
+    if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '') return 'invocationId required';
+    if (typeof ev['stepId'] !== 'string' || !TRACE_KEY_RE.test(ev['stepId'])) return 'stepId fails its VO regex';
+    if (ev['itemKey'] !== null && (typeof ev['itemKey'] !== 'string' || !TRACE_KEY_RE.test(ev['itemKey']))) return 'itemKey fails its VO regex';
+    if (typeof ev['attempt'] !== 'number' || ev['attempt'] < 1) return 'attempt must be >= 1';
+    if (typeof ev['phase'] !== 'string' || ev['phase'] === '') return 'phase required';
+    if (!Array.isArray(ev['causedBy']) || (ev['causedBy'] as unknown[]).some((n) => typeof n !== 'number')) return 'causedBy must be a number array';
+    return null;
+  }
+  if (kind === 'settled') {
+    if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '') return 'invocationId required';
+    if (ev['outcome'] !== 'ok' && ev['outcome'] !== 'null' && ev['outcome'] !== 'error') return 'outcome must be ok|null|error';
+    return null;
+  }
+  if (kind === 'run.opened') {
+    if (typeof ev['planDigest'] !== 'string' || typeof ev['execFp'] !== 'string') return 'run.opened needs planDigest + execFp';
+    return null;
+  }
+  if (kind === 'run.closed') {
+    const c = ev['counts'];
+    if (typeof c !== 'object' || c === null) return 'run.closed needs counts';
+    return null;
+  }
+  return 'unknown event kind';
+}
+
+/** Open a trace state and buffer the run.opened frame. Throws on an invalid runId (fail-closed). */
+export function traceInit(runId: string, planDigest: string, execFp: string): TraceState {
+  if (!TRACE_RUNID_RE.test(runId)) throw new Error('loop-trace: runId fails ' + String(TRACE_RUNID_RE));
+  const state: TraceState = { runId, seq: 0, dispatched: 0, settled: 0, buffer: [] };
+  const opened: TraceRunOpened = { v: 1, runId, seq: ++state.seq, event: 'run.opened', planDigest, execFp };
+  traceBuffer(state, opened);
+  return state;
+}
+
+function traceBuffer(state: TraceState, e: TraceEvent): void {
+  const err = traceValidateEvent(e);
+  if (err !== null) throw new Error('loop-trace: refusing non-conforming event (' + err + ') — the authoritative ordering source is never repaired later');
+  state.buffer.push(JSON.stringify(e));
+}
+
+/**
+ * Allocate the DISPATCH seq and buffer the event — called SYNCHRONOUSLY immediately before the
+ * `agent()`/`parallel()` call (the same synchronous statement pair; AM-2). Returns the seq.
+ */
+export function traceOnDispatch(
+  state: TraceState,
+  e: { invocationId: string; stepId: string; itemKey: string | null; attempt: number; phase: string; model: string | null; causedBy: number[] },
+): number {
+  const seq = ++state.seq;
+  state.dispatched++;
+  traceBuffer(state, {
+    v: 1,
+    runId: state.runId,
+    seq,
+    event: 'dispatched',
+    invocationId: e.invocationId,
+    stepId: e.stepId,
+    itemKey: e.itemKey,
+    attempt: e.attempt,
+    phase: e.phase,
+    model: e.model,
+    causedBy: e.causedBy,
+  });
+  return seq;
+}
+
+/** Allocate the SETTLE seq and buffer the event — called synchronously in the continuation after
+ * the await resolves or rejects. Returns the seq (the causedBy input for dependents). */
+export function traceOnSettle(state: TraceState, e: { invocationId: string; outcome: 'ok' | 'null' | 'error' }): number {
+  const seq = ++state.seq;
+  state.settled++;
+  traceBuffer(state, { v: 1, runId: state.runId, seq, event: 'settled', invocationId: e.invocationId, outcome: e.outcome });
+  return seq;
+}
+
+/** Buffer the run.closed frame (a trace without it parses as incomplete). */
+export function traceClose(state: TraceState): void {
+  const closed: TraceRunClosed = {
+    v: 1,
+    runId: state.runId,
+    seq: ++state.seq,
+    event: 'run.closed',
+    counts: { dispatched: state.dispatched, settled: state.settled },
+  };
+  traceBuffer(state, closed);
+}
+
+/**
+ * Drain the buffer into ONE batched append command (the flush the cheap writer agent runs).
+ * Each ENTIRE line is shq-escaped before splicing (JSON.stringify never emits raw newlines, so
+ * printf '%s\n' emits exactly one record per line). Wall-clock is added SHELL-SIDE via sed —
+ * diagnostic only (INV-16). Returns null when the buffer is empty (no agent call to spend).
+ */
+export function traceFlushCmd(state: TraceState, traceFileAbs: string): string | null {
+  if (state.buffer.length === 0) return null;
+  const lines = state.buffer.splice(0, state.buffer.length);
+  const file = traceShellQuote(traceFileAbs);
+  const dir = traceShellQuote(traceFileAbs.replace(/\/[^/]*$/, ''));
+  const printfs = lines
+    .map((l) => "printf '%s\\n' " + traceShellQuote(l) + ' | sed "s/}$/,\\"wallTime\\":\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\"}/" >> ' + file)
+    .join(' && ');
+  return 'mkdir -p ' + dir + ' && ' + printfs;
+}
+
+/**
+ * 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
+ * swallowing only the panel leg's failure. The `loop` producer marker stops a generated loop's
+ * high-frequency zero counters from displacing a live `/feature-adr` run's meaningful panel.
+ */
+export function traceFaRecordCmd(dzBin: unknown, slug: unknown, stepLabel: unknown, projectAbs: unknown): string | null {
+  if (typeof slug !== 'string' || slug === ''
+    || typeof stepLabel !== 'string' || stepLabel === ''
+    || typeof projectAbs !== 'string' || projectAbs === '') return null;
+  const bin = typeof dzBin === 'string' && dzBin !== '' ? dzBin : 'dz';
+  const cmd = traceShellQuote(bin) + ' statusline --fa-record --slug ' + traceShellQuote(slug)
+    + ' --step ' + traceShellQuote(stepLabel) + ' --kind loop --project ' + traceShellQuote(projectAbs);
+  return cmd + ' >/dev/null 2>&1';
+}
+
+/** Build one feature-ADR run-cost row without manufacturing wall-clock data in JavaScript. */
+export function traceLedgerLine(opts: {
+  slug: unknown;
+  runId?: unknown;
+  planDigest?: unknown;
+  /**
+   * `agents` is the TOTAL number of agent invocations this run made — model dispatches AND infra
+   * agents (trace flush, checkpoint read/write, training-pair write/backfill, landed-barrier probes,
+   * and this ledger writer itself) — counted at write time. It is NOT the trace's model-dispatch
+   * count; the ledger's `agents` column means `agent_count` from the Workflow completion
+   * notification, and this row must not silently redefine it.
+   */
+  agents?: unknown;
+  date?: unknown;
+  outcome?: unknown;
+}): string | null {
+  try {
+    if (typeof opts.slug !== 'string' || opts.slug === '') return null;
+    const agents = typeof opts.agents === 'number'
+      && Number.isFinite(opts.agents)
+      && Number.isInteger(opts.agents)
+      && opts.agents >= 0
+      ? opts.agents
+      : 0;
+    const date = typeof opts.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(opts.date) ? opts.date : null;
+    const outcome = typeof opts.outcome === 'string' && opts.outcome !== '' ? opts.outcome : 'unknown';
+    const line = JSON.stringify({
+      slug: opts.slug,
+      stage: 'loop-run',
+      tier: null,
+      tokens: null,
+      minutes: null,
+      agents,
+      coder: null,
+      grade: null,
+      date,
+      auto: true,
+      outcome,
+      runId: typeof opts.runId === 'string' ? opts.runId : null,
+      planDigest: typeof opts.planDigest === 'string' ? opts.planDigest : null,
+    });
+    return line.length <= 4000 ? line : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Build the single command that appends a run-cost row and confirms the write. */
+export function traceLedgerAppendCmd(repoAbs: unknown, line: unknown): string | null {
+  if (typeof repoAbs !== 'string' || repoAbs === '' || typeof line !== 'string' || line === '') return null;
+  const dir = traceShellQuote(repoAbs + '/.dz/feature-adr');
+  const file = traceShellQuote(repoAbs + '/.dz/feature-adr/run-cost-ledger.jsonl');
+  // The field token has a fixed position, and JSON-escaped scalar values (including slug,
+  // runId, and planDigest) cannot introduce the raw `"date":null` token targeted by sed.
+  return 'mkdir -p ' + dir
+    + " && printf '%s' " + traceShellQuote(line)
+    + ' | sed "s/\\"date\\":null/\\"date\\":\\"$(date -u +%Y-%m-%d)\\"/" >> ' + file
+    + " && printf '\\n' >> " + file
+    + ' && echo LEDGER-OK';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// READER HALF — parseTrace / runInvariants / assembleTimeline / renderTimelineHtml.
+// Pure over strings; the CLI does the fs.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TraceRun {
+  runId: string | null;
+  planDigest: string | null;
+  execFp: string | null;
+  events: TraceEvent[];
+  /** No run.closed frame ⇒ the tail may be lost; truncated-window invariants report inconclusive. */
+  incomplete: boolean;
+  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). */
+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>();
+  for (const line of String(text ?? '').split('\n')) {
+    const t = line.trim();
+    if (t === '') continue;
+    let e: unknown;
+    try {
+      e = JSON.parse(t);
+    } catch {
+      run.parseErrors.push('unparseable line: ' + t.slice(0, 120));
+      continue;
+    }
+    const err = traceValidateEvent(e);
+    if (err !== null) {
+      run.parseErrors.push('invalid event (' + err + '): ' + t.slice(0, 120));
+      continue;
+    }
+    const ev = e as TraceEvent;
+    if (ev.event === 'run.opened') {
+      run.runId = ev.runId;
+      run.planDigest = ev.planDigest;
+      run.execFp = ev.execFp;
+    }
+    if (ev.event === 'run.closed') run.incomplete = false;
+    if (ev.event === 'dispatched') {
+      const key = ev.invocationId + '@' + ev.attempt;
+      if (dispatchSeen.has(key)) run.parseErrors.push('duplicate dispatch for ' + key);
+      dispatchSeen.add(key);
+    }
+    if (ev.event === 'settled') {
+      if (settledSeen.has(ev.invocationId)) {
+        run.parseErrors.push('duplicate settle for invocation ' + ev.invocationId + ' — refusing to merge (INV-15)');
+        continue;
+      }
+      settledSeen.add(ev.invocationId);
+    }
+    run.events.push(ev);
+  }
+  return run;
+}
+
+export type InvariantStatus = 'pass' | 'fail' | 'inconclusive';
+
+export interface InvariantVerdict {
+  id: string;
+  status: InvariantStatus;
+  message: string;
+}
+
+interface Invocation {
+  invocationId: string;
+  stepId: string;
+  itemKey: string | null;
+  dispatchSeq: number;
+  settleSeq: number | null;
+  causedBy: number[];
+}
+
+function invocations(run: TraceRun): Invocation[] {
+  const out = new Map<string, Invocation>();
+  for (const e of run.events) {
+    if (e.event === 'dispatched') {
+      out.set(e.invocationId, {
+        invocationId: e.invocationId,
+        stepId: e.stepId,
+        itemKey: e.itemKey,
+        dispatchSeq: e.seq,
+        settleSeq: null,
+        causedBy: e.causedBy,
+      });
+    } else if (e.event === 'settled') {
+      const inv = out.get(e.invocationId);
+      if (inv) inv.settleSeq = e.seq;
+    }
+  }
+  return [...out.values()];
+}
+
+/**
+ * Evaluate the plan-derived runtime invariants over an observed trace. Consumes ONLY
+ * `toTraceProjection(plan)` (AM-3) and ONLY runtime-assigned `seq` (never wallTime — INV-16).
+ * The SAME function serves the fitness suite and `dz workflow-trace` (one implementation,
+ * two call sites). An incomplete trace turns window-truncated checks inconclusive, never pass.
+ */
+export function runInvariants(projection: TraceProjection, run: TraceRun): InvariantVerdict[] {
+  const out: InvariantVerdict[] = [];
+  const invs = invocations(run);
+
+  // INV-14: seq unique + strictly increasing in event order.
+  {
+    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)' });
+  }
+
+  // INV-15: pairing (a dangling dispatch is only conclusive on a complete trace).
+  {
+    const dangling = invs.filter((i) => i.settleSeq === null);
+    if (run.parseErrors.some((p) => p.includes('duplicate settle'))) {
+      out.push({ id: 'dispatch-settle-pairing', status: 'fail', message: 'duplicate settle refused at parse (INV-15)' });
+    } else if (dangling.length > 0) {
+      out.push({
+        id: 'dispatch-settle-pairing',
+        status: run.incomplete ? 'inconclusive' : 'fail',
+        message: dangling.length + ' invocation(s) never settled' + (run.incomplete ? ' (trace incomplete — window truncated)' : ''),
+      });
+    } else {
+      out.push({ id: 'dispatch-settle-pairing', status: 'pass', message: 'every dispatch has exactly one settle' });
+    }
+  }
+
+  // Happens-before from deps: every dispatch of step X after the settle of each dep (by seq).
+  for (const hb of projection.happensBefore) {
+    const depSettles = invs.filter((i) => i.stepId === hb.afterSettleOf && i.settleSeq !== null).map((i) => i.settleSeq as number);
+    const xDispatches = invs.filter((i) => i.stepId === hb.step).map((i) => i.dispatchSeq);
+    const id = 'happens-before:' + hb.afterSettleOf + '→' + hb.step;
+    if (xDispatches.length === 0 || depSettles.length === 0) {
+      out.push({ id, status: run.incomplete ? 'inconclusive' : 'fail', message: 'edge unobserved' + (run.incomplete ? ' (incomplete trace)' : ' in a complete trace') });
+      continue;
+    }
+    const minDispatch = Math.min(...xDispatches);
+    const maxSettle = Math.max(...depSettles);
+    // required ordering: at least one settle of the dep precedes EVERY dispatch of X; strict form:
+    // every dispatch of X comes after SOME settle of its dep.
+    const violated = xDispatches.some((d) => !depSettles.some((s) => s < d));
+    if (violated) out.push({ id, status: 'fail', message: `dispatch of ${hb.step} (seq ${minDispatch}) precedes every settle of ${hb.afterSettleOf} (max settle seq ${maxSettle})` });
+    else out.push({ id, status: 'pass', message: 'ordering respected' });
+  }
+
+  // Regions: concurrency bound + join coverage (over seq windows, never wallTime).
+  for (const region of projection.regions) {
+    const members = invs.filter((i) => region.members.includes(i.stepId) || i.stepId === region.fanout);
+    const bound = region.maxFanout;
+    const idC = 'region-concurrency:' + region.fanout;
+    if (bound >= 1 && members.length > 0) {
+      // sweep over dispatch/settle transitions in seq order
+      const points: { seq: number; delta: number }[] = [];
+      for (const m of members) {
+        points.push({ seq: m.dispatchSeq, delta: 1 });
+        if (m.settleSeq !== null) points.push({ seq: m.settleSeq, delta: -1 });
+      }
+      points.sort((a, b) => a.seq - b.seq);
+      let cur = 0;
+      let peak = 0;
+      for (const p of points) {
+        cur += p.delta;
+        peak = Math.max(peak, cur);
+      }
+      if (peak > bound) out.push({ id: idC, status: 'fail', message: `observed scheduling concurrency ${peak} exceeds maxFanout ${bound}` });
+      else out.push({ id: idC, status: 'pass', message: `peak scheduled concurrency ${peak} <= maxFanout ${bound}` });
+    }
+    // Join coverage: the join itself is a structural pseudo-step (no trace event of its own), so
+    // its trace-visible witnesses are (a) every dispatched member settles (a dispatched branch is
+    // never skippable) and (b) every post-region dispatching step (`after`) dispatches AFTER every
+    // member settle — both by SEQ.
+    const idJ = 'join-coverage:' + region.fanout;
+    if (region.joinPolicy === 'all-activated' || region.joinPolicy === 'all-declared') {
+      const dangling = members.filter((m) => m.settleSeq === null);
+      if (dangling.length > 0) {
+        out.push({
+          id: idJ,
+          status: run.incomplete ? 'inconclusive' : 'fail',
+          message: `${dangling.length} dispatched branch(es) never settled (policy ${region.joinPolicy}) — a dispatched branch is never skippable` + (run.incomplete ? ' (trace incomplete)' : ''),
+        });
+      } else {
+        const afterDispatches = invs.filter((i) => region.after.includes(i.stepId)).map((i) => i.dispatchSeq);
+        const maxMemberSettle = members.length > 0 ? Math.max(...members.map((m) => m.settleSeq as number)) : 0;
+        const early = afterDispatches.filter((d) => d < maxMemberSettle);
+        if (early.length > 0) {
+          out.push({ id: idJ, status: 'fail', message: `a post-barrier step dispatched (seq ${Math.min(...early)}) before every branch settled (max settle seq ${maxMemberSettle})` });
+        } else {
+          out.push({ id: idJ, status: 'pass', message: 'every dispatched branch settled; post-barrier steps dispatched after the last settle' });
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+// ── expected-invariants.json evaluation (fitness fixtures — hand-authored, requirement-derived) ──
+
+export interface ExpectedInvariant {
+  /** happens-before: `before` event must have a smaller seq than `after`.
+   * streaming-overlap: QUANTIFIED streaming property (QE round-3 B4) — SOME dispatch of
+   * `downstream` must precede the FINAL settle of `upstream` (by seq). */
+  type: 'happens-before' | 'no-overlap' | 'max-concurrency' | 'streaming-overlap';
+  /** For happens-before. */
+  before?: { event: 'dispatched' | 'settled'; stepId: string; itemKey?: string | null };
+  after?: { event: 'dispatched' | 'settled'; stepId: string; itemKey?: string | null };
+  /** For streaming-overlap. */
+  upstream?: string;
+  downstream?: string;
+  /** For no-overlap / max-concurrency. */
+  steps?: string[];
+  limit?: number;
+  note?: string;
+}
+
+function findSeq(run: TraceRun, sel: { event: 'dispatched' | 'settled'; stepId: string; itemKey?: string | null }): number | null {
+  const invs = invocations(run);
+  const matches = invs.filter((i) => i.stepId === sel.stepId && (sel.itemKey === undefined || i.itemKey === (sel.itemKey ?? null)));
+  if (matches.length === 0) return null;
+  if (sel.event === 'dispatched') return Math.min(...matches.map((m) => m.dispatchSeq));
+  const settles = matches.filter((m) => m.settleSeq !== null).map((m) => m.settleSeq as number);
+  return settles.length === 0 ? null : Math.max(...settles);
+}
+
+/** Evaluate hand-authored expected invariants (from a fitness fixture) over a trace — by SEQ only. */
+export function evaluateExpectedInvariants(expected: ExpectedInvariant[], run: TraceRun): InvariantVerdict[] {
+  const out: InvariantVerdict[] = [];
+  expected.forEach((inv, idx) => {
+    const id = 'expected[' + idx + ']:' + inv.type + (inv.note ? ' ' + inv.note : '');
+    if (inv.type === 'happens-before') {
+      if (!inv.before || !inv.after) {
+        out.push({ id, status: 'inconclusive', message: 'malformed expected invariant' });
+        return;
+      }
+      const b = findSeq(run, inv.before);
+      const a = findSeq(run, inv.after);
+      if (b === null || a === null) {
+        out.push({ id, status: run.incomplete ? 'inconclusive' : 'fail', message: 'selector matched no event' });
+        return;
+      }
+      if (b < a) out.push({ id, status: 'pass', message: `seq ${b} < ${a}` });
+      else out.push({ id, status: 'fail', message: `required seq(${inv.before.event} ${inv.before.stepId}) < seq(${inv.after.event} ${inv.after.stepId}) but ${b} >= ${a}` });
+      return;
+    }
+    if (inv.type === 'streaming-overlap') {
+      // QE round-3 B4 (reviewer R3(a), CONFIRMED): the round-2 spec was the ITEM-PAIR LITERAL
+      // seq(dispatch sb:item1) < seq(settle sa:item3) — a completed reverse-batched pipeline
+      // execution with ZERO resolver deviations legally settles sa:item3 first and was condemned.
+      // The quantified form: EXISTS a dispatch of `downstream` with seq < the FINAL settle of
+      // `upstream`. Every legal completed pipeline order passes (any non-final upstream settle
+      // hands off to its downstream dispatch before the final upstream settle under the suite's
+      // one-settle-per-turn scheduling model); a barrier topology NEVER passes (its join forces
+      // every downstream dispatch after ALL upstream settles).
+      if (typeof inv.upstream !== 'string' || typeof inv.downstream !== 'string') {
+        out.push({ id, status: 'inconclusive', message: 'streaming-overlap needs upstream + downstream stepIds' });
+        return;
+      }
+      const all = invocations(run);
+      const upSettles = all.filter((i) => i.stepId === inv.upstream && i.settleSeq !== null).map((i) => i.settleSeq as number);
+      const downDispatches = all.filter((i) => i.stepId === inv.downstream).map((i) => i.dispatchSeq);
+      if (upSettles.length === 0 || downDispatches.length === 0) {
+        out.push({ id, status: run.incomplete ? 'inconclusive' : 'fail', message: 'selector matched no event' });
+        return;
+      }
+      const finalUpSettle = Math.max(...upSettles);
+      const firstOverlap = downDispatches.filter((d) => d < finalUpSettle).sort((x, y) => x - y)[0];
+      if (firstOverlap !== undefined) {
+        out.push({ id, status: 'pass', message: `streaming overlap observed: seq(dispatch ${inv.downstream}) ${firstOverlap} < seq(final settle ${inv.upstream}) ${finalUpSettle}` });
+      } else {
+        out.push({ id, status: 'fail', message: `no dispatch of ${inv.downstream} precedes the final settle of ${inv.upstream} (min dispatch seq ${Math.min(...downDispatches)} >= final settle seq ${finalUpSettle}) — barrier-shaped execution, not a streaming pipeline` });
+      }
+      return;
+    }
+    if (inv.type === 'max-concurrency') {
+      const invs = invocations(run).filter((i) => (inv.steps ?? []).includes(i.stepId));
+      const points: { seq: number; delta: number }[] = [];
+      for (const m of invs) {
+        points.push({ seq: m.dispatchSeq, delta: 1 });
+        if (m.settleSeq !== null) points.push({ seq: m.settleSeq, delta: -1 });
+      }
+      points.sort((x, y) => x.seq - y.seq);
+      let cur = 0;
+      let peak = 0;
+      for (const p of points) {
+        cur += p.delta;
+        peak = Math.max(peak, cur);
+      }
+      const limit = inv.limit ?? Infinity;
+      if (peak <= limit) out.push({ id, status: 'pass', message: `peak ${peak} <= ${limit}` });
+      else out.push({ id, status: 'fail', message: `peak scheduled concurrency ${peak} > limit ${limit}` });
+      return;
+    }
+    if (inv.type === 'no-overlap') {
+      const [sa, sb] = inv.steps ?? [];
+      if (!sa || !sb) {
+        out.push({ id, status: 'inconclusive', message: 'no-overlap needs two steps' });
+        return;
+      }
+      const A = invocations(run).filter((i) => i.stepId === sa);
+      const B = invocations(run).filter((i) => i.stepId === sb);
+      const overlap = A.some((a) => B.some((b) => a.settleSeq !== null && b.settleSeq !== null && a.dispatchSeq < b.settleSeq && b.dispatchSeq < a.settleSeq));
+      if (overlap) out.push({ id, status: 'fail', message: `${sa} and ${sb} overlap in scheduled windows` });
+      else out.push({ id, status: 'pass', message: 'no forbidden overlap' });
+      return;
+    }
+    out.push({ id, status: 'inconclusive', message: 'unknown expected-invariant type' });
+  });
+  return out;
+}
+
+// ── timeline assembly (dz workflow-trace) ────────────────────────────────────
+
+export interface TimelineRow {
+  seq: number;
+  kind: 'trace' | 'checkpoint' | 'ledger' | 'usage' | 'journal';
+  label: string;
+  detail: string;
+  wallTime: string | null;
+}
+
+export interface Timeline {
+  runId: string | null;
+  incomplete: boolean;
+  rows: TimelineRow[];
+  sources: string[];
+}
+
+/**
+ * Merge one timeline: trace.jsonl is the AUTHORITATIVE order (rows sorted by seq); checkpoints,
+ * cost-ledger lines and usageEvents are appended as unordered context rows (seq 0); journal.jsonl
+ * contributes DIAGNOSTIC agentId correlation only, never ordering (the ACL of 04 §8).
+ */
+export function assembleTimeline(input: {
+  trace: string;
+  checkpoints?: string | null;
+  ledger?: string | null;
+  usageEvents?: unknown[] | null;
+  journal?: string | null;
+}): Timeline {
+  const run = parseTrace(input.trace);
+  const rows: TimelineRow[] = [];
+  const sources: string[] = ['trace'];
+  for (const e of run.events) {
+    if (e.event === 'dispatched') {
+      rows.push({ seq: e.seq, kind: 'trace', label: `dispatch ${e.stepId}${e.itemKey ? ':' + e.itemKey : ''}#${e.attempt}`, detail: `phase=${e.phase} model=${e.model ?? '-'} causedBy=[${e.causedBy.join(',')}]`, wallTime: null });
+    } else if (e.event === 'settled') {
+      rows.push({ seq: e.seq, kind: 'trace', label: `settle ${e.invocationId}`, detail: `outcome=${e.outcome}`, wallTime: e.wallTime ?? null });
+    } else if (e.event === 'run.opened') {
+      rows.push({ seq: e.seq, kind: 'trace', label: 'run.opened', detail: `plan=${e.planDigest.slice(0, 12)} exec-fp=${e.execFp.slice(0, 12)}`, wallTime: null });
+    } else {
+      rows.push({ seq: e.seq, kind: 'trace', label: 'run.closed', detail: JSON.stringify(e.counts), wallTime: null });
+    }
+  }
+  rows.sort((a, b) => a.seq - b.seq);
+  if (input.checkpoints) {
+    sources.push('checkpoints');
+    for (const line of input.checkpoints.split('\n')) {
+      const t = line.trim();
+      if (t === '') continue;
+      try {
+        const e = JSON.parse(t) as { stage?: string };
+        rows.push({ seq: 0, kind: 'checkpoint', label: `checkpoint ${e.stage ?? '?'}`, detail: t.slice(0, 120), wallTime: null });
+      } catch {
+        rows.push({ seq: 0, kind: 'checkpoint', label: 'checkpoint (malformed line)', detail: t.slice(0, 120), wallTime: null });
+      }
+    }
+  }
+  if (input.ledger) {
+    sources.push('ledger');
+    for (const line of input.ledger.split('\n')) {
+      const t = line.trim();
+      if (t !== '') rows.push({ seq: 0, kind: 'ledger', label: 'cost', detail: t.slice(0, 160), wallTime: null });
+    }
+  }
+  if (Array.isArray(input.usageEvents)) {
+    sources.push('usageEvents');
+    for (const u of input.usageEvents) rows.push({ seq: 0, kind: 'usage', label: 'usage', detail: JSON.stringify(u).slice(0, 160), wallTime: null });
+  }
+  if (input.journal) {
+    sources.push('journal (diagnostic only — never ordering)');
+    let n = 0;
+    for (const line of input.journal.split('\n')) if (line.trim() !== '') n++;
+    rows.push({ seq: 0, kind: 'journal', label: 'journal', detail: `${n} host-journal line(s) — agentId correlation only; the host journal carries no seq/ts and NEVER orders this timeline`, wallTime: null });
+  }
+  return { runId: run.runId, incomplete: run.incomplete, rows, sources };
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/**
+ * ONE self-contained HTML file: mermaid for the plan TOPOLOGY, an HTML/CSS waterfall TABLE for the
+ * event timeline — two different renderers structurally (Codex 04/Q3: mermaid degrades on dense
+ * traces; the timeline is never a second mermaid diagram).
+ */
+export function renderTimelineHtml(timeline: Timeline, projection: TraceProjection | null, verdicts: InvariantVerdict[]): string {
+  const mermaid: string[] = ['graph TD'];
+  if (projection) {
+    for (const hb of projection.happensBefore) mermaid.push(`  ${hb.afterSettleOf} --> ${hb.step}`);
+    for (const r of projection.regions) {
+      mermaid.push(`  ${r.fanout} -. fanout x${r.maxFanout} .-> ${r.join || 'join'}`);
+    }
+  }
+  const traceRows = timeline.rows.filter((r) => r.kind === 'trace');
+  const maxSeq = Math.max(1, ...traceRows.map((r) => r.seq));
+  const bar = (seq: number): string => `<div class="bar" style="margin-left:${((seq - 1) / maxSeq) * 80}%;width:${Math.max(1, 80 / maxSeq)}%"></div>`;
+  const rowsHtml = timeline.rows
+    .map((r) => `<tr class="k-${r.kind}"><td>${r.seq || ''}</td><td>${esc(r.label)}</td><td>${esc(r.detail)}</td><td>${esc(r.wallTime ?? '')}</td><td class="w">${r.kind === 'trace' && r.seq > 0 ? bar(r.seq) : ''}</td></tr>`)
+    .join('\n');
+  const verdictsHtml = verdicts.map((v) => `<li class="v-${v.status}"><b>${esc(v.id)}</b> — ${v.status.toUpperCase()}: ${esc(v.message)}</li>`).join('\n');
+  return `<!doctype html><html><head><meta charset="utf-8"><title>loop-trace ${esc(timeline.runId ?? '')}</title>
+<style>
+body{font:14px/1.45 system-ui,sans-serif;margin:1.5rem;max-width:1100px}
+table{border-collapse:collapse;width:100%}td,th{border:1px solid #ccc;padding:2px 6px;font-size:12px}
+.w{min-width:240px}.bar{height:10px;background:#4a7;border-radius:2px}
+.v-fail{color:#b00}.v-pass{color:#171}.v-inconclusive{color:#970}
+pre.mermaid{background:#f6f6f6;padding:8px}
+.note{color:#666;font-size:12px}
+</style></head><body>
+<h1>loop-trace timeline — run ${esc(timeline.runId ?? '(unknown)')}${timeline.incomplete ? ' <em>(INCOMPLETE — no run.closed; the unflushed tail may be lost)</em>' : ''}</h1>
+<p class="note">Ordering source: the loop's own trace.jsonl seq (runtime-assigned at dispatch/settle transitions). wallTime is diagnostic only (INV-16). Sources: ${esc(timeline.sources.join(', '))}.</p>
+<h2>Plan topology (mermaid)</h2>
+<pre class="mermaid">${esc(mermaid.join('\n'))}</pre>
+<h2>Invariant verdicts</h2>
+<ul>${verdictsHtml || '<li>(no plan given — invariants not evaluated)</li>'}</ul>
+<h2>Event waterfall (HTML table — deliberately not mermaid)</h2>
+<table><tr><th>seq</th><th>event</th><th>detail</th><th>wallTime (diagnostic)</th><th>waterfall</th></tr>
+${rowsHtml}
+</table>
+</body></html>`;
+}