lazycodex-ai 5.1.44 → 5.1.46

package/packages/shared-skills/skills/ulw-research/scripts/text-normalize.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test"
+
+import { findNormalized, normalizeText, tokenize } from "./text-normalize.mjs"
+
+describe("normalizeText", () => {
+	test("#given NFD and NFC Korean #when normalized #then both are equal NFC strings", () => {
+		// given
+		const nfc = "매출은 한국어로 적었다"
+		const nfd = nfc.normalize("NFD")
+		// when
+		const a = normalizeText(nfd)
+		const b = normalizeText(nfc)
+		// then
+		expect(nfd).not.toBe(nfc)
+		expect(a).toBe(b)
+		expect(a).toBe(nfc)
+	})
+
+	test("#given curly and CJK quote glyphs #when normalized #then they become straight quotes", () => {
+		// given
+		const raw = "\u201Cgrowth\u201D \u2018ok\u2019 \u300Cquoted\u300D \u300Etitle\u300F \u00ABfr\u00BB"
+		// when
+		const out = normalizeText(raw)
+		// then
+		expect(out).toBe("\"growth\" 'ok' \"quoted\" \"title\" \"fr\"")
+	})
+
+	test("#given runs of mixed whitespace #when normalized #then they collapse to single spaces and are trimmed", () => {
+		// when
+		const out = normalizeText("  a \t\n b\u00A0\u00A0c  ")
+		// then
+		expect(out).toBe("a b c")
+	})
+})
+
+describe("tokenize", () => {
+	test("#given Latin words and Hangul eojeol with punctuation #when tokenized #then tokens split on whitespace and punctuation", () => {
+		// when
+		const tokens = tokenize("Revenue rose, 매출은 100억 원이다. (\u201Cok\u201D)")
+		// then
+		expect(tokens).toEqual(["Revenue", "rose", "매출은", "100억", "원이다", "ok"])
+	})
+})
+
+describe("findNormalized", () => {
+	test("#given raw text with double spaces and curly quotes #when a straight-quoted needle is found #then RAW offsets slice back to the raw substring", () => {
+		// given
+		const hay = "He said  \u201Cgrowth  is\n strong\u201D  today."
+		// when
+		const hit = findNormalized(hay, "\"growth is strong\"")
+		// then
+		if (hit === null) throw new Error("needle not found")
+		expect(hay.slice(hit.start, hit.end)).toBe("\u201Cgrowth  is\n strong\u201D")
+	})
+
+	test("#given NFD Korean raw text with double spaces #when an NFC needle is found #then RAW offsets slice the NFD substring", () => {
+		// given
+		const rawNfc = "앞 문장. 매출은  100억 원이다. 끝"
+		const hay = rawNfc.normalize("NFD")
+		const expected = "매출은  100억 원이다".normalize("NFD")
+		// when
+		const hit = findNormalized(hay, "매출은 100억 원이다")
+		// then
+		if (hit === null) throw new Error("needle not found")
+		expect(hay.slice(hit.start, hit.end)).toBe(expected)
+	})
+
+	test("#given a needle absent from the text #when searched #then null is returned", () => {
+		// when / then
+		expect(findNormalized("abc", "zzz")).toBeNull()
+		expect(findNormalized("abc", "   ")).toBeNull()
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/text-similarity.mjs

@@ -0,0 +1,28 @@
+// text-similarity.mjs - similarity in [0, 1] from normalized Levenshtein distance.
+//
+// Both inputs go through normalizeText first (NFC, quote glyphs, whitespace), then the
+// edit distance is computed over code points and divided by the longer length.
+// Plain Node ESM, no dependencies.
+
+import { normalizeText } from "./text-normalize.mjs"
+
+function levenshtein(a, b) {
+	let previous = Array.from({ length: b.length + 1 }, (_, k) => k)
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i]
+		for (let k = 1; k <= b.length; k++) {
+			const cost = a[i - 1] === b[k - 1] ? 0 : 1
+			current.push(Math.min(previous[k] + 1, current[k - 1] + 1, previous[k - 1] + cost))
+		}
+		previous = current
+	}
+	return previous[b.length]
+}
+
+export function similarity(a, b) {
+	const left = Array.from(normalizeText(a))
+	const right = Array.from(normalizeText(b))
+	const longest = Math.max(left.length, right.length)
+	if (longest === 0) return 1
+	return 1 - levenshtein(left, right) / longest
+}

package/packages/shared-skills/skills/ulw-research/scripts/text-similarity.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test"
+
+import { similarity } from "./text-similarity.mjs"
+
+describe("similarity", () => {
+	test("#given identical strings #when compared #then similarity is exactly 1", () => {
+		// when / then
+		expect(similarity("a", "a")).toBe(1)
+		expect(similarity("", "")).toBe(1)
+	})
+
+	test("#given an OCR-noisy copy of a sentence #when compared #then similarity is at least 0.95", () => {
+		// given
+		const clean = "The company reported revenue of 100 billion won in the third quarter of 2025."
+		const noisy = "The  cornpany reported revenue of 100 bi1lion won in the third quarter of 2025. "
+		// when
+		const score = similarity(clean, noisy)
+		// then
+		expect(score).toBeGreaterThanOrEqual(0.95)
+		expect(score).toBeLessThan(1)
+	})
+
+	test("#given NFD vs NFC and curly vs straight quotes #when compared #then normalization makes them equal", () => {
+		// when / then
+		expect(similarity("\u201C매출은 늘었다\u201D".normalize("NFD"), "\"매출은 늘었다\"")).toBe(1)
+	})
+
+	test("#given a different sentence #when compared #then similarity is below 0.8", () => {
+		// given
+		const a = "The company reported revenue of 100 billion won in the third quarter of 2025."
+		const b = "Analysts expect margins to shrink next year as input costs keep rising."
+		// when
+		const score = similarity(a, b)
+		// then
+		expect(score).toBeLessThan(0.8)
+		expect(score).toBeGreaterThanOrEqual(0)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/unit-algebra.mjs

@@ -0,0 +1,101 @@
+// Canonical factor algebra. Exponents are bigint; aliases enter only through normalizeInput.
+import { fromDecimal, mul, sigFigsOf, toDecimal } from "./rational.mjs"
+import { dimensionOf, normalizeUnit } from "./units.mjs"
+import { refuse } from "./unit-errors.mjs"
+export { refuse, RuleError } from "./unit-errors.mjs"
+
+const SCALED = new Set(["bp", "basispoint", "basispoints"])
+export const isPercentish = (unit) => unit === "%" || unit === "%p"
+const scaled = (text) => SCALED.has(text.replace(/\s+/g, "").toLowerCase())
+
+function atomOf(text) {
+	if (text === "1") return null
+	const atom = scaled(text) ? "%p" : normalizeUnit(text) ?? text
+	if (dimensionOf(atom) === "scale") refuse(`"${text}" is a scale word (${atom}), not a unit`, undefined, "scale_atom", "a counted unit with scale in the numeral")
+	return atom
+}
+
+const combine = (a, b, sign) => {
+	for (const [atom, power] of b) a.set(atom, (a.get(atom) ?? 0n) + sign * power)
+	return a
+}
+
+/** Iterative unit parser: factor maps plus the input's decimal scaling exponent. */
+function parse(raw) {
+	if (raw === null) return { factors: new Map(), shift: 0n }
+	if (typeof raw !== "string" || !raw.trim()) refuse("unit must be text or explicit null", undefined, "unit_text", "canonical unit text or null")
+	const tokens = raw.match(/[*/()^]|[^*/()^]+/g).map((x) => x.trim()).filter(Boolean)
+	const frames = [{ factors: new Map(), shift: 0n, sign: 1n, need: true }]
+	let affine = false
+	const apply = (value, i) => {
+		if (tokens[i] === "^") {
+			const power = tokens[i + 1]
+			if (!/^[+-]?\d+$/.test(power ?? "")) refuse(`unit "${raw}" has a bad exponent`, undefined, "exponent", "an integer exponent")
+			const n = BigInt(power)
+			value = { factors: new Map([...value.factors].map(([a, p]) => [a, p * n])), shift: value.shift * n }
+			i += 2
+		}
+		const frame = frames.at(-1)
+		combine(frame.factors, value.factors, frame.sign)
+		frame.shift += frame.sign * value.shift
+		frame.need = false
+		return i
+	}
+	for (let i = 0; i < tokens.length;) {
+		const frame = frames.at(-1)
+		const token = tokens[i]
+		if (frame.need) {
+			if (token === "(") {
+				frames.push({ factors: new Map(), shift: 0n, sign: 1n, need: true })
+				i++
+			} else {
+				if (/^[*/()^]$/.test(token)) refuse(`unexpected "${token}" in unit "${raw}"`)
+				const atom = atomOf(token)
+				affine ||= dimensionOf(atom) === "temperature"
+				i = apply({ factors: new Map(atom === null ? [] : [[atom, 1n]]), shift: scaled(token) ? -2n : 0n }, i + 1)
+			}
+		} else if (token === ")" && frames.length > 1) {
+			const value = frames.pop()
+			i = apply(value, i + 1)
+		} else if (token === "*" || token === "/") {
+			frame.sign = token === "*" ? 1n : -1n
+			frame.need = true
+			i++
+		} else refuse(`unexpected "${token}" in unit "${raw}"`)
+	}
+	if (frames.length !== 1 || frames[0].need) refuse(`unit "${raw}" ends early or is missing a closing parenthesis`)
+	// Refuse affine composites before cancellation loses the atom that made them unsafe.
+	if (affine && (tokens.length !== 1 || frames[0].shift !== 0n)) refuse("affine (temperature) units cannot occur in composites", undefined, "affine_units", "a non-affine composite or bare temperature for convert")
+	return frames[0]
+}
+
+function format(factors) {
+	const side = (sign) => [...factors].filter(([, p]) => sign * p > 0n).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+		.map(([a, p]) => { const n = sign * p; return n === 1n ? a : `${a}^${n}` })
+	const top = side(1n)
+	const bottom = side(-1n)
+	if (!top.length && !bottom.length) return null
+	return `${top.join("*") || "1"}${bottom.length ? `/${bottom.length === 1 ? bottom[0] : `(${bottom.join("*")})`}` : ""}`
+}
+
+export const canonicalUnit = (raw) => format(parse(raw).factors)
+export function inputScale(raw) {
+	const { shift } = parse(raw)
+	if (shift === 0n) return null
+	if (shift > 10000n || shift < -10000n) refuse("scaled alias exponent exceeds exact input capacity", undefined, "scale_range", "an absolute decimal scale exponent <= 10000")
+	return shift > 0n ? `1${"0".repeat(Number(shift))}` : `0.${"0".repeat(Number(-shift - 1n))}1`
+}
+
+export function normalizeInput(unit, value) {
+	const canonical = canonicalUnit(unit)
+	const factor = inputScale(unit)
+	return { unit: canonical, value: factor ? toDecimal(mul(fromDecimal(value), fromDecimal(factor)), sigFigsOf(value)) : value }
+}
+
+export const unitTimes = (a, b) => format(combine(parse(a).factors, parse(b).factors, 1n))
+export const unitOver = (a, b) => format(combine(parse(a).factors, parse(b).factors, -1n))
+export const isAffine = (unit) => typeof unit === "string" && dimensionOf(unit) === "temperature"
+export function isCurrencyRate(unit) {
+	const currencies = [...parse(unit).factors].filter(([a, n]) => n !== 0n && dimensionOf(a)?.startsWith("currency:"))
+	return currencies.some(([, n]) => n > 0n) && currencies.some(([, n]) => n < 0n)
+}

package/packages/shared-skills/skills/ulw-research/scripts/unit-errors.mjs

@@ -0,0 +1,23 @@
+// Classified refusals shared by public derivation boundaries and the registry.
+export class RuleError extends Error {
+	constructor(detail, hint, shape = "invalid_input", expected = "a valid ledger and derivation specification") {
+		super(detail)
+		this.detail = detail
+		this.shape = shape
+		this.expected = expected
+		if (hint) this.hint = hint
+	}
+}
+
+export const refuse = (detail, hint, shape, expected) => {
+	throw new RuleError(detail, hint, shape, expected)
+}
+
+export function refusal(error) {
+	return {
+		shape: error instanceof RuleError ? error.shape : "invalid_input",
+		expected: error instanceof RuleError ? error.expected : "valid JSON fields matching the fact ledger grammar",
+		detail: error instanceof Error ? error.message : "invalid input",
+		...(error instanceof RuleError && error.hint ? { hint: error.hint } : {}),
+	}
+}

package/packages/shared-skills/skills/ulw-research/scripts/unit-metadata.mjs

@@ -0,0 +1,31 @@
+// Metadata contracts and order-independent JSON equality, shared by schema and algebra.
+import { isDeepStrictEqual } from "node:util"
+import { refuse } from "./unit-errors.mjs"
+
+export const METADATA = ["population", "accounting_basis", "snapshot_window", "entity", "valid_at"]
+export const sameDeclared = isDeepStrictEqual
+export const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0
+export const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+
+export function metadataErrors(row) {
+	return METADATA.filter((field) => {
+		const value = row[field]
+		return value !== null && !(nonEmpty(value) || (["population", "snapshot_window"].includes(field) && object(value)))
+	}).map((field) => `${field} must be explicitly null or valid non-empty metadata`)
+}
+
+export function checkMetadata(rows, fields) {
+	for (const row of rows) {
+		const errors = metadataErrors(row)
+		if (errors.length) refuse(`${row.fact_id}: ${errors.join("; ")}`, undefined, "metadata", "present, type-valid metadata; explicit null when unknown")
+	}
+	for (const field of fields) {
+		if (rows.some((row) => !sameDeclared(row[field], rows[0][field]))) {
+			refuse(`${field} differs across ${rows.map((row) => row.fact_id).join(", ")}`, undefined, "metadata", `equal ${field}`)
+		}
+	}
+}
+
+export function propagatedMetadata(rows) {
+	return Object.fromEntries(METADATA.map((field) => [field, rows.every((row) => sameDeclared(row[field], rows[0][field])) ? structuredClone(rows[0][field]) : null]))
+}

package/packages/shared-skills/skills/ulw-research/scripts/unit-pairs.mjs

@@ -0,0 +1,72 @@
+// unit-pairs.mjs - the typed operand-unit rules shared by the operation registry and expr nodes (references/unit-rules.md).
+// equalUnits and notAffine guard whole operations; minusUnit and plusUnit are the typed-pair rules that diff and sum
+// use and that expr's `-` and `+` nodes follow; inferExpr assigns a canonical unit to every node of an expr tree.
+
+import { isAffine, isPercentish, refuse, unitOver, unitTimes } from "./unit-algebra.mjs"
+import { postorder } from "./fact-expr.mjs"
+import { checkMetadata, propagatedMetadata } from "./unit-metadata.mjs"
+
+export const show = (unit) => JSON.stringify(unit ?? null)
+export const listed = (rows, units) => rows.map((row, index) => `${row.fact_id} ${units[index] ?? "null"}`).join(", ")
+
+export function equalUnits(rows, units) {
+	if (units.some((unit) => unit !== units[0])) refuse(`unit differs across ${listed(rows, units)}`)
+	return units[0]
+}
+
+export function notAffine(op, rows, units) {
+	if (units.some(isAffine)) refuse(`${op} refuses affine (temperature) units: ${listed(rows, units)}`)
+}
+
+/** The typed-pair rule shared by diff and expr `-`: U-U is U; %-% is %p; %-%p is %; %p-%p is %p; %p-% is refused. */
+export function minusUnit(a, b, where) {
+	if (isAffine(a) || isAffine(b)) refuse(`${where}: subtracting affine (temperature) values as absolute values has no meaning`)
+	if (a === b) return a === "%" ? "%p" : a
+	if (a === "%" && b === "%p") return "%"
+	refuse(`${where}: ${show(a)} - ${show(b)} is not a typed pair (U-U, %-%, %-%p, %p-%p)`)
+}
+
+export function plusUnit(a, b, where) {
+	if (isAffine(a) || isAffine(b)) refuse(`${where}: adding affine (temperature) values has no meaning`)
+	if (a === b && a === "%") refuse(`${where}: adding % values needs disjoint shares of one reference: use --op sum`)
+	if (a === b) return a
+	if ((a === "%" && b === "%p") || (a === "%p" && b === "%")) return "%"
+	refuse(`${where}: ${show(a)} + ${show(b)} has no common unit`)
+}
+
+/** Unit of every node of an expr tree; refuses when a node's unit cannot be inferred. */
+export function inferExpr(ast, unitsById, rowsById = null) {
+	const units = new Map()
+	const metadata = new Map()
+	for (const node of postorder(ast)) {
+		let unit
+		if (node.id) unit = unitsById.get(node.id)
+		else if (node.literal) unit = null
+		else if (node.fn === "pct") {
+			unit = units.get(node.arg)
+			if (unit !== null) refuse(`pct() takes a dimensionless value, got ${show(unit)}`)
+			unit = "%"
+		} else {
+			const left = units.get(node.left)
+			const right = units.get(node.right)
+			if (node.op === "+") unit = plusUnit(left, right, "expr")
+			else if (node.op === "-") unit = minusUnit(left, right, "expr")
+			else {
+				if (isAffine(left) || isAffine(right)) refuse(`expr: ${node.op} on affine (temperature) units has no meaning`)
+				const fraction = (value) => (isPercentish(value) ? null : value)
+				unit = (node.op === "*" ? unitTimes : unitOver)(fraction(left), fraction(right))
+			}
+		}
+		units.set(node, unit)
+		if (rowsById) {
+			const children = node.id ? [rowsById.get(node.id)] : node.literal ? [] : node.fn ? [metadata.get(node.arg)] : [metadata.get(node.left), metadata.get(node.right)]
+			const rows = children.filter(Boolean)
+			if (rows.length) {
+				const fields = node.op === "+" || node.op === "-" ? ["population", "snapshot_window", "accounting_basis"] : node.op === "/" ? ["population", "snapshot_window"] : []
+				checkMetadata(rows, fields)
+				metadata.set(node, { fact_id: "expression", ...propagatedMetadata(rows) })
+			}
+		}
+	}
+	return { unit: units.get(ast), units, metadata: metadata.get(ast) }
+}

package/packages/shared-skills/skills/ulw-research/scripts/unit-precision.mjs

@@ -0,0 +1,44 @@
+// Precision is stored independently from display strings; generated fields are rederived on replay.
+import { sigFigsOf, toDecimal } from "./rational.mjs"
+import { refuse } from "./unit-errors.mjs"
+
+export const toBig = (r) => ({ num: BigInt(r.num), den: BigInt(r.den) })
+export const toText = (r) => ({ num: String(r.num), den: String(r.den) })
+export const placesOf = (decimal) => (String(decimal).split(".")[1] ?? "").length
+export function terminates(r) {
+	let den = r.den
+	for (const prime of [2n, 5n]) while (den % prime === 0n) den /= prime
+	return den === 1n
+}
+export function precisionOf(row) {
+	if (row.precision !== null && row.precision !== undefined) {
+		const p = row.precision
+		if (!p || typeof p !== "object" || Object.keys(p).sort().join(",") !== "places,sigfigs" || !Number.isSafeInteger(p.places) || p.places < 0 || !Number.isSafeInteger(p.sigfigs) || p.sigfigs < 1) refuse("invalid stored precision", undefined, "precision_field", "{ places: nonnegative integer, sigfigs: positive integer }")
+		return p
+	}
+	return { places: placesOf(row.value), sigfigs: sigFigsOf(row.value) }
+}
+export function resultPrecision(rows, literals, exact, mode) {
+	const inputs = [...rows.map(precisionOf), ...literals.map((value) => precisionOf({ value }))]
+	const places = Math.min(...inputs.map((p) => p.places))
+	const sigfigs = Math.min(...inputs.map((p) => p.sigfigs))
+	if (mode === "places") return { places, sigfigs: sigFigsOf(roundPlaces(exact, places)) }
+	const rendered = toDecimal(exact, sigfigs)
+	return { places: placesOf(rendered), sigfigs }
+}
+export function roundPlaces(r, places) {
+	const digits = ((r.num < 0n ? -r.num : r.num) * 10n ** BigInt(places) * 2n + r.den) / (r.den * 2n)
+	const text = digits.toString().padStart(places + 1, "0")
+	return (r.num < 0n && digits !== 0n ? "-" : "") + (places ? `${text.slice(0, -places)}.${text.slice(-places)}` : text)
+}
+export function renderValue(exact, precision, mode) {
+	const plain = terminates(exact) ? toDecimal(exact) : null
+	const n = precision[mode]
+	if (plain !== null && (mode === "places" ? placesOf(plain) <= n : sigFigsOf(plain) < n)) return plain
+	return mode === "places" ? roundPlaces(exact, n) : toDecimal(exact, n)
+}
+export function display(value, unit) {
+	const [whole, fraction] = value.split(".")
+	const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ",") + (fraction === undefined ? "" : `.${fraction}`)
+	return unit === null ? grouped : unit === "%" ? `${grouped}%` : `${grouped} ${unit}`
+}

package/packages/shared-skills/skills/ulw-research/scripts/unit-rules-shapes.mjs

@@ -0,0 +1,64 @@
+// Structural rules used by the operation table, shared by schema and recomputation.
+import { leaves, parseExpr } from "./fact-expr.mjs"
+import { isRational } from "./fact-ledger-kinds.mjs"
+import { canonicalUnit, RuleError } from "./unit-algebra.mjs"
+import { nonEmpty, object } from "./unit-metadata.mjs"
+import { show } from "./unit-pairs.mjs"
+
+export const COMMON = ["operands null", "operands empty", "wrong arity", "missing operand id", "invalid rational", "no operation", "repeated operand", "self reference",
+	"kind operation", "audit fields", "precision field", "compatibility field", "metadata fields", "noncanonical operand"]
+export const shapes = (...own) => Object.freeze([...COMMON, ...own])
+export const needsContext = (row) => object(row.context) ? null : `${row.operation} rows carry a context object, got ${show(row.context)}`
+export const noContext = (row) => row.context === null ? null : `${row.operation} rows carry no context, got ${show(row.context)}`
+export const repeatedOperand = (ids) => new Set(ids).size !== ids.length ? `operand ${ids.find((id, i) => ids.indexOf(id) !== i)} is repeated: the operands of one row are distinct facts` : null
+
+export function sumShape(row) {
+	const missing = needsContext(row)
+	if (missing) return missing
+	const c = row.context
+	if (Object.keys(c).sort().join(",") !== "disjoint,reference" || typeof c.disjoint !== "boolean" || !(c.reference === null || nonEmpty(c.reference) || object(c.reference))) return "sum context needs exactly boolean disjoint and null, text, or map reference"
+	if (object(c.reference) && (Object.keys(c.reference).sort().join(",") !== [...row.operands].sort().join(",") || !Object.values(c.reference).every(nonEmpty))) return "reference map must name exactly the supplied operands"
+	return null
+}
+
+export function convertShape(row) {
+	const target = object(row.context) ? row.context.target : undefined
+	if (!nonEmpty(target)) return needsContext(row) ?? "a convert row carries its target in context.target"
+	if (Object.keys(row.context).join(",") !== "target") return "convert context has exactly target"
+	try {
+		const canonical = canonicalUnit(target)
+		return canonical === target ? null : `context.target ${show(target)} is not canonical unit text (canonical: ${show(canonical)})`
+	} catch (error) {
+		if (error instanceof RuleError) return `context.target ${show(target)} is not unit text: ${error.detail}`
+		throw error
+	}
+}
+
+export function exprShape(row) {
+	try {
+		const ids = leaves(parseExpr(row.formula)).ids
+		if (ids.length !== row.operands.length || ids.some((id) => !row.operands.includes(id))) return `formula ids ${ids.join(", ")} do not match operands ${row.operands.join(", ")}`
+		return null
+	} catch (error) {
+		if (error instanceof RuleError) return error.detail
+		throw error
+	}
+}
+
+export function rowShape(row, rules) {
+	if (!object(row)) return "the row is not an object"
+	if (!Object.hasOwn(rules, row.operation)) return `operation ${show(row.operation)} is not one of ${Object.keys(rules).join(", ")}`
+	const rule = rules[row.operation]
+	const { operands, exact } = row
+	if (!Array.isArray(operands) || !operands.length || !operands.every(nonEmpty)) return `operands must be a non-empty array of fact ids, got ${show(operands)}`
+	const repeated = repeatedOperand(operands)
+	if (repeated) return repeated
+	if (operands.includes(row.fact_id)) return `${row.fact_id} cites itself as an operand`
+	if (!rule.arity(operands.length)) return `${row.operation} takes ${rule.arityText}, got ${operands.length}`
+	if (!isRational(exact)) return `exact must be { num, den } reduced integer strings, got ${show(exact)}`
+	if (row.kind !== rule.kind) return `kind ${row.kind} must be ${rule.kind} for ${row.operation}`
+	const own = rule.shape(row)
+	if (own) return own
+	if (!nonEmpty(row.formula) || !Array.isArray(row.derived_from) || row.derived_from.length !== operands.length) return "formula and derived_from are required audit fields"
+	return null
+}

package/packages/shared-skills/skills/ulw-research/scripts/unit-rules.mjs

@@ -0,0 +1,173 @@
+// The sole per-operation registry: guards, context, arithmetic, precision, audit and compatibility.
+import { evaluate, leaves } from "./fact-expr.mjs"
+import { add, div, mul, sub, toDecimal } from "./rational.mjs"
+import { canonicalUnit, inputScale, isAffine, isCurrencyRate, isPercentish, refuse, RuleError, unitOver } from "./unit-algebra.mjs"
+import { checkMetadata, nonEmpty, object, propagatedMetadata } from "./unit-metadata.mjs"
+import { equalUnits, inferExpr, listed, minusUnit, notAffine, show } from "./unit-pairs.mjs"
+import { display, terminates, toBig } from "./unit-precision.mjs"
+import { convertShape, exprShape, noContext, repeatedOperand, rowShape, shapes, sumShape } from "./unit-rules-shapes.mjs"
+import { convertFactor, dimensionOf } from "./units.mjs"
+export { canonicalUnit, inferExpr, isAffine, RuleError }
+
+const EXPR_HINT = "currencies never convert by table: add a dated rate row and use --op expr"
+const compare = (a, b) => a.num * b.den - b.num * a.den
+const SNAPSHOT = ["population", "snapshot_window"]
+const ADDITIVE = [...SNAPSHOT, "accounting_basis"]
+const pair = (a, b) => (spec) => [spec[a], spec[b]]
+const listOf = (spec) => spec.operands
+const generated = (exact, formula, factor = null) => ({ exact, formula, factor })
+const idsOf = (rows) => rows.map((r) => r.fact_id)
+const valuesOf = (rows) => rows.map((r) => toBig(r.exact))
+const ordinary = {
+	kind: "derived", compatibility: "checked", context: () => null, shape: noContext,
+	precision: () => "sigfigs", render: (shown) => shown, metadataResult: propagatedMetadata,
+}
+const binary = { ...ordinary, arity: (n) => n === 2, arityText: "two operands" }
+
+function sharedReference(rows, reference) {
+	if (nonEmpty(reference)) return
+	if (object(reference)) {
+		const named = rows.map((r) => reference[r.fact_id])
+		if (Object.keys(reference).length === rows.length && named.every(nonEmpty) && named.every((v) => v === named[0])) return
+		refuse("% operands name different references or missing/extra ids", undefined, "reference", "one denominator for exactly the operands")
+	}
+	refuse("summing % operands needs one shared reference (denominator): pass reference")
+}
+
+/** Registry rows own every operation-specific choice; consumers only dispatch through these rows. */
+export const OPERATION_RULES = Object.freeze({
+	sum: Object.freeze({
+		...ordinary, arity: (n) => n >= 2, arityText: "two or more operands", operandIds: listOf,
+		inputFields: ["operands", "disjoint", "reference"],
+		context: (s) => ({ disjoint: Object.hasOwn(s, "disjoint") ? s.disjoint : false, reference: Object.hasOwn(s, "reference") ? s.reference : null }),
+		metadata: ADDITIVE, precision: () => "places", shape: sumShape,
+		resultUnit(rows, units, context) {
+			notAffine("sum", rows, units)
+			const unit = equalUnits(rows, units)
+			if (unit === "%") {
+				if (context.disjoint !== true) refuse("summing % operands needs disjoint shares: pass disjoint")
+				sharedReference(rows, context.reference)
+				if (!nonEmpty(context.rationale)) refuse("summing % operands needs a rationale for the disjoint shares")
+				const values = valuesOf(rows)
+				if (values.some((r) => r.num < 0n || r.num > 100n * r.den) || compare(values.reduce(add), { num: 100n, den: 1n }) > 0n) refuse("disjoint shares must each be in [0, 100] and total <= 100", undefined, "share_total", "valid disjoint shares totaling at most 100%")
+			}
+			return unit
+		},
+		calculate: (rows) => generated(valuesOf(rows).reduce(add), idsOf(rows).join(" + ")),
+		malformed: shapes("no context", "% without disjoint", "% without reference", "% without rationale", "unequal units", "affine units", "closed context", "share total"),
+	}),
+	diff: Object.freeze({
+		...binary, operandIds: listOf, metadata: ADDITIVE, precision: () => "places",
+		inputFields: ["operands"],
+		resultUnit: (rows, units) => minusUnit(units[0], units[1], `diff ${listed(rows, units)}`),
+		calculate: (rows) => generated(sub(...valuesOf(rows)), idsOf(rows).join(" - ")),
+		malformed: shapes("%p - % pair", "unit - other unit pair", "affine units", "stray context"),
+	}),
+	growth: Object.freeze({
+		...binary, arityText: "two operands (from, to)", operandIds: pair("from", "to"), metadata: ["population", "accounting_basis"],
+		inputFields: ["from", "to"],
+		resultUnit(rows, units) {
+			const [from, to] = rows
+			notAffine("growth", rows, units)
+			equalUnits(rows, units)
+			if (!nonEmpty(from.entity) || from.entity !== to.entity) refuse(`growth needs one declared entity: ${from.entity} vs ${to.entity}`)
+			if (!nonEmpty(from.valid_at) || !nonEmpty(to.valid_at) || from.valid_at === to.valid_at) refuse(`growth needs two different valid_at periods: ${from.valid_at} vs ${to.valid_at}`)
+			if (toBig(from.exact).num <= 0n) refuse(`growth needs a positive starting value in ${from.fact_id}`)
+			return "%"
+		},
+		calculate(rows) { const [a, b] = valuesOf(rows); const [x, y] = idsOf(rows); return generated(mul(div(sub(b, a), a), 100n), `(${y} - ${x}) / ${x} * 100`) },
+		malformed: shapes("affine units", "unequal units", "entity mismatch", "one period", "from <= 0", "stray context"),
+	}),
+	share: Object.freeze({
+		...binary, arityText: "two operands (part, whole)", operandIds: pair("part", "whole"), metadata: SNAPSHOT,
+		inputFields: ["part", "whole"],
+		resultUnit(rows, units) {
+			notAffine("share", rows, units)
+			equalUnits(rows, units)
+			const [part, whole] = valuesOf(rows)
+			if (whole.num <= 0n) refuse(`share needs a positive whole in ${rows[1].fact_id}`)
+			if (part.num < 0n || compare(part, whole) > 0n) refuse(`share needs 0 <= part <= whole: ${rows[0].fact_id} is outside [0, ${rows[1].fact_id}]`)
+			return "%"
+		},
+		calculate: (rows) => generated(mul(div(...valuesOf(rows)), 100n), `${idsOf(rows).join(" / ")} * 100`),
+		malformed: shapes("affine units", "unequal units", "whole <= 0", "part < 0", "part above whole", "stray context"),
+	}),
+	ratio: Object.freeze({
+		...binary, arityText: "two operands (num, den)", operandIds: pair("num", "den"), metadata: SNAPSHOT,
+		inputFields: ["num", "den"],
+		resultUnit(rows, units) {
+			notAffine("ratio", rows, units)
+			if (toBig(rows[1].exact).num === 0n) refuse(`ratio denominator ${rows[1].fact_id} is zero`)
+			if (units[0] === units[1]) return null
+			if (units.some(isPercentish)) refuse(`a ratio over % or %p needs equal units: ${listed(rows, units)}; use expr`)
+			return unitOver(units[0], units[1])
+		},
+		calculate: (rows) => generated(div(...valuesOf(rows)), idsOf(rows).join(" / ")),
+		malformed: shapes("affine units", "divides by zero", "stray context"),
+	}),
+	convert: Object.freeze({
+		...ordinary, kind: "converted", arity: (n) => n === 1, arityText: "one operand", operandIds: listOf, metadata: [],
+		inputFields: ["operands", "to"],
+		context: (s) => ({ target: canonicalUnit(s.to) }), shape: convertShape,
+		defaultUnit: (s) => s.to,
+		resultUnit(rows, units, context) {
+			if (!nonEmpty(context.target)) refuse("convert needs a target unit")
+			const [from] = units
+			const target = context.target
+			if (from === target) refuse(`${rows[0].fact_id} is already in ${target}`)
+			if ([from, target].some((u) => dimensionOf(u)?.startsWith("currency:"))) refuse(`${rows[0].fact_id} in ${show(from)} has no table conversion to ${target} (a currency)`, EXPR_HINT)
+			if (!convertFactor(from, target)) refuse(`${rows[0].fact_id} in ${show(from)} has no table conversion to ${target}`)
+			return target
+		},
+		calculate(rows, context) {
+			const row = rows[0]
+			const f = convertFactor(row.unit, context.target)
+			const scale = { num: f.num, den: f.den }
+			const text = terminates(scale) ? toDecimal(scale) : `${scale.num}/${scale.den}`
+			return generated(add(mul(toBig(row.exact), scale), f.offset ?? 0n), `${row.fact_id} * ${text}${f.offset ? ` + ${f.offset.num}/${f.offset.den}` : ""}`, terminates(scale) ? text : null)
+		},
+		render: (shown, rows) => `${shown} (${display(rows[0].value, rows[0].unit)})`,
+		malformed: shapes("no context", "empty target", "alias target", "currency target", "no factor to target", "closed context"),
+	}),
+	expr: Object.freeze({
+		...ordinary, arity: (n) => n >= 1, arityText: "one or more operands", compatibility: "unchecked",
+		expression: true, operandIds: (s, ast) => Object.hasOwn(s, "operands") ? s.operands : leaves(ast).ids,
+		inputFields: ["formula", "operands"],
+		metadata: [], precision: (ast) => ast?.op === "+" || ast?.op === "-" ? "places" : "sigfigs",
+		resultUnit(rows, units, _context, ast) {
+			for (const r of rows) if (isCurrencyRate(r.unit) && !nonEmpty(r.valid_at)) refuse(`FX rate ${r.fact_id} needs a dated valid_at; date compatibility remains unchecked`, EXPR_HINT, "undated_rate", "a dated FX rate row")
+			const inferred = inferExpr(ast, new Map(rows.map((r, i) => [r.fact_id, units[i]])), new Map(rows.map((r) => [r.fact_id, r]))).unit
+			notAffine("expr", rows, units)
+			return inferred
+		},
+		calculate(rows, _context, ast, formula) {
+			const { units } = inferExpr(ast, new Map(rows.map((r) => [r.fact_id, r.unit])))
+			return generated(evaluate(ast, new Map(rows.map((r) => [r.fact_id, toBig(r.exact)])), units), formula.trim())
+		},
+		shape: (row) => noContext(row) ?? exprShape(row),
+		malformed: shapes("formula id mismatch", "parse error", "divides by zero", "uninferable unit", "affine sum", "stray context", "undated rate"),
+	}),
+})
+
+export function ruleOf(op) {
+	if (!Object.hasOwn(OPERATION_RULES, op)) refuse(`unknown operation ${String(op)}; use one of ${Object.keys(OPERATION_RULES).join(", ")}`, undefined, "operation", Object.keys(OPERATION_RULES))
+	return OPERATION_RULES[op]
+}
+export function operandUnit(row) {
+	if (canonicalUnit(row.unit) !== row.unit || inputScale(row.unit)) refuse(`${row.fact_id} unit must be canonical stored text`, undefined, "noncanonical_operand", { unit: canonicalUnit(row.unit) })
+	return row.unit
+}
+export function expectedUnit(op, rows, { ast = null, context = null } = {}) {
+	const rule = ruleOf(op)
+	const repeated = repeatedOperand(idsOf(rows))
+	if (repeated) refuse(repeated, undefined, "repeated_operand", "distinct operand ids")
+	if (!rule.arity(rows.length)) refuse(`${op} takes ${rule.arityText}, got ${rows.length}`, undefined, "arity", rule.arityText)
+	const units = rows.map(operandUnit)
+	checkMetadata(rows, rule.metadata)
+	return rule.resultUnit(rows, units, context ?? {}, ast)
+}
+export function renderPrecision(op, unit, ast = null) {
+	return unit === "%p" ? "places" : ruleOf(op).precision(ast)
+}
+export const unitMismatch = (op, rows, unit, expected) => `unit ${show(unit)} does not follow from ${op} over ${rows.map((r) => `${r.fact_id} ${r.unit ?? "null"}`).join(", ")}: expected unit ${show(expected)}`
+export const malformed = (row) => rowShape(row, OPERATION_RULES)