lazycodex-ai 5.1.44 → 5.1.46

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

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+import { extractPairs, hasHedge, PAIR_KINDS } from "./fact-pairs.mjs"
+import { fill } from "./fact-fill.mjs"
+
+type Row = Record<string, unknown> & { fact_id: string }
+type Pair = Record<string, unknown> & { pair_id: string; kind: string; sentence: string }
+
+const FIXTURES = join(import.meta.dir, "tests/fixtures/fidelity")
+const BASE = JSON.parse(readFileSync(join(FIXTURES, "ledger-basic.json"), "utf8")) as { schemaVersion: number; rows: Row[] }
+const Q7 = BASE.rows.find((row) => row.fact_id === "Q7")
+if (Q7 === undefined) throw new Error("ledger-basic.json lost Q7")
+const Q8 = { ...Q7, fact_id: "Q8", label: "outlook", quote: "Demand may recover in 2027" }
+const LEDGER = { ...BASE, rows: [...BASE.rows, Q8] }
+const CLAIMS = indexClaims(readFileSync(join(FIXTURES, "claim-graph.md"), "utf8"))
+
+const SOURCE = [
+	"<!doctype html><html lang=\"en\"><body>",
+	"<h1>Bridge report</h1>",
+	"<h2 id=\"findings\">Findings</h2>",
+	"<p>The span is {{F12:span_len:q}}, or {{F40:span_mm}} [S4].</p>",
+	"<p>The rate is {{F13:rate}} [S4].</p>",
+	"<p>The operator wrote {{Q8:outlook}}, so the recovery is certain and fully funded now.</p>",
+	"<p>The note says {{Q7:completion}}<span data-translates=\"Q7\">completion is not expected before 2027</span>.</p>",
+	"<p data-claim=\"C2\">Revenue grew 10 percent in 2025.</p>",
+	"<p data-kind=\"opinion\">This looks like a sound plan.</p>",
+	"<h2>Sources</h2>",
+	"<ol><li id=\"s4\">[S4] Bridge authority page, retrieved 2026-10-01. Its span is {{F13:rate}}.</li></ol>",
+	"</body></html>",
+].join("\n")
+
+function filled(): { out: string; fillMap: { fact_id: string }[] } {
+	const result = fill(SOURCE, LEDGER, { format: "html" })
+	if (result.out === null) throw new Error(`fixture failed to fill: ${JSON.stringify(result.errors)}`)
+	return { out: result.out, fillMap: result.fillMap as { fact_id: string }[] }
+}
+
+function pairs(): Pair[] {
+	const { out, fillMap } = filled()
+	return extractPairs(out, LEDGER, CLAIMS, fillMap) as Pair[]
+}
+
+describe("extractPairs: a filled report", () => {
+	test("#given the filled fixture #when extracted #then pairs come in document order with P ids", () => {
+		const result = pairs()
+		expect(result.map((pair) => [pair.pair_id, pair.kind])).toEqual([
+			["P1", "quote"],
+			["P2", "quote"],
+			["P3", "quote"],
+			["P4", "quote"],
+			["P5", "translation"],
+			["P6", "claim"],
+		])
+	})
+
+	test("#given the fixture that produces every pair kind #when extracted #then the kinds are exactly PAIR_KINDS", () => {
+		expect([...new Set(pairs().map((pair) => pair.kind))].sort()).toEqual([...PAIR_KINDS].sort())
+		expect(Object.isFrozen(PAIR_KINDS)).toBe(true)
+	})
+
+	test("#given two facts sharing one source quote #when extracted #then one quote pair names both", () => {
+		const [first] = pairs()
+		expect(first).toMatchObject({
+			kind: "quote",
+			sentence_key: "findings#F12,F40",
+			fact_ids: ["F12", "F40"],
+			quote: "The bridge has a main span of up to 320 m.",
+			source_lang: "en",
+			report_lang: "en",
+			force_strong: false,
+		})
+		expect(first.sentence).toContain("up to 320 m")
+	})
+
+	test("#given an unhedged quote with its value kept #when extracted #then force_strong stays false", () => {
+		expect(pairs()[1]).toMatchObject({ fact_ids: ["F13"], quote: "The rate reached 15.2% in May.", force_strong: false })
+	})
+
+	test("#given a hedged quote whose sentence ends without a hedge #when extracted #then force_strong is true", () => {
+		expect(pairs()[2]).toMatchObject({ fact_ids: ["Q8"], quote: "Demand may recover in 2027", force_strong: true })
+	})
+
+	test("#given a data-translates span #when extracted #then a translation pair carries the span text", () => {
+		const result = pairs()
+		expect(result[3]).toMatchObject({ kind: "quote", fact_ids: ["Q7"] })
+		expect(result[4]).toMatchObject({
+			kind: "translation",
+			fact_ids: ["Q7"],
+			quote: "we estimate completion no earlier than 2027",
+			sentence: "completion is not expected before 2027",
+		})
+	})
+
+	test("#given a sentence bound only by data-claim #when extracted #then a claim pair carries the node statement", () => {
+		expect(pairs()[5]).toMatchObject({
+			kind: "claim",
+			claim_id: "C2",
+			statement: "Revenue grew about 10 percent in 2025.",
+			sentence: "Revenue grew 10 percent in 2025.",
+			force_strong: true,
+		})
+	})
+
+	test("#given an opinion paragraph and a sources section #when extracted #then neither yields a pair", () => {
+		const sentences = pairs().map((pair) => pair.sentence)
+		expect(sentences.some((text) => text.includes("sound plan"))).toBe(false)
+		expect(sentences.some((text) => text.includes("Bridge authority"))).toBe(false)
+	})
+
+	test("#given a fill map that omits a fact #when extracted #then that hand-typed fact yields no pair", () => {
+		const { out, fillMap } = filled()
+		const kept = fillMap.filter((entry) => entry.fact_id !== "F13")
+		const result = extractPairs(out, LEDGER, CLAIMS, kept) as Pair[]
+		expect(result.some((pair) => Array.isArray(pair.fact_ids) && (pair.fact_ids as string[]).includes("F13"))).toBe(false)
+	})
+
+	test("#given no fill map #when extracted #then every data-fact element counts as filled", () => {
+		const { out } = filled()
+		expect((extractPairs(out, LEDGER, CLAIMS) as Pair[]).length).toBe(6)
+	})
+
+	test("#given a Hangul quote #when extracted #then source_lang is ko", () => {
+		const html = "<html><body><h2>Findings</h2><p>HBM revenue reached {{F21:hbm_rev}} [S5].</p></body></html>"
+		const result = fill(html, LEDGER, { format: "html" }) as { out: string; fillMap: { fact_id: string }[] }
+		const [pair] = extractPairs(result.out, LEDGER, CLAIMS, result.fillMap) as Pair[]
+		expect(pair).toMatchObject({ fact_ids: ["F21"], source_lang: "ko", report_lang: "en" })
+	})
+})
+
+describe("extractPairs: a fill map over translations", () => {
+	test("#given a fill map that omits the translated fact #when extracted #then no translation pair is emitted", () => {
+		const { out, fillMap } = filled()
+		const kept = fillMap.filter((entry) => entry.fact_id !== "Q7")
+		const result = extractPairs(out, LEDGER, CLAIMS, kept) as Pair[]
+		expect(result.some((pair) => pair.kind === "translation")).toBe(false)
+	})
+})
+
+describe("hasHedge: a month is not a hedge", () => {
+	test("#given a text that starts with the month May #when checked #then it does not count as hedged", () => {
+		expect(hasHedge("May 2024 sales rose.")).toBe(false)
+	})
+
+	test("#given a sentence-initial modal may #when checked #then it still counts as hedged", () => {
+		expect(hasHedge("May the figure hold through 2027.")).toBe(true)
+		expect(hasHedge("Demand may recover in 2027.")).toBe(true)
+	})
+})
+
+describe("extractPairs: determinism", () => {
+	test("#given the same filled report twice #when extracted #then both results are byte-for-byte equal", () => {
+		const { out, fillMap } = filled()
+		const first = JSON.stringify(extractPairs(out, LEDGER, CLAIMS, fillMap))
+		const second = JSON.stringify(extractPairs(out, LEDGER, CLAIMS, fillMap))
+		expect(second).toBe(first)
+	})
+})
+
+describe("extractPairs: the no-model contract", () => {
+	test("#given the module source #when read #then it never fetches or imports a network or model client", () => {
+		const text = readFileSync(join(import.meta.dir, "fact-pairs.mjs"), "utf8")
+		expect(text).not.toMatch(/\bfetch\s*\(|node:https?|node:net|from\s+"(?!\.\/|node:)/u)
+	})
+})

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

@@ -0,0 +1,89 @@
+// Iterative postorder verifier: one snapshot and one arithmetic evaluation per reachable node.
+import { compute } from "./fact-derive.mjs"
+import { parseExpr } from "./fact-expr.mjs"
+import { isLegacyDerived, kindRuleErrors, readFlaws, readRow } from "./fact-ledger-kinds.mjs"
+import { rowErrors } from "./fact-ledger-schema.mjs"
+import { refuse } from "./unit-algebra.mjs"
+import { refusal } from "./unit-errors.mjs"
+import { object, sameDeclared } from "./unit-metadata.mjs"
+import { expectedUnit, malformed, ruleOf, unitMismatch } from "./unit-rules.mjs"
+
+const derived = (row) => row.kind === "derived" || row.kind === "converted"
+const fail = (detail, shape, expected) => ({ ok: false, detail, shape, expected })
+function refuseLegacy(row) {
+	if (isLegacyDerived(row)) refuse(`${row.fact_id} was written before precision, compatibility, and context existed; regenerate it with derive`, undefined, "legacy derived row", "a derived row regenerated by derive")
+}
+
+function verifyRow(row, rows) {
+	const rule = ruleOf(row.operation)
+	const ast = rule.expression ? parseExpr(row.formula) : null
+	const context = { ...row.context, rationale: row.rationale }
+	const unit = expectedUnit(row.operation, rows, { ast, context })
+	const expected = { unit, ...compute(row.operation, rows, unit, ast, context, row.formula), derived_from: rows.map((r) => r.fact_id) }
+	if (row.unit !== unit) return fail(`${row.fact_id}: ${unitMismatch(row.operation, rows, row.unit, unit)}`, "result_unit", expected)
+	for (const field of Object.keys(expected)) {
+		if (!sameDeclared(row[field], expected[field])) return fail(`${row.fact_id}: stored ${field} differs from the recomputed result`, `${field}_mismatch`, expected)
+	}
+	return { ok: true, expected }
+}
+
+export function verifyGraph(ledger, roots, requireActive = false, override = null) {
+	try {
+		if (!object(ledger) || !Array.isArray(ledger.rows)) refuse("ledger rows must be an array")
+		const byId = new Map()
+		for (const r of ledger.rows) {
+			if (!object(r) || typeof r.fact_id !== "string" || byId.has(r.fact_id)) refuse("ledger rows need distinct fact ids", undefined, "identity", "distinct fact ids")
+			byId.set(r.fact_id, r)
+		}
+		if (override) byId.set(override.fact_id, override)
+		const states = new Map()
+		const snapshots = new Map()
+		const results = new Map()
+		const stack = roots.map((id) => ({ id, finish: false }))
+		while (stack.length) {
+			const { id, finish } = stack.pop()
+			if (states.get(id) === "done") continue
+			if (!finish) {
+				if (states.get(id) === "open") refuse(`${id}: operands form a cycle`, undefined, "cycle", "an acyclic dependency graph")
+				const original = byId.get(id)
+				if (!original) refuse(`no ledger row ${id}`, undefined, "missing_operand", "an existing fact id")
+				const row = { ...readRow(original) }
+				snapshots.set(id, row)
+				if (requireActive && row.status !== "active") refuse(`${id} is ${row.status}`, undefined, "inactive_dependency", "active dependencies at every depth")
+				const [flaw] = readFlaws(row)
+				if (flaw) refuse(`${id}: ${flaw.detail}`, undefined, flaw.shape, flaw.expected)
+				if (derived(row)) {
+					refuseLegacy(row)
+					const shape = malformed(row)
+					if (shape) refuse(`${id}: ${shape}`, undefined, "malformed_row", "the operation's registry row shape")
+				}
+				const errors = derived(row) ? kindRuleErrors(row, id) : rowErrors(row)
+				if (errors.length) refuse(errors.join("; "), undefined, "row_schema", "a canonical row matching its kind and operation")
+				if (row.exact === null || row.value === null) refuse(`${id} has no exact value to derive from`)
+				states.set(id, "open")
+				stack.push({ id, finish: true })
+				if (derived(row)) for (const dependency of row.operands) stack.push({ id: dependency, finish: false })
+			} else {
+				const row = snapshots.get(id)
+				if (derived(row)) {
+					const result = verifyRow(row, row.operands.map((ref) => snapshots.get(ref)))
+					if (!result.ok) return result
+					const errors = rowErrors(row)
+					if (errors.length) refuse(errors.join("; "), undefined, "row_schema", "a complete canonical row")
+					results.set(id, result)
+				}
+				states.set(id, "done")
+			}
+		}
+		return results.get(roots[0]) ?? { ok: true }
+	} catch (error) { return { ok: false, ...refusal(error) } }
+}
+
+export function recompute(ledger, row) {
+	try {
+		refuseLegacy(row)
+		const shape = malformed(row)
+		if (shape) refuse(shape, undefined, "malformed_row", "a valid derived or converted row")
+		return verifyGraph(ledger, [row.fact_id], false, row)
+	} catch (error) { return { ok: false, ...refusal(error) } }
+}

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

@@ -0,0 +1,409 @@
+import { expect, test } from "bun:test"
+
+import { derive, recompute } from "./fact-derive.mjs"
+import { addRow, emptyLedger, retractRow, validateLedger } from "./fact-ledger.mjs"
+import { canonicalUnit } from "./unit-rules.mjs"
+import { convertFactor } from "./units.mjs"
+
+type Row = Record<string, unknown>
+type Book = { schemaVersion: number; rows: Row[]; events: unknown[] }
+const now = "2026-10-23T08:00:00Z"
+function book(values: string[] = ["1", "3"], units: Array<string | null> = ["m", "m"], extras: Row[] = []): Book {
+	const ledger = emptyLedger() as Book
+	values.forEach((value, i) => addRow(ledger, {
+		kind: "measured", value, unit: units[i], raw: value, quote: value, source_id: "S1",
+		locator: { artifact: "sources/S1/text.txt", char_start: 0, char_end: 1 },
+		snapshot_sha256: "a".repeat(64), extracted_by: "test", observed_at: now, label: `f${i + 1}`,
+		...extras[i],
+	}))
+	return ledger
+}
+function row(ledger: Book, spec: Row): Row {
+	const result = derive(ledger, { ...spec, now })
+	if (!("row" in result)) throw Error(JSON.stringify(result))
+	return result.row as Row
+}
+const sum = { op: "sum", operands: ["F1", "F2"], unit: "m" }
+function refused(ledger: Book, spec: unknown) {
+	const before = structuredClone(ledger)
+	const result = derive(ledger, spec)
+	expect(result).toMatchObject({ error: "incompatible_operands" })
+	expect(ledger).toEqual(before)
+	return result
+}
+
+test("dimension 01: kind operation consistency cannot disable recursive trust", () => {
+	for (const patch of [{ operation: null }, { kind: "measured" }, { operation: "convert" }]) {
+		const l = book()
+		const inner = row(l, sum)
+		const outer = row(l, { op: "convert", operands: [inner.fact_id], to: "cm" })
+		Object.assign(inner, patch, { value: "999", exact: { num: "999", den: "1" } })
+		expect(validateLedger(l).length).toBeGreaterThan(0)
+		expect(recompute(l, outer).ok).toBe(false)
+		refused(l, { op: "convert", operands: [inner.fact_id], to: "cm" })
+	}
+})
+
+test("dimension 02: direct and expression metadata propagate with identical compatibility", () => {
+	for (const field of ["population", "accounting_basis", "snapshot_window"]) {
+		const incompatible = book(["1", "3"], ["m", "m"], [{ [field]: "adults" }, { [field]: "children" }])
+		refused(incompatible, sum)
+		refused(incompatible, { op: "expr", formula: "F1 + F2", unit: "m" })
+	}
+	const meta = { population: "all", accounting_basis: "cash", snapshot_window: "2026", entity: "acme", valid_at: "2026" }
+	const l = book(["1", "3"], ["m", "m"], [meta, meta])
+	for (const spec of [sum, { op: "expr", formula: "F1 + F2", unit: "m" }]) {
+		const inner = row(l, spec)
+		expect(inner).toMatchObject(meta)
+		expect(row(l, { op: "convert", operands: [inner.fact_id], to: "cm" })).toMatchObject(meta)
+	}
+})
+
+test("dimension 03: precision survives stored intermediates and conversion round trips", () => {
+	const l = book(["1.20", "2.30", "0.04"], ["m", "m", "m"])
+	const inner = row(l, sum)
+	expect(inner.value).toBe("3.5")
+	expect(row(l, { ...sum, operands: [inner.fact_id, "F3"] }).value).toBe("3.54")
+	const cm = row(l, { op: "convert", operands: [inner.fact_id], to: "cm" })
+	const m = row(l, { op: "convert", operands: [cm.fact_id], to: "m" })
+	expect(row(l, { ...sum, operands: [m.fact_id, "F3"] }).value).toBe("3.54")
+	expect(recompute(l, m).ok).toBe(true)
+})
+
+test("dimension 04: scaled aliases preserve composite factor scale", () => {
+	for (const [unit, value, formula, expectedUnit, expected] of [
+		["bp/person", "100", "F1 * F2", "%p", "1"],
+		["person/bp", "1", "F1 / F2", "1/%p", "100"],
+		["bp^2/person", "10000", "F1 * F2", "%p^2", "1"],
+	] as const) {
+		const l = book([value, "1"], [unit, "person"])
+		expect(row(l, { op: "expr", formula, unit: expectedUnit }).exact).toEqual({ num: expected, den: "1" })
+	}
+})
+
+test("dimension 05: public refusal API is total classified and append atomic", () => {
+	for (const bad of [null, undefined, 1, [], {}, { op: "wat" }, { ...sum, operands: null }]) {
+		const result = refused(book(), bad)
+		expect(result).toMatchObject({ shape: expect.any(String), expected: expect.anything() })
+	}
+	for (const bad of [null, [], {}, { num: "NaN", den: "1" }, { num: "1", den: "0" }]) {
+		const l = book()
+		l.rows[0].exact = bad
+		refused(l, sum)
+		const result = recompute(l, l.rows[0])
+		expect(result).toMatchObject({ ok: false, shape: expect.any(String) })
+		expect(result.expected).toBeDefined()
+	}
+	for (const bad of [null, undefined, 1, [], {}]) {
+		expect(() => recompute(bad, bad)).not.toThrow()
+		expect(recompute(bad, bad)).toMatchObject({ ok: false, shape: expect.any(String) })
+	}
+})
+
+test("dimension 06: aliases normalize at input; derived rows store canonical units, source aliases read canonical (dimension 31)", () => {
+	const l = book(["1", "3"], ["metre", "m"])
+	expect(l.rows[0].unit).toBe("m")
+	const result = row(l, sum)
+	l.rows[0].unit = "metre"
+	expect(validateLedger(l)).toEqual([])
+	expect(recompute(l, result).ok).toBe(true)
+	const relabeled = { ...result, unit: "metre" }
+	l.rows[l.rows.indexOf(result)] = relabeled
+	expect(validateLedger(l).length).toBeGreaterThan(0)
+	expect(recompute(l, relabeled).ok).toBe(false)
+})
+
+test("dimension 07: exact rationals are reduced canonical integer strings; dev's integer pairs read reduced (dimension 31)", () => {
+	for (const [exact, reduced] of [[{ num: "2", den: "2" }, "1"], [{ num: "01", den: "1" }, "1"], [{ num: "-0", den: "1" }, "0"], [{ num: "-6", den: "06" }, "-1"]] as const) {
+		const l = book(["1", "3"])
+		Object.assign(l.rows[0], { kind: "assumed", rationale: "given", value: reduced, source_id: null, locator: null, snapshot_sha256: null, exact })
+		expect(validateLedger(l)).toEqual([])
+		expect(row(l, { op: "expr", formula: "F1", unit: "m" }).exact).toEqual({ num: reduced, den: "1" })
+	}
+	for (const exact of [{ num: 1, den: "1" }, { num: "1", den: "-1" }, { num: "1", den: "0" }, { num: "1.5", den: "1" }]) {
+		const l = book()
+		Object.assign(l.rows[0], { kind: "assumed", rationale: "given", exact })
+		expect(validateLedger(l).length).toBeGreaterThan(0)
+		refused(l, { op: "expr", formula: "F1", unit: "m" })
+	}
+	const l = book()
+	const made = row(l, sum)
+	made.exact = { num: "8", den: "2" }
+	expect(validateLedger(l).length).toBeGreaterThan(0)
+	expect(recompute(l, made).ok).toBe(false)
+})
+
+test("dimension 08: context schemas reject foreign keys and wrong types", () => {
+	const l = book()
+	const result = row(l, sum)
+	for (const context of [{ disjoint: "true", reference: 7 }, { disjoint: false, reference: null, target: "km" }, { disjoint: false, reference: null, extra: true }]) {
+		expect(recompute(l, { ...result, context }).ok).toBe(false)
+	}
+	refused(l, { ...sum, disjoint: "true" })
+	refused(l, { ...sum, target: "km" })
+	refused(l, { ...sum, op: "diff", disjoint: true })
+	refused(l, { op: "diff", operands: ["F1", "F2"], unit: "m", context: { target: "km" } })
+})
+
+test("dimension 09: redundant audit fields are rederived and compared", () => {
+	const l = book()
+	for (const spec of [sum, { op: "convert", operands: ["F1"], to: "cm" }]) {
+		const result = row(l, spec)
+		for (const patch of [{ factor: "999" }, { formula: "999" }, { derived_from: ["F2"] }, { raw: "999" }]) {
+			expect(recompute(l, { ...result, ...patch }).ok).toBe(false)
+		}
+	}
+})
+
+test("dimension 10: metadata equality ignores object insertion order but not invalid presence", () => {
+	const l = book(["1", "3"], ["m", "m"], [{ population: { age: 20, place: "x" } }, { population: { place: "x", age: 20 } }])
+	expect(row(l, sum).value).toBe("4")
+	for (const value of [undefined, 3, "", []]) {
+		const bad = book()
+		bad.rows[0].population = value
+		refused(bad, sum)
+	}
+})
+
+test("dimension 11: inactive descendants remain historically verifiable but ineligible", () => {
+	const l = book()
+	const inner = row(l, sum)
+	const outer = row(l, { op: "convert", operands: [inner.fact_id], to: "cm" })
+	retractRow(l, "F1", "wrong source")
+	expect(recompute(l, outer).ok).toBe(true)
+	refused(l, { op: "convert", operands: [outer.fact_id], to: "m" })
+})
+
+test("dimension 12: shared DAG nodes are verified once and deep expressions are stack independent", () => {
+	const l = book()
+	const first = row(l, sum)
+	let a = first
+	let b = row(l, { ...sum, operands: [first.fact_id, "F1"] })
+	for (let i = 0; i < 10; i++) [a, b] = [b, row(l, { ...sum, operands: [a.fact_id, b.fact_id] })]
+	let visits = 0
+	const exact = first.exact
+	Object.defineProperty(first, "exact", { get: () => { visits++; return exact }, configurable: true })
+	expect(recompute(l, b).ok).toBe(true)
+	expect(visits).toBe(1)
+	const deep = `${"(".repeat(12000)}F1${")".repeat(12000)}`
+	expect(row(book(), { op: "expr", formula: deep, unit: "m" }).value).toBe("1")
+	const chain = book()
+	const template = row(chain, { op: "expr", formula: "F1", unit: "m" })
+	let previous = String(template.fact_id)
+	for (let i = 4; i < 12004; i++) {
+		const fact_id = `F${i}`
+		chain.rows.push({ ...template, fact_id, label: `chain-${i}`, operands: [previous], derived_from: [previous], formula: previous })
+		previous = fact_id
+	}
+	expect(validateLedger(chain)).toEqual([])
+	expect(recompute(chain, chain.rows.at(-1)).ok).toBe(true)
+})
+
+test("dimension 13: composite exponents are exact bigint and normalization idempotent", () => {
+	for (const [input, expected] of [["m^9007199254740993", "m^9007199254740993"], ["m^9007199254740993/m^9007199254740992", "m"], ["m^0", null], ["m^-2", "1/m^2"], ["m/(s/kg)", "kg*m/s"]] as const) {
+		expect(canonicalUnit(input)).toBe(expected)
+		expect(canonicalUnit(expected)).toBe(expected)
+	}
+	for (const input of ["m^1e3", "m^1.5", "m^"]) expect(() => canonicalUnit(input)).toThrow()
+})
+
+test("dimension 14: affine and scale atoms cannot hide in composites or cancellation", () => {
+	for (const unit of ["C/s", "F*m", "C/C", "(C/s)^2"]) {
+		let l: Book
+		try { l = book(["1", "3"], [unit, unit]) } catch { continue }
+		expect(derive(l, { op: "ratio", num: "F1", den: "F2", unit: null }).error).toBeDefined()
+	}
+	for (const unit of ["million", "m/M", "bn/bn"]) expect(() => canonicalUnit(unit)).toThrow()
+})
+
+test("dimension 15: disjoint shares individually and jointly stay within one whole", () => {
+	const spec = { op: "sum", operands: ["F1", "F2"], unit: "%", disjoint: true, reference: "all", rationale: "disjoint" }
+	for (const values of [["60", "60"], ["-1", "50"], ["101", "0"]]) refused(book(values, ["%", "%"]), spec)
+	expect(row(book(["40", "60"], ["%", "%"]), spec).value).toBe("100")
+	refused(book(["20", "30"], ["%", "%"]), { ...spec, reference: { F1: "all", F2: "all", F99: "all" } })
+})
+
+test("dimension 16: FX arithmetic persists unchecked compatibility and requires a dated rate", () => {
+	const spec = { op: "expr", formula: "F1 * F2", unit: "USD" }
+	refused(book(["100", "1.10"], ["EUR", "USD/EUR"]), spec)
+	const l = book(["100", "1.10"], ["EUR", "USD/EUR"], [{ valid_at: "2026-10-23" }, { valid_at: "2026-10-23" }])
+	const result = row(l, spec)
+	expect(result.compatibility).toBe("unchecked")
+	expect(result.exact).toEqual({ num: "110", den: "1" })
+	expect(recompute(l, result).ok).toBe(true)
+	expect(recompute(l, { ...result, compatibility: "checked" }).ok).toBe(false)
+})
+
+test("dimension 17: symbols are case sensitive and opaque text stays opaque", () => {
+	expect(canonicalUnit("Mb")).toBe("Mb")
+	expect(canonicalUnit("MB")).toBe("MB")
+	expect(canonicalUnit("m b")).toBe("m b")
+	expect(canonicalUnit(" metric ton ")).toBe("metric ton")
+	expect(canonicalUnit("m / s")).toBe("m/s")
+	expect(canonicalUnit("\u03bcm")).not.toBe(canonicalUnit("\u00b5m"))
+})
+
+test("dimension 18: undefined and missing required fields never stand in for null", () => {
+	const l = book()
+	for (const unit of [undefined, ""]) refused(l, { op: "ratio", num: "F1", den: "F2", unit })
+	refused(l, { op: "ratio", num: "F1", den: "F2" })
+	expect(row(l, { op: "ratio", num: "F1", den: "F2", unit: null }).unit).toBeNull()
+	for (const patch of [{ unit: undefined }, { value: undefined }, { population: undefined }]) {
+		const bad = book()
+		Object.assign(bad.rows[0], patch)
+		refused(bad, sum)
+	}
+})
+
+test("dimension 19: allocation above safe integer remains exact and unique", () => {
+	const l = book()
+	l.rows[1].fact_id = "F9007199254740992"
+	const result = row(l, { ...sum, operands: ["F1", "F9007199254740992"] })
+	expect(result.fact_id).toBe("F9007199254740993")
+	expect(recompute(l, result).ok).toBe(true)
+})
+
+test("dimension 20: supplied expression operand set must match formula leaves", () => {
+	for (const operands of [["F2"], ["F1", "F2"], ["F1", "F1"], [], null]) refused(book(), { op: "expr", formula: "F1", unit: "m", operands })
+	expect(row(book(), { op: "expr", formula: "F1 + F2", operands: ["F2", "F1"], unit: "m" }).value).toBe("4")
+})
+
+test("dimension 21: expression root and literal precision remain explicit", () => {
+	const l = book(["1000", "3"], ["m", "m"])
+	expect(row(l, { op: "expr", formula: "F1 - F2", unit: "m" }).value).toBe("997")
+	expect(row(l, { op: "expr", formula: "(F1 - F2) * 1", unit: "m" }).value).toBe("1000")
+	expect(row(l, { op: "expr", formula: "(F1 - F2) * 1.00", unit: "m" }).value).toBe("1000")
+})
+
+test("dimension 22: cloned snapshots are deterministic and replay appends a new identity", () => {
+	const original = book()
+	const left = structuredClone(original)
+	const right = structuredClone(original)
+	expect(row(left, sum)).toEqual(row(right, sum))
+	expect(row(left, sum).fact_id).toBe("F4")
+	expect(original.rows).toHaveLength(2)
+})
+
+test("dimension 23: coherent trusted input rewrites are a documented arithmetic limitation", () => {
+	const l = book(["0", "3"])
+	const km = row(l, { op: "convert", operands: ["F1"], to: "km" })
+	const cm = row(l, { op: "convert", operands: ["F1"], to: "cm" })
+	const coherent = { ...cm, fact_id: km.fact_id, label: km.label }
+	expect(recompute(l, coherent).ok).toBe(true)
+	expect(recompute(l, { ...km, unit: "cm" }).ok).toBe(false)
+})
+
+test("dimension 24: sum permutation and ordered arithmetic keep their own semantics", () => {
+	const l = book(["2", "5"])
+	for (const operands of [["F1", "F2"], ["F2", "F1"]]) expect(row(l, { ...sum, operands }).exact).toEqual({ num: "7", den: "1" })
+	expect(row(l, { ...sum, op: "diff" }).exact).toEqual({ num: "-3", den: "1" })
+	expect(row(l, { ...sum, op: "diff", operands: ["F2", "F1"] }).exact).toEqual({ num: "3", den: "1" })
+})
+
+test("dimension 25: numeric domain boundaries do not forbid negative ordinary arithmetic", () => {
+	for (const values of [["6", "5"], ["-1", "5"], ["0", "0"]]) expect(derive(book(values), { op: "share", part: "F1", whole: "F2", unit: "%" }).error).toBeDefined()
+	expect(row(book(["-2", "-5"]), sum).exact).toEqual({ num: "-7", den: "1" })
+	expect(derive(book(), { op: "expr", formula: "F1 / (F2 - F2)", unit: null }).error).toBeDefined()
+})
+
+test("dimension 26: percent products and pct nodes preserve fraction semantics", () => {
+	const l = book(["20", "50"], ["%", "%"])
+	expect(row(l, { op: "expr", formula: "pct(F1 * F2)", unit: "%" }).exact).toEqual({ num: "10", den: "1" })
+	expect(row(l, { op: "diff", operands: ["F2", "F1"], unit: "%p" }).exact).toEqual({ num: "30", den: "1" })
+	expect(derive(l, { op: "expr", formula: "pct(F1)", unit: "%" }).error).toBeDefined()
+})
+
+test("dimension 27: conversion maps compose with exact independent rational arithmetic", () => {
+	const groups = [["mm", "cm", "m", "km"], ["g", "kg", "t"], ["ms", "s", "min", "h"], ["B", "KB", "MB", "GB", "TB"], ["C", "F"], ["%", "\u2030"], ["KRW", "KRW-e3", "KRW-e4", "KRW-e8", "KRW-e12"]]
+	const apply = (factor: { num: bigint; den: bigint; offset?: { num: bigint; den: bigint } } | null, x: [bigint, bigint]): [bigint, bigint] => {
+		if (!factor) throw Error("missing conversion")
+		const o = factor.offset ?? { num: 0n, den: 1n }
+		return [x[0] * factor.num * o.den + o.num * x[1] * factor.den, x[1] * factor.den * o.den]
+	}
+	for (const group of groups) for (const a of group) for (const b of group) for (const c of group) {
+		for (const value of [-3n, 0n, 7n]) {
+			const direct = apply(convertFactor(a, c), [value, 1n])
+			const chained = apply(convertFactor(b, c), apply(convertFactor(a, b), [value, 1n]))
+			expect(direct[0] * chained[1]).toBe(chained[0] * direct[1])
+		}
+	}
+	expect(derive(book(), { op: "convert", operands: ["F1"], to: "furlong" }).error).toBeDefined()
+})
+
+test("dimension 28: grammar rejects injection and preserves precedence", () => {
+	for (const formula of ["F1;globalThis.x=1", "-F1", "F1 ** 2", "pct F1", "(F1", "F1 F2"]) expect(derive(book(), { op: "expr", formula, unit: "m" }).error).toBeDefined()
+	expect(row(book(), { op: "expr", formula: "F1 + F2 * 2", unit: "m" }).exact).toEqual({ num: "7", den: "1" })
+})
+
+test("dimension 29: signed rounding ties and canonical display are exact", () => {
+	for (const [values, expected] of [[["-1.25", "-2.5"], "-3.8"], [["1.25", "2.5"], "3.8"], [["999.5", "0"], "1000"]] as const) {
+		expect(row(book([...values]), sum).value).toBe(expected)
+	}
+	const l = book(["20", "15"], ["%", "%"])
+	const delta = row(l, { op: "diff", operands: ["F1", "F2"], unit: "%p" })
+	expect(recompute(l, { ...delta, render: "5 pp" }).ok).toBe(false)
+})
+
+test("dimension 30: seeded factor trees have an independent arithmetic and unit oracle", () => {
+	let seed = 0x11009
+	const next = () => { seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0; return seed }
+	const atoms = ["m", "s", "person"]
+	for (let i = 0; i < 100; i++) {
+		const counts = [0, 0, 0]
+		const factors = Array.from({ length: 5 }, () => {
+			const index = next() % atoms.length
+			const exponent = (next() % 7) - 3
+			counts[index] += exponent
+			return `(${atoms[index]}^${exponent})`
+		})
+		const side = (positive: boolean) => atoms.map((a, index) => ({ a, n: counts[index] })).filter(({ n }) => positive ? n > 0 : n < 0).sort((a, b) => a.a.localeCompare(b.a)).map(({ a, n }) => Math.abs(n) === 1 ? a : `${a}^${Math.abs(n)}`)
+		const top = side(true).join("*") || "1"
+		const bottom = side(false)
+		const expectedUnit = bottom.length ? `${top}/${bottom.length === 1 ? bottom[0] : `(${bottom.join("*")})`}` : top === "1" ? null : top
+		expect(canonicalUnit(factors.join("*"))).toBe(expectedUnit)
+		const a = BigInt(1 + next() % 100)
+		const b = BigInt(1 + next() % 100)
+		const l = book([String(a), String(b)], [factors.join("*"), "person"])
+		const result = row(l, { op: "expr", formula: "F1 * F2 / F2", unit: expectedUnit })
+		expect(result.exact).toEqual({ num: String(a), den: "1" })
+		expect(result.unit).toBe(expectedUnit)
+		expect(recompute(l, result).ok).toBe(true)
+		expect(recompute(l, { ...result, exact: { num: String(a + 1n), den: "1" } }).ok).toBe(false)
+	}
+})
+
+test("dimension 30: independent rational oracle crosses every operation with metadata and tampering", () => {
+	let state = 3917
+	const next = () => { state = (Math.imul(state, 1103515245) + 12345) >>> 0; return state }
+	const exact = (n: bigint, d = 1n) => {
+		let a = n < 0n ? -n : n
+		let b = d
+		while (b) [a, b] = [b, a % b]
+		return { num: String(n / a), den: String(d / a) }
+	}
+	for (let i = 0; i < 50; i++) {
+		const a = BigInt(1 + next() % 50)
+		const b = a + BigInt(1 + next() % 50)
+		const meta = { population: { country: "x", cohort: i }, accounting_basis: "cash", snapshot_window: "2026", entity: "acme" }
+		const specs: Array<[Row, { num: string; den: string }]> = [
+			[{ ...sum }, exact(a + b)],
+			[{ ...sum, op: "diff" }, exact(a - b)],
+			[{ op: "ratio", num: "F1", den: "F2", unit: null }, exact(a, b)],
+			[{ op: "share", part: "F1", whole: "F2", unit: "%" }, exact(100n * a, b)],
+			[{ op: "growth", from: "F1", to: "F2", unit: "%" }, exact(100n * (b - a), a)],
+			[{ op: "convert", operands: ["F1"], to: "cm" }, exact(100n * a)],
+			[{ op: "expr", formula: "F1 * 2 / F2", unit: null }, exact(2n * a, b)],
+		]
+		for (const [spec, expected] of specs) {
+			const l = book([String(a), String(b)], ["metre", "m"], [{ ...meta, valid_at: "2025" }, { ...meta, valid_at: "2026" }])
+			const result = row(l, spec)
+			expect(result.exact).toEqual(expected)
+			expect(recompute(l, result).ok).toBe(true)
+			expect(recompute(l, { ...result, unit: "person" }).ok).toBe(false)
+			expect(recompute(l, { ...result, exact: { num: String(BigInt(expected.num) + 1n), den: expected.den } }).ok).toBe(false)
+		}
+		const l = book([String(100n * a), String(b)], ["bp/person", "person"])
+		const result = row(l, { op: "expr", formula: "F1 * F2", unit: "%p" })
+		expect(result.exact).toEqual(exact(a * b))
+	}
+})