lazycodex-ai 5.1.44 → 5.1.46

package/packages/shared-skills/skills/ulw-research/scripts/fact-fill.mjs

@@ -0,0 +1,194 @@
+// fact-fill.mjs - the fill step: substitute every fact pointer in a report source from the
+// ledger, all or nothing. Fatal errors (pointer_label_mismatch, unresolved_placeholder,
+// quote_anchor_unresolved, unit_duplicated) return out null; warnings (particle_unverified,
+// fallback_without_entity) never block. A twice-failed sentence can be replaced by an attributed
+// block quote of its source row (replaceFailed). No IO, but not pure: unless options.view is set,
+// it records each replaced sentence in options.replaceFailed through markReplaced. node: builtins only.
+
+import { finalReading, rewriteParticle } from "./particles-ko.mjs"
+import { failureCount, markReplaced, sentenceKey } from "./fidelity-state.mjs"
+import { findPlaceholders, lead, qualifiedText, renderBlockquote, renderQuote, renderValueHtml, subSpan, valueParts } from "./placeholder.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+
+const FORMATS = Object.freeze(["html", "md"])
+const TRANSLATION = Object.freeze({
+	html: /^\s*<span data-translates="(Q\d+)">[\s\S]*?<\/span>/u,
+	md: /^\s*<!-- translates: (Q\d+) -->[^\n]*/u,
+})
+const HEADING = Object.freeze({ html: /<h[1-6]\b([^>]*)>([\s\S]*?)<\/h[1-6]>/giu, md: /^#{1,6}[ \t]+(.+)$/gmu })
+
+const lineOf = (text, at) => text.slice(0, at).split("\n").length
+
+function resolveValue(row, parsed, format) {
+	const { valueText, unitText } = valueParts(row)
+	const text = { full: row.raw, value: valueText, unit: unitText, q: qualifiedText(row) }[parsed.mode]
+	if (text === null) return { code: "quote_anchor_unresolved", message: `${row.fact_id} has qualifier ${row.qualifier}, but its quote holds no qualifier beside "${row.raw}"` }
+	return { row, parsed, visible: text, rendered: format === "html" ? renderValueHtml(row, text) : text }
+}
+
+function resolveQuote(row, parsed, format) {
+	const whole = { text: row.quote, start: 0, end: row.quote.length }
+	const selection = parsed.mode === "lead" ? lead(row.quote, parsed.lead) : parsed.mode === "span" ? subSpan(row.quote, parsed.from, parsed.to) : whole
+	if (selection === null) {
+		return { code: "quote_anchor_unresolved", message: `from "${parsed.from}" and to "${parsed.to}" must each occur exactly once in ${row.fact_id}'s quote, in that order` }
+	}
+	const rendered = renderQuote(row, parsed.selector, selection.text, format)
+	return { row, parsed, visible: `[${row.source_id}]`, rendered, selector: parsed.selector, quote_span: [selection.start, selection.end] }
+}
+
+function resolve(found, rows, format) {
+	const { parsed } = found
+	if (parsed.error) return { code: "unresolved_placeholder", message: parsed.error }
+	const row = rows.get(parsed.id)
+	if (row === undefined) return { code: "unresolved_placeholder", message: `${parsed.id} is not in the fact ledger` }
+	if (row.status !== "active") return { code: "unresolved_placeholder", message: `${parsed.id} is ${row.status}; cite its replacement` }
+	if (row.label !== parsed.label) return { code: "pointer_label_mismatch", message: `${parsed.id} has label "${row.label}", not "${parsed.label}"` }
+	return parsed.kind === "Q" ? resolveQuote(row, parsed, format) : resolveValue(row, parsed, format)
+}
+
+/** A unit typed right after a pointer that already renders it: never absorbed, always an error. */
+function unitDuplicated(text, item) {
+	if (item.parsed.kind !== "F" || (item.parsed.mode !== "full" && item.parsed.mode !== "q")) return false
+	const suffix = item.row.raw.replace(/^[\s\S]*\d/u, "").trim()
+	const units = [item.row.unit, valueParts(item.row).unitText, suffix].filter((unit) => typeof unit === "string" && unit !== "")
+	const following = text.slice(item.end).replace(/^[ \t]+/u, "")
+	return units.some((unit) => following.startsWith(unit) && !/[A-Za-z0-9]/u.test(following[unit.length] ?? ""))
+}
+
+/*
+ * Sentence-key rules (fidelity-state.mjs sentenceKey(slug, ids)); any other producer of keys must match:
+ * - slug source: an HTML heading's id attribute wins over its text; md headings use their text.
+ * - slugify: strip tags, lowercase, turn each run of non-letters/digits (\p{L}\p{N}) into "-",
+ *   trim leading and trailing "-".
+ * - a sentence takes the nearest heading that starts strictly before the sentence's start offset;
+ *   a sentence before the first heading gets slug "".
+ * - fact ids cited in the sentence are de-duplicated before sentenceKey sorts them.
+ */
+function slugify(text) {
+	return text
+		.replace(/<[^>]*>/gu, "")
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}]+/gu, "-")
+		.replace(/^-+|-+$/gu, "")
+}
+
+function headings(text, format) {
+	return [...text.matchAll(HEADING[format])].map((match) => {
+		const id = format === "html" ? /\bid="([^"]*)"/u.exec(match[1])?.[1] : undefined
+		return { at: match.index, slug: slugify(id ?? match[match.length - 1]) }
+	})
+}
+
+/** Sentence offsets over the source with pointers, comments and (html) tags blanked to equal length. */
+function sentencesOf(text, found, format) {
+	let masked = text
+	for (const item of found) masked = masked.slice(0, item.start) + "x".repeat(item.end - item.start) + masked.slice(item.end)
+	const blank = (part) => part.replace(/[^\n]/gu, " ")
+	masked = masked.replace(/<!--[\s\S]*?-->/gu, blank)
+	if (format === "html") masked = masked.replace(/<[^>]*>/gu, blank)
+	return splitSentences(masked)
+}
+
+function replacements(text, found, items, options, warnings) {
+	const { format, replaceFailed: state } = options
+	const marks = headings(text, format)
+	const out = []
+	for (const sentence of sentencesOf(text, found, format)) {
+		const inside = items.filter((item) => item.start >= sentence.start && item.end <= sentence.end)
+		if (inside.length === 0) continue
+		const slug = marks.filter((mark) => mark.at < sentence.start).at(-1)?.slug ?? ""
+		const key = sentenceKey(slug, [...new Set(inside.map((item) => item.row.fact_id))])
+		if (failureCount(state, key) < 2) continue
+		const rows = inside.map((item) => item.row)
+		const source = rows.find((row) => row.kind === "quote") ?? rows.find((row) => row.source_id !== null && row.quote !== "")
+		if (source === undefined) continue
+		let rendered = options.fallback === "omit" ? "" : renderBlockquote(source, key, format)
+		if (rendered !== "" && format === "md") {
+			if (sentence.start > 0 && text[sentence.start - 1] !== "\n") rendered = `\n\n${rendered}`
+			if (sentence.end < text.length && text[sentence.end] !== "\n") rendered = `${rendered}\n\n`
+		}
+		if (rendered !== "" && source.entity === null) {
+			warnings.push({ code: "fallback_without_entity", token: key, line: lineOf(text, sentence.start), message: `${source.fact_id} has no entity; the block quote cites [${source.source_id}] alone` })
+		}
+		out.push({ start: sentence.start, end: sentence.end, key, source, rendered })
+	}
+	return out
+}
+
+/** The text after a pointer: rewrite a following Korean particle, and map a translation span. */
+function afterPlaceholder(segment, item, context) {
+	const { format, text, warnings, fillMap } = context
+	const probeEnd = format === "html" && segment.includes("<") ? segment.indexOf("<") : segment.length
+	const result = rewriteParticle(segment.slice(0, probeEnd), finalReading(item.visible, null))
+	let next = segment
+	if (result.applied) next = result.text + segment.slice(probeEnd)
+	else if (result.candidate) {
+		warnings.push({ code: "particle_unverified", token: item.token, line: lineOf(text, item.start), message: `the particle after ${item.token} was not rewritten; check it by eye` })
+	}
+	const translation = item.parsed.kind === "Q" ? TRANSLATION[format].exec(next) : null
+	if (translation !== null && translation[1] === item.row.fact_id) {
+		const span = translation[0].trimStart()
+		const start = context.out.length + translation[0].length - span.length
+		fillMap.push({ token: span, fact_id: translation[1], translates: translation[1], start, end: start + span.length, rendered: span })
+	}
+	return next
+}
+
+function assemble(text, parts, context) {
+	let cursor = 0
+	let previous = null
+	const flush = (until) => {
+		const segment = text.slice(cursor, until)
+		context.out += previous?.parsed ? afterPlaceholder(segment, previous, context) : segment
+	}
+	for (const part of parts) {
+		flush(part.start)
+		const start = context.out.length
+		if (part.parsed) {
+			const extra = part.selector === undefined ? {} : { selector: part.selector, quote_span: part.quote_span }
+			context.fillMap.push({ token: part.token, fact_id: part.row.fact_id, start, end: start + part.rendered.length, rendered: part.rendered, ...extra })
+		} else if (part.rendered !== "") {
+			context.fillMap.push({ token: null, fact_id: part.source.fact_id, replaced: part.key, start, end: start + part.rendered.length, rendered: part.rendered })
+		}
+		context.out += part.rendered
+		cursor = part.end
+		previous = part
+	}
+	flush(text.length)
+	return context.out
+}
+
+/**
+ * @param {string} sourceText the report source with {{F..}} / {{Q..}} pointers
+ * @param {{ rows: object[] }} ledger
+ * @param {{ format?: "html"|"md", replaceFailed?: object, fallback?: "quote"|"omit", view?: boolean }} [options]
+ * @returns {{ out: string|null, fillMap: object[], errors: object[], warnings: object[] }}
+ */
+export function fill(sourceText, ledger, options = {}) {
+	const format = options.format ?? "html"
+	if (!FORMATS.includes(format)) throw new TypeError(`format must be one of ${FORMATS.join(", ")}`)
+	const rows = new Map(ledger.rows.map((row) => [row.fact_id, row]))
+	const found = findPlaceholders(sourceText)
+	const errors = []
+	const warnings = []
+	const items = []
+	for (const pointer of found) {
+		const resolved = resolve(pointer, rows, format)
+		const line = lineOf(sourceText, pointer.start)
+		if (resolved.code) errors.push({ code: resolved.code, token: pointer.token, line, message: resolved.message })
+		else {
+			const item = { ...pointer, ...resolved }
+			if (unitDuplicated(sourceText, item)) {
+				errors.push({ code: "unit_duplicated", token: pointer.token, line, message: `${pointer.token} already renders its unit; use {{${item.row.fact_id}:${item.row.label}:value}}` })
+			} else items.push(item)
+		}
+	}
+	if (errors.length > 0) return { out: null, fillMap: [], errors, warnings }
+	const replaced = options.replaceFailed ? replacements(sourceText, found, items, { ...options, format }, warnings) : []
+	const kept = items.filter((item) => !replaced.some((block) => item.start >= block.start && item.end <= block.end))
+	const parts = [...kept, ...replaced].sort((a, b) => a.start - b.start)
+	const context = { format, text: sourceText, warnings, fillMap: [], out: "" }
+	const out = assemble(sourceText, parts, context)
+	if (!options.view) for (const block of replaced) markReplaced(options.replaceFailed, block.key)
+	return { out, fillMap: context.fillMap, errors, warnings }
+}

