lazycodex-ai 5.1.45 → 5.1.46

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

@@ -0,0 +1,388 @@
+import { describe, expect, test } from "bun:test"
+
+import { derive, display, recompute } from "./fact-derive.mjs"
+import { parseExpr } from "./fact-expr.mjs"
+import { addRow, emptyLedger, OPERATIONS } from "./fact-ledger.mjs"
+import { canonicalUnit, expectedUnit, isAffine, OPERATION_RULES, renderPrecision } from "./unit-rules.mjs"
+
+// Property checks of references/unit-rules.md: every case table below is keyed by the registry's own operation list,
+// so a new operation without valid, relabel, and malformed cases fails here.
+
+type Row = Record<string, unknown>
+type Ledger = { schemaVersion: number; rows: Row[]; events: unknown[] }
+type Spec = Record<string, unknown>
+
+const HASH = "a".repeat(64)
+
+function measured(factId: string, value: string, unit: string | null, extra: Row = {}): Row {
+	return {
+		fact_id: factId,
+		kind: "measured",
+		value,
+		unit,
+		raw: `${value} ${unit ?? ""}`.trim(),
+		quote: `The figure is ${value}.`,
+		source_id: "S1",
+		locator: { artifact: "sources/S1/text.txt", char_start: 0, char_end: 20 },
+		snapshot_sha256: HASH,
+		extracted_by: "fact add --find",
+		observed_at: "2026-10-23T08:00:00Z",
+		label: factId.toLowerCase(),
+		...extra,
+	}
+}
+
+function ledger(): Ledger {
+	const built = emptyLedger() as Ledger
+	const rows = [
+		measured("F1", "1", "m"),
+		measured("F2", "3", "m"),
+		measured("F3", "20", "%"),
+		measured("F4", "15", "%"),
+		measured("F5", "5", "%p"),
+		measured("F6", "100", "case", { valid_at: "2025", entity: "acme" }),
+		measured("F7", "112", "case", { valid_at: "2026", entity: "acme" }),
+		measured("F8", "40", "person"),
+		measured("F9", "200", "person"),
+		measured("F10", "100", "USD"),
+		measured("F11", "20", "USD/person"),
+		measured("F12", "0", "m"),
+		measured("F13", "25", "C", { valid_at: "2025", entity: "x" }),
+		measured("F14", "30", "C", { valid_at: "2026", entity: "x" }),
+		measured("F15", "0", "person"),
+		measured("F16", "2.5", "kilometre"),
+		measured("F17", "120", "case", { valid_at: "2026", entity: "other" }),
+		measured("F18", "0", "case", { valid_at: "2025", entity: "acme" }),
+		measured("F19", "-5", "person"),
+		measured("F20", "2", "%p"),
+		measured("F21", "105", "case", { valid_at: "2025", entity: "acme" }),
+		measured("F22", "200", "person"),
+	]
+	for (const row of rows) addRow(built, row)
+	return built
+}
+
+const PCT_SUM = { op: "sum", operands: ["F3", "F4"], unit: "%", disjoint: true, reference: "all respondents", rationale: "disjoint answer shares" }
+
+const VALID: Record<string, Array<{ spec: Spec; unit: string | null; precision?: "places" | "sigfigs" }>> = {
+	sum: [
+		{ spec: { op: "sum", operands: ["F1", "F2"], unit: "m" }, unit: "m" },
+		{ spec: { op: "sum", operands: ["F1", "F2"], unit: "metre" }, unit: "m" },
+		{ spec: PCT_SUM, unit: "%" },
+	],
+	diff: [
+		{ spec: { op: "diff", operands: ["F2", "F1"], unit: "m" }, unit: "m" },
+		{ spec: { op: "diff", operands: ["F3", "F4"], unit: "pp" }, unit: "%p" },
+		{ spec: { op: "diff", operands: ["F3", "F5"], unit: "%" }, unit: "%" },
+		{ spec: { op: "diff", operands: ["F5", "F20"], unit: "%p" }, unit: "%p" },
+	],
+	growth: [{ spec: { op: "growth", from: "F6", to: "F7", unit: "%" }, unit: "%" }],
+	share: [
+		{ spec: { op: "share", part: "F8", whole: "F9", unit: "%" }, unit: "%" },
+		{ spec: { op: "share", part: "F22", whole: "F9", unit: "%" }, unit: "%" },
+	],
+	ratio: [
+		{ spec: { op: "ratio", num: "F10", den: "F11", unit: "person" }, unit: "person" },
+		{ spec: { op: "ratio", num: "F1", den: "F2", unit: null }, unit: null },
+		{ spec: { op: "ratio", num: "F10", den: "F9", unit: "USD/person" }, unit: "USD/person" },
+	],
+	convert: [
+		{ spec: { op: "convert", operands: ["F12"], to: "km" }, unit: "km" },
+		{ spec: { op: "convert", operands: ["F16"], to: "m" }, unit: "m" },
+		{ spec: { op: "convert", operands: ["F2"], to: "kilometre" }, unit: "km" },
+	],
+	expr: [
+		{ spec: { op: "expr", formula: "F3 - F4", unit: "%p" }, unit: "%p", precision: "places" },
+		{ spec: { op: "expr", formula: "F2 - F1", unit: "m" }, unit: "m", precision: "places" },
+		{ spec: { op: "expr", formula: "F5", unit: "%p" }, unit: "%p", precision: "places" },
+		{ spec: { op: "expr", formula: "F1 * F1 / F2", unit: "m" }, unit: "m" },
+		{ spec: { op: "expr", formula: "F10 / F11", unit: "person" }, unit: "person" },
+		{ spec: { op: "expr", formula: "pct(F8 / F9)", unit: "%" }, unit: "%" },
+		{ spec: { op: "expr", formula: "F3 * F9", unit: "person" }, unit: "person" },
+	],
+}
+
+/** Invariant 5 per operation: sum and diff render by decimal places, the rest by significant figures (expr cases override). */
+const PRECISION: Record<string, "places" | "sigfigs"> = { sum: "places", diff: "places", growth: "sigfigs", share: "sigfigs", ratio: "sigfigs", convert: "sigfigs", expr: "sigfigs" }
+
+const RELABELS = [null, "%", "%p", "pp", "bp", "m", "metre", "km", "kilometre", "cm", "C", "case", "person", "USD", "USD/person", "person/USD", "KRW-e8"]
+
+type Mutation = { name: string; base: Spec; mutate: (row: Row, book: Ledger) => Row; reason: string }
+const generic = (base: Spec, arity: string[], arityReason = "takes ", missingReason = "no ledger row F999"): Mutation[] => [
+	{ name: "operands null", base, mutate: (row) => ({ ...row, operands: null }), reason: "operands must be a non-empty array" },
+	{ name: "operands empty", base, mutate: (row) => ({ ...row, operands: [] }), reason: "operands must be a non-empty array" },
+	{ name: "wrong arity", base, mutate: (row) => ({ ...row, operands: arity }), reason: arityReason },
+	{ name: "missing operand id", base, mutate: (row) => ({ ...row, operands: (row.operands as string[]).map((id, index) => (index === 0 ? "F999" : id)) }), reason: missingReason },
+	{ name: "invalid rational", base, mutate: (row) => ({ ...row, exact: { num: "x", den: "1" } }), reason: "exact must be { num, den }" },
+	{ name: "no operation", base, mutate: (row) => ({ ...row, operation: "mean" }), reason: 'operation "mean" is not one of' },
+	{ name: "repeated operand", base, mutate: (row) => ({ ...row, operands: repeatFirst(row.operands as string[]) }), reason: "is repeated" },
+	{ name: "self reference", base, mutate: (row) => ({ ...row, operands: (row.operands as string[]).map((id, index) => (index === 0 ? row.fact_id : id)) }), reason: "cites itself" },
+	{ name: "kind operation", base, mutate: (row) => ({ ...row, kind: "assumed" }), reason: "kind assumed" },
+	{ name: "audit fields", base, mutate: (row) => ({ ...row, factor: "999" }), reason: "factor" },
+	{ name: "precision field", base, mutate: (row) => ({ ...row, precision: { places: -1, sigfigs: 0 } }), reason: "precision" },
+	{ name: "compatibility field", base, mutate: (row) => ({ ...row, compatibility: "invalid" }), reason: "compatibility" },
+	{ name: "metadata fields", base, mutate: (row) => ({ ...row, population: { tampered: true } }), reason: "population" },
+	{ name: "noncanonical operand", base, mutate: (row, book) => {
+		const operand = book.rows.find((r) => r.fact_id === (row.operands as string[])[0])
+		if (!operand) throw Error("fixture operand missing")
+		operand.unit = `${operand.unit}*bp/%p`
+		return row
+	}, reason: "canonical" },
+]
+/** The first operand id in a second slot: [F1, F2] -> [F1, F1]; a one-operand row gets [F1, F1]. */
+const repeatFirst = (ids: string[]) => (ids.length === 1 ? [ids[0], ids[0]] : [...ids.slice(0, -1), ids[0]])
+const operands = (ids: string[]) => (row: Row) => ({ ...row, operands: ids })
+
+const MALFORMED: Record<string, Mutation[]> = {
+	sum: [
+		...generic(VALID.sum[0].spec, ["F1"]),
+		{ name: "no context", base: VALID.sum[0].spec, mutate: (row) => ({ ...row, context: null }), reason: "sum rows carry a context object" },
+		{ name: "% without disjoint", base: PCT_SUM, mutate: (row) => ({ ...row, context: { disjoint: false, reference: "all respondents" } }), reason: "needs disjoint shares" },
+		{ name: "% without reference", base: PCT_SUM, mutate: (row) => ({ ...row, context: { disjoint: true, reference: null } }), reason: "one shared reference" },
+		{ name: "% without rationale", base: PCT_SUM, mutate: (row) => ({ ...row, rationale: null }), reason: "needs a rationale" },
+		{ name: "unequal units", base: VALID.sum[0].spec, mutate: operands(["F1", "F8"]), reason: "unit differs" },
+		{ name: "affine units", base: VALID.sum[0].spec, mutate: operands(["F13", "F14"]), reason: "sum refuses affine" },
+		{ name: "closed context", base: VALID.sum[0].spec, mutate: (row) => ({ ...row, context: { disjoint: "true", reference: 7, extra: true } }), reason: "sum context" },
+		{ name: "share total", base: PCT_SUM, mutate: (row, book) => {
+			for (const operand of book.rows.filter((r) => ["F3", "F4"].includes(String(r.fact_id)))) Object.assign(operand, { value: "60", exact: { num: "60", den: "1" } })
+			return row
+		}, reason: "total <= 100" },
+	],
+	diff: [
+		...generic(VALID.diff[0].spec, ["F2", "F1", "F8"]),
+		{ name: "%p - % pair", base: VALID.diff[2].spec, mutate: operands(["F5", "F3"]), reason: '"%p" - "%" is not a typed pair' },
+		{ name: "unit - other unit pair", base: VALID.diff[0].spec, mutate: operands(["F1", "F8"]), reason: '"m" - "person" is not a typed pair' },
+		{ name: "affine units", base: VALID.diff[0].spec, mutate: operands(["F14", "F13"]), reason: "affine (temperature)" },
+		{ name: "stray context", base: VALID.diff[0].spec, mutate: (row) => ({ ...row, context: "x" }), reason: "diff rows carry no context" },
+	],
+	growth: [
+		...generic(VALID.growth[0].spec, ["F6"]),
+		{ name: "affine units", base: VALID.growth[0].spec, mutate: operands(["F13", "F14"]), reason: "growth refuses affine" },
+		{ name: "unequal units", base: VALID.growth[0].spec, mutate: operands(["F6", "F8"]), reason: "unit differs" },
+		{ name: "entity mismatch", base: VALID.growth[0].spec, mutate: operands(["F6", "F17"]), reason: "growth needs one declared entity" },
+		{ name: "one period", base: VALID.growth[0].spec, mutate: operands(["F6", "F21"]), reason: "two different valid_at periods" },
+		{ name: "from <= 0", base: VALID.growth[0].spec, mutate: operands(["F18", "F7"]), reason: "positive starting value in F18" },
+		{ name: "stray context", base: VALID.growth[0].spec, mutate: (row) => ({ ...row, context: { target: "km" } }), reason: "growth rows carry no context" },
+	],
+	share: [
+		...generic(VALID.share[0].spec, ["F8"]),
+		{ name: "affine units", base: VALID.share[0].spec, mutate: operands(["F13", "F14"]), reason: "share refuses affine" },
+		{ name: "unequal units", base: VALID.share[0].spec, mutate: operands(["F8", "F1"]), reason: "unit differs" },
+		{ name: "whole <= 0", base: VALID.share[0].spec, mutate: operands(["F8", "F15"]), reason: "positive whole in F15" },
+		{ name: "part < 0", base: VALID.share[0].spec, mutate: operands(["F19", "F9"]), reason: "F19 is outside [0, F9]" },
+		{ name: "part above whole", base: VALID.share[0].spec, mutate: operands(["F9", "F8"]), reason: "F9 is outside [0, F8]" },
+		{ name: "stray context", base: VALID.share[0].spec, mutate: (row) => ({ ...row, context: "x" }), reason: "share rows carry no context" },
+	],
+	ratio: [
+		...generic(VALID.ratio[0].spec, ["F10"]),
+		{ name: "affine units", base: VALID.ratio[0].spec, mutate: operands(["F13", "F14"]), reason: "ratio refuses affine" },
+		{ name: "divides by zero", base: VALID.ratio[0].spec, mutate: operands(["F10", "F15"]), reason: "denominator F15 is zero" },
+		{ name: "stray context", base: VALID.ratio[0].spec, mutate: (row) => ({ ...row, context: { target: "km" } }), reason: "ratio rows carry no context" },
+	],
+	convert: [
+		...generic(VALID.convert[0].spec, ["F12", "F1"]),
+		{ name: "no context", base: VALID.convert[0].spec, mutate: (row) => ({ ...row, context: null }), reason: "convert rows carry a context object" },
+		{ name: "empty target", base: VALID.convert[0].spec, mutate: (row) => ({ ...row, context: { target: "" } }), reason: "carries its target in context.target" },
+		{ name: "alias target", base: VALID.convert[0].spec, mutate: (row) => ({ ...relabel(row, "kilometre")[0], context: { target: "kilometre" } }), reason: 'context.target "kilometre" is not canonical' },
+		{ name: "currency target", base: VALID.convert[0].spec, mutate: (row) => ({ ...row, context: { target: "USD" } }), reason: "no table conversion to USD (a currency)" },
+		{ name: "no factor to target", base: VALID.convert[0].spec, mutate: (row) => ({ ...row, context: { target: "person" } }), reason: 'F12 in "m" has no table conversion to person' },
+		{ name: "closed context", base: VALID.convert[0].spec, mutate: (row) => ({ ...row, context: { target: "km", extra: true } }), reason: "exactly target" },
+	],
+	expr: [
+		...generic(VALID.expr[0].spec, ["F3", "F4", "F5"], "do not match operands", "do not match operands F999, F4"),
+		{ name: "formula id mismatch", base: VALID.expr[0].spec, mutate: (row) => ({ ...row, formula: "F3 - F99" }), reason: "do not match operands" },
+		{ name: "parse error", base: VALID.expr[0].spec, mutate: (row) => ({ ...row, formula: "F3 -" }), reason: "the expression ends early" },
+		{ name: "divides by zero", base: VALID.expr[0].spec, mutate: (row) => ({ ...row, formula: "F3 / (F4 - F4)" }), reason: "the expression divides by zero" },
+		{ name: "uninferable unit", base: VALID.expr[0].spec, mutate: (row) => ({ ...row, formula: "F3 + F4" }), reason: "adding % values" },
+		{ name: "affine sum", base: VALID.expr[0].spec, mutate: (row) => ({ ...row, formula: "F13 + F14", operands: ["F13", "F14"] }), reason: "adding affine (temperature)" },
+		{ name: "stray context", base: VALID.expr[0].spec, mutate: (row) => ({ ...row, context: { target: "km" } }), reason: "expr rows carry no context" },
+		{ name: "undated rate", base: VALID.expr[0].spec, mutate: (row, book) => {
+			const rate = book.rows.find((r) => r.fact_id === "F3")
+			if (!rate) throw Error("fixture rate missing")
+			rate.unit = "USD/EUR"
+			return { ...row, formula: "F3 * F4" }
+		}, reason: "dated valid_at" },
+	],
+}
+
+/** Review r6 HIGH: one id twice is never disjoint shares; expr repeats F1 inside its formula and stores the id set. */
+const REPEATED: Record<string, Spec> = {
+	sum: { ...PCT_SUM, operands: ["F3", "F3"] },
+	diff: { op: "diff", operands: ["F3", "F3"], unit: "%p" },
+	growth: { op: "growth", from: "F6", to: "F6", unit: "%" },
+	share: { op: "share", part: "F9", whole: "F9", unit: "%" },
+	ratio: { op: "ratio", num: "F10", den: "F10", unit: null },
+	convert: { op: "convert", operands: ["F12", "F12"], to: "km" },
+	expr: { op: "expr", formula: "F1 * F1 / F2", unit: "m" },
+}
+
+function rowOf(result: { row?: Row; error?: string; detail?: string }): Row {
+	if (!result.row) throw new Error(`expected a row, got ${result.error}: ${result.detail}`)
+	return result.row
+}
+
+/** The row relabeled to `unit`; when the operation persists a context, a second variant rewrites that context too. */
+function relabel(row: Row, unit: string | null): Row[] {
+	const shown = display(row.value, unit)
+	const render = row.operation === "convert" ? `${shown} ${String(row.render).slice(String(row.render).indexOf("("))}` : shown
+	const plain = { ...row, unit, raw: render, render }
+	const context = row.context as Row
+	if (row.operation === "convert") return [plain, { ...plain, context: { ...context, target: unit } }]
+	if (row.operation === "sum") return [plain, { ...plain, context: { ...context, reference: `relabeled ${unit}` } }]
+	return [plain]
+}
+
+const OPS = Object.keys(OPERATION_RULES)
+
+test("the case tables cover exactly the registry's operations, which are the ledger schema's operations", () => {
+	expect([...OPS].sort()).toEqual([...OPERATIONS].sort())
+	for (const table of [VALID, MALFORMED]) expect(Object.keys(table).sort()).toEqual([...OPS].sort())
+})
+
+describe.each(OPS)("%s", (op) => {
+	test("valid typed operands derive, and the stored row recomputes ok", () => {
+		for (const { spec, unit } of VALID[op]) {
+			const book = ledger()
+			const row = rowOf(derive(book, spec))
+			expect(row.unit).toBe(unit)
+			expect(recompute(book, row)).toMatchObject({ ok: true })
+		}
+	})
+
+	test("every other unit, alias, or null is a relabel: recompute names the expected unit and derive refuses it", () => {
+		for (const { spec, unit } of VALID[op]) {
+			const book = ledger()
+			const row = rowOf(derive(book, spec))
+			for (const other of RELABELS.filter((candidate) => candidate !== unit)) {
+				const [plain, ...withContext] = relabel(row, other)
+				const result = recompute(book, plain)
+				expect({ other, ok: result.ok }).toEqual({ other, ok: false })
+				expect(result.detail).toContain(`expected unit ${JSON.stringify(unit)}`)
+				for (const variant of withContext) {
+					// A rewritten convert target is ok only when it is exactly the row an honest derive to that target writes
+					// (0 m to cm is 0 cm); an alias target, or any other rewrite, is ok:false.
+					const honest = op === "convert" ? derive(ledger(), { ...spec, to: other }).row : undefined
+					const consistent = honest !== undefined && ["unit", "exact", "value", "render", "formula", "factor", "precision", "compatibility"].every((key) => JSON.stringify(honest[key]) === JSON.stringify(variant[key]))
+					const rewritten = recompute(book, variant)
+					expect({ other, context: variant.context, ok: rewritten.ok }).toEqual({ other, context: variant.context, ok: consistent })
+				}
+				const declared = derive(ledger(), { ...spec, unit: other })
+				if (other !== "bp" && canonicalUnit(other) === unit) expect(declared.row?.unit).toBe(unit)
+				else expect({ other, error: declared.error }).toEqual({ other, error: "incompatible_operands" })
+			}
+		}
+	})
+
+	test("render precision follows invariant 5: sum, diff, a +/- expr root, and %p by decimal places; the rest by significant figures", () => {
+		for (const { spec, unit, precision } of VALID[op]) {
+			const row = rowOf(derive(ledger(), spec))
+			const ast = op === "expr" ? parseExpr(spec.formula) : null
+			expect({ spec, precision: renderPrecision(op, row.unit, ast) }).toEqual({ spec, precision: precision ?? PRECISION[op] })
+		}
+	})
+
+	test("the malformed cases are exactly the registry's malformed shapes", () => {
+		expect(MALFORMED[op].map((mutation) => mutation.name).sort()).toEqual([...OPERATION_RULES[op].malformed].sort())
+	})
+
+	test("operand identity: derive refuses a repeated operand id; only expr may repeat an id, and only inside its formula", () => {
+		const spec = REPEATED[op]
+		const result = derive(ledger(), spec)
+		if (op === "expr") {
+			expect(rowOf(result).operands).toEqual(["F1", "F2"])
+			return
+		}
+		expect({ error: result.error, detail: result.detail }).toEqual({ error: "incompatible_operands", detail: expect.stringContaining("is repeated") })
+	})
+
+	test("each malformed shape is ok:false for its own reason and never throws", () => {
+		for (const { name, base, mutate, reason } of MALFORMED[op]) {
+			const book = ledger()
+			const row = rowOf(derive(book, base))
+			let result: { ok: boolean; detail?: string } = { ok: true }
+			expect(() => {
+				result = recompute(book, mutate(row, book))
+			}).not.toThrow()
+			expect({ name, ok: result.ok }).toEqual({ name, ok: false })
+			expect(result).toMatchObject({ shape: expect.any(String), expected: expect.anything() })
+			expect({ name, detail: result.detail }).toEqual({ name, detail: expect.stringContaining(reason) })
+		}
+	})
+})
+
+describe("units", () => {
+	test("aliases canonicalize at input and composites cancel", () => {
+		expect(canonicalUnit("pp")).toBe("%p")
+		expect(canonicalUnit("bp")).toBe("%p")
+		expect(canonicalUnit("kilometre")).toBe("km")
+		expect(canonicalUnit("USD/(USD/person)")).toBe("person")
+		expect(canonicalUnit("USD / kg")).toBe("USD/kg")
+		expect(canonicalUnit("m/m")).toBeNull()
+		expect(canonicalUnit(null)).toBeNull()
+		expect(isAffine("C")).toBe(true)
+		expect(isAffine("F")).toBe(true)
+		expect(isAffine("m")).toBe(false)
+	})
+
+	test("unit text with no registered alias is stored as given, inner whitespace kept", () => {
+		expect(canonicalUnit("USD / million people")).toBe("USD/million people")
+		for (const unit of ["million people", "metric ton", "USD per person"]) {
+			expect(canonicalUnit(` ${unit} `)).toBe(unit)
+			const book = emptyLedger() as Ledger
+			addRow(book, measured("F1", "5", unit))
+			addRow(book, measured("F2", "7", unit))
+			const row = rowOf(derive(book, { op: "sum", operands: ["F1", "F2"], unit }))
+			expect(row).toMatchObject({ unit, render: `12 ${unit}` })
+			expect(recompute(book, row)).toMatchObject({ ok: true })
+		}
+	})
+
+	test("review r6 LOW 2: a scale word is never a unit atom; plain unit text that contains one is stored as given", () => {
+		for (const unit of ["million", "M", "bn", "billion", "e6", "thousand", "USD/M", "million*person"]) {
+			expect(() => canonicalUnit(unit)).toThrow("scale word")
+			const book = emptyLedger() as Ledger
+			expect(() => addRow(book, measured("F1", "5", unit))).toThrow("scale word")
+			addRow(book, measured("F1", "5", "m"))
+			addRow(book, measured("F2", "7", "m"))
+			book.rows[0].unit = unit
+			const result = derive(book, { op: "sum", operands: ["F1", "F2"], unit: "m" })
+			expect({ unit, error: result.error, detail: result.detail }).toEqual({ unit, error: "incompatible_operands", detail: expect.stringContaining("scale word") })
+		}
+		expect(canonicalUnit("million people")).toBe("million people")
+	})
+
+	test("expectedUnit is the registry's answer for stored operand rows", () => {
+		const book = ledger()
+		const rows = (ids: string[]) => ids.map((id) => book.rows.find((row) => row.fact_id === id) as Row)
+		expect(expectedUnit("diff", rows(["F3", "F4"]), {})).toBe("%p")
+		expect(expectedUnit("ratio", rows(["F10", "F11"]), {})).toBe("person")
+		expect(expectedUnit("convert", rows(["F12"]), { context: { target: "km" } })).toBe("km")
+	})
+
+	test("nested derived operands are verified recursively; a cycle is refused", () => {
+		const book = ledger()
+		const inner = rowOf(derive(book, { op: "sum", operands: ["F1", "F2"], unit: "m" }))
+		const outer = rowOf(derive(book, { op: "convert", operands: [inner.fact_id as string], to: "km" }))
+		expect(recompute(book, outer).ok).toBe(true)
+		inner.exact = { num: "5", den: "1" }
+		const tampered = recompute(book, outer)
+		expect(tampered.ok).toBe(false)
+		expect(tampered.detail).toContain(String(inner.fact_id))
+		const a = { ...inner, fact_id: "F90", label: "cycle-a", operands: ["F91", "F1"], exact: { num: "4", den: "1" } }
+		const b = { ...inner, fact_id: "F91", label: "cycle-b", operands: ["F90", "F1"], exact: { num: "4", den: "1" } }
+		book.rows.push(a, b)
+		let cycle: { ok: boolean; detail?: string } = { ok: true }
+		expect(() => {
+			cycle = recompute(book, a)
+		}).not.toThrow()
+		expect(cycle.ok).toBe(false)
+		expect(cycle.detail).toContain("cycle")
+		const through = derive(book, { op: "sum", operands: ["F90", "F2"], unit: "m" })
+		expect({ error: through.error, detail: through.detail }).toEqual({ error: "incompatible_operands", detail: expect.stringContaining("cycle") })
+		const self = { ...inner, fact_id: "F92", label: "self", operands: ["F92", "F1"] }
+		book.rows.push(self)
+		expect(recompute(book, self)).toMatchObject({ ok: false, detail: expect.stringContaining("cites itself") })
+		const onSelf = derive(book, { op: "convert", operands: ["F92"], to: "km" })
+		expect({ error: onSelf.error, detail: onSelf.detail }).toEqual({ error: "incompatible_operands", detail: expect.stringContaining("cites itself") })
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/fidelity-binding.mjs

@@ -0,0 +1,130 @@
+// fidelity-binding.mjs - sentence binding and claim-status checks of the fidelity gate.
+//
+// proseSentences walks every leaf prose element (p, li) outside figures, tables and page chrome,
+// keeps the offsets of each data-fact element inside its text, and splits it into sentences, so
+// every check sees which ledger rows a sentence cites. bindingChecks raises unbound_sentence (a
+// findings sentence with no fact, placeholder, citation, or data-claim), claim_status_invalid (a
+// data-claim id that is unknown, refuted or unresolved outside a Gaps or Contradictions section,
+// or high-risk and missing from verified-claims), and conflicting_readings (two active rows with
+// one value and unit but different periods or qualifiers cited in one sentence). Plain Node ESM.
+
+import { proseText } from "./html-lite.mjs"
+import { fromDecimal, eq } from "./rational.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+import { normalizeUnit } from "./units.mjs"
+
+const SKIP = new Set(["code", "pre", "kbd", "samp", "script", "style", "svg", "template", "noscript"])
+const CONTAINERS = new Set(["figure", "table", "nav", "header", "footer"])
+/** data-kind values whose sentences need no binding (opinion and recommendation blocks). */
+export const EXEMPT_KINDS = Object.freeze(["opinion", "recommendation"])
+export const isExemptKind = (kind) => EXEMPT_KINDS.includes(kind)
+const DECIMAL = /^-?\d+(?:\.\d+)?$/
+/** Gaps and Contradictions headings (English, and the Korean gap/limit/contradiction/conflict words). */
+const GAPS_HEADING = /\b(?:gaps?|contradictions?|unresolved)\b|\uACF5\uBC31|\uD55C\uACC4|\uBAA8\uC21C|\uC0C1\uCDA9/i
+
+/** Canonical unit token, or the raw unit without spaces, lowercased; "" for none. */
+export function unitKey(unit) {
+	if (unit === null || unit === undefined) return ""
+	return normalizeUnit(String(unit)) ?? String(unit).replace(/\s+/g, "").toLowerCase()
+}
+
+/** Exact decimal equality; false when either side is not a plain decimal. */
+export function sameValue(a, b) {
+	const [x, y] = [String(a ?? "").replace(/,/g, ""), String(b ?? "").replace(/,/g, "")]
+	return DECIMAL.test(x) && DECIMAL.test(y) && eq(fromDecimal(x), fromDecimal(y))
+}
+
+function serialize(node, out) {
+	for (const child of node.children) {
+		if (child.tag === "#text") out.text += child.text
+		else if (child.tag === "br") out.text += " "
+		else if (SKIP.has(child.tag)) continue
+		else if (child.attrs["data-fact"] !== undefined) {
+			const text = proseText(child)
+			out.facts.push({ id: child.attrs["data-fact"], start: out.text.length, end: out.text.length + text.length, text, node: child })
+			out.text += text
+		} else serialize(child, out)
+	}
+	return out
+}
+
+/**
+ * Leaf prose elements with their sentences and the facts each sentence cites.
+ * @returns {{ owner: object, scope: object, kind: string|null, sentences: { text: string, start: number, end: number, facts: object[] }[] }[]}
+ */
+export function proseSentences(ctx) {
+	const { closest, descendants } = ctx.util
+	const blocks = []
+	for (const { node, scope } of ctx.elements) {
+		if (node.tag !== "p" && node.tag !== "li") continue
+		if (node.tag === "li" && descendants(node).some((child) => child.tag === "p" || child.tag === "li")) continue
+		if (closest(node, (cur) => CONTAINERS.has(cur.tag))) continue
+		const { text, facts } = serialize(node, { text: "", facts: [] })
+		const sentences = splitSentences(text).map((s) => ({ ...s, facts: facts.filter((f) => f.start < s.end && f.end > s.start) }))
+		blocks.push({ owner: node, scope, kind: ctx.kindOf(scope), sentences })
+	}
+	return blocks
+}
+
+function claimList(claims) {
+	const list = Array.isArray(claims) ? claims : (claims?.claims ?? [])
+	return new Map(list.map((claim) => [claim.claim_id, claim]))
+}
+
+const selfOrUp = (ctx, node, test) => test(node) || Boolean(ctx.util.closest(node, test))
+
+function claimDefects(ctx, claims) {
+	const byId = claimList(claims)
+	const out = []
+	for (const { node, scope } of ctx.elements) {
+		const attr = node.attrs["data-claim"]
+		if (attr === undefined) continue
+		const heading = scope.section?.heading
+		const inGaps = Boolean(heading) && GAPS_HEADING.test(proseText(heading))
+		for (const id of attr.split(/[\s,]+/).filter(Boolean)) {
+			const claim = byId.get(id)
+			let why = null
+			if (!claim) why = `data-claim ${id} is not in the claim index`
+			else if (/refuted|unresolved/i.test(claim.status) && !inGaps) why = `claim ${id} is ${claim.status} but asserted outside Gaps or Contradictions`
+			else if (!inGaps && /high/i.test(claim.risk) && !claim.in_verified) why = `high-risk claim ${id} is not in verified-claims`
+			if (why) out.push(ctx.defect("claim_status_invalid", node, why))
+		}
+	}
+	return out
+}
+
+function conflict(rows, facts) {
+	const cited = [...new Set(facts.map((f) => f.id))].map((id) => rows.get(id)).filter((row) => row && row.status === "active" && row.kind !== "quote")
+	for (let i = 0; i < cited.length; i++) {
+		for (let k = i + 1; k < cited.length; k++) {
+			const [a, b] = [cited[i], cited[k]]
+			if (!sameValue(a.value, b.value) || unitKey(a.unit) !== unitKey(b.unit)) continue
+			if (a.valid_at !== b.valid_at || a.qualifier !== b.qualifier) return [a, b]
+		}
+	}
+	return null
+}
+
+/**
+ * @param {object} ctx buildContext(...) from gates-static.mjs
+ * @param {{ claims: object[] } | object[] | null} claims indexClaims(...) output or its claims array
+ * @param {{ rows: object[] } | null} ledger
+ */
+export function bindingChecks(ctx, claims, ledger) {
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const out = []
+	for (const block of proseSentences(ctx)) {
+		const findings = Boolean(block.scope.section) && block.kind === null
+		const exempt = selfOrUp(ctx, block.owner, (cur) => isExemptKind(cur.attrs["data-kind"]) || cur.attrs["data-claim"] !== undefined)
+		for (const sentence of block.sentences) {
+			const bound = sentence.facts.length > 0 || ctx.util.citationMarker.test(sentence.text) || sentence.text.includes("{{")
+			if (findings && !exempt && !bound) out.push(ctx.defect("unbound_sentence", block.owner, `no fact, citation, or data-claim binds: "${sentence.text.slice(0, 80)}"`))
+			const pair = conflict(rows, sentence.facts)
+			if (pair) {
+				const [a, b] = pair
+				out.push(ctx.defect("conflicting_readings", block.owner, `${a.fact_id} (${a.valid_at ?? "no period"}) and ${b.fact_id} (${b.valid_at ?? "no period"}) share ${a.value} ${a.unit ?? ""} in one sentence`))
+			}
+		}
+	}
+	return [...out, ...claimDefects(ctx, claims)]
+}

package/packages/shared-skills/skills/ulw-research/scripts/fidelity-binding.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+import { bindingChecks } from "./fidelity-binding.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+
+type Defect = { code: string; message: string }
+
+const FIX = join(import.meta.dir, "tests", "fixtures", "fidelity")
+const LEDGER = JSON.parse(readFileSync(join(FIX, "ledger-verify.json"), "utf8"))
+const CLAIMS = indexClaims(readFileSync(join(FIX, "claim-graph.md"), "utf8"))
+
+function run(body: string, claims: unknown = CLAIMS): Defect[] {
+	const html = /<h2/.test(body) ? body : `<h2>Findings</h2>\n${body}`
+	return bindingChecks(buildContext(parseHtml(html), {}), claims, LEDGER) as Defect[]
+}
+
+const codes = (defects: Defect[]) => defects.map((defect) => defect.code)
+const fact = (id: string, text: string) => `<data class="fact" data-fact="${id}">${text}</data>`
+
+describe("sentence binding", () => {
+	test("#given a findings paragraph with no marker #when checked #then unbound_sentence", () => {
+		expect(codes(run("<p>The bridge is popular with tourists.</p>"))).toEqual(["unbound_sentence"])
+	})
+
+	test("#given the same paragraph marked as opinion #when checked #then clean", () => {
+		expect(run('<p data-kind="opinion">The bridge is popular with tourists.</p>')).toEqual([])
+	})
+
+	test("#given a citation, a fact, or a claim on each sentence #when checked #then clean", () => {
+		const body = `<p>Tourism grew [S4]. Units reached ${fact("F2", "1,237")}.</p><p data-claim="C1">The design follows the standard.</p>`
+		expect(run(body)).toEqual([])
+	})
+
+	test("#given one unbound sentence after a cited one #when checked #then only that sentence is flagged", () => {
+		expect(codes(run("<p>Tourism grew [S4]. Everyone loves it.</p>"))).toEqual(["unbound_sentence"])
+	})
+
+	test("#given an unbound paragraph outside findings (appendix, closing, sources) #when checked #then out of scope", () => {
+		const body = "<h2>Appendix</h2><p>Plain words.</p><h2>How this report was made</h2><p>Plain words.</p><h2>Sources</h2><p>Plain words.</p>"
+		expect(run(body)).toEqual([])
+	})
+})
+
+describe("claim status", () => {
+	test("#given a data-claim id that is not in the claim index #when checked #then claim_status_invalid", () => {
+		expect(codes(run('<p data-claim="C99">The design is the safest.</p>'))).toEqual(["claim_status_invalid"])
+	})
+
+	test("#given a refuted claim cited in findings #when checked #then claim_status_invalid", () => {
+		expect(codes(run('<p data-claim="C3">The project finished early.</p>'))).toEqual(["claim_status_invalid"])
+	})
+
+	test("#given the refuted claim in a Contradictions section #when checked #then clean", () => {
+		expect(run('<h2>Contradictions</h2><p data-claim="C3">The project finished early.</p>')).toEqual([])
+	})
+
+	test("#given a normal-risk partial claim not in verified-claims #when checked #then clean", () => {
+		expect(run('<p data-claim="C2">Revenue grew about ten percent.</p>')).toEqual([])
+	})
+
+	test("#given a high-risk claim missing from verified-claims #when checked #then claim_status_invalid", () => {
+		const claims = { claims: [{ claim_id: "C7", statement: "x", risk: "high", status: "supported", in_verified: false }], errors: [] }
+		expect(codes(run('<p data-claim="C7">A strong statement.</p>', claims))).toEqual(["claim_status_invalid"])
+	})
+})
+
+describe("conflicting readings", () => {
+	test("#given two 12 % rows with YoY and QoQ periods in one sentence #when checked #then conflicting_readings", () => {
+		const body = `<p>Revenue grew ${fact("F3", "12%")} and ${fact("F4", "12%")} [S4].</p>`
+		expect(codes(run(body))).toEqual(["conflicting_readings"])
+	})
+
+	test("#given the two readings in separate sentences #when checked #then clean", () => {
+		const body = `<p>Revenue grew ${fact("F3", "12%")} [S4]. Quarterly growth was ${fact("F4", "12%")} [S4].</p>`
+		expect(run(body)).toEqual([])
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/fidelity-brief.mjs

@@ -109,6 +109,11 @@ export function isLocked(parsed) {
 	return FIDELITY_FIELDS.every((field) => Object.hasOwn(parsed.fields, field) && LOCKED_ANSWERED_BY.has(parsed.answered_by[field]))
 }
 
+/** The brief's `meaning check` field turns the meaning verifier off only when it reads "off". */
+export function meaningCheckEnabled(parsed) {
+	return !/^off\b/iu.test(parsed?.fields?.["meaning check"] ?? "")
+}
+
 function incompleteDefect(briefPath, parsed) {
 	const reasons = []
 	if (!parsed.present) reasons.push("no ## Fidelity block")