lazycodex-ai 5.1.45 → 5.1.46

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

@@ -31,7 +31,7 @@ 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 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("")
 
@@ -60,11 +60,17 @@ const GENERATORS: Record<string, Gen> = {
 		},
 	},
 	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"]) },
+	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
 }
 
@@ -75,7 +81,7 @@ function validRow(kind: string, random: Random) {
 	return row
 }
 
-const ledgerOf = (row: object) => ({ schemaVersion: LEDGER_SCHEMA_VERSION, rows: [row], events: [] })
+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", () => {
@@ -116,6 +122,15 @@ describe("rows generated from KIND_RULES", () => {
 		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)

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")
+	})
+})

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

@@ -4,7 +4,8 @@
 // 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"
+import { DECIMAL, isCount, isCurrentDerived, isNonEmpty, isObject, isString, kindRuleErrors, LATER_COLUMNS, readRow, storedErrors } from "./fact-ledger-kinds.mjs"
+import { malformed } from "./unit-rules.mjs"
 
 export { DECIMAL, isNonEmpty, isString } from "./fact-ledger-kinds.mjs"
 
@@ -50,8 +51,13 @@ export const ROW_DEFAULTS = Object.freeze({
 	formula: null,
 	factor: null,
 	rationale: null,
+	context: null,
+	precision: null,
+	compatibility: null,
 	status: "active",
 })
+/** Fields added after schema version 1 shipped: written on every new row, optional when reading an older ledger. */
+const OPTIONAL_FIELDS = new Set(LATER_COLUMNS)
 const REQUIRED = ["fact_id", "kind", "raw", "quote", "extracted_by", "observed_at", "label"]
 export const ROW_FIELDS = Object.freeze([...REQUIRED, ...Object.keys(ROW_DEFAULTS)])
 
@@ -70,10 +76,16 @@ function nullOr(value, test) {
 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 ROW_FIELDS) check(errors, OPTIONAL_FIELDS.has(key) || Object.hasOwn(row, key), `${at}.${key} is required`)
 	for (const key of Object.keys(row)) check(errors, ROW_FIELDS.includes(key), `${at}.${key} is not a ledger field`)
 	check(errors, FACT_KINDS.includes(row.kind), `${at}.kind must be one of ${FACT_KINDS.join(", ")}`)
-	errors.push(...kindRuleErrors(row, at))
+	// Dimension 31 wins at read time: per-kind rules see the row as readRow normalizes it.
+	errors.push(...kindRuleErrors(readRow(row), at))
+	errors.push(...storedErrors(row).map((e) => `${at}.${e}`))
+	if (isCurrentDerived(row)) {
+		const problem = malformed(row)
+		if (problem) errors.push(`${at}: ${problem}`)
+	}
 	check(errors, row.unit === undefined || nullOr(row.unit, isNonEmpty), `${at}.unit must be null or a non-empty token`)
 	for (const key of ["raw", "quote"]) check(errors, row[key] === undefined || isString(row[key]), `${at}.${key} must be a string`)
 	check(errors, row.extracted_by === undefined || isNonEmpty(row.extracted_by), `${at}.extracted_by must be a non-empty string`)
@@ -100,6 +112,12 @@ function validateRow(row, index, errors) {
 	check(errors, row.status === undefined || FACT_STATUSES.includes(row.status), `${at}.status must be one of ${FACT_STATUSES.join(", ")}`)
 }
 
+export function rowErrors(row) {
+	const errors = []
+	validateRow(row, 0, errors)
+	return errors
+}
+
 // The status machine and event rule of references/fact-ledger-grammar.md. validateLedger replays
 // events through transitionError, and every writer in fact-ledger.mjs calls it before appending.
 export const TRANSITIONS = Object.freeze({ active: Object.freeze(["retracted", "superseded"]), retracted: Object.freeze([]), superseded: Object.freeze([]) })
@@ -163,20 +181,19 @@ export function provenanceErrors(rows) {
 		}
 	})
 	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
+	for (const root of refs.keys()) {
+		const stack = [{ id: root, finish: false }]
+		const path = []
+		while (stack.length) {
+			const { id, finish } = stack.pop()
+			if (state.get(id) === "done") continue
+			if (finish) { state.set(id, "done"); path.pop(); continue }
+			if (state.get(id) === "open") return [...errors, `${id} derives from itself through cycle ${[...path, id].join(" -> ")}`]
+			state.set(id, "open")
+			path.push(id)
+			stack.push({ id, finish: true })
+			for (const next of refs.get(id)) if (next !== id && refs.has(next)) stack.push({ id: next, finish: false })
 		}
-		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
 }

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

