lazycodex-ai 5.1.43 → 5.1.45

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

@@ -0,0 +1,141 @@
+import { describe, expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { KIND_COLUMNS, KIND_RULES as RULES_TABLE, KIND_TABLE_BEGIN, KIND_TABLE_END, exactFromDecimal, renderKindTable } from "./fact-ledger-kinds.mjs"
+import { FACT_KINDS, LEDGER_SCHEMA_VERSION, ROW_DEFAULTS, validateLedger } from "./fact-ledger-schema.mjs"
+
+// Property tests generated from KIND_RULES: for every kind, rows built from each column's rule
+// validate, and breaking exactly one column's rule is rejected with an error naming that column.
+
+/** mulberry32: a fixed seed gives the same rows 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
+	}
+}
+
+const KIND_RULES = RULES_TABLE as Record<string, Record<string, string>>
+
+type Random = () => number
+const int = (random: Random, max: number) => Math.floor(random() * max)
+const pick = <T>(random: Random, list: T[]): T => list[int(random, list.length)]
+
+function decimal(random: Random) {
+	const whole = `${pick(random, ["-", ""])}${int(random, 5000)}`
+	return random() < 0.5 ? whole : `${whole}.${String(int(random, 1000)).padStart(pick(random, [1, 2, 3]), "0").slice(0, 3)}`
+}
+const rational = (random: Random) => ({ num: `${int(random, 200) - 100}`, den: `${1 + int(random, 50)}` })
+const locator = (random: Random) => ({ artifact: `sources/S${1 + int(random, 9)}/text.txt`, char_start: 3, char_end: 3 + int(random, 80) })
+const sha = (random: Random) => Array.from({ length: 64 }, () => "0123456789abcdef"[int(random, 16)]).join("")
+
+type Row = Record<string, unknown> & { value: string }
+type Gen = { valid: (random: Random, row: Row) => unknown; invalid: (random: Random, row: Row) => unknown }
+
+/** One valid and one invalid generator per rule name; an unknown rule name fails the test below. */
+const GENERATORS: Record<string, Gen> = {
+	f_id: { valid: (r) => `F${1 + int(r, 99)}`, invalid: (r) => `Q${1 + int(r, 99)}` },
+	q_id: { valid: (r) => `Q${1 + int(r, 99)}`, invalid: (r) => `F${1 + int(r, 99)}` },
+	decimal: { valid: decimal, invalid: (r) => pick(r, ["1e3", "", null, 12, "1,000"]) },
+	null: { valid: () => null, invalid: (r) => pick(r, ["0", { num: "1", den: "1" }, "S1", "why"]) },
+	source: { valid: (r) => `S${1 + int(r, 9)}`, invalid: (r) => pick(r, [null, "F1", "S"]) },
+	source_or_null: { valid: (r) => pick(r, [null, `S${1 + int(r, 9)}`]), invalid: (r) => pick(r, ["F1", "S", 3]) },
+	locator: { valid: locator, invalid: (r) => pick(r, [null, { artifact: "", char_start: 0, char_end: 1 }, { artifact: "a", char_start: 5, char_end: 1 }]) },
+	locator_or_null: { valid: (r) => pick(r, [null, locator(r)]), invalid: (r) => pick(r, ["here", { artifact: "", char_start: 0, char_end: 1 }]) },
+	sha256: { valid: sha, invalid: (r) => pick(r, [null, "abc", "A".repeat(64)]) },
+	sha256_or_null: { valid: (r) => pick(r, [null, sha(r)]), invalid: (r) => pick(r, ["abc", 7]) },
+	string_or_null: { valid: (r) => pick(r, [null, "", "a reason"]), invalid: (r) => pick(r, [5, false, {}]) },
+	non_empty: { valid: () => "assumed from the filing year", invalid: (r) => pick(r, ["", null]) },
+	from_value: {
+		valid: (_r, row) => exactFromDecimal(row.value),
+		invalid: (r, row) => {
+			const exact = exactFromDecimal(row.value)
+			return pick(r, [null, { num: `${BigInt(exact.num) + 7n}`, den: exact.den }, { num: `${BigInt(exact.num) * 2n}`, den: `${BigInt(exact.den) * 2n}` }])
+		},
+	},
+	rational_or_null: { valid: (r) => pick(r, [null, rational(r)]), invalid: (r) => pick(r, [{ num: "1", den: "0" }, { num: 1, den: "2" }, "1/2"]) },
+	by_derive: { valid: (r) => pick(r, [null, rational(r)]), invalid: (r) => pick(r, [{ num: "1", den: "0" }, { num: "x", den: "2" }, "1/2"]) },
+}
+
+function baseRow(kind: string): Row {
+	const row: Record<string, unknown> = { ...structuredClone(ROW_DEFAULTS), kind, raw: "raw", quote: "quoted text", extracted_by: "fact add", observed_at: "2026-10-23T08:00:00Z", label: "x" }
+	return row as Row
+}
+
+/** A row whose every KIND_COLUMNS field follows its kind's rule, in column order (exact after value). */
+function validRow(kind: string, random: Random) {
+	const row = baseRow(kind)
+	for (const column of KIND_COLUMNS) row[column] = GENERATORS[KIND_RULES[kind][column]].valid(random, row)
+	return row
+}
+
+const ledgerOf = (row: object) => ({ schemaVersion: LEDGER_SCHEMA_VERSION, rows: [row], events: [] })
+const SEEDS = Array.from({ length: 60 }, (_, index) => index + 1)
+
+describe("KIND_RULES covers the grammar", () => {
+	test("every kind has a rule for every column, and every rule has a generator", () => {
+		expect(Object.keys(KIND_RULES)).toEqual([...FACT_KINDS])
+		for (const kind of FACT_KINDS) {
+			expect(Object.keys(KIND_RULES[kind])).toEqual([...KIND_COLUMNS])
+			for (const column of KIND_COLUMNS) expect(Object.hasOwn(GENERATORS, KIND_RULES[kind][column])).toBe(true)
+		}
+	})
+})
+
+describe("rows generated from KIND_RULES", () => {
+	for (const kind of FACT_KINDS) {
+		test(`${kind}: seeded valid rows validate`, () => {
+			for (const seed of SEEDS) {
+				const row = validRow(kind, prng(seed))
+				expect({ seed, errors: validateLedger(ledgerOf(row)) }).toEqual({ seed, errors: [] })
+			}
+		})
+
+		for (const column of KIND_COLUMNS) {
+			test(`${kind}: breaking only the ${column} rule (${KIND_RULES[kind][column]}) is rejected`, () => {
+				for (const seed of SEEDS) {
+					const random = prng(seed * 7919)
+					const row = validRow(kind, random)
+					row[column] = GENERATORS[KIND_RULES[kind][column]].invalid(random, row)
+					const errors = validateLedger(ledgerOf(row))
+					expect({ seed, value: row[column], named: errors.some((error: string) => error.startsWith(`rows[0].${column}`)) }).toEqual({ seed, value: row[column], named: true })
+				}
+			})
+		}
+	}
+
+	test("review MEDIUM: a measured row with value -0.50 and exact 7/1 is rejected", () => {
+		const row = { ...validRow("measured", prng(1)), value: "-0.50", exact: { num: "7", den: "1" } }
+		expect(validateLedger(ledgerOf(row)).some((error: string) => error.startsWith("rows[0].exact"))).toBe(true)
+		expect(validateLedger(ledgerOf({ ...row, exact: { num: "-1", den: "2" } }))).toEqual([])
+	})
+
+	test("review LOW 1: a quote row with a non-null exact is rejected", () => {
+		const row = { ...validRow("quote", prng(2)), exact: { num: "1", den: "1" } }
+		expect(validateLedger(ledgerOf(row)).some((error: string) => error.startsWith("rows[0].exact"))).toBe(true)
+	})
+})
+
+describe("the grammar's per-kind table is rendered from KIND_RULES", () => {
+	const grammar = readFileSync(join(import.meta.dir, "..", "references", "fact-ledger-grammar.md"), "utf8")
+
+	test("the committed table section equals renderKindTable() byte for byte", () => {
+		const begin = grammar.indexOf(KIND_TABLE_BEGIN)
+		const end = grammar.indexOf(KIND_TABLE_END)
+		expect(begin).toBeGreaterThanOrEqual(0)
+		expect(end).toBeGreaterThan(begin)
+		expect(grammar.slice(begin + KIND_TABLE_BEGIN.length + 1, end)).toBe(renderKindTable())
+	})
+
+	test("node fact-ledger-kinds.mjs --render-grammar prints the same table", () => {
+		const result = spawnSync("node", [join(import.meta.dir, "fact-ledger-kinds.mjs"), "--render-grammar"], { encoding: "utf8" })
+		expect(result.status).toBe(0)
+		expect(result.stdout).toBe(renderKindTable())
+	})
+})

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

@@ -0,0 +1,204 @@
+// 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, isNonEmpty, isObject, isString, kindRuleErrors } from "./fact-ledger-kinds.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,
+	status: "active",
+})
+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, 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(", ")}`)
+	errors.push(...kindRuleErrors(row, at))
+	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(", ")}`)
+}
+
+// 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()
+	const visit = (id, path) => {
+		if (state.get(id) === "done") return null
+		if (state.get(id) === "open") return [...path.slice(path.indexOf(id)), id]
+		state.set(id, "open")
+		for (const next of refs.get(id)) {
+			const cycle = next !== id && refs.has(next) ? visit(next, [...path, id]) : null
+			if (cycle) return cycle
+		}
+		state.set(id, "done")
+		return null
+	}
+	for (const id of refs.keys()) {
+		const cycle = visit(id, [])
+		if (cycle) return [...errors, `${cycle[0]} derives from itself through ${cycle.join(" -> ")}`]
+	}
+	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,103 @@
+// 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 } from "./fact-ledger-kinds.mjs"
+import { LEDGER_SCHEMA_VERSION, ROW_DEFAULTS, ROW_FIELDS, transitionError, validateLedger } from "./fact-ledger-schema.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("; ")}`)
+}
+
+export function readLedger(dir) {
+	const file = join(dir, LEDGER_FILENAME)
+	if (!existsSync(file)) return emptyLedger()
+	const ledger = readJsonFile(file)
+	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 = 0
+	for (const row of ledger.rows) {
+		const match = ID_NUMBER[prefix].exec(row.fact_id ?? "")
+		if (match) max = Math.max(max, Number(match[1]))
+	}
+	return `${prefix}${max + 1}`
+}
+
+/**
+ * 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 (exactComesFromValue(filled.kind) && filled.exact === null && isString(filled.value) && DECIMAL.test(filled.value)) {
+		filled.exact = exactFromDecimal(filled.value)
+	}
+	const ordered = Object.fromEntries(ROW_FIELDS.filter((key) => Object.hasOwn(filled, key)).map((key) => [key, filled[key]]))
+	for (const key of Object.keys(filled)) if (!ROW_FIELDS.includes(key)) ordered[key] = filled[key]
+	assertValid({ ...ledger, rows: [...ledger.rows, ordered] })
+	ledger.rows.push(ordered)
+	return ordered
+}
+
+/** 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`
+}