lazycodex-ai 5.1.44 → 5.1.46

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

@@ -0,0 +1,221 @@
+// fact-ledger-schema.mjs - the fact ledger's vocabulary and validation: row fields and defaults,
+// kinds, statuses, qualifiers, and validateLedger over rows, status events, and their history.
+// The grammar it encodes is references/fact-ledger-grammar.md; every per-kind column rule lives in
+// KIND_RULES (fact-ledger-kinds.mjs), never here.
+// Pure functions with no IO; fact-ledger.mjs owns reading, writing, and row changes. node: builtins only.
+
+import { DECIMAL, isCount, isCurrentDerived, isNonEmpty, isObject, isString, kindRuleErrors, LATER_COLUMNS, readRow, storedErrors } from "./fact-ledger-kinds.mjs"
+import { malformed } from "./unit-rules.mjs"
+
+export { DECIMAL, isNonEmpty, isString } from "./fact-ledger-kinds.mjs"
+
+export const LEDGER_SCHEMA_VERSION = 1
+export const FACT_KINDS = Object.freeze(["measured", "quote", "derived", "assumed", "converted"])
+export const FACT_STATUSES = Object.freeze(["active", "superseded", "retracted"])
+export const OPERATIONS = Object.freeze(["sum", "diff", "growth", "ratio", "share", "convert", "expr"])
+/** Canonical qualifier terms; surface forms in either language map onto these. */
+export const QUALIFIERS = Object.freeze([
+	"upper_inclusive",
+	"lower_inclusive",
+	"approximate",
+	"near",
+	"lower_exclusive",
+	"upper_exclusive",
+])
+
+export const ROW_DEFAULTS = Object.freeze({
+	value: null,
+	unit: null,
+	value_span: null,
+	source_id: null,
+	locator: null,
+	locate_hint: null,
+	snapshot_sha256: null,
+	valid_at: null,
+	qualifier: null,
+	entity: null,
+	sentence_id: null,
+	observation_id: null,
+	fuzzy: false,
+	outside_floor: false,
+	population: null,
+	missing_rule: null,
+	accounting_basis: null,
+	snapshot_window: null,
+	revision: null,
+	exact: null,
+	render: null,
+	operation: null,
+	operands: [],
+	derived_from: [],
+	formula: null,
+	factor: null,
+	rationale: null,
+	context: null,
+	precision: null,
+	compatibility: null,
+	status: "active",
+})
+/** Fields added after schema version 1 shipped: written on every new row, optional when reading an older ledger. */
+const OPTIONAL_FIELDS = new Set(LATER_COLUMNS)
+const REQUIRED = ["fact_id", "kind", "raw", "quote", "extracted_by", "observed_at", "label"]
+export const ROW_FIELDS = Object.freeze([...REQUIRED, ...Object.keys(ROW_DEFAULTS)])
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+const LABEL = /^[a-z0-9_-]{1,32}$/
+const FACT_REF = /^[FQ]\d+$/
+
+function check(errors, condition, message) {
+	if (!condition) errors.push(message)
+}
+
+function nullOr(value, test) {
+	return value === null || test(value)
+}
+
+function validateRow(row, index, errors) {
+	const at = `rows[${index}]`
+	if (!isObject(row)) return errors.push(`${at} must be an object`)
+	for (const key of ROW_FIELDS) check(errors, OPTIONAL_FIELDS.has(key) || Object.hasOwn(row, key), `${at}.${key} is required`)
+	for (const key of Object.keys(row)) check(errors, ROW_FIELDS.includes(key), `${at}.${key} is not a ledger field`)
+	check(errors, FACT_KINDS.includes(row.kind), `${at}.kind must be one of ${FACT_KINDS.join(", ")}`)
+	// Dimension 31 wins at read time: per-kind rules see the row as readRow normalizes it.
+	errors.push(...kindRuleErrors(readRow(row), at))
+	errors.push(...storedErrors(row).map((e) => `${at}.${e}`))
+	if (isCurrentDerived(row)) {
+		const problem = malformed(row)
+		if (problem) errors.push(`${at}: ${problem}`)
+	}
+	check(errors, row.unit === undefined || nullOr(row.unit, isNonEmpty), `${at}.unit must be null or a non-empty token`)
+	for (const key of ["raw", "quote"]) check(errors, row[key] === undefined || isString(row[key]), `${at}.${key} must be a string`)
+	check(errors, row.extracted_by === undefined || isNonEmpty(row.extracted_by), `${at}.extracted_by must be a non-empty string`)
+	check(errors, row.observed_at === undefined || (isString(row.observed_at) && ISO_DATE.test(row.observed_at)), `${at}.observed_at must be an ISO timestamp`)
+	check(errors, row.label === undefined || (isString(row.label) && LABEL.test(row.label)), `${at}.label must match [a-z0-9_-]{1,32}`)
+	const span = row.value_span
+	check(errors, span === undefined || nullOr(span, (v) => Array.isArray(v) && v.length === 2 && v.every(isCount) && v[0] <= v[1]), `${at}.value_span must be null or [start, end]`)
+	for (const key of ["locate_hint", "valid_at", "entity", "observation_id", "missing_rule", "accounting_basis", "formula", "render"]) {
+		if (row[key] !== undefined) check(errors, nullOr(row[key], isString), `${at}.${key} must be null or a string`)
+	}
+	for (const key of ["population", "snapshot_window", "revision"]) {
+		if (row[key] !== undefined) check(errors, nullOr(row[key], (v) => isString(v) || isObject(v)), `${at}.${key} must be null, a string, or an object`)
+	}
+	if (row.qualifier !== undefined) check(errors, nullOr(row.qualifier, (v) => QUALIFIERS.includes(v)), `${at}.qualifier must be null or one of ${QUALIFIERS.join(", ")}`)
+	if (row.sentence_id !== undefined) check(errors, nullOr(row.sentence_id, (v) => isString(v) && /^S\d+:s\d+$/.test(v)), `${at}.sentence_id must be null or S<n>:s<k>`)
+	for (const key of ["fuzzy", "outside_floor"]) {
+		if (row[key] !== undefined) check(errors, typeof row[key] === "boolean", `${at}.${key} must be a boolean`)
+	}
+	if (row.operation !== undefined) check(errors, nullOr(row.operation, (v) => OPERATIONS.includes(v)), `${at}.operation must be null or one of ${OPERATIONS.join(", ")}`)
+	for (const key of ["operands", "derived_from"]) {
+		if (row[key] !== undefined) check(errors, Array.isArray(row[key]) && row[key].every((v) => isString(v) && FACT_REF.test(v)), `${at}.${key} must be an array of fact ids`)
+	}
+	if (row.factor !== undefined) check(errors, nullOr(row.factor, (v) => isString(v) && DECIMAL.test(v)), `${at}.factor must be null or a decimal string`)
+	check(errors, row.status === undefined || FACT_STATUSES.includes(row.status), `${at}.status must be one of ${FACT_STATUSES.join(", ")}`)
+}
+
+export function rowErrors(row) {
+	const errors = []
+	validateRow(row, 0, errors)
+	return errors
+}
+
+// The status machine and event rule of references/fact-ledger-grammar.md. validateLedger replays
+// events through transitionError, and every writer in fact-ledger.mjs calls it before appending.
+export const TRANSITIONS = Object.freeze({ active: Object.freeze(["retracted", "superseded"]), retracted: Object.freeze([]), superseded: Object.freeze([]) })
+const EVENT_FIELDS = Object.freeze(["fact_id", "from", "to", "replacement", "reason"])
+
+/**
+ * @param {Map<string, string>} statuses each fact's status at the event's position
+ * @returns {string | null} why the event is not a legal transition, or null
+ */
+export function transitionError(statuses, event) {
+	if (!isObject(event)) return "an event must be an object"
+	const id = event.fact_id
+	if (!statuses.has(id)) return `no ledger row ${id}`
+	if (EVENT_FIELDS.some((key) => !Object.hasOwn(event, key)) || Object.keys(event).some((key) => !EVENT_FIELDS.includes(key))) {
+		return `${id}: an event has exactly the fields ${EVENT_FIELDS.join(", ")}`
+	}
+	const current = statuses.get(id)
+	if (event.from !== current) return `${id} is ${current}, but the event moves it from ${event.from}`
+	if (!TRANSITIONS[current].includes(event.to)) return `${id} cannot move from ${current} to ${event.to}`
+	if (event.to === "superseded") {
+		if (event.replacement === null) return `supersede ${id} needs a replacement row; use retract for a fact with no replacement`
+		if (event.replacement === id) return `${id} cannot be its own replacement`
+		if (!statuses.has(event.replacement)) return `no replacement row ${event.replacement} for ${id}`
+		if (statuses.get(event.replacement) !== "active") return `replacement row ${event.replacement} is ${statuses.get(event.replacement)} (superseding ${id})`
+	} else if (event.replacement !== null) return `${id} is ${event.to} but names replacement ${event.replacement}`
+	if (!isNonEmpty(event.reason)) return `a reason is required to mark ${id} ${event.to}`
+	return null
+}
+
+/** Replay every event from all-active; each row's status must be where its event chain leaves it. */
+function validateHistory(ledger, errors) {
+	const statuses = new Map(ledger.rows.filter(isObject).map((row) => [row.fact_id, "active"]))
+	const counts = new Map()
+	ledger.events.forEach((event, index) => {
+		const problem = transitionError(statuses, event)
+		if (problem) errors.push(`events[${index}]: ${problem}`)
+		if (!isObject(event) || !statuses.has(event.fact_id) || !FACT_STATUSES.includes(event.to)) return
+		statuses.set(event.fact_id, event.to)
+		counts.set(event.fact_id, (counts.get(event.fact_id) ?? 0) + 1)
+	})
+	ledger.rows.forEach((row, index) => {
+		if (!isObject(row) || !FACT_STATUSES.includes(row.status)) return
+		const to = statuses.get(row.fact_id)
+		if (!counts.has(row.fact_id)) check(errors, row.status === "active", `rows[${index}]: ${row.fact_id} is ${row.status} but has no status event`)
+		else check(errors, to === row.status, `rows[${index}]: ${row.fact_id} has status ${row.status} but its last event moves it to ${to}`)
+	})
+}
+
+/** operands and derived_from name existing rows, never the row itself, and close no cycle. */
+export function provenanceErrors(rows) {
+	const errors = []
+	const refs = new Map()
+	for (const row of rows) if (isObject(row)) refs.set(row.fact_id, [row.operands, row.derived_from].flatMap((list) => (Array.isArray(list) ? list : [])))
+	rows.forEach((row, index) => {
+		for (const key of ["operands", "derived_from"]) {
+			if (!isObject(row) || !Array.isArray(row[key])) continue
+			for (const ref of row[key]) {
+				if (ref === row.fact_id) errors.push(`rows[${index}].${key}: ${ref} references itself`)
+				else check(errors, refs.has(ref), `rows[${index}].${key}: ${row.fact_id} references ${ref}, which has no ledger row`)
+			}
+		}
+	})
+	const state = new Map()
+	for (const root of refs.keys()) {
+		const stack = [{ id: root, finish: false }]
+		const path = []
+		while (stack.length) {
+			const { id, finish } = stack.pop()
+			if (state.get(id) === "done") continue
+			if (finish) { state.set(id, "done"); path.pop(); continue }
+			if (state.get(id) === "open") return [...errors, `${id} derives from itself through cycle ${[...path, id].join(" -> ")}`]
+			state.set(id, "open")
+			path.push(id)
+			stack.push({ id, finish: true })
+			for (const next of refs.get(id)) if (next !== id && refs.has(next)) stack.push({ id: next, finish: false })
+		}
+	}
+	return errors
+}
+
+/** @returns {string[]} every schema error; empty when the ledger is valid. */
+export function validateLedger(ledger) {
+	const errors = []
+	if (!isObject(ledger)) return ["ledger must be an object"]
+	check(errors, ledger.schemaVersion === LEDGER_SCHEMA_VERSION, `schemaVersion must be ${LEDGER_SCHEMA_VERSION}`)
+	if (!Array.isArray(ledger.rows)) return [...errors, "rows must be an array"]
+	ledger.rows.forEach((row, index) => validateRow(row, index, errors))
+	const ids = new Set()
+	const labels = new Set()
+	ledger.rows.forEach((row, index) => {
+		if (!isObject(row)) return
+		check(errors, !ids.has(row.fact_id), `rows[${index}].fact_id ${row.fact_id} is a duplicate`)
+		check(errors, row.label === undefined || !labels.has(row.label), `rows[${index}]: ${row.fact_id} has duplicate label ${row.label}`)
+		ids.add(row.fact_id)
+		labels.add(row.label)
+	})
+	errors.push(...provenanceErrors(ledger.rows))
+	if (Array.isArray(ledger.events)) validateHistory(ledger, errors)
+	else errors.push("events must be an array")
+	return errors
+}

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

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test"
+
+import { LEDGER_SCHEMA_VERSION, ROW_DEFAULTS, validateLedger } from "./fact-ledger-schema.mjs"
+
+function measuredRow(factId: string, label: string) {
+	return {
+		...structuredClone(ROW_DEFAULTS),
+		fact_id: factId,
+		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,
+		exact: { num: "320", den: "1" },
+	}
+}
+
+function ledgerOf(...rows: object[]) {
+	return { schemaVersion: LEDGER_SCHEMA_VERSION, rows, events: [] }
+}
+
+describe("validateLedger (schema module)", () => {
+	test("given a complete measured row, when validated, then there are no errors", () => {
+		expect(validateLedger(ledgerOf(measuredRow("F1", "span")))).toEqual([])
+	})
+
+	test("given two rows with one label, when validated, then the duplicate label is reported", () => {
+		const errors = validateLedger(ledgerOf(measuredRow("F1", "span"), measuredRow("F2", "span")))
+		expect(errors.some((e: string) => e.includes("duplicate label"))).toBe(true)
+	})
+
+	test("given an assumed row without rationale, when validated, then rationale is required", () => {
+		const errors = validateLedger(ledgerOf({ ...measuredRow("F1", "span"), kind: "assumed" }))
+		expect(errors.some((e: string) => e.includes("rationale"))).toBe(true)
+	})
+})

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

