lazycodex-ai 5.1.44 → 5.1.46

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

@@ -0,0 +1,250 @@
+// fact-ledger-kinds.mjs - the per-kind column rules of the fact ledger as one table, KIND_RULES.
+// validateLedger checks every per-kind column through kindRuleErrors, the writers read their
+// per-kind choices (id prefix, measured exact) from it, and the per-kind table in
+// references/fact-ledger-grammar.md is rendered from it (`node fact-ledger-kinds.mjs --render-grammar`).
+// Also the value primitives the schema shares. Pure functions with no IO; node: builtins only.
+
+import { isCliEntry } from "./entry-guard.mjs"
+import { canonicalUnit, inputScale, RuleError } from "./unit-algebra.mjs"
+import { metadataErrors } from "./unit-metadata.mjs"
+import { mul } from "./rational.mjs"
+import { placesOf, roundPlaces, toBig } from "./unit-precision.mjs"
+import { OPERATION_RULES } from "./unit-rules.mjs"
+
+export const DECIMAL = /^-?\d+(?:\.\d+)?$/
+const INTEGER = /^-?\d+$/
+const SHA256 = /^[0-9a-f]{64}$/
+const SOURCE_ID = /^S\d+$/
+
+export const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+export const isString = (value) => typeof value === "string"
+export const isNonEmpty = (value) => typeof value === "string" && value.length > 0
+export const isCount = (value) => Number.isInteger(value) && value >= 0
+const isDecimal = (value) => isString(value) && DECIMAL.test(value)
+export function isRational(exact) {
+	if (!isObject(exact) || Object.keys(exact).sort().join(",") !== "den,num" || !isString(exact.num) || !isString(exact.den) || !INTEGER.test(exact.num) || !/^[1-9]\d*$/.test(exact.den)) return false
+	let a = BigInt(exact.num)
+	let b = BigInt(exact.den)
+	if (String(a) !== exact.num) return false
+	if (a < 0n) a = -a
+	while (b !== 0n) [a, b] = [b, a % b]
+	return a === 1n
+}
+
+/** The exact rational of a decimal string, reduced. */
+export function exactFromDecimal(value) {
+	const [whole, fraction = ""] = value.replace(/^-/, "").split(".")
+	let num = BigInt(whole + fraction)
+	let den = 10n ** BigInt(fraction.length)
+	let a = num
+	let b = den
+	while (b !== 0n) [a, b] = [b, a % b]
+	if (a > 1n) [num, den] = [num / a, den / a]
+	return { num: `${value.startsWith("-") && num !== 0n ? "-" : ""}${num}`, den: `${den}` }
+}
+
+/** @returns {string[]} what is wrong with a locator object, each message prefixed with `at`. */
+export function locatorErrors(locator, at) {
+	const errors = []
+	if (!isObject(locator)) return errors
+	if (!isNonEmpty(locator.artifact)) errors.push(`${at}.artifact must be a non-empty string`)
+	if (!(isCount(locator.char_start) && isCount(locator.char_end) && locator.char_start <= locator.char_end)) errors.push(`${at}.char_start/char_end must be integers with start <= end`)
+	for (const key of ["page", "line"]) {
+		if (locator[key] !== undefined && !(Number.isInteger(locator[key]) && locator[key] >= 1)) errors.push(`${at}.${key} must be an integer >= 1`)
+	}
+	for (const key of ["table", "row_label", "col_label"]) {
+		if (locator[key] !== undefined && !isString(locator[key])) errors.push(`${at}.${key} must be a string`)
+	}
+	return errors
+}
+
+const isLocator = (value) => isObject(value) && locatorErrors(value, "").length === 0
+const orNull = (test) => (value, row) => value === null || test(value, row)
+const locatorDetail = (value, at) => locatorErrors(value, at)
+
+/**
+ * Every rule a KIND_RULES cell may name: `cell` is its text in the grammar table, `says` ends the
+ * error message, `test(value, row)` decides it, and `prefix` (id rules only) is what nextId uses.
+ */
+export const RULES = Object.freeze({
+	f_id: { cell: "`F<n>`", says: "F<n>", prefix: "F", test: (v) => isString(v) && /^F\d+$/.test(v) },
+	q_id: { cell: "`Q<n>`", says: "Q<n>", prefix: "Q", test: (v) => isString(v) && /^Q\d+$/.test(v) },
+	decimal: { cell: "decimal", says: "a decimal string", test: isDecimal },
+	null: { cell: "null", says: "null", test: (v) => v === null },
+	source: { cell: "`S<n>`", says: "S<n>", test: (v) => isString(v) && SOURCE_ID.test(v) },
+	source_or_null: { cell: "`S<n>` or null", says: "S<n> or null", test: orNull((v) => isString(v) && SOURCE_ID.test(v)) },
+	locator: { cell: "object", says: "a locator object", test: isLocator, detail: locatorDetail },
+	locator_or_null: { cell: "object or null", says: "a locator object or null", test: orNull(isLocator), detail: locatorDetail },
+	sha256: { cell: "sha256", says: "a sha256 hex digest", test: (v) => isString(v) && SHA256.test(v) },
+	sha256_or_null: { cell: "sha256 or null", says: "a sha256 hex digest or null", test: orNull((v) => isString(v) && SHA256.test(v)) },
+	string_or_null: { cell: "string or null", says: "null or a string", test: orNull(isString) },
+	non_empty: { cell: "non-empty", says: "a non-empty string (required for this kind)", test: isNonEmpty },
+	from_value: {
+		cell: "from `value`",
+		says: "the reduced exact rational of value",
+		test: (v, row) => isRational(v) && (!isDecimal(row.value) || (v.num === exactFromDecimal(row.value).num && v.den === exactFromDecimal(row.value).den)),
+	},
+	rational_or_null: { cell: "rational or null", says: "null or { num: integer string, den: positive integer string }", test: orNull(isRational) },
+	by_derive: { cell: "reduced rational", says: "a reduced { num: integer string, den: positive integer string }", test: isRational },
+	context_by_derive: { cell: "written by derive (object or null)", says: "null or an object", test: orNull(isObject) },
+	derived_operation: { cell: "sum/diff/growth/share/ratio/expr", says: "a derived operation", test: (v) => Object.hasOwn(OPERATION_RULES, v) && OPERATION_RULES[v].kind === "derived" },
+	convert_operation: { cell: "`convert`", says: "convert", test: (v) => Object.hasOwn(OPERATION_RULES, v) && OPERATION_RULES[v].kind === "converted" },
+	precision: { cell: "`{ places, sigfigs }`", says: "nonnegative places and positive sigfigs", test: (v) => isObject(v) && Object.keys(v).sort().join(",") === "places,sigfigs" && Number.isSafeInteger(v.places) && v.places >= 0 && Number.isSafeInteger(v.sigfigs) && v.sigfigs >= 1 },
+	compatibility: { cell: "checked or unchecked (expr)", says: "the operation's compatibility", test: (v, r) => Object.hasOwn(OPERATION_RULES, r.operation) && v === OPERATION_RULES[r.operation].compatibility },
+})
+
+/** The grammar's per-kind columns, in table order; `exact` follows `value` because it reads it. */
+export const KIND_COLUMNS = Object.freeze(["fact_id", "value", "source_id", "locator", "snapshot_sha256", "rationale", "exact", "context", "operation", "precision", "compatibility"])
+
+const sourced = { source_id: "source", locator: "locator", snapshot_sha256: "sha256" }
+const unsourced = { source_id: "source_or_null", locator: "locator_or_null", snapshot_sha256: "sha256_or_null" }
+const row = (cells) => Object.freeze(Object.fromEntries(KIND_COLUMNS.map((column) => [column, cells[column] ?? (["precision", "compatibility"].includes(column) && cells.operation !== "null" ? column : "null")])))
+
+export const KIND_RULES = Object.freeze({
+	measured: row({ fact_id: "f_id", value: "decimal", ...sourced, rationale: "string_or_null", exact: "from_value", context: "null", operation: "null" }),
+	quote: row({ fact_id: "q_id", value: "null", ...sourced, rationale: "string_or_null", exact: "null", context: "null", operation: "null" }),
+	derived: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive", context: "context_by_derive", operation: "derived_operation" }),
+	assumed: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "non_empty", exact: "rational_or_null", context: "null", operation: "null" }),
+	converted: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive", context: "context_by_derive", operation: "convert_operation" }),
+})
+
+/** The id prefix nextId assigns for a kind; an unknown kind gets F and fails validation later. */
+export function idPrefix(kind) {
+	return RULES[KIND_RULES[kind]?.fact_id ?? "f_id"].prefix
+}
+
+/** Whether addRow computes the row's exact from its decimal value. */
+export function exactComesFromValue(kind) {
+	return KIND_RULES[kind]?.exact === "from_value"
+}
+
+/** Columns added after schema version 1 shipped; a ledger written before them still loads (dimension 31). */
+export const LATER_COLUMNS = Object.freeze(["context", "precision", "compatibility"])
+const DERIVED_KINDS = Object.freeze(["derived", "converted"])
+const PRE_REGISTRY_COLUMNS = KIND_COLUMNS.slice(0, KIND_COLUMNS.indexOf("exact") + 1)
+
+/** A derived or converted row written before the later columns existed: loadable, never an operand. */
+export const isLegacyDerived = (row) => isObject(row) && DERIVED_KINDS.includes(row.kind) && LATER_COLUMNS.every((column) => !Object.hasOwn(row, column))
+/** A derived or converted row carrying this version's columns: the only rows checked strictly at read time. */
+export const isCurrentDerived = (row) => isObject(row) && DERIVED_KINDS.includes(row.kind) && !isLegacyDerived(row)
+
+/** An exact carrying keys beyond num and den: never normalized, never silently stripped, flagged on use. */
+export const hasUnknownExactKeys = (exact) => isObject(exact) && isString(exact.num) && isString(exact.den) && Object.keys(exact).sort().join(",") !== "den,num"
+/** Any integer pair dev's writer accepted, reduced: sign on num, no leading zeros, gcd 1; anything else as given. */
+function readExact(exact) {
+	if (!isObject(exact) || hasUnknownExactKeys(exact) || !isString(exact.num) || !isString(exact.den) || !INTEGER.test(exact.num) || !/^\d+$/.test(exact.den) || /^0+$/.test(exact.den)) return exact
+	const { num, den } = mul({ num: BigInt(exact.num), den: BigInt(exact.den) }, 1n)
+	return { num: String(num), den: String(den) }
+}
+
+const readDecimal = (value) => (isDecimal(value) ? value.replace(/^(-?)0+(?=\d)/, "$1") : value)
+
+/** A source unit read through the alias table; unknown, scaled, or unparseable text stays as given. */
+export function sourceUnit(unit) {
+	try {
+		const canonical = canonicalUnit(unit)
+		return isString(canonical) && !inputScale(unit) ? canonical : unit
+	} catch (error) {
+		if (error instanceof RuleError) return unit
+		throw error
+	}
+}
+
+/**
+ * A row as every reader sees it (dimension 31 wins at read time): rows not written by derive in this
+ * version get reduced exacts and decimals; source rows also get canonical units and null later columns.
+ * Current derived rows stay as stored so tampering is still detected. Idempotent.
+ */
+export function readRow(row) {
+	if (!isObject(row) || !Object.hasOwn(KIND_RULES, row.kind) || isCurrentDerived(row)) return row
+	const read = { ...row, value: readDecimal(row.value), exact: exactComesFromValue(row.kind) ? row.exact : readExact(row.exact) }
+	if (DERIVED_KINDS.includes(row.kind)) return read
+	read.unit = sourceUnit(row.unit)
+	for (const column of LATER_COLUMNS) if (!Object.hasOwn(read, column)) read[column] = null
+	return read
+}
+
+const carriesDerivation = (row) => row.operation !== null || row.operands?.length || row.derived_from?.length || row.formula !== null || row.factor !== null
+
+/** Dimension 32: a stored exact must equal the row's own value at the value's decimal places. */
+function valueExactDisagreement(row) {
+	const exact = readExact(row.exact)
+	const value = readDecimal(row.value)
+	if (!isRational(exact) || !isDecimal(value) || roundPlaces(toBig(exact), placesOf(value)) === value) return null
+	return `value ${value} disagrees with exact ${exact.num}/${exact.den} at ${placesOf(value)} decimal places`
+}
+function unitFlaw(unit) {
+	try {
+		return isString(unit) && (canonicalUnit(unit) !== unit || inputScale(unit)) ? `unit ${unit} has no canonical stored text` : null
+	} catch (error) {
+		if (error instanceof RuleError) return `unit ${unit}: ${error.message}`
+		throw error
+	}
+}
+
+/**
+ * What a loadable source row (read through readRow) still breaks under the strict dimensions: dev's
+ * writer accepted it, so it loads, but derive and recompute refuse it as an operand with this shape.
+ * addRow refuses a new row that has any. Empty for derived and converted rows.
+ */
+export function readFlaws(row) {
+	if (!isObject(row) || DERIVED_KINDS.includes(row.kind)) return []
+	const flaws = []
+	if (carriesDerivation(row)) flaws.push({ shape: "dimension 1", detail: "a source row carries an operation or derivation fields", expected: "null operation and empty derivation fields on measured, quote, and assumed rows" })
+	const unit = unitFlaw(row.unit)
+	if (unit) flaws.push({ shape: "dimension 6", detail: unit, expected: "a registered or canonical unit without scale" })
+	for (const detail of metadataErrors(row)) flaws.push({ shape: "dimension 18", detail, expected: "present, type-valid metadata; explicit null when unknown" })
+	const unknownKeys = hasUnknownExactKeys(row.exact)
+	const disagreement = unknownKeys ? null : valueExactDisagreement(row)
+	if (unknownKeys) flaws.push({ shape: "dimension 7", detail: `exact has unknown keys: ${Object.keys(row.exact).filter((key) => key !== "num" && key !== "den").join(", ")}`, expected: "an exact with exactly num and den (the stored row is kept as written)" })
+	if (disagreement) flaws.push({ shape: "dimension 32", detail: disagreement, expected: "an exact equal to value at the value's decimal places" })
+	return flaws
+}
+
+/** @returns {string[]} every per-kind column error of one row; empty for an unknown kind. */
+export function kindRuleErrors(candidate, at) {
+	const rules = KIND_RULES[candidate.kind]
+	if (rules === undefined) return []
+	const errors = []
+	const legacy = isLegacyDerived(candidate)
+	const columns = legacy ? PRE_REGISTRY_COLUMNS : isCurrentDerived(candidate) ? KIND_COLUMNS : KIND_COLUMNS.filter((column) => column !== "operation")
+	for (const column of columns) {
+		const value = candidate[column] === undefined && LATER_COLUMNS.includes(column) ? null : candidate[column]
+		const rule = RULES[legacy && column === "exact" ? "rational_or_null" : rules[column]]
+		// An exact with unknown keys loads as written (never stripped); readFlaws refuses it at use and at write.
+		if (column === "exact" && hasUnknownExactKeys(value) && !isCurrentDerived(candidate)) continue
+		if (rule.test(value, candidate)) continue
+		errors.push(`${at}.${column} must be ${rule.says} for a ${candidate.kind} row`)
+		if (rule.detail) errors.push(...rule.detail(value, `${at}.${column}`))
+	}
+	return errors
+}
+
+/** At-rest rules of current derived rows; source rows answer to readFlaws at use and at write instead. */
+export function storedErrors(row) {
+	if (!isCurrentDerived(row)) return []
+	const errors = metadataErrors(row)
+	try {
+		if (canonicalUnit(row.unit) !== row.unit || inputScale(row.unit)) errors.push("unit must be canonical stored text")
+	} catch (error) { errors.push(error.message) }
+	return errors
+}
+
+export const KIND_TABLE_BEGIN = "<!-- kind-rules:begin (rendered from KIND_RULES; do not edit by hand) -->"
+export const KIND_TABLE_END = "<!-- kind-rules:end -->"
+
+/** The grammar's per-kind Markdown table, one line per column, ending in a newline. */
+export function renderKindTable() {
+	const kinds = Object.keys(KIND_RULES)
+	const lines = [`| field | ${kinds.join(" | ")} |`, `|${"---|".repeat(kinds.length + 1)}`]
+	for (const column of KIND_COLUMNS) lines.push(`| \`${column}\` | ${kinds.map((kind) => RULES[KIND_RULES[kind][column]].cell).join(" | ")} |`)
+	return `${lines.join("\n")}\n`
+}
+
+if (isCliEntry(import.meta.url)) {
+	if (process.argv[2] === "--render-grammar" && process.argv.length === 3) process.stdout.write(renderKindTable())
+	else {
+		process.stderr.write("usage: node fact-ledger-kinds.mjs --render-grammar\n")
+		process.exitCode = 2
+	}
+}

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