package/packages/shared-skills/skills/ulw-research/scripts/fact-fill.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { fill } from "./fact-fill.mjs"
+import { retractRow, supersedeRow, validateLedger } from "./fact-ledger.mjs"
+import { failureCount, sentenceKey } from "./fidelity-state.mjs"
+
+const LEDGER = JSON.parse(readFileSync(join(import.meta.dir, "tests/fixtures/fidelity/ledger-basic.json"), "utf8"))
+const F12_DATA = '<data class="fact" value="320" data-fact="F12" data-unit="m" data-lineage="MEASURED">320 m</data>'
+const QUOTE = "we estimate completion no earlier than 2027"
+// Korean particles and words, as escapes: eul, girok, i, ollatda, ga, isang.
+const EUL = "\uC744"
+const GIROK = "\uAE30\uB85D"
+const I = "\uC774"
+const OLLATDA = "\uC62C\uB790\uB2E4"
+const GA = "\uAC00"
+const ISANG = "\uC774\uC0C1"
+
+type State = { schemaVersion: number; failures: Record<string, number>; replaced: string[] }
+function failedTwice(key: string): State {
+	return { schemaVersion: 1, failures: { [key]: 2 }, replaced: [] }
+}
+const codes = (list: { code: string }[]) => list.map((item) => item.code)
+
+describe("fill: fixture", () => {
+	test("the ledger fixture is a valid ledger", () => {
+		expect(validateLedger(LEDGER)).toEqual([])
+	})
+})
+
+describe("fill: value placeholders (html)", () => {
+	test("{{F12:span_len}} renders the <data> element with the raw text", () => {
+		const result = fill("<p>The span is {{F12:span_len}}.</p>", LEDGER, { format: "html" })
+		expect(result.errors).toEqual([])
+		expect(result.out).toBe(`<p>The span is ${F12_DATA}.</p>`)
+		expect(result.fillMap).toHaveLength(1)
+		expect(result.fillMap[0]).toMatchObject({ token: "{{F12:span_len}}", fact_id: "F12", rendered: F12_DATA })
+	})
+
+	test(":q copies the source qualifier with the quantity", () => {
+		const result = fill("<p>{{F12:span_len:q}}</p>", LEDGER, { format: "html" })
+		expect(result.out).toContain('data-lineage="MEASURED">up to 320 m</data>')
+	})
+
+	test(":value and :unit render one part each", () => {
+		const result = fill("<p>{{F12:span_len:value}} metres, unit {{F12:span_len:unit}}</p>", LEDGER, { format: "md" })
+		expect(result.out).toBe("<p>320 metres, unit m</p>")
+	})
+
+	test("a converted row renders DERIVED lineage", () => {
+		const result = fill("<p>{{F40:span_mm}}</p>", LEDGER, { format: "html" })
+		expect(result.out).toContain('data-fact="F40" data-unit="mm" data-lineage="DERIVED">320000 mm</data>')
+	})
+
+	test("an all-English template fills with no warnings", () => {
+		const result = fill("The span is {{F12:span_len}} long.", LEDGER, { format: "html" })
+		expect(result.out).not.toBeNull()
+		expect(result.warnings).toEqual([])
+	})
+})
+
+describe("fill: fatal errors write nothing", () => {
+	test("a label mismatch is pointer_label_mismatch with out null", () => {
+		const result = fill("<p>Line one.</p>\n<p>{{F12:wrong}}</p>", LEDGER, { format: "html" })
+		expect(result.out).toBeNull()
+		expect(result.errors[0]).toMatchObject({ code: "pointer_label_mismatch", token: "{{F12:wrong}}", line: 2 })
+	})
+
+	test("an unknown id is unresolved_placeholder; no row is guessed", () => {
+		const result = fill("<p>{{F99:x}}</p>", LEDGER, { format: "html" })
+		expect(result.out).toBeNull()
+		expect(codes(result.errors)).toEqual(["unresolved_placeholder"])
+	})
+
+	test("a malformed pointer is unresolved_placeholder", () => {
+		expect(codes(fill("<p>{{F12}}</p>", LEDGER, { format: "html" }).errors)).toEqual(["unresolved_placeholder"])
+	})
+
+	test("a unit typed after a value placeholder is unit_duplicated, never absorbed", () => {
+		const result = fill("<p>{{F13:rate}}%</p>", LEDGER, { format: "html" })
+		expect(result.out).toBeNull()
+		expect(codes(result.errors)).toEqual(["unit_duplicated"])
+		expect(fill("<p>{{F13:rate:value}}%</p>", LEDGER, { format: "html" }).errors).toEqual([])
+	})
+
+	test("a retracted row is unresolved_placeholder; fill never renders it", () => {
+		const ledger = structuredClone(LEDGER)
+		retractRow(ledger, "F12", "source withdrawn")
+		expect(validateLedger(ledger)).toEqual([])
+		const result = fill("<p>Line one.</p>\n<p>{{F12:span_len}}</p>", ledger, { format: "html" })
+		expect(result.out).toBeNull()
+		expect(result.fillMap).toEqual([])
+		expect(result.errors).toEqual([{ code: "unresolved_placeholder", token: "{{F12:span_len}}", line: 2, message: "F12 is retracted; cite its replacement" }])
+	})
+
+	test("a superseded row is unresolved_placeholder; fill never renders it", () => {
+		const ledger = structuredClone(LEDGER)
+		supersedeRow(ledger, "F12", "F40", "restated in mm")
+		expect(validateLedger(ledger)).toEqual([])
+		const result = fill("{{F12:span_len:value}}", ledger, { format: "md" })
+		expect(result.out).toBeNull()
+		expect(result.fillMap).toEqual([])
+		expect(result.errors).toEqual([{ code: "unresolved_placeholder", token: "{{F12:span_len:value}}", line: 1, message: "F12 is superseded; cite its replacement" }])
+	})
+
+	test("an anchor occurring twice is quote_anchor_unresolved", () => {
+		const result = fill('<p>{{Q7:completion:from="ti":to="2027"}}</p>', LEDGER, { format: "html" })
+		expect(result.out).toBeNull()
+		expect(codes(result.errors)).toEqual(["quote_anchor_unresolved"])
+	})
+})
+
+describe("fill: quote placeholders", () => {
+	test("from/to renders the sub-span in quotes plus the source marker", () => {
+		const result = fill('<p>{{Q7:completion:from="no earlier":to="2027"}}</p>', LEDGER, { format: "html" })
+		expect(result.out).toBe('<p><q data-fact="Q7" data-quote-sel="from=no earlier;to=2027">\u2026no earlier than 2027</q> [S4]</p>')
+	})
+
+	test("full and lead selectors", () => {
+		expect(fill("{{Q7:completion}}", LEDGER, { format: "html" }).out).toBe(`<q data-fact="Q7" data-quote-sel="full">${QUOTE}</q> [S4]`)
+		expect(fill("{{Q7:completion:lead=2}}", LEDGER, { format: "html" }).out).toBe('<q data-fact="Q7" data-quote-sel="lead=2">we estimate\u2026</q> [S4]')
+	})
+
+	test("md format puts the selector into fillMap", () => {
+		const result = fill("{{Q7:completion:lead=2}}", LEDGER, { format: "md" })
+		expect(result.out).toBe('"we estimate\u2026" [S4]')
+		expect(result.fillMap[0]).toMatchObject({ fact_id: "Q7", selector: "lead=2", quote_span: [0, 11] })
+	})
+
+	test("a translation span after a quote placeholder is preserved and mapped", () => {
+		const source = '{{Q7:completion}} <span data-translates="Q7">translation</span> rest'
+		const result = fill(source, LEDGER, { format: "html" })
+		expect(result.out).toContain('<span data-translates="Q7">translation</span> rest')
+		const entry = result.fillMap.find((item: { translates?: string }) => item.translates === "Q7")
+		expect(entry).toBeDefined()
+		expect(result.out.slice(entry.start, entry.end)).toBe(entry.rendered)
+		const md = fill("{{Q7:completion}} <!-- translates: Q7 --> translation", LEDGER, { format: "md" })
+		expect(md.fillMap.some((item: { translates?: string }) => item.translates === "Q7")).toBe(true)
+	})
+})
+
+describe("fill: Korean particles", () => {
+	test("a closed final keeps eul", () => {
+		const result = fill(`<p>{{F21:hbm_rev}}${EUL} ${GIROK}</p>`, LEDGER, { format: "html" })
+		expect(result.out).toContain(`</data>${EUL} ${GIROK}`)
+		expect(result.warnings).toEqual([])
+	})
+
+	test("percent is open: i becomes ga", () => {
+		const result = fill(`<p>{{F13:rate}}${I} ${OLLATDA}</p>`, LEDGER, { format: "html" })
+		expect(result.out).toContain(`15.2%</data>${GA} ${OLLATDA}`)
+	})
+
+	test("a candidate particle with no boundary is untouched and warned", () => {
+		const result = fill(`<p>{{F13:rate}}${ISANG}</p>`, LEDGER, { format: "html" })
+		expect(result.out).toContain(`</data>${ISANG}</p>`)
+		expect(codes(result.warnings)).toEqual(["particle_unverified"])
+	})
+})
+
+describe("fill: md maps", () => {
+	test("fillMap offsets slice to the rendered text", () => {
+		const result = fill(`# Findings\n\nSpan {{F12:span_len}}, rate {{F13:rate}}${I} ${OLLATDA}, {{Q7:completion:lead=3}}.\n`, LEDGER, { format: "md" })
+		expect(result.errors).toEqual([])
+		expect(result.fillMap).toHaveLength(3)
+		for (const entry of result.fillMap) expect(result.out.slice(entry.start, entry.end)).toBe(entry.rendered)
+		expect(result.fillMap[0].rendered).toBe("320 m")
+		expect(result.out).toContain(`15.2%${GA}`)
+	})
+})
+
+describe("fill: replace-failed", () => {
+	const SOURCE = '<h2 id="findings">Findings</h2>\n<p>Completion slips: {{Q7:completion}}. Other text stays.</p>'
+	const KEY = sentenceKey("findings", ["Q7"])
+
+	test("a key that failed twice becomes the attributed blockquote; no entity warns", () => {
+		const state = failedTwice(KEY)
+		const result = fill(SOURCE, LEDGER, { format: "html", replaceFailed: state })
+		expect(result.out).not.toBeNull()
+		expect(result.out).toContain(`<blockquote data-fact="Q7" data-replaced="${KEY}">`)
+		expect(result.out).toContain(`"${QUOTE}"`)
+		expect(result.out).toContain("<footer>[S4]</footer>")
+		expect(result.out).toContain("Other text stays.</p>")
+		expect(result.out).not.toContain("Completion slips")
+		expect(codes(result.warnings)).toEqual(["fallback_without_entity"])
+		expect(state.replaced).toEqual([KEY])
+	})
+
+	test("a row with entity and valid_at carries them in the footer", () => {
+		const source = `<h2>Market</h2>\n<p>Revenue was {{F21:hbm_rev}}.</p>`
+		const result = fill(source, LEDGER, { format: "html", replaceFailed: failedTwice(sentenceKey("market", ["F21"])) })
+		expect(result.out).toContain("<footer>[S5], on HBM3E (2026 Q3)</footer>")
+		expect(result.warnings).toEqual([])
+	})
+
+	test("a key below two failures is filled normally", () => {
+		const state: State = { schemaVersion: 1, failures: { [KEY]: 1 }, replaced: [] }
+		const result = fill(SOURCE, LEDGER, { format: "html", replaceFailed: state })
+		expect(result.out).toContain("Completion slips:")
+		expect(state.replaced).toEqual([])
+	})
+
+	test("fallback omit removes the sentence", () => {
+		const result = fill(SOURCE, LEDGER, { format: "html", replaceFailed: failedTwice(KEY), fallback: "omit" })
+		expect(result.out).toBe('<h2 id="findings">Findings</h2>\n<p> Other text stays.</p>')
+	})
+
+	test("view leaves the state unchanged", () => {
+		const state = failedTwice(KEY)
+		const result = fill(SOURCE, LEDGER, { format: "html", replaceFailed: state, view: true })
+		expect(result.out).toContain("<blockquote")
+		expect(state.replaced).toEqual([])
+		expect(failureCount(state, KEY)).toBe(2)
+	})
+
+	test("md renders a > block with the footer line", () => {
+		const result = fill("## Findings\n\nCompletion slips: {{Q7:completion}}.\n", LEDGER, { format: "md", replaceFailed: failedTwice(KEY) })
+		expect(result.out).toBe(`## Findings\n\n> "${QUOTE}"\n> [S4]\n`)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/fact-ledger-grammar.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from "bun:test"
+
+import { TRANSITIONS, addRow, emptyLedger, nextId, retractRow, supersedeRow, transitionError, validateLedger } from "./fact-ledger.mjs"
+
+// Property-style checks of references/fact-ledger-grammar.md: every ledger the writers build is
+// valid, and every single-invariant break the validator rejects is also refused by the writers.
+
+type Row = { fact_id: string; status: string; kind: string; label: string; operands: string[]; derived_from: string[] }
+type LedgerEvent = { fact_id: string; from: string; to: string; replacement?: string | null; reason?: string }
+type Ledger = { rows: Row[]; events: LedgerEvent[] }
+
+function measured(label: string) {
+	return {
+		kind: "measured",
+		value: "320",
+		unit: "m",
+		raw: "320 m",
+		quote: "The span is 320 m.",
+		value_span: [12, 15],
+		source_id: "S1",
+		locator: { artifact: "sources/S1/text.txt", line: 3, char_start: 40, char_end: 62 },
+		snapshot_sha256: "a".repeat(64),
+		extracted_by: "fact add --find",
+		observed_at: "2026-10-23T08:00:00Z",
+		label,
+	}
+}
+
+function quoteRow(label: string) {
+	return { ...measured(label), kind: "quote", value: null, unit: null, value_span: null }
+}
+
+function derivedRow(label: string, from: string[], kind = "derived") {
+	return {
+		kind,
+		value: "2",
+		raw: "2",
+		quote: "",
+		extracted_by: "fact derive",
+		observed_at: "2026-10-23T08:00:00Z",
+		label,
+		operation: kind === "converted" ? "convert" : "expr",
+		operands: [...from],
+		derived_from: [...from],
+		factor: kind === "converted" ? "1000" : null,
+		exact: { num: "2", den: "1" },
+		formula: from.join(" + "), render: "2", precision: { places: 0, sigfigs: 1 },
+		compatibility: kind === "converted" ? "checked" : "unchecked",
+		context: kind === "converted" ? { target: "km" } : null,
+	}
+}
+
+/** mulberry32: a fixed seed gives the same ledger on every run. */
+function prng(seed: number) {
+	let state = seed >>> 0
+	return () => {
+		state = (state + 0x6d2b79f5) >>> 0
+		let t = state
+		t = Math.imul(t ^ (t >>> 15), t | 1)
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+function pick<T>(random: () => number, list: T[]): T {
+	return list[Math.floor(random() * list.length)]
+}
+
+const ids = (ledger: Ledger, keep: (row: Row) => boolean) => ledger.rows.filter(keep).map((row) => row.fact_id)
+
+/** Writes the writers must refuse on any ledger; each returns nothing and must throw. */
+function illegalWrites(ledger: Ledger, random: () => number): (() => unknown)[] {
+	const active = ids(ledger, (row) => row.status === "active")
+	const ended = ids(ledger, (row) => row.status !== "active")
+	const writes: (() => unknown)[] = [() => addRow(ledger, derivedRow("dangling", ["F999"])), () => addRow(ledger, measured(pick(random, ledger.rows).label))]
+	if (active.length > 0) {
+		const id = pick(random, active)
+		writes.push(() => supersedeRow(ledger, id, id, "self"), () => supersedeRow(ledger, id, null, "none"), () => retractRow(ledger, id, ""))
+		if (ended.length > 0) writes.push(() => supersedeRow(ledger, id, pick(random, ended), "to an ended row"))
+	}
+	if (ended.length > 0) writes.push(() => retractRow(ledger, pick(random, ended), "again"))
+	return writes
+}
+
+/** Random addRow / retractRow / supersedeRow sequences from an empty ledger, with refused writes mixed in. */
+function randomLedger(seed: number) {
+	const random = prng(seed)
+	const ledger: Ledger = emptyLedger()
+	const steps = 4 + Math.floor(random() * 14)
+	for (let step = 0; step < steps; step += 1) {
+		const active = ids(ledger, (row) => row.status === "active")
+		const values = ids(ledger, (row) => row.fact_id.startsWith("F"))
+		const roll = random()
+		if (roll < 0.3 || values.length < 2) addRow(ledger, measured(`m${step}`))
+		else if (roll < 0.4) addRow(ledger, quoteRow(`q${step}`))
+		else if (roll < 0.6) {
+			const kind = pick(random, ["derived", "converted"])
+			const from = kind === "converted" ? [pick(random, values)] : [...new Set([pick(random, values), pick(random, values)])]
+			addRow(ledger, derivedRow(`d${step}`, from, kind))
+		}
+		else if (roll < 0.8 && active.length > 0) retractRow(ledger, pick(random, active), "wrong page")
+		else if (active.length > 1) {
+			const id = pick(random, active)
+			supersedeRow(ledger, id, pick(random, active.filter((other: string) => other !== id)), "newer filing")
+		}
+		const before = JSON.stringify(ledger)
+		const write = pick(random, illegalWrites(ledger, random))
+		expect(write).toThrow()
+		expect(JSON.stringify(ledger)).toBe(before)
+	}
+	return ledger
+}
+
+const LEDGERS = Array.from({ length: 200 }, (_, index) => randomLedger(index + 1))
+
+describe("every ledger the writers build is valid", () => {
+	test("200 seeded random write sequences all validate, and refused writes leave the ledger unchanged", () => {
+		for (const ledger of LEDGERS) expect(validateLedger(ledger)).toEqual([])
+		const events = LEDGERS.flatMap((ledger) => ledger.events)
+		expect(events.some((event) => event.to === "superseded")).toBe(true)
+		expect(events.some((event) => event.to === "retracted")).toBe(true)
+		expect(LEDGERS.some((ledger) => ledger.rows.some((row) => row.kind === "converted"))).toBe(true)
+	})
+})
+
+type Break = { name: string; mutate: (ledger: Ledger) => string | null; rejects: RegExp; write: (ledger: Ledger) => unknown; refuses: RegExp }
+
+const firstEvent = (ledger: Ledger, to?: string) => ledger.events.find((event) => to === undefined || event.to === to) as LedgerEvent
+const firstRow = (ledger: Ledger, keep: (row: Row) => boolean) => ledger.rows.find(keep) as Row
+const activeId = (ledger: Ledger) => firstRow(ledger, (row) => row.status === "active")?.fact_id
+
+const BREAKS: Break[] = [
+	{ name: "superseded event with a null replacement", mutate: (l) => { const e = firstEvent(l, "superseded"); if (!e || !activeId(l)) return null; e.replacement = null; return e.fact_id }, rejects: /needs a replacement row/, write: (l) => supersedeRow(l, activeId(l), null, "x"), refuses: /needs a replacement row/ },
+	{ name: "self replacement", mutate: (l) => { const e = firstEvent(l, "superseded"); if (!e || !activeId(l)) return null; e.replacement = e.fact_id; return e.fact_id }, rejects: /cannot be its own replacement/, write: (l) => supersedeRow(l, activeId(l), activeId(l), "x"), refuses: /cannot be its own replacement/ },
+	{ name: "duplicate transition", mutate: (l) => { const e = firstEvent(l); if (!e) return null; l.events.push({ ...e }); return e.fact_id }, rejects: /but the event moves it from active/, write: (l) => retractRow(l, firstEvent(l).fact_id, "x"), refuses: /cannot move from (retracted|superseded)/ },
+	{ name: "from mismatch", mutate: (l) => { const e = firstEvent(l); if (!e) return null; e.from = e.to; return e.fact_id }, rejects: /is active, but the event moves it from/, write: (l) => supersedeRow(l, firstEvent(l).fact_id, activeId(l) ?? "F1", "x"), refuses: /cannot move from|own replacement/ },
+	{ name: "active row with events", mutate: (l) => { const r = firstRow(l, (row) => row.status !== "active"); if (!r) return null; r.status = "active"; return r.fact_id }, rejects: /has status active but its last event moves it to/, write: (l) => { const r = firstRow(l, (row) => row.status !== "active"); const problem = transitionError(new Map([[r.fact_id, r.status]]), { fact_id: r.fact_id, from: r.status, to: "active", replacement: null, reason: "x" }); if (problem) throw new Error(problem) }, refuses: /cannot move from (retracted|superseded) to active/ },
+	{ name: "non-active row without events", mutate: (l) => { const e = firstEvent(l); if (!e) return null; l.events = l.events.filter((event) => event.fact_id !== e.fact_id); return e.fact_id }, rejects: /but has no status event/, write: (l) => addRow(l, { ...measured("fresh"), status: "retracted" }), refuses: /but has no status event/ },
+	{ name: "dangling operand", mutate: (l) => { const r = firstRow(l, (row) => row.operands.length > 0); if (!r) return null; r.operands[0] = "F999"; return r.fact_id }, rejects: /references F999, which has no ledger row/, write: (l) => addRow(l, derivedRow("fresh", ["F999"])), refuses: /references F999, which has no ledger row/ },
+	{ name: "self derived_from", mutate: (l) => { const r = firstRow(l, (row) => row.derived_from.length > 0); if (!r) return null; r.derived_from.push(r.fact_id); return r.fact_id }, rejects: /references itself/, write: (l) => addRow(l, { ...derivedRow("fresh", []), derived_from: [nextId(l, "derived")] }), refuses: /references itself/ },
+	{ name: "cyclic derived_from", mutate: (l) => { const r = firstRow(l, (row) => row.derived_from.length > 0); if (!r) return null; firstRow(l, (row) => row.fact_id === r.derived_from[0]).derived_from.push(r.fact_id); return r.fact_id }, rejects: /derives from itself through/, write: (l) => addRow(l, derivedRow("fresh", [`F${l.rows.length + 5}`])), refuses: /which has no ledger row/ },
+	{ name: "duplicate label", mutate: (l) => { if (l.rows.length < 2) return null; l.rows[1].label = l.rows[0].label; return l.rows[1].fact_id }, rejects: /has duplicate label/, write: (l) => addRow(l, measured(l.rows[0].label)), refuses: /has duplicate label/ },
+]
+
+describe("every single-invariant break is rejected by the validator and refused by the writers", () => {
+	for (const broken of BREAKS) {
+		test(broken.name, () => {
+			let applied = 0
+			for (const valid of LEDGERS) {
+				const ledger = structuredClone(valid)
+				const factId = broken.mutate(ledger)
+				if (factId === null) continue
+				applied += 1
+				const errors = validateLedger(ledger)
+				expect(errors.some((error: string) => broken.rejects.test(error) && error.includes(factId))).toBe(true)
+				const untouched = structuredClone(valid)
+				expect(() => broken.write(untouched)).toThrow(broken.refuses)
+				expect(untouched).toEqual(valid)
+			}
+			expect(applied).toBeGreaterThan(10)
+		})
+	}
+
+	test("no transition leads back to active", () => {
+		for (const targets of Object.values(TRANSITIONS)) expect(targets).not.toContain("active")
+	})
+})
+
+function twoRows() {
+	const ledger = emptyLedger()
+	addRow(ledger, measured("a"))
+	addRow(ledger, measured("b"))
+	return ledger
+}
+
+describe("validateLedger is as strict as the writers (review r5 MEDIUM)", () => {
+	test("a superseded event with a null replacement is rejected", () => {
+		const ledger = twoRows()
+		supersedeRow(ledger, "F1", "F2", "newer filing")
+		ledger.events[0].replacement = null
+		expect(validateLedger(ledger).some((e: string) => e.includes("F1") && e.includes("replacement"))).toBe(true)
+	})
+
+	test("a row superseded by itself is rejected", () => {
+		const ledger = twoRows()
+		supersedeRow(ledger, "F1", "F2", "newer filing")
+		ledger.events[0].replacement = "F1"
+		expect(validateLedger(ledger).some((e: string) => e.includes("F1") && e.includes("replacement"))).toBe(true)
+	})
+
+	test("two events that both move F1 from active to retracted are rejected", () => {
+		const ledger = twoRows()
+		retractRow(ledger, "F1", "wrong page")
+		ledger.events.push({ ...ledger.events[0] })
+		expect(validateLedger(ledger).some((e: string) => e.includes("events[1]") && e.includes("F1"))).toBe(true)
+	})
+})