@dzhechkov/harness-core 0.3.145 → 0.3.147

package/src/event-chain.ts

@@ -0,0 +1,870 @@
+/**
+ * Hash-chained, sequence-numbered learning-event logs (feature `event-chain`, ADR-001/ADR-002).
+ *
+ * `.dz/recall-usage.jsonl` and `.dz/guard-audit.jsonl` are the ENTIRE evidence base for every
+ * `dz compounding` verdict and for `dz guard promote`. Before this module a record had no identity
+ * and no link to its neighbour, so a defect in the code that REWRITES those files was invisible to
+ * everything except a human noticing a wrong number — which is exactly how the 2 → 4 → 6
+ * double-count in `compactRecallUsageLog` was found (fixed 2026-07-28, see `recall-usage.ts`).
+ *
+ * WHAT THIS IS. A corruption check for OUR OWN bugs: a buggy compaction, a torn write, two writers
+ * racing. Each appended record carries `seq` (monotonic within its segment) and `prevHash` (FNV-1a
+ * over the previous record's line, exactly as it sits on disk), and {@link verifyEventChain}
+ * classifies what it finds.
+ *
+ * WHAT THIS IS NOT — read {@link EVENT_CHAIN_SCOPE} before describing it to anyone. FNV-1a is not
+ * cryptography and the threat model has no adversary: anyone who can edit the log can recompute the
+ * chain in one line of code. That is deliberate and sufficient, because the failures we actually
+ * ship are our own. ruview's ADR-010 names a `TamperedEntry` class; this module does not, because a
+ * defect class called "Tampered" IS the over-claim.
+ *
+ * FNV-1a collisions are CONSTRUCTIBLE — a 32-bit hash has none of the collision resistance a
+ * cryptographic one does, and a reviewer demonstrated a pair (Codex QE LOW-8). That is a documented
+ * property, not a surprise: the chain detects ACCIDENT classes (a compaction bug, a torn write, a
+ * race), not chosen-input attacks, which is exactly the corruption-not-tamper scope above. Swapping
+ * in sha256 would buy nothing this threat model needs and would invite the over-claim back.
+ *
+ * Everything here is PURE — no filesystem, no clock. Writers own their IO (the house pattern from
+ * `recall-usage.ts`), which is what keeps the never-block discipline of the apply leg intact.
+ *
+ * @packageDocumentation
+ */
+
+/** The one sentence that states what the chain is and is not. Printed by every verify surface. */
+export const EVENT_CHAIN_SCOPE =
+  'corruption detection for our own bugs (compaction, torn writes, races) — FNV-1a is not cryptography, ' +
+  'the threat model has no adversary, and anyone who can edit the log can recompute the chain';
+
+/** `prevHash` of the first record of a chain segment. */
+export const EVENT_CHAIN_GENESIS_HASH = '00000000';
+
+/** How many bytes of a log's tail a writer needs to read to find the last line. */
+export const EVENT_CHAIN_TAIL_BYTES = 65_536;
+
+/**
+ * Bytes charged per line for its chain fields when a rewriter budgets its output. Measured against
+ * the widest realistic shape: `,"seq":<up to 15 digits>,"prevHash":"xxxxxxxx",` plus the reset
+ * marker — deliberately generous, because under-charging would blow a byte cap.
+ */
+export const EVENT_CHAIN_FIELD_OVERHEAD_BYTES = 64;
+
+/** Marker record a rewriter puts first so its output can be checked against its input (ADR-002). */
+export const EVENT_CHAIN_LEDGER_KIND = 'chain-ledger';
+
+const HEX8 = /^[0-9a-f]{8}$/;
+
+export type EventChainDefectKind =
+  /** A record's `prevHash` does not match the line before it — or a hole where a link should be. */
+  | 'BrokenLink'
+  /** The same `seq` appears twice in one segment — a rewrite duplicated a line, or two writers raced. */
+  | 'DuplicateSeq'
+  /** `seq` went backwards without a recorded segment restart. */
+  | 'NonMonotonicSeq'
+  /** A line that is not a readable record — the shape a partial write leaves. */
+  | 'TornTail'
+  /** A rewrite accounts for more events than it measured in its input (ADR-002 — the 2 → 4 → 6 class). */
+  | 'DoubleCounted'
+  /** A rewrite's own three numbers do not add up, or claim an impossible drop (ADR-002 AM-3). */
+  | 'LedgerImbalance'
+  /** A ledger line whose fields are missing, mistyped or non-finite — never silently ignored (AM-5). */
+  | 'MalformedLedger'
+  /** A rewrite's claim was never completed: the segment restarted or the file ended first (AM-4). */
+  | 'ClaimInterrupted';
+
+/**
+ * The defect vocabulary, as data. ruview's ADR-010 names one more class that this list deliberately
+ * omits — a class whose name would assert exactly the promise {@link EVENT_CHAIN_SCOPE} refuses —
+ * and a test asserts no kind here ever grows that vocabulary.
+ */
+export const EVENT_CHAIN_DEFECT_KINDS: readonly EventChainDefectKind[] = [
+  'BrokenLink',
+  'DuplicateSeq',
+  'NonMonotonicSeq',
+  'TornTail',
+  'DoubleCounted',
+  'LedgerImbalance',
+  'MalformedLedger',
+  'ClaimInterrupted',
+];
+
+export interface EventChainDefect {
+  readonly kind: EventChainDefectKind;
+  /** 1-based index into the lines handed to the verifier. */
+  readonly line: number;
+  readonly detail: string;
+  readonly seq?: number;
+}
+
+export interface EventChainVerification {
+  readonly ok: boolean;
+  /** Non-empty lines examined. */
+  readonly lines: number;
+  /** Lines carrying a well-formed `seq` + `prevHash`. */
+  readonly chained: number;
+  /**
+   * Leading run of records written before chaining existed. LEGAL, never a defect — the chain is
+   * allowed to start mid-file. Reported so the uncovered part is honest rather than invisible.
+   */
+  readonly preChainPrefix: number;
+  /** Recorded discontinuities (`chainReset: true`) — a torn tail the writer refused to paper over. */
+  readonly resets: number;
+  /** Highest `seq` seen in the last segment, or null when nothing is chained. */
+  readonly lastSeq: number | null;
+  readonly defects: readonly EventChainDefect[];
+  /** {@link EVENT_CHAIN_SCOPE}, carried in the result so no surface can print a verdict without it. */
+  readonly scope: string;
+}
+
+export interface ChainFields {
+  readonly seq: number;
+  readonly prevHash: string;
+  /** Present only when the writer had to start a fresh segment because the tail was unreadable. */
+  readonly chainReset?: true;
+}
+
+export interface EventChainLedger {
+  readonly kind: typeof EVENT_CHAIN_LEDGER_KIND;
+  /** Event weight of the INPUT, measured before aggregation. */
+  readonly sourceEvents: number;
+  /** What a byte budget deliberately discarded — so trimming is not mistaken for loss. */
+  readonly droppedEvents: number;
+  /** Last `seq` this rewrite wrote. Records past it are outside the claim. */
+  readonly throughSeq: number;
+  readonly compactedAt: string;
+}
+
+/**
+ * FNV-1a, 32 bits, over both UTF-16 bytes of every code unit in order.
+ *
+ * Both bytes, unconditionally: folding with `& 0xff` would make every Cyrillic pair that shares a
+ * low byte collide, and these logs carry Russian prompts. 32 bits gives roughly a 1-in-4.3e9
+ * accidental-collision chance per link, which is the right size for detecting a bug and the wrong
+ * size for detecting an enemy — see {@link EVENT_CHAIN_SCOPE}.
+ */
+export function fnv1a32(text: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text.charCodeAt(i);
+    h = Math.imul(h ^ (c & 0xff), 0x01000193) >>> 0;
+    h = Math.imul(h ^ ((c >>> 8) & 0xff), 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/** Strip the line terminator a reader may have left, so writer and verifier hash the same string. */
+function stripEol(line: string): string {
+  return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+
+/** The hash a record's successor must carry. Input is the line AS WRITTEN (ADR-001 decision 2). */
+export function chainHashOf(line: string): string {
+  return fnv1a32(stripEol(line));
+}
+
+/** Non-empty lines of a JSONL text, terminators stripped. The one splitter both sides use. */
+export function chainLinesOf(text: string): string[] {
+  const out: string[] = [];
+  for (const raw of text.split('\n')) {
+    const line = stripEol(raw);
+    if (line.trim() !== '') out.push(line);
+  }
+  return out;
+}
+
+/**
+ * Last usable line of a log's TAIL chunk — all a writer needs to extend the chain (FR-2).
+ *
+ * When the chunk does not start at byte 0 its first line may be a fragment; with more than one line
+ * present the fragment is simply not the last one, and with exactly one line the caller is looking
+ * at a single record longer than {@link EVENT_CHAIN_TAIL_BYTES}, which no writer here produces —
+ * that returns `undefined`, and the caller starts a marked segment rather than chaining onto a guess.
+ */
+export function lastChainLine(tailText: string, opts: { readonly partial?: boolean } = {}): string | undefined {
+  if (typeof tailText !== 'string') return undefined;
+  const lines = chainLinesOf(tailText);
+  if (lines.length === 0) return undefined;
+  if (opts.partial === true && !tailText.includes('\n')) return undefined;
+  return lines[lines.length - 1];
+}
+
+/** What an appender needs to know about the file it is about to extend. */
+export interface LogTail {
+  readonly lastLine: string | undefined;
+  /**
+   * False when the file's final byte is not a newline — the shape a torn write leaves.
+   *
+   * LOAD-BEARING: appending straight onto a fragment GLUES the new record to it, so one torn write
+   * silently eats the next one too. (Found by the CLI torn-tail test, 2026-07-29 — the first append
+   * after a truncated line produced a single unreadable line instead of a marked restart.) The
+   * appender emits a leading newline so the damage stays exactly one record wide.
+   */
+  readonly endsWithNewline: boolean;
+  /**
+   * True when the file is NOT empty but no complete record could be found in the tail window.
+   *
+   * AM-6 (Codex QE MED-6): without this, a torn record longer than {@link EVENT_CHAIN_TAIL_BYTES}
+   * gave `lastLine: undefined`, which is indistinguishable from an EMPTY file — so the appender
+   * started an UNMARKED genesis segment and quietly broke the marked-segment contract that ADR-001
+   * D4 exists to enforce. "I saw nothing" and "there is nothing" are different facts.
+   */
+  readonly unreadable: boolean;
+}
+
+/** Read a tail chunk into the facts an appender needs. `partial` ⇒ the chunk starts mid-file. */
+export function readTailInfo(tailText: string, opts: { readonly partial?: boolean } = {}): LogTail {
+  const text = typeof tailText === 'string' ? tailText : '';
+  const lastLine = lastChainLine(text, opts);
+  return {
+    lastLine,
+    endsWithNewline: text === '' || text.endsWith('\n'),
+    unreadable: lastLine === undefined && text.trim() !== '',
+  };
+}
+
+/** An empty log — what an appender assumes when the file is absent. */
+export const EMPTY_LOG_TAIL: LogTail = { lastLine: undefined, endsWithNewline: true, unreadable: false };
+
+/**
+ * The exact text to append for a run of records: chained, newline-terminated, and preceded by a
+ * newline when the file ends mid-line. THE one place that knows how to extend one of these logs —
+ * the recall hook and the guard audit must not each carry their own copy of this reasoning.
+ */
+export function appendChainedLines(records: readonly object[], tail: LogTail = EMPTY_LOG_TAIL): string {
+  // AM-6: an unreadable tail is a TORN tail, never an empty one — it must produce a MARKED segment.
+  const lines = chainRecordLines(records, tail.lastLine, { forceReset: tail.unreadable === true });
+  if (lines.length === 0) return '';
+  return `${tail.endsWithNewline === false ? '\n' : ''}${lines.join('\n')}\n`;
+}
+
+interface ParsedChainRecord {
+  readonly record: Record<string, unknown>;
+  readonly seq: number | undefined;
+  readonly prevHash: string | undefined;
+  readonly reset: boolean;
+}
+
+function parseLine(line: string): ParsedChainRecord | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(line) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const rawSeq = record['seq'];
+  const rawPrev = record['prevHash'];
+  const seq =
+    typeof rawSeq === 'number' && Number.isSafeInteger(rawSeq) && rawSeq >= 1 ? rawSeq : undefined;
+  const prevHash = typeof rawPrev === 'string' && HEX8.test(rawPrev) ? rawPrev : undefined;
+  return { record, seq, prevHash, reset: record['chainReset'] === true };
+}
+
+/**
+ * The chain fields the next appended record must carry, derived from the last line ALONE.
+ *
+ * TOTAL by construction — it cannot throw for any input, because the apply-leg hook's top safety
+ * property is never-block (ADR-001 D2). Every unreadable shape resolves the same way: start a fresh
+ * segment AND record the discontinuity, so a break is visible instead of silently healed (D4).
+ *
+ * - no last line (new/empty file)              → genesis, no marker: this is a chain START
+ * - last line is an unchained record           → genesis, no marker: the chain starts mid-file (FR-5)
+ * - last line is a chained record              → `seq + 1`, linked to that line's hash
+ * - last line is unreadable / has a bad `seq`  → genesis + `chainReset: true` (FR-3)
+ */
+export function nextChainFields(
+  lastLine: string | undefined,
+  opts: { readonly forceReset?: boolean } = {},
+): ChainFields {
+  try {
+    // AM-6: the caller saw a non-empty file it could not read a record from. That is a torn tail,
+    // and a torn tail is ALWAYS a marked segment — never a silent genesis.
+    if (opts.forceReset === true) {
+      return { seq: 1, prevHash: EVENT_CHAIN_GENESIS_HASH, chainReset: true };
+    }
+    if (typeof lastLine !== 'string' || lastLine.trim() === '') {
+      return { seq: 1, prevHash: EVENT_CHAIN_GENESIS_HASH };
+    }
+    const parsed = parseLine(stripEol(lastLine));
+    if (parsed === undefined) {
+      return { seq: 1, prevHash: EVENT_CHAIN_GENESIS_HASH, chainReset: true };
+    }
+    if (parsed.seq === undefined && parsed.prevHash === undefined) {
+      // A pre-chain record: this append is the first link, not a break.
+      return { seq: 1, prevHash: EVENT_CHAIN_GENESIS_HASH };
+    }
+    if (parsed.seq === undefined || parsed.prevHash === undefined || parsed.seq >= Number.MAX_SAFE_INTEGER) {
+      // Half a chain header, a non-integer/overflowing counter: readable JSON, unusable link.
+      return { seq: 1, prevHash: EVENT_CHAIN_GENESIS_HASH, chainReset: true };
+    }
+    return { seq: parsed.seq + 1, prevHash: chainHashOf(stripEol(lastLine)) };
+  } catch {
+    return { seq: 1, prevHash: EVENT_CHAIN_GENESIS_HASH, chainReset: true };
+  }
+}
+
+/** Append the chain fields to a record. Fields go LAST so readers that whitelist keys are unaffected. */
+export function withChainFields<T extends object>(record: T, fields: ChainFields): T & ChainFields {
+  return {
+    ...record,
+    seq: fields.seq,
+    prevHash: fields.prevHash,
+    ...(fields.chainReset === true ? { chainReset: true as const } : {}),
+  };
+}
+
+/**
+ * Serialise a run of records into chained lines (no trailing newline on each), continuing from
+ * `lastLine`. Used both by the appenders (1..3 records per prompt) and by the rewriters.
+ */
+export function chainRecordLines(
+  records: readonly object[],
+  lastLine: string | undefined,
+  opts: { readonly forceReset?: boolean } = {},
+): string[] {
+  const out: string[] = [];
+  let prev = lastLine;
+  let force = opts.forceReset === true;
+  for (const rec of records) {
+    const line = JSON.stringify(withChainFields(rec, nextChainFields(prev, { forceReset: force })));
+    force = false; // only the FIRST record of the run opens the new segment
+    out.push(line);
+    prev = line;
+  }
+  return out;
+}
+
+/**
+ * Default event weight of a line (ADR-002 decision 4): the ledger itself weighs nothing, an
+ * aggregate weighs the reads it folded, anything else is one event.
+ */
+export function defaultEventWeight(record: Record<string, unknown>): number {
+  if (record['kind'] === EVENT_CHAIN_LEDGER_KIND) return 0;
+  if (record['kind'] === 'aggregate') {
+    const reads = record['reads'];
+    return typeof reads === 'number' && Number.isFinite(reads) && reads > 0 ? Math.floor(reads) : 0;
+  }
+  return 1;
+}
+
+/**
+ * Build the chained lines of a full rewrite: a {@link EventChainLedger} first, then the records.
+ *
+ * `sourceEvents` must be measured from the INPUT, before aggregation — a number derived from the
+ * output can never disagree with it, which is the whole point (ADR-002).
+ */
+export function chainRewrite(
+  records: readonly object[],
+  opts: {
+    readonly sourceEvents: number;
+    readonly droppedEvents?: number;
+    readonly compactedAt: string;
+  },
+): string[] {
+  const sourceEvents = clampCount(opts.sourceEvents);
+  const droppedEvents = clampCount(opts.droppedEvents ?? 0);
+  const ledger: EventChainLedger = {
+    kind: EVENT_CHAIN_LEDGER_KIND,
+    sourceEvents,
+    droppedEvents,
+    throughSeq: records.length + 1,
+    compactedAt: opts.compactedAt,
+  };
+  return chainRecordLines([ledger, ...records], undefined);
+}
+
+function clampCount(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+
+/** Total event weight of a JSONL text — the measurement a rewriter records as `sourceEvents`. */
+export function eventWeightOfText(
+  text: string,
+  weightOf: (record: Record<string, unknown>) => number = defaultEventWeight,
+): number {
+  let total = 0;
+  for (const line of chainLinesOf(text)) {
+    const parsed = parseLine(line);
+    if (parsed === undefined) continue;
+    const w = weightOf(parsed.record);
+    if (Number.isFinite(w) && w > 0) total += Math.floor(w);
+  }
+  return total;
+}
+
+export interface VerifyEventChainOptions {
+  readonly eventWeight?: (record: Record<string, unknown>) => number;
+}
+
+interface LedgerClaim {
+  readonly line: number;
+  readonly segment: number;
+  readonly fromSeq: number;
+  readonly throughSeq: number;
+  readonly sourceEvents: number;
+  readonly droppedEvents: number;
+  accounted: number;
+  /** Still awaiting the chained evidence up to `throughSeq`. */
+  open: boolean;
+  /** Set when the segment restarted (or the file ended) before the claim was satisfied. */
+  interruptedAtLine: number | null;
+}
+
+/**
+ * Verify a chained log. PURE: hand it the lines, get back every defect it can name.
+ *
+ * A file that has never been chained verifies OK with `preChainPrefix === lines` — records written
+ * before chaining existed are legal, and the uncovered prefix is reported as a count rather than
+ * flagged (FR-5). Once the chain starts, an unchained record after it is a hole (`BrokenLink`).
+ */
+export function verifyEventChain(
+  lines: readonly string[],
+  opts: VerifyEventChainOptions = {},
+): EventChainVerification {
+  const weightOf = typeof opts.eventWeight === 'function' ? opts.eventWeight : defaultEventWeight;
+  const defects: EventChainDefect[] = [];
+  const claims: LedgerClaim[] = [];
+
+  // Index of the last non-empty line, so "torn TAIL" can be told from a torn record mid-file.
+  let lastNonEmpty = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (stripEol(lines[i] ?? '').trim() !== '') lastNonEmpty = i;
+  }
+
+  let examined = 0;
+  let chained = 0;
+  let preChainPrefix = 0;
+  let resets = 0;
+  let chainStarted = false;
+  let segment = 0;
+  let prevLine: string | undefined;
+  let prevSeq: number | undefined;
+  let seen = new Set<number>();
+  // CROSS-SEGMENT duplicate CONTENT (Codex re-QE MED): the per-segment `seen` set resets on every
+  // re-anchor, so a whole duplicated `seq 1..N` segment produced only the one BrokenLink and the
+  // copies hid behind the restart. `(seq, line-hash)` pairs are tracked GLOBALLY: identical content
+  // repeating under the same seq is named wherever it lands — while AM-9's healthy-successor case
+  // (same seqs, DIFFERENT records) stays cascade-free.
+  const seenPairs = new Set<string>();
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = stripEol(lines[i] ?? '');
+    if (line.trim() === '') continue;
+    examined += 1;
+    const lineNo = i + 1;
+    const parsed = parseLine(line);
+
+    if (parsed === undefined) {
+      defects.push({
+        kind: 'TornTail',
+        line: lineNo,
+        detail:
+          i === lastNonEmpty
+            ? 'the last line is not a readable record — a partial write; the next append starts a marked segment'
+            : 'unreadable record mid-file (a torn write that was later appended past) — its content is lost',
+      });
+      prevLine = line; // its raw bytes are still what the next record hashed
+      continue;
+    }
+
+    if (parsed.seq === undefined || parsed.prevHash === undefined) {
+      if (chainStarted) {
+        defects.push({
+          kind: 'BrokenLink',
+          line: lineNo,
+          detail: 'record has no chain fields but the chain already started — a hole in the chain',
+        });
+      } else {
+        preChainPrefix += 1;
+      }
+      prevLine = line;
+      continue;
+    }
+
+    chained += 1;
+    const isSegmentStart = parsed.prevHash === EVENT_CHAIN_GENESIS_HASH && parsed.seq === 1;
+
+    if (!chainStarted) {
+      chainStarted = true;
+      segment = 1;
+      seen = new Set<number>();
+      prevSeq = undefined;
+      if (!isSegmentStart) {
+        // The chain's very first link must anchor to genesis; anything else lost its predecessors.
+        defects.push({
+          kind: 'BrokenLink',
+          line: lineNo,
+          seq: parsed.seq,
+          detail: `the first chained record does not start a segment (seq ${parsed.seq}, prevHash ${parsed.prevHash}) — earlier chained records were lost`,
+        });
+      } else if (parsed.reset) {
+        // The chain's first link is itself a recorded discontinuity (the writer met a torn tail
+        // before any chained record existed). Still a restart, still counted.
+        resets += 1;
+      }
+    } else if (parsed.reset) {
+      if (!isSegmentStart) {
+        defects.push({
+          kind: 'BrokenLink',
+          line: lineNo,
+          seq: parsed.seq,
+          detail: 'record is marked chainReset but does not start a segment (needs seq 1 and the genesis prevHash)',
+        });
+      } else {
+        // AM-4 (Codex QE HIGH-4): a marked restart does NOT absolve an unfinished claim. A rewrite
+        // could emit `ledger, two records, RESET, an aggregate of 100` and have the 100 fall outside
+        // every claim's segment — laundering events through a legal-looking discontinuity. Two
+        // independent lines close it: this one, which names the restart as the cause, and the
+        // end-of-file sweep below, which reports any claim left open however the segment ended.
+        // Each has its own test; removing either one turns a report RED.
+        for (const c of claims) {
+          if (c.open && c.segment === segment && c.interruptedAtLine === null) c.interruptedAtLine = lineNo;
+        }
+        resets += 1;
+        segment += 1;
+        seen = new Set<number>();
+        prevSeq = undefined;
+      }
+    } else {
+      // A normal link: its prevHash must be the hash of the line above it.
+      const expected = prevLine === undefined ? EVENT_CHAIN_GENESIS_HASH : chainHashOf(prevLine);
+      const unmarkedRestart = isSegmentStart && parsed.prevHash !== expected;
+      if (parsed.prevHash !== expected) {
+        defects.push({
+          kind: 'BrokenLink',
+          line: lineNo,
+          seq: parsed.seq,
+          detail: unmarkedRestart
+            ? 'segment restart without a chainReset marker — a break the writer did not record'
+            : `prevHash ${parsed.prevHash} does not match the preceding line (${expected})`,
+        });
+      }
+      if (unmarkedRestart) {
+        // RE-ANCHOR. Observed live 2026-07-29: one incident (a single unchained record slipped in
+        // from the hook's degraded fallback path) produced FIVE defects — the break itself plus a
+        // DuplicateSeq for every healthy record that followed, because the new segment's seq 1,2,3
+        // collided with the old segment's. A cascade buries the incident it is reporting. The break
+        // is named once, above; from here the records are judged on their own segment.
+        //
+        // An unmarked restart interrupts open claims exactly as a marked one does. Honest scope of
+        // that line: DETECTION already comes from the end-of-file sweep (a claim left open is
+        // reported however the segment ended), so this is what makes the report name the CAUSE and
+        // its line rather than saying only "the chain ends before it".
+        for (const c of claims) {
+          if (c.open && c.segment === segment && c.interruptedAtLine === null) c.interruptedAtLine = lineNo;
+        }
+        segment += 1;
+        seen = new Set<number>();
+        prevSeq = undefined;
+      } else if (prevSeq !== undefined) {
+        // ORDER IS LOAD-BEARING. Equality first: two writers that read the same tail both mint
+        // `prevSeq + 1`, and calling that "non-monotonic" would bury the race under the wrong name.
+        // Below-previous is the restart shape, which deserves the name that says a step went
+        // backwards. A repeat that is neither adjacent nor below can only follow an earlier break.
+        if (parsed.seq === prevSeq) {
+          defects.push({
+            kind: 'DuplicateSeq',
+            line: lineNo,
+            seq: parsed.seq,
+            detail: `seq ${parsed.seq} repeats the previous record — a duplicated record, or two writers racing on the same tail`,
+          });
+        } else if (parsed.seq < prevSeq) {
+          defects.push({
+            kind: 'NonMonotonicSeq',
+            line: lineNo,
+            seq: parsed.seq,
+            detail: `seq ${parsed.seq} follows ${prevSeq} without a recorded chainReset`,
+          });
+        } else if (seen.has(parsed.seq)) {
+          defects.push({
+            kind: 'DuplicateSeq',
+            line: lineNo,
+            seq: parsed.seq,
+            detail: `seq ${parsed.seq} already appears in this segment`,
+          });
+        }
+      }
+    }
+
+    const contentPair = `${parsed.seq}|${chainHashOf(line)}`;
+    if (seenPairs.has(contentPair)) {
+      defects.push({
+        kind: 'DuplicateSeq',
+        line: lineNo,
+        seq: parsed.seq,
+        detail: 'cross-segment duplicate content — the same seq with an identical record appeared earlier (a re-anchored restart does not absolve copies)',
+      });
+    }
+    seenPairs.add(contentPair);
+    seen.add(parsed.seq);
+    prevSeq = parsed.seq;
+    prevLine = line;
+
+    // Accounting FIRST, then registration: a ledger never counts itself.
+    for (const c of claims) {
+      if (c.segment === segment && parsed.seq > c.fromSeq && parsed.seq <= c.throughSeq) {
+        const w = weightOf(parsed.record);
+        if (Number.isFinite(w) && w > 0) c.accounted += Math.floor(w);
+      }
+      if (c.open && c.segment === segment && parsed.seq >= c.throughSeq) c.open = false;
+    }
+    const ledger = readLedgerClaim(parsed.record, lineNo, segment, parsed.seq);
+    if (ledger !== undefined) {
+      if ('defect' in ledger) defects.push(ledger.defect);
+      else claims.push(ledger.claim);
+    }
+  }
+
+  for (const c of claims) {
+    if (c.open && c.interruptedAtLine === null) c.interruptedAtLine = -1; // ran out of file
+    if (c.interruptedAtLine !== null) {
+      defects.push({
+        kind: 'ClaimInterrupted',
+        line: c.line,
+        detail:
+          c.interruptedAtLine === -1
+            ? `the rewrite claimed to write through seq ${c.throughSeq}, but the chain ends before it — the evidence it accounts for is not in the file`
+            : `the rewrite claimed to write through seq ${c.throughSeq}, but the segment restarted at line ${c.interruptedAtLine} first — a marked reset does not satisfy a claim`,
+      });
+      continue; // an unfinished claim has no arithmetic to check; reporting both would be noise
+    }
+    // AM-3: the raw equality, no clamps. `droppedEvents` is what the budget deliberately discarded,
+    // so a rewrite must account for exactly what it did not drop.
+    if (c.droppedEvents < 0 || c.droppedEvents > c.sourceEvents) {
+      defects.push({
+        kind: 'LedgerImbalance',
+        line: c.line,
+        detail: `droppedEvents ${c.droppedEvents} is outside [0, sourceEvents=${c.sourceEvents}] — a rewrite cannot discard events it never read`,
+      });
+      continue;
+    }
+    const total = c.accounted + c.droppedEvents;
+    if (total > c.sourceEvents) {
+      defects.push({
+        kind: 'DoubleCounted',
+        line: c.line,
+        detail: `the rewrite accounts for ${c.accounted} event(s) + ${c.droppedEvents} dropped = ${total}, but measured ${c.sourceEvents} in its input — an event is counted more than once (the 2 → 4 → 6 class)`,
+      });
+    } else if (total < c.sourceEvents) {
+      defects.push({
+        kind: 'LedgerImbalance',
+        line: c.line,
+        detail: `the rewrite accounts for ${c.accounted} event(s) + ${c.droppedEvents} dropped = ${total}, but claimed ${c.sourceEvents} — records it carried are unaccounted for`,
+      });
+    }
+  }
+
+  defects.sort((a, b) => a.line - b.line || a.kind.localeCompare(b.kind));
+
+  return {
+    ok: defects.length === 0,
+    lines: examined,
+    chained,
+    preChainPrefix,
+    resets,
+    lastSeq: prevSeq ?? null,
+    defects,
+    scope: EVENT_CHAIN_SCOPE,
+  };
+}
+
+/**
+ * Read a ledger line into a CLAIM, or into a named defect. Nothing in between.
+ *
+ * AM-5 (Codex QE HIGH-5): the previous version returned `undefined` for a malformed ledger, which
+ * meant a hand-edited or truncated ledger DISABLED the accounting check in silence — the strongest
+ * check in the module, switched off by damaging the very line that carries it. An invalid ledger in
+ * the chained region is now `MalformedLedger`.
+ *
+ * AM-3 (Codex QE HIGH-3): NO CLAMPS HERE. `Math.max(0, source - dropped)` accepted `dropped > source`
+ * and quietly turned an impossible claim into a satisfiable one. The verifier enforces the raw
+ * equality; the clamp belongs in the WRITER, which must never emit a negative in the first place.
+ */
+function readLedgerClaim(
+  record: Record<string, unknown>,
+  line: number,
+  segment: number,
+  seq: number,
+): { claim: LedgerClaim } | { defect: EventChainDefect } | undefined {
+  if (record['kind'] !== EVENT_CHAIN_LEDGER_KIND) return undefined;
+  const source = record['sourceEvents'];
+  const dropped = record['droppedEvents'];
+  const through = record['throughSeq'];
+  const bad = (detail: string): { defect: EventChainDefect } => ({
+    defect: { kind: 'MalformedLedger', line, seq, detail },
+  });
+  // Every numeric read from a log gets a finite/integer check: a `1e400` in a hand-edited file
+  // parses to Infinity, and an Infinity ceiling silently disables the check it is supposed to be.
+  if (typeof source !== 'number' || !Number.isSafeInteger(source) || source < 0) {
+    return bad(`sourceEvents is not a non-negative integer (${describe(source)}) — the accounting claim is unusable`);
+  }
+  if (typeof through !== 'number' || !Number.isSafeInteger(through) || through < seq) {
+    return bad(`throughSeq is not an integer >= this record's own seq (${describe(through)}) — the claim covers no readable range`);
+  }
+  if (dropped !== undefined && (typeof dropped !== 'number' || !Number.isSafeInteger(dropped))) {
+    return bad(`droppedEvents is not an integer (${describe(dropped)})`);
+  }
+  const droppedEvents = typeof dropped === 'number' ? dropped : 0;
+  return {
+    claim: {
+      line,
+      segment,
+      fromSeq: seq,
+      throughSeq: through,
+      sourceEvents: source,
+      droppedEvents,
+      accounted: 0,
+      open: through > seq,
+      interruptedAtLine: null,
+    },
+  };
+}
+
+function describe(value: unknown): string {
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'non-finite';
+  return value === undefined ? 'absent' : typeof value;
+}
+
+// ── Guarded rewrite (AM-1 · Codex QE CRITICAL-1) ────────────────────────────────────────────────
+
+/**
+ * What a rewriter must observe about the live file to know nobody appended behind its back.
+ *
+ * A read → compute → temp → rename rewrite has a window: an append landing after the read is
+ * OVERWRITTEN by the rename, and — because it was never in the input the ledger measured — verify
+ * reports the result as perfectly clean. Silent loss, invisible to the very check built to see it.
+ */
+export interface RewriteSnapshot {
+  readonly bytes: number;
+  readonly lines: number;
+  readonly lastLine: string | undefined;
+  /** FNV over the WHOLE text: bytes+lines+lastLine miss an equal-length edit to a non-tail line
+   *  (Codex re-QE HIGH) — only a full-content hash makes "unchanged" mean unchanged. */
+  readonly textHash: string;
+}
+
+export function rewriteSnapshot(text: string): RewriteSnapshot {
+  const safe = typeof text === 'string' ? text : '';
+  const lines = chainLinesOf(safe);
+  return { bytes: safe.length, lines: lines.length, lastLine: lines[lines.length - 1], textHash: chainHashOf(safe) };
+}
+
+/** True when the live file is byte-for-byte where the snapshot left it. */
+export function rewriteSnapshotUnchanged(a: RewriteSnapshot, b: RewriteSnapshot): boolean {
+  return a.textHash === b.textHash && a.bytes === b.bytes && a.lines === b.lines && a.lastLine === b.lastLine;
+}
+
+export type GuardedRewriteStatus =
+  /** The rewrite landed. */
+  | 'rewritten'
+  /** Another rewriter holds the lock — this one did nothing, which is correct. */
+  | 'locked'
+  /** Appends kept landing mid-rewrite; nothing was renamed. NO DATA WAS LOST. */
+  | 'raced'
+  /** The input's chain is already defective; laundering it into a clean rewrite is refused (AM-2). */
+  | 'refused-dirty'
+  /** The file could not be read. */
+  | 'unreadable'
+  /** The rewrite produced nothing usable; the file is left alone. */
+  | 'empty';
+
+export interface GuardedRewriteResult {
+  readonly status: GuardedRewriteStatus;
+  readonly attempts: number;
+  /** Populated for `refused-dirty` so the caller can say WHY, loudly. */
+  readonly defects: readonly EventChainDefect[];
+}
+
+export interface GuardedRewriteIo {
+  /** Read the whole live log. `undefined` ⇒ unreadable. */
+  readonly read: () => string | undefined;
+  /** Write to a temp file and atomically rename it over the log. */
+  readonly replace: (text: string) => void;
+  /** Take the rewrite lock. `false` ⇒ someone else owns it. */
+  readonly acquireLock: () => boolean;
+  readonly releaseLock: () => void;
+}
+
+/** A rewrite proposal: the new text, plus whatever made the rewriter refuse. */
+export interface RewriteProposal {
+  readonly text: string;
+  readonly refusedDirty?: boolean;
+  readonly defects?: readonly EventChainDefect[];
+}
+
+export const DEFAULT_REWRITE_ATTEMPTS = 3;
+
+/**
+ * Run a whole-file rewrite so that a concurrent append can never be silently overwritten.
+ *
+ * Three guards, in order:
+ *  1. an exclusive lock, so two rewriters cannot interleave at all;
+ *  2. a re-read of the live file after computing the new text and BEFORE the rename — if it moved,
+ *     the attempt is ABANDONED and retried against the newer file, so the append is folded in
+ *     rather than lost;
+ *  3. a bounded attempt count — a log under constant append is left alone, never truncated.
+ *
+ * HONEST RESIDUAL (state it, do not paper over it): the re-read narrows the window to the interval
+ * between the final read and the `rename` syscall; it does not close it, because a conditional
+ * rename is not an operation the filesystem offers. What it removes is the wide window (the whole
+ * parse + compact + write) that made loss likely rather than rare.
+ *
+ * Pure orchestration — all IO is injected, which is what makes the race testable deterministically.
+ */
+export function guardedRewrite(
+  io: GuardedRewriteIo,
+  propose: (text: string) => RewriteProposal,
+  opts: { readonly attempts?: number } = {},
+): GuardedRewriteResult {
+  const max =
+    typeof opts.attempts === 'number' && Number.isFinite(opts.attempts) && opts.attempts >= 1
+      ? Math.floor(opts.attempts)
+      : DEFAULT_REWRITE_ATTEMPTS;
+  if (!io.acquireLock()) return { status: 'locked', attempts: 0, defects: [] };
+  let attempts = 0;
+  try {
+    for (let i = 0; i < max; i += 1) {
+      attempts += 1;
+      const before = io.read();
+      if (typeof before !== 'string') return { status: 'unreadable', attempts, defects: [] };
+      const snapshot = rewriteSnapshot(before);
+      const proposal = propose(before);
+      if (proposal.refusedDirty === true) {
+        return { status: 'refused-dirty', attempts, defects: proposal.defects ?? [] };
+      }
+      if (typeof proposal.text !== 'string' || proposal.text === '') {
+        return { status: 'empty', attempts, defects: [] };
+      }
+      const after = io.read();
+      if (typeof after !== 'string') return { status: 'unreadable', attempts, defects: [] };
+      if (!rewriteSnapshotUnchanged(snapshot, rewriteSnapshot(after))) continue; // someone appended
+      io.replace(proposal.text);
+      return { status: 'rewritten', attempts, defects: [] };
+    }
+    return { status: 'raced', attempts, defects: [] };
+  } finally {
+    io.releaseLock();
+  }
+}
+
+/** Convenience wrapper for callers holding the whole file. */
+export function verifyEventChainText(text: string, opts: VerifyEventChainOptions = {}): EventChainVerification {
+  return verifyEventChain(chainLinesOf(typeof text === 'string' ? text : ''), opts);
+}
+
+/**
+ * One line an operator can read. Always carries {@link EVENT_CHAIN_SCOPE} so no surface can print a
+ * chain verdict without also printing what it does and does not mean.
+ */
+export function renderEventChainVerification(v: EventChainVerification, label: string): string {
+  const head = v.ok ? 'chain OK' : `chain FAILED (${v.defects.length} defect(s))`;
+  const parts = [
+    `${label}: ${head}`,
+    `${v.chained} chained`,
+    `${v.preChainPrefix} pre-chain (uncovered)`,
+  ];
+  if (v.resets > 0) parts.push(`${v.resets} recorded restart(s)`);
+  const kinds = [...new Set(v.defects.map((d) => d.kind))];
+  if (kinds.length > 0) parts.push(kinds.join('/'));
+  return `${parts.join(' · ')} — ${v.scope}`;
+}