@@ -7,8 +7,9 @@ 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 { DECIMAL, exactComesFromValue, exactFromDecimal, idPrefix, isString, readFlaws, readRow } from "./fact-ledger-kinds.mjs"
 import { LEDGER_SCHEMA_VERSION, ROW_DEFAULTS, ROW_FIELDS, transitionError, validateLedger } from "./fact-ledger-schema.mjs"
+import { normalizeInput } from "./unit-algebra.mjs"
 
 export { exactFromDecimal } from "./fact-ledger-kinds.mjs"
 export { FACT_KINDS, FACT_STATUSES, LEDGER_SCHEMA_VERSION, OPERATIONS, QUALIFIERS, ROW_FIELDS, TRANSITIONS, transitionError, validateLedger } from "./fact-ledger-schema.mjs"
@@ -24,11 +25,24 @@ function assertValid(ledger) {
 	if (errors.length > 0) throw new CliError(`invalid fact ledger: ${errors.join("; ")}`)
 }
 
+/** The row's fields in ROW_FIELDS order, then any unknown field (which validation reports). */
+function ordered(row) {
+	const out = Object.fromEntries(ROW_FIELDS.filter((key) => Object.hasOwn(row, key)).map((key) => [key, row[key]]))
+	for (const key of Object.keys(row)) if (!ROW_FIELDS.includes(key)) out[key] = row[key]
+	return out
+}
+
+/**
+ * Every row comes back as readRow normalizes it (reduced exacts and decimals; source rows with canonical
+ * units and null later columns) before any strict rule runs; the file changes on the next write.
+ */
 export function readLedger(dir) {
 	const file = join(dir, LEDGER_FILENAME)
 	if (!existsSync(file)) return emptyLedger()
 	const ledger = readJsonFile(file)
 	assertValid(ledger)
+	ledger.rows = ledger.rows.map((row) => ordered(readRow(row)))
+	assertValid(ledger)
 	return ledger
 }
 
@@ -44,12 +58,12 @@ 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
+	let max = 0n
 	for (const row of ledger.rows) {
 		const match = ID_NUMBER[prefix].exec(row.fact_id ?? "")
-		if (match) max = Math.max(max, Number(match[1]))
+		if (match && BigInt(match[1]) > max) max = BigInt(match[1])
 	}
-	return `${prefix}${max + 1}`
+	return `${prefix}${max + 1n}`
 }
 
 /**
@@ -60,14 +74,20 @@ export function nextId(ledger, kind) {
  */
 export function addRow(ledger, row) {
 	const filled = { ...structuredClone(ROW_DEFAULTS), ...row, fact_id: row.fact_id ?? nextId(ledger, row.kind) }
+	if (!["derived", "converted"].includes(filled.kind)) {
+		const normalized = normalizeInput(filled.unit, filled.value)
+		if (normalized.value !== filled.value && filled.exact !== null) throw new CliError("scaled input must omit exact; it is computed after normalization")
+		Object.assign(filled, readRow({ ...filled, ...normalized }))
+	}
 	if (exactComesFromValue(filled.kind) && filled.exact === null && isString(filled.value) && DECIMAL.test(filled.value)) {
 		filled.exact = exactFromDecimal(filled.value)
 	}
-	const 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
+	const added = ordered(filled)
+	const flaws = readFlaws(added)
+	if (flaws.length > 0) throw new CliError(`invalid fact ledger: ${flaws.map((flaw) => `${flaw.shape}: ${flaw.detail}`).join("; ")}`)
+	assertValid({ ...ledger, rows: [...ledger.rows, added] })
+	ledger.rows.push(added)
+	return added
 }
 
 /** Build the event from the row's current status and append it only if transitionError allows it. */

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

@@ -121,6 +121,7 @@ describe("ids and status", () => {
 			operands: ["F1", "F2"],
 			derived_from: ["F1", "F2"],
 			exact: { num: "1", den: "3" },
+			formula: "F1 / F2", render: "0.333", precision: { places: 3, sigfigs: 3 }, compatibility: "checked",
 		})
 		expect(derived.fact_id).toBe("F3")
 		expect(nextId(ledger, "quote")).toBe("Q2")