@@ -0,0 +1,156 @@
+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) => exactFromDecimal(decimal(random))
+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: rational, invalid: (r) => pick(r, [null, { num: "1", den: "0" }, { num: "x", den: "2" }, "1/2"]) },
+	context_by_derive: { valid: (_r, row) => row.kind === "converted" ? { target: "km" } : null, invalid: (r) => pick(r, ["km", 3, ["km"], false]) },
+	derived_operation: { valid: () => "expr", invalid: (r) => pick(r, [null, "convert", "mean"]) },
+	convert_operation: { valid: () => "convert", invalid: (r) => pick(r, [null, "sum", "mean"]) },
+	precision: { valid: () => ({ places: 2, sigfigs: 3 }), invalid: (r) => pick(r, [null, { places: -1, sigfigs: 3 }, { places: 2, sigfigs: 0 }]) },
+	compatibility: { valid: (_r, row) => row.operation === "expr" ? "unchecked" : "checked", invalid: () => "invalid" },
+}
+
+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" }
+	if (kind === "derived" || kind === "converted") Object.assign(row, { operands: ["F1000"], derived_from: ["F1000"], formula: "F1000", render: "raw" })
+	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, { ...validRow("measured", prng(42)), fact_id: "F1000", label: "dependency" }], 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 r6 LOW 3: context is a derived or converted column; a measured, quote, or assumed row carrying one is rejected", () => {
+		for (const kind of ["measured", "quote", "assumed"]) {
+			const row = { ...validRow(kind, prng(3)), context: { target: "km" } }
+			expect({ kind, named: validateLedger(ledgerOf(row)).some((error: string) => error.startsWith("rows[0].context")) }).toEqual({ kind, named: true })
+		}
+		expect(validateLedger(ledgerOf(validRow("converted", prng(4))))).toEqual([])
+		expect(validateLedger(ledgerOf({ ...validRow("derived", prng(4)), context: { target: "km" } })).length).toBeGreaterThan(0)
+	})
+
+	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-legacy.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { copyFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { derive, recompute } from "./fact-derive.mjs"
+import { LEDGER_FILENAME, addRow, emptyLedger, readLedger, validateLedger, writeLedger } from "./fact-ledger.mjs"
+
+// Generated by dev's own addRow (tests/fixtures/fidelity/gen-legacy-dev.mjs pins the dev commit):
+// no context/precision/compatibility columns, alias units, unreduced and zero-padded exacts.
+const FIXTURE = join(import.meta.dir, "tests", "fixtures", "fidelity", "ledger-legacy-dev.json")
+const SOURCE_IDS = ["F1", "F2", "F3", "F4", "F5", "F6", "F7", "F8", "Q1", "F9", "F10", "F11", "F12", "F13", "F16", "F17", "F18"]
+
+type Row = Record<string, unknown>
+type Ledger = { schemaVersion: number; rows: Row[]; events: unknown[] }
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "ulw-legacy-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
+}
+
+const fixture = (): Ledger => JSON.parse(readFileSync(FIXTURE, "utf8"))
+const rowOf = (ledger: Ledger, id: string): Row => ledger.rows.find((row) => row.fact_id === id) as Row
+
+function loaded(): { dir: string; ledger: Ledger } {
+	const dir = tempDir()
+	copyFileSync(FIXTURE, join(dir, LEDGER_FILENAME))
+	return { dir, ledger: readLedger(dir) as Ledger }
+}
+
+describe("ledgers written by dev's writer (dimension 31 wins at read time)", () => {
+	test("#given dev's generated ledger #when validated #then it has no errors", () => {
+		expect(validateLedger(fixture())).toEqual([])
+	})
+
+	test("#given dev's ledger #when read #then exacts, decimals, and source units are normalized", () => {
+		const { ledger } = loaded()
+		expect(["F1", "F3", "F4", "F5", "F6", "F8", "F11"].map((id) => rowOf(ledger, id).unit)).toEqual(["km", "%", "%p", "person", "KRW-e3", "%", "km"])
+		const exacts = Object.fromEntries(["F10", "F11", "F12", "F13", "F14", "F15", "F18"].map((id) => [id, rowOf(ledger, id).exact]))
+		expect(exacts).toEqual({ F10: { num: "1", den: "1" }, F11: { num: "5", den: "2" }, F12: { num: "7", den: "1" }, F13: { num: "-5", den: "2" }, F14: { num: "41", den: "2" }, F15: { num: "12000", den: "1" }, F18: { num: "3", den: "1", note: "from the brief" } })
+		expect(rowOf(ledger, "F7").value).toBe("7")
+		for (const id of SOURCE_IDS) {
+			for (const column of ["context", "precision", "compatibility"]) expect(rowOf(ledger, id)[column]).toBeNull()
+		}
+		for (const id of ["F14", "F15"]) expect(Object.hasOwn(rowOf(ledger, id), "precision")).toBe(false)
+		expect(validateLedger(ledger)).toEqual([])
+	})
+
+	test("#given dev's ledger #when measured rows are summed #then the new row is canonical and recomputes", () => {
+		for (const ledger of [fixture(), loaded().ledger]) {
+			const result = derive(ledger, { op: "sum", operands: ["F1", "F2"], unit: "km" })
+			expect(result.error).toBeUndefined()
+			expect(result.row).toMatchObject({ kind: "derived", unit: "km", value: "21", exact: { num: "41", den: "2" }, compatibility: "checked" })
+			const padded = derive(ledger, { op: "sum", operands: ["F1", "F7"], unit: "km" })
+			expect(padded.row).toMatchObject({ value: "19", exact: { num: "19", den: "1" } })
+			expect(validateLedger(ledger)).toEqual([])
+			expect(recompute(ledger, result.row).ok).toBe(true)
+		}
+	})
+
+	test("#given a legacy derived or converted row #when recomputed #then it reports a legacy derived row", () => {
+		for (const ledger of [fixture(), loaded().ledger]) {
+			for (const id of ["F14", "F15"]) {
+				const result = recompute(ledger, rowOf(ledger, id))
+				expect(result.ok).toBe(false)
+				expect(result.shape).toBe("legacy derived row")
+			}
+		}
+	})
+
+	test("#given a legacy derived or converted row #when used as an operand #then derive refuses it", () => {
+		const ledger = fixture()
+		const before = ledger.rows.length
+		for (const id of ["F14", "F15"]) {
+			const result = derive(ledger, { op: "sum", operands: [id, "F2"], unit: "km" })
+			expect(result.error).toBe("incompatible_operands")
+			expect(result.shape).toBe("legacy derived row")
+		}
+		expect(ledger.rows.length).toBe(before)
+	})
+
+	test("#given a loadable row the strict dimensions reject #when used as an operand #then it is flagged by dimension", () => {
+		const ledger = loaded().ledger
+		const before = ledger.rows.length
+		for (const [id, shape] of [["F16", "dimension 18"], ["F17", "dimension 1"]]) {
+			const result = derive(ledger, { op: "sum", operands: [id, "F2"], unit: "km" })
+			expect(result.error).toBe("incompatible_operands")
+			expect(result.shape).toBe(shape)
+		}
+		expect(ledger.rows.length).toBe(before)
+	})
+
+	test("#given a new source row with a flaw dev accepted #when added #then this version's writer refuses it", () => {
+		const ledger = fixture()
+		const blank = { ...rowOf(ledger, "F16"), fact_id: undefined, label: "blank-again" }
+		expect(() => addRow(ledger, blank)).toThrow("dimension 18")
+	})
+
+	test("#given dev's ledger #when read and written twice #then the second pass changes nothing", () => {
+		const { dir, ledger } = loaded()
+		writeLedger(dir, ledger)
+		const once = readFileSync(join(dir, LEDGER_FILENAME), "utf8")
+		const written = JSON.parse(once) as Ledger
+		expect(rowOf(written, "F11").exact).toEqual({ num: "5", den: "2" })
+		expect(Object.hasOwn(rowOf(written, "F14"), "precision")).toBe(false)
+		writeLedger(dir, readLedger(dir))
+		expect(readFileSync(join(dir, LEDGER_FILENAME), "utf8")).toBe(once)
+		expect(readLedger(dir)).toEqual(written)
+	})
+
+	test("#given a current derived row with its later columns stripped #when validated #then it reads as legacy and never recomputes", () => {
+		const ledger = fixture()
+		const made = derive(ledger, { op: "sum", operands: ["F1", "F2"], unit: "km" }).row as Row
+		const stripped = rowOf(ledger, made.fact_id as string)
+		for (const column of ["context", "precision", "compatibility"]) delete stripped[column]
+		stripped.unit = "kilometers"
+		expect(validateLedger(ledger)).toEqual([])
+		expect(recompute(ledger, stripped).shape).toBe("legacy derived row")
+	})
+
+	test("#given a ledger written by this version #when read and written #then it is unchanged", () => {
+		const dir = tempDir()
+		const ledger = emptyLedger() as Ledger
+		const source = { kind: "measured", raw: "", quote: "", source_id: "S1", locator: { artifact: "sources/S1/text.txt", char_start: 0, char_end: 4 }, snapshot_sha256: "b".repeat(64), extracted_by: "fact add --find", observed_at: "2026-10-23T08:00:00Z" }
+		addRow(ledger, { ...source, value: "3", unit: "kilometers", label: "a" })
+		addRow(ledger, { ...source, value: "4", unit: "km", label: "b" })
+		expect(derive(ledger, { op: "sum", operands: ["F1", "F2"], unit: "km" }).error).toBeUndefined()
+		writeLedger(dir, ledger)
+		const first = readFileSync(join(dir, LEDGER_FILENAME), "utf8")
+		writeLedger(dir, readLedger(dir))
+		expect(readFileSync(join(dir, LEDGER_FILENAME), "utf8")).toBe(first)
+		expect(readLedger(dir)).toEqual(JSON.parse(first))
+	})
+
+	test("#given a legacy exact with an unknown key #when read and written #then the key survives and the row is refused as an operand", () => {
+		const { dir, ledger } = loaded()
+		writeLedger(dir, ledger)
+		const written = JSON.parse(readFileSync(join(dir, LEDGER_FILENAME), "utf8")) as Ledger
+		expect(rowOf(written, "F18").exact).toEqual({ num: "3", den: "1", note: "from the brief" })
+		const result = derive(ledger, { op: "sum", operands: ["F18", "F2"], unit: "km" })
+		expect(result.error).toBe("incompatible_operands")
+		expect(result.shape).toBe("dimension 7")
+		expect(recompute(ledger, rowOf(ledger, "F18")).ok).toBe(false)
+	})
+
+	test("#given an assumed row whose value and exact disagree #when read #then it loads flagged and a new row is refused (dimension 32)", () => {
+		const dir = tempDir()
+		const seed = fixture()
+		const mismatched = { ...rowOf(seed, "F11"), fact_id: "F19", label: "mismatched-exact", unit: "km", value: "1.5", exact: { num: "3", den: "1" } }
+		seed.rows.push(mismatched)
+		writeFileSync(join(dir, LEDGER_FILENAME), JSON.stringify(seed))
+		const ledger = readLedger(dir) as Ledger
+		expect(rowOf(ledger, "F19").value).toBe("1.5")
+		const result = derive(ledger, { op: "sum", operands: ["F19", "F2"], unit: "km" })
+		expect(result.error).toBe("incompatible_operands")
+		expect(result.shape).toBe("dimension 32")
+		expect(() => addRow(ledger, { ...mismatched, fact_id: undefined, label: "mismatch-new" })).toThrow("dimension 32")
+	})
+})