@dzhechkov/harness-core 0.3.145 → 0.3.147

package/dist/event-chain.js

@@ -0,0 +1,663 @@
+/**
+ * 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}$/;
+/**
+ * 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 = [
+    'BrokenLink',
+    'DuplicateSeq',
+    'NonMonotonicSeq',
+    'TornTail',
+    'DoubleCounted',
+    'LedgerImbalance',
+    'MalformedLedger',
+    'ClaimInterrupted',
+];
+/**
+ * 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) {
+    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) {
+    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) {
+    return fnv1a32(stripEol(line));
+}
+/** Non-empty lines of a JSONL text, terminators stripped. The one splitter both sides use. */
+export function chainLinesOf(text) {
+    const out = [];
+    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, opts = {}) {
+    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];
+}
+/** Read a tail chunk into the facts an appender needs. `partial` ⇒ the chunk starts mid-file. */
+export function readTailInfo(tailText, opts = {}) {
+    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 = { 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, tail = EMPTY_LOG_TAIL) {
+    // 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`;
+}
+function parseLine(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    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, opts = {}) {
+    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(record, fields) {
+    return {
+        ...record,
+        seq: fields.seq,
+        prevHash: fields.prevHash,
+        ...(fields.chainReset === true ? { chainReset: true } : {}),
+    };
+}
+/**
+ * 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, lastLine, opts = {}) {
+    const out = [];
+    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) {
+    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, opts) {
+    const sourceEvents = clampCount(opts.sourceEvents);
+    const droppedEvents = clampCount(opts.droppedEvents ?? 0);
+    const ledger = {
+        kind: EVENT_CHAIN_LEDGER_KIND,
+        sourceEvents,
+        droppedEvents,
+        throughSeq: records.length + 1,
+        compactedAt: opts.compactedAt,
+    };
+    return chainRecordLines([ledger, ...records], undefined);
+}
+function clampCount(value) {
+    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, weightOf = defaultEventWeight) {
+    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;
+}
+/**
+ * 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, opts = {}) {
+    const weightOf = typeof opts.eventWeight === 'function' ? opts.eventWeight : defaultEventWeight;
+    const defects = [];
+    const claims = [];
+    // 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;
+    let prevSeq;
+    let seen = new Set();
+    // 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();
+    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();
+            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();
+                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();
+                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, line, segment, seq) {
+    if (record['kind'] !== EVENT_CHAIN_LEDGER_KIND)
+        return undefined;
+    const source = record['sourceEvents'];
+    const dropped = record['droppedEvents'];
+    const through = record['throughSeq'];
+    const bad = (detail) => ({
+        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) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : 'non-finite';
+    return value === undefined ? 'absent' : typeof value;
+}
+export function rewriteSnapshot(text) {
+    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, b) {
+    return a.textHash === b.textHash && a.bytes === b.bytes && a.lines === b.lines && a.lastLine === b.lastLine;
+}
+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, propose, opts = {}) {
+    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, opts = {}) {
+    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, label) {
+    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}`;
+}
+//# sourceMappingURL=event-chain.js.map