@@ -194,6 +195,7 @@ describe("read and write", () => {
 			operands: ["F1", "F2"],
 			derived_from: ["F1", "F2"],
 			exact: { num: "1", den: "3" },
+			formula: "F1 / F2", render: "0.333", precision: { places: 3, sigfigs: 3 }, compatibility: "checked",
 		})
 		writeLedger(dir, ledger)
 		const loaded = readLedger(dir)

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

@@ -0,0 +1,231 @@
+// fact-locate.mjs - deterministic fact locators over a source snapshot.
+//
+// Each locator returns { value, unit, raw, quote, value_span, sentence_id, qualifier, locator } or
+// { error: "fact_not_located" | "fact_ambiguous", candidates }; it never guesses. `quote` is the
+// whole containing sentence, cell, or line of text.txt, `value_span` is [start, end] inside
+// `quote` with quote.slice(...value_span) === raw, and locator.char_start/char_end place `quote`
+// in text.txt. Every call takes `sourceId` (S<n>) so sentence ids match sentences.jsonl.
+// Plain Node ESM, sibling imports only; no network, no OCR.
+
+import { proseText } from "./html-lite.mjs"
+import { QUALIFIERS } from "./lexicon.mjs"
+import { parseNumeral } from "./numerals.mjs"
+import { indexSentences, snapshotBlocks } from "./source-snapshot.mjs"
+import { findNormalized, normalizeText, tokenize } from "./text-normalize.mjs"
+import { similarity } from "./text-similarity.mjs"
+import { normalizeUnit } from "./units.mjs"
+
+const FIND_WINDOW = 80
+const CONTEXT = 60
+const FUZZY_FLOOR = 0.95
+const PHRASES = QUALIFIERS.map((phrase) => phrase.split(" "))
+const SINGLE_QUALIFIERS = new Set(QUALIFIERS.filter((phrase) => !phrase.includes(" ")))
+
+const notLocated = (candidates = []) => ({ error: "fact_not_located", candidates })
+const ambiguous = (candidates) => ({ error: "fact_ambiguous", candidates })
+const label = (text) => normalizeText(text).toLowerCase()
+const clean = (token) => token.replace(/^[^\p{L}\p{N}%]+|[^\p{L}\p{N}%]+$/gu, "").toLowerCase()
+const sentenceAt = (sentences, offset) => sentences.find((row) => row.start <= offset && offset < row.end) ?? null
+
+function requireSource(sourceId) {
+	if (!/^S[1-9]\d*$/.test(String(sourceId))) throw new TypeError(`sourceId must be S<n>, got ${sourceId}`)
+}
+
+/** Every normalized occurrence of `needle`, as raw [start, end) offsets. */
+function findAll(text, needle) {
+	const hits = []
+	for (let from = 0; from < text.length; ) {
+		const hit = findNormalized(text.slice(from), needle)
+		if (!hit) break
+		hits.push({ start: from + hit.start, end: from + hit.end })
+		from += hit.start + 1
+	}
+	return hits
+}
+
+function locatorFor(text, sourceId, start, end, extra = {}) {
+	const before = text.slice(0, start)
+	const pageStart = before.lastIndexOf("\f") + 1
+	const page = text.includes("\f") ? { page: before.split("\f").length } : {}
+	return { artifact: `${sourceId}/text.txt`, ...page, line: before.slice(pageStart).split("\n").length, char_start: start, char_end: end, ...extra }
+}
+
+function candidate(text, sentences, start, end) {
+	return { sentence_id: sentenceAt(sentences, start)?.sid ?? null, char_start: start, char_end: end, context: text.slice(Math.max(0, start - CONTEXT), end + CONTEXT) }
+}
+
+/** A QUALIFIERS token ending within the 2 tokens before the value, or the 1 token right after it. */
+function qualifierAround(quote, [start, end]) {
+	const before = quote.slice(0, start).split(/\s+/).filter(Boolean).map(clean)
+	for (let skip = 0; skip < 2; skip++) {
+		for (const words of PHRASES) {
+			const stop = before.length - skip
+			if (stop - words.length >= 0 && before.slice(stop - words.length, stop).join(" ") === words.join(" ")) return words.join(" ")
+		}
+	}
+	const next = /^\s*(\S+)/.exec(quote.slice(end))
+	return next && SINGLE_QUALIFIERS.has(clean(next[1])) ? clean(next[1]) : null
+}
+
+/** A located quantity: `holder` is the quote's { sid, start, end, text }, `numeral` is parsed from holder.text. */
+function quantityResult(text, sourceId, holder, numeral, extra = {}, unitFallback = null) {
+	const unit = numeral.unitRaw ? (normalizeUnit(numeral.unitRaw) ?? numeral.unitRaw) : unitFallback
+	return {
+		value: numeral.value,
+		unit,
+		raw: numeral.raw,
+		quote: holder.text,
+		value_span: [numeral.span[0], numeral.span[1]],
+		sentence_id: holder.sid,
+		qualifier: qualifierAround(holder.text, numeral.span),
+		locator: locatorFor(text, sourceId, holder.start, holder.end, extra),
+	}
+}
+
+/** --find: one anchor occurrence, then the first numeral starting within 80 chars after it in the same sentence. */
+export function locateFind(text, { find, unitExpected, sourceId }) {
+	requireSource(sourceId)
+	const sentences = indexSentences(text, sourceId)
+	const hits = findAll(text, find)
+	if (hits.length === 0) return notLocated()
+	if (hits.length > 1) return ambiguous(hits.map((hit) => candidate(text, sentences, hit.start, hit.end)))
+	const [hit] = hits
+	const sentence = sentenceAt(sentences, hit.start)
+	if (!sentence || hit.end > sentence.end) return notLocated()
+	const from = hit.end - sentence.start
+	const numeral = parseNumeral(sentence.text, from)
+	if (!numeral || numeral.span[0] - from > FIND_WINDOW) return notLocated([candidate(text, sentences, hit.start, hit.end)])
+	const result = quantityResult(text, sourceId, sentence, numeral)
+	if (unitExpected === undefined) return result
+	const expected = normalizeUnit(unitExpected) ?? unitExpected
+	return result.unit === expected ? result : { error: "unit_expected_mismatch", expected, found: result.unit, candidates: [result] }
+}
+
+function cellsOf(row) {
+	const cells = []
+	for (const cell of row.children.filter((child) => child.tag === "td" || child.tag === "th")) {
+		const span = Math.max(1, Number.parseInt(cell.attrs.colspan ?? "1", 10) || 1)
+		for (let k = 0; k < span; k++) cells.push(cell)
+	}
+	return cells
+}
+
+function rowsOf(table) {
+	const rows = []
+	const walk = (node) => {
+		for (const child of node.children) {
+			if (child.tag === "tr") rows.push(child)
+			else if (child.tag !== "table" && child.tag !== "#text") walk(child)
+		}
+	}
+	walk(table)
+	return rows
+}
+
+function tablesOf(root) {
+	const tables = []
+	const walk = (node) => {
+		for (const child of node.children) {
+			if (child.tag === "table") tables.push(child)
+			if (child.tag !== "#text") walk(child)
+		}
+	}
+	walk(root)
+	return tables.map((table) => {
+		const rows = rowsOf(table)
+		const header = rows.find((row) => row.children.some((child) => child.tag === "th")) ?? rows[0]
+		const caption = table.children.find((child) => child.tag === "caption")
+		return { table, header, rows: rows.filter((row) => row !== header), caption: caption ? label(proseText(caption)) : null }
+	})
+}
+
+const cellLabel = (cell) => label(proseText(cell))
+const indexesOf = (labels, wanted) => labels.flatMap((value, index) => (value === wanted ? [index] : []))
+
+/** --table/--row/--col: the table by id, caption, or a header label; row and column by normalized label, never by index. */
+export function locateTable(sourceHtml, { table, row, col, sourceId }) {
+	requireSource(sourceId)
+	const { root, text, blocks } = snapshotBlocks(sourceHtml)
+	const key = label(table)
+	const tables = tablesOf(root).filter((entry) => entry.table.attrs.id === table || entry.caption === key || (entry.header && cellsOf(entry.header).map(cellLabel).includes(key)))
+	if (tables.length !== 1) return tables.length === 0 ? notLocated() : ambiguous(tables.map((entry) => ({ table: entry.table.attrs.id ?? entry.caption })))
+	const [{ header, rows }] = tables
+	const headerCells = header ? cellsOf(header) : []
+	const columns = indexesOf(headerCells.map(cellLabel), label(col))
+	const matches = rows.filter((candidateRow) => cellsOf(candidateRow).length > 0 && cellLabel(cellsOf(candidateRow)[0]) === label(row))
+	if (columns.length > 1 || matches.length > 1) return ambiguous([...columns.map((index) => ({ col: index })), ...matches.map((match) => ({ row_line: match.line }))])
+	const cell = columns.length === 1 && matches.length === 1 ? cellsOf(matches[0])[columns[0]] : null
+	const block = cell ? blocks.find((entry) => entry.node === cell) : null
+	if (!block) return notLocated()
+	const holder = { sid: sentenceAt(indexSentences(text, sourceId), block.start)?.sid ?? null, start: block.start, end: block.end, text: text.slice(block.start, block.end) }
+	const numeral = parseNumeral(holder.text)
+	if (!numeral) return notLocated()
+	const headerUnit = /\(([^()]+)\)\s*$/.exec(cellLabel(headerCells[columns[0]]))
+	return quantityResult(text, sourceId, holder, numeral, { table, row_label: row, col_label: col }, headerUnit ? normalizeUnit(headerUnit[1]) : null)
+}
+
+/** --page/--line: exactly one quantity on that line of that page (pages split on a form feed). */
+export function locatePageLine(text, { page, line, sourceId }) {
+	requireSource(sourceId)
+	const pages = text.split("\f")
+	if (!Number.isInteger(page) || page < 1 || page > pages.length) return notLocated()
+	const lines = pages[page - 1].split("\n")
+	if (!Number.isInteger(line) || line < 1 || line > lines.length) return notLocated()
+	let start = pages.slice(0, page - 1).reduce((sum, body) => sum + body.length + 1, 0)
+	for (const body of lines.slice(0, line - 1)) start += body.length + 1
+	const holder = { start, end: start + lines[line - 1].length, text: lines[line - 1] }
+	const numerals = []
+	for (let numeral = parseNumeral(holder.text); numeral; numeral = parseNumeral(holder.text, numeral.span[1])) numerals.push(numeral)
+	const sentences = indexSentences(text, sourceId)
+	if (numerals.length !== 1) return numerals.length === 0 ? notLocated() : ambiguous(numerals.map((numeral) => candidate(text, sentences, start + numeral.span[0], start + numeral.span[1])))
+	holder.sid = sentenceAt(sentences, start + numerals[0].span[0])?.sid ?? null
+	return quantityResult(text, sourceId, holder, numerals[0])
+}
+
+/** Token-aligned windows of `sentence` whose similarity to `match` reaches the fuzzy floor; best first. */
+function fuzzyWindow(sentence, match) {
+	const target = normalizeText(match).length
+	const wanted = new Set(tokenize(match))
+	const present = new Set(tokenize(sentence.text))
+	if (wanted.size === 0 || [...wanted].filter((token) => present.has(token)).length / wanted.size < 0.5) return null
+	const bounds = [...sentence.text.matchAll(/[\p{L}\p{N}]+/gu)].map((m) => [m.index, m.index + m[0].length])
+	let best = null
+	for (let i = 0; i < bounds.length; i++) {
+		for (let j = i; j < bounds.length; j++) {
+			const window = sentence.text.slice(bounds[i][0], bounds[j][1])
+			if (window.length > target * 1.06 + 2) break
+			if (window.length < target * 0.94 - 2) continue
+			const score = similarity(window, match)
+			if (score >= FUZZY_FLOOR && (!best || score > best.score)) best = { score, start: sentence.start + bounds[i][0], end: sentence.start + bounds[j][1] }
+		}
+	}
+	return best
+}
+
+function quoteResult(text, sourceId, sentences, start, end, fuzzy) {
+	const first = sentenceAt(sentences, start)
+	const last = sentenceAt(sentences, end - 1) ?? first
+	return {
+		value: null,
+		unit: null,
+		raw: text.slice(start, end),
+		quote: text.slice(first.start, last.end),
+		value_span: null,
+		sentence_id: first.sid,
+		qualifier: null,
+		fuzzy,
+		locator: locatorFor(text, sourceId, first.start, last.end),
+	}
+}
+
+/** --match: a normalized exact match (fuzzy false), else the one window with similarity >= 0.95 (fuzzy true). */
+export function locateMatch(text, { match, sourceId }) {
+	requireSource(sourceId)
+	const sentences = indexSentences(text, sourceId)
+	const hits = findAll(text, match)
+	if (hits.length > 1) return ambiguous(hits.map((hit) => candidate(text, sentences, hit.start, hit.end)))
+	if (hits.length === 1) return quoteResult(text, sourceId, sentences, hits[0].start, hits[0].end, false)
+	const windows = sentences.map((sentence) => fuzzyWindow(sentence, match)).filter(Boolean)
+	if (windows.length > 1) return ambiguous(windows.map((window) => candidate(text, sentences, window.start, window.end)))
+	return windows.length === 1 ? quoteResult(text, sourceId, sentences, windows[0].start, windows[0].end, true) : notLocated()
+}