@@ -0,0 +1,123 @@
+// fact-ledger.mjs - the verbatim fact ledger: one row per measured, quoted, derived, assumed,
+// or converted value, with its source locator and exact rational. Rows are never deleted:
+// retract and supersede change status and append an event. Validation and the field vocabulary
+// live in fact-ledger-schema.mjs and are re-exported here. node: builtins only.
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+
+import { CliError, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
+import { DECIMAL, exactComesFromValue, exactFromDecimal, idPrefix, isString, readFlaws, readRow } from "./fact-ledger-kinds.mjs"
+import { LEDGER_SCHEMA_VERSION, ROW_DEFAULTS, ROW_FIELDS, transitionError, validateLedger } from "./fact-ledger-schema.mjs"
+import { normalizeInput } from "./unit-algebra.mjs"
+
+export { exactFromDecimal } from "./fact-ledger-kinds.mjs"
+export { FACT_KINDS, FACT_STATUSES, LEDGER_SCHEMA_VERSION, OPERATIONS, QUALIFIERS, ROW_FIELDS, TRANSITIONS, transitionError, validateLedger } from "./fact-ledger-schema.mjs"
+
+export const LEDGER_FILENAME = "fact-ledger.json"
+
+export function emptyLedger() {
+	return { schemaVersion: LEDGER_SCHEMA_VERSION, rows: [], events: [] }
+}
+
+function assertValid(ledger) {
+	const errors = validateLedger(ledger)
+	if (errors.length > 0) throw new CliError(`invalid fact ledger: ${errors.join("; ")}`)
+}
+
+/** The row's fields in ROW_FIELDS order, then any unknown field (which validation reports). */
+function ordered(row) {
+	const out = Object.fromEntries(ROW_FIELDS.filter((key) => Object.hasOwn(row, key)).map((key) => [key, row[key]]))
+	for (const key of Object.keys(row)) if (!ROW_FIELDS.includes(key)) out[key] = row[key]
+	return out
+}
+
+/**
+ * Every row comes back as readRow normalizes it (reduced exacts and decimals; source rows with canonical
+ * units and null later columns) before any strict rule runs; the file changes on the next write.
+ */
+export function readLedger(dir) {
+	const file = join(dir, LEDGER_FILENAME)
+	if (!existsSync(file)) return emptyLedger()
+	const ledger = readJsonFile(file)
+	assertValid(ledger)
+	ledger.rows = ledger.rows.map((row) => ordered(readRow(row)))
+	assertValid(ledger)
+	return ledger
+}
+
+export function writeLedger(dir, ledger) {
+	assertValid(ledger)
+	const file = join(dir, LEDGER_FILENAME)
+	writeJsonAtomic(file, ledger)
+	return file
+}
+
+const ID_NUMBER = Object.freeze({ F: /^F(\d+)$/, Q: /^Q(\d+)$/ })
+
+/** The next id with the kind's prefix from KIND_RULES (F<n> for value rows, Q<n> for quotes). */
+export function nextId(ledger, kind) {
+	const prefix = idPrefix(kind)
+	let max = 0n
+	for (const row of ledger.rows) {
+		const match = ID_NUMBER[prefix].exec(row.fact_id ?? "")
+		if (match && BigInt(match[1]) > max) max = BigInt(match[1])
+	}
+	return `${prefix}${max + 1n}`
+}
+
+/**
+ * Fill defaults, assign the next id, validate the whole ledger (provenance included), then append.
+ * Only kinds whose KIND_RULES exact is from_value (measured) get exact from their decimal:
+ * derived and converted rows carry the exact that derive computed from the operands and factor,
+ * never one read back from the rounded value.
+ */
+export function addRow(ledger, row) {
+	const filled = { ...structuredClone(ROW_DEFAULTS), ...row, fact_id: row.fact_id ?? nextId(ledger, row.kind) }
+	if (!["derived", "converted"].includes(filled.kind)) {
+		const normalized = normalizeInput(filled.unit, filled.value)
+		if (normalized.value !== filled.value && filled.exact !== null) throw new CliError("scaled input must omit exact; it is computed after normalization")
+		Object.assign(filled, readRow({ ...filled, ...normalized }))
+	}
+	if (exactComesFromValue(filled.kind) && filled.exact === null && isString(filled.value) && DECIMAL.test(filled.value)) {
+		filled.exact = exactFromDecimal(filled.value)
+	}
+	const added = ordered(filled)
+	const flaws = readFlaws(added)
+	if (flaws.length > 0) throw new CliError(`invalid fact ledger: ${flaws.map((flaw) => `${flaw.shape}: ${flaw.detail}`).join("; ")}`)
+	assertValid({ ...ledger, rows: [...ledger.rows, added] })
+	ledger.rows.push(added)
+	return added
+}
+
+/** Build the event from the row's current status and append it only if transitionError allows it. */
+function changeStatus(ledger, id, to, replacement, reason) {
+	const row = ledger.rows.find((candidate) => candidate.fact_id === id)
+	const event = { fact_id: id, from: row?.status ?? null, to, replacement: replacement ?? null, reason }
+	const problem = transitionError(new Map(ledger.rows.map((candidate) => [candidate.fact_id, candidate.status])), event)
+	if (problem) throw new CliError(problem)
+	ledger.events.push(event)
+	row.status = to
+	return row
+}
+
+export function retractRow(ledger, id, reason) {
+	return changeStatus(ledger, id, "retracted", null, reason)
+}
+
+export function supersedeRow(ledger, id, replacementId, reason) {
+	return changeStatus(ledger, id, "superseded", replacementId, reason)
+}
+
+function cell(value) {
+	return value === null || value === undefined ? "" : String(value).replace(/\|/g, "\\|").replace(/\n/g, " ")
+}
+
+/** The `--view` table: one line per row, retracted and superseded rows included. */
+export function renderLedgerMarkdown(ledger) {
+	const lines = ["| fact_id | kind | label | value | unit | source | status | raw |", "|---|---|---|---|---|---|---|---|"]
+	for (const row of ledger.rows) {
+		lines.push(`| ${[row.fact_id, row.kind, row.label, row.value, row.unit, row.source_id, row.status, row.raw].map(cell).join(" | ")} |`)
+	}
+	return `${lines.join("\n")}\n`
+}

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

@@ -0,0 +1,254 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import {
+	LEDGER_FILENAME,
+	LEDGER_SCHEMA_VERSION,
+	addRow,
+	emptyLedger,
+	nextId,
+	readLedger,
+	renderLedgerMarkdown,
+	retractRow,
+	supersedeRow,
+	validateLedger,
+	writeLedger,
+} from "./fact-ledger.mjs"
+
+const HASH = "a".repeat(64)
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "ulw-ledger-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
+}
+
+function measured(label: string, value = "320") {
+	return {
+		kind: "measured",
+		value,
+		unit: "m",
+		raw: `${value} m`,
+		quote: `The span is ${value} m.`,
+		value_span: [12, 12 + value.length],
+		source_id: "S1",
+		locator: { artifact: "sources/S1/text.txt", line: 3, char_start: 40, char_end: 62 },
+		snapshot_sha256: HASH,
+		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 ledgerWith(...rows: object[]) {
+	const ledger = emptyLedger()
+	for (const row of rows) addRow(ledger, row)
+	return ledger
+}
+
+describe("validateLedger", () => {
+	test("accepts a ledger built by addRow", () => {
+		expect(validateLedger(ledgerWith(measured("span"), quoteRow("claim")))).toEqual([])
+	})
+
+	test("rejects a row missing label", () => {
+		const ledger = ledgerWith(measured("span"))
+		delete (ledger.rows[0] as Record<string, unknown>).label
+		expect(validateLedger(ledger).some((e: string) => e.includes("label"))).toBe(true)
+	})
+
+	test("rejects a duplicate label", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows.push({ ...ledger.rows[0], fact_id: "F2" })
+		expect(validateLedger(ledger).some((e: string) => e.includes("duplicate label"))).toBe(true)
+	})
+
+	test("rejects an assumed row without rationale", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows[0].kind = "assumed"
+		expect(validateLedger(ledger).some((e: string) => e.includes("rationale"))).toBe(true)
+	})
+
+	test("rejects a value row with a non-decimal value", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows[0].value = "320m"
+		expect(validateLedger(ledger).some((e: string) => e.includes("value"))).toBe(true)
+	})
+
+	test("rejects an exact with a non-string num", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows[0].exact = { num: 1, den: "3" }
+		expect(validateLedger(ledger).some((e: string) => e.includes("exact"))).toBe(true)
+	})
+
+	test("rejects operands and derived_from ids with no ledger row", () => {
+		const ledger = ledgerWith(measured("span"))
+		ledger.rows.push({ ...ledger.rows[0], fact_id: "F2", kind: "derived", label: "ratio", operation: "ratio", operands: ["F9"], derived_from: ["F1", "Q7"] })
+		const errors = validateLedger(ledger)
+		expect(errors.some((e: string) => e.includes("operands") && e.includes("F9"))).toBe(true)
+		expect(errors.some((e: string) => e.includes("derived_from") && e.includes("Q7"))).toBe(true)
+		expect(errors.some((e: string) => e.includes("F1"))).toBe(false)
+	})
+
+	test("a bare row with only fact_id returns at least three errors", () => {
+		expect(validateLedger({ rows: [{ fact_id: "F1" }] }).length).toBeGreaterThanOrEqual(3)
+	})
+})
+
+describe("ids and status", () => {
+	test("nextId sequences F1, F2 then Q1, and a derived row gets F3", () => {
+		const ledger = emptyLedger()
+		expect(addRow(ledger, measured("a")).fact_id).toBe("F1")
+		expect(addRow(ledger, measured("b")).fact_id).toBe("F2")
+		expect(addRow(ledger, quoteRow("c")).fact_id).toBe("Q1")
+		expect(nextId(ledger, "derived")).toBe("F3")
+		const derived = addRow(ledger, {
+			kind: "derived",
+			value: "0.333",
+			unit: null,
+			raw: "0.333",
+			quote: "",
+			extracted_by: "fact derive",
+			observed_at: "2026-10-23T08:00:00Z",
+			label: "ratio",
+			operation: "ratio",
+			operands: ["F1", "F2"],
+			derived_from: ["F1", "F2"],
+			exact: { num: "1", den: "3" },
+			formula: "F1 / F2", render: "0.333", precision: { places: 3, sigfigs: 3 }, compatibility: "checked",
+		})
+		expect(derived.fact_id).toBe("F3")
+		expect(nextId(ledger, "quote")).toBe("Q2")
+	})
+
+	test("measured rows store exact from their decimal", () => {
+		const ledger = ledgerWith(measured("span", "12.50"))
+		expect(ledger.rows[0].exact).toEqual({ num: "25", den: "2" })
+	})
+
+	test("retractRow keeps the row with status retracted", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F1", "wrong page")
+		expect(ledger.rows).toHaveLength(2)
+		expect(ledger.rows[0].status).toBe("retracted")
+		expect(ledger.events[0]).toMatchObject({ fact_id: "F1", to: "retracted", reason: "wrong page" })
+		expect(validateLedger(ledger)).toEqual([])
+		expect(() => retractRow(ledger, "F9", "x")).toThrow()
+	})
+
+	test("supersedeRow points at the replacement", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		supersedeRow(ledger, "F1", "F2", "newer filing")
+		expect(ledger.rows[0].status).toBe("superseded")
+		expect(ledger.events[0]).toMatchObject({ fact_id: "F1", replacement: "F2" })
+		expect(validateLedger(ledger)).toEqual([])
+	})
+
+	test("supersedeRow refuses a replacement that is not active", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F2", "wrong page")
+		expect(() => supersedeRow(ledger, "F1", "F2", "newer filing")).toThrow(/F2 is retracted/)
+		expect(ledger.rows[0].status).toBe("active")
+		expect(ledger.events).toHaveLength(1)
+	})
+
+	test("supersedeRow without a replacement throws and points at retract", () => {
+		const ledger = ledgerWith(measured("a"))
+		expect(() => supersedeRow(ledger, "F1", null, "newer filing")).toThrow(/supersede F1 needs a replacement row; use retract/)
+		expect(ledger.rows[0].status).toBe("active")
+		expect(ledger.events).toHaveLength(0)
+	})
+})
+
+describe("read and write", () => {
+	test("write then read round-trips byte-identically", () => {
+		const dir = tempDir()
+		const ledger = ledgerWith(measured("span"), quoteRow("claim"))
+		writeLedger(dir, ledger)
+		const first = readFileSync(join(dir, LEDGER_FILENAME), "utf8")
+		const loaded = readLedger(dir)
+		expect(loaded).toEqual(ledger)
+		writeLedger(dir, loaded)
+		expect(readFileSync(join(dir, LEDGER_FILENAME), "utf8")).toBe(first)
+		expect(readdirSync(dir)).toEqual([LEDGER_FILENAME])
+		expect(loaded.schemaVersion).toBe(LEDGER_SCHEMA_VERSION)
+	})
+
+	test("a derived row with an exact rational round-trips and validates", () => {
+		const dir = tempDir()
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		addRow(ledger, {
+			kind: "derived",
+			value: "0.333",
+			raw: "0.333",
+			quote: "",
+			extracted_by: "fact derive",
+			observed_at: "2026-10-23T08:00:00Z",
+			label: "third",
+			operation: "ratio",
+			operands: ["F1", "F2"],
+			derived_from: ["F1", "F2"],
+			exact: { num: "1", den: "3" },
+			formula: "F1 / F2", render: "0.333", precision: { places: 3, sigfigs: 3 }, compatibility: "checked",
+		})
+		writeLedger(dir, ledger)
+		const loaded = readLedger(dir)
+		expect(loaded.rows[2].exact).toEqual({ num: "1", den: "3" })
+		expect(loaded.rows[2].value).toBe("0.333")
+		expect(validateLedger(loaded)).toEqual([])
+	})
+
+	test("readLedger of a missing file is an empty ledger; writeLedger refuses an invalid one", () => {
+		const dir = tempDir()
+		expect(readLedger(dir)).toEqual(emptyLedger())
+		const ledger = ledgerWith(measured("a"))
+		ledger.rows[0].value = "abc"
+		expect(() => writeLedger(dir, ledger)).toThrow()
+		expect(readdirSync(dir)).toEqual([])
+	})
+
+	test("renderLedgerMarkdown lists every row", () => {
+		const text = renderLedgerMarkdown(ledgerWith(measured("span"), quoteRow("claim")))
+		expect(text).toContain("| F1 | measured | span |")
+		expect(text).toContain("| Q1 | quote | claim |")
+	})
+})
+
+describe("validateLedger checks events against rows", () => {
+	test("a retracted event that carries a replacement is an error", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F1", "wrong page")
+		ledger.events[0].replacement = "F2"
+		expect(validateLedger(ledger).some((e: string) => /F1 is retracted but names replacement F2/.test(e))).toBe(true)
+	})
+
+	test("the last event for a fact must match its row status", () => {
+		const ledger = ledgerWith(measured("a"), measured("b"))
+		retractRow(ledger, "F1", "wrong page")
+		ledger.rows[0].status = "active"
+		expect(validateLedger(ledger).some((e: string) => /F1 has status active but its last event moves it to retracted/.test(e))).toBe(true)
+	})
+
+	test("a non-active row with no event is an error", () => {
+		const ledger = ledgerWith(measured("a"))
+		ledger.rows[0].status = "superseded"
+		expect(validateLedger(ledger).some((e: string) => /F1 is superseded but has no status event/.test(e))).toBe(true)
+	})
+
+	test("an event with an invalid from or to status is an error naming the fact", () => {
+		const ledger = ledgerWith(measured("a"))
+		retractRow(ledger, "F1", "wrong page")
+		ledger.events[0].from = "gone"
+		const errors = validateLedger(ledger)
+		expect(errors.some((e: string) => /events\[0\]: F1 is active, but the event moves it from gone/.test(e))).toBe(true)
+		ledger.events[0].from = "active"
+		ledger.events[0].to = "active"
+		expect(validateLedger(ledger).some((e: string) => /events\[0\]: F1 cannot move from active to active/.test(e))).toBe(true)
+	})
+})