lazycodex-ai 5.1.44 → 5.1.46

package/packages/omo-codex/plugin/skills/ulw-research/scripts/source-snapshot.mjs

@@ -0,0 +1,176 @@
+// source-snapshot.mjs - the per-source snapshot that fact locators read.
+//
+// snapshotFromHtml turns a page into text.txt form: one line per block (prose blocks via
+// proseText, one table cell per line; head, scripts, styles and code are dropped). writeSnapshot
+// writes <sourcesDir>/<S-id>/ with text.txt (pages joined by a form feed), source.html when html
+// was given, meta.json, sentences.jsonl (sid S<n>:s<k>) and acronyms.json. The sha256 covers
+// text.txt only. Nothing here touches the network: the caller supplies the html or text.
+// Plain Node ESM, node: builtins and sibling imports only.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { sha256Of } from "./cli-support.mjs"
+import { parseHtml, PROSE_TAGS, proseText } from "./html-lite.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+
+const SKIP = new Set(["head", "script", "style", "svg", "code", "pre", "kbd", "samp", "template", "noscript"])
+const INLINE = new Set([
+	"a", "abbr", "b", "bdi", "bdo", "cite", "data", "del", "dfn", "em", "font", "i", "ins", "label", "mark", "q", "s",
+	"small", "span", "strong", "sub", "sup", "time", "u", "var",
+])
+const SOURCE_ID = /^S[1-9]\d*$/
+const EXTRACTOR = /^(?:tool:source-snapshot@1|model|extractor:[\w.@+-]+)$/
+const KINDS = new Set(["page", "command", "document"])
+const PROVENANCE = new Set(["primary", "secondary", "unknown"])
+const ACRONYM_AFTER = /\(([A-Z]{2,6})\)/g
+const ACRONYM_BEFORE = /(?<![\p{L}\p{N}])([A-Z]{2,6})\s?\(([A-Z][^()\n]{2,79})\)/gu
+const NAME_WORD = /^[A-Z][\p{L}\p{N}-]*$/u
+const CONNECTOR = new Set(["of", "and", "for", "the", "in", "on", "to", "&"])
+
+/**
+ * Block lines of a page: { root, text, blocks: [{ node, start, end }] } where text joins the block
+ * texts with "\n" and text.slice(start, end) is one block. fact-locate reads cells through `node`.
+ */
+export function snapshotBlocks(html) {
+	const root = parseHtml(html)
+	const lines = []
+	let buffer = ""
+	const flush = (node) => {
+		const line = buffer.replace(/\s+/g, " ").trim()
+		buffer = ""
+		if (line) lines.push({ node, text: line })
+	}
+	const walk = (node) => {
+		for (const child of node.children) {
+			if (child.tag === "#text") buffer += child.text
+			else if (SKIP.has(child.tag)) continue
+			else if (child.tag === "br") flush(node)
+			else if (INLINE.has(child.tag)) walk(child)
+			else if (PROSE_TAGS.has(child.tag)) {
+				flush(node)
+				const line = proseText(child)
+				if (line) lines.push({ node: child, text: line })
+			} else {
+				flush(node)
+				walk(child)
+				flush(child)
+			}
+		}
+	}
+	walk(root)
+	flush(root)
+	const blocks = []
+	let at = 0
+	for (const line of lines) {
+		blocks.push({ node: line.node, start: at, end: at + line.text.length })
+		at += line.text.length + 1
+	}
+	return { root, text: lines.map((line) => line.text).join("\n"), blocks }
+}
+
+/** text.txt form of an html page. */
+export function snapshotFromHtml(html) {
+	return snapshotBlocks(html).text
+}
+
+/** Sentence index rows { sid: "S<n>:s<k>", start, end, text }; a form feed (page break) always ends a sentence. */
+export function indexSentences(text, sourceId) {
+	return splitSentences(text.replace(/\f/g, "\n")).map((row) => ({
+		sid: `${sourceId}:${row.sid}`,
+		start: row.start,
+		end: row.end,
+		text: text.slice(row.start, row.end),
+	}))
+}
+
+const sentenceIdAt = (sentences, offset) => sentences.find((row) => row.start <= offset && offset < row.end)?.sid ?? null
+
+/** "High Bandwidth Memory (HBM)": the capitalized words before the parenthesis, at most one per letter. */
+function nameBefore(text, at, letters) {
+	const prefix = text.slice(Math.max(0, at - 160), at)
+	if (!/\S[ \t]?$/.test(prefix)) return null
+	const words = [...prefix.matchAll(/\S+/g)]
+	const picked = []
+	let content = 0
+	for (let k = words.length - 1; k >= 0 && content < letters; k--) {
+		const word = words[k][0]
+		if (NAME_WORD.test(word)) content++
+		else if (!CONNECTOR.has(word) || picked.length === 0) break
+		picked.unshift(words[k])
+	}
+	while (picked.length > 0 && CONNECTOR.has(picked[0][0])) picked.shift()
+	if (picked.length === 0) return null
+	const start = at - prefix.length + picked[0].index
+	const end = at - prefix.length + picked[picked.length - 1].index + picked[picked.length - 1][0].length
+	return { start, expansion: text.slice(start, end) }
+}
+
+/** Every `Full Name (ACR)` and `ACR (Full Name)` in the text, ordered by position. */
+export function findAcronyms(text, sentences) {
+	const entries = []
+	for (const match of text.matchAll(ACRONYM_AFTER)) {
+		const name = nameBefore(text, match.index, match[1].length)
+		if (!name || name.expansion === match[1]) continue
+		entries.push({ acronym: match[1], expansion: name.expansion, span: [name.start, match.index + match[0].length] })
+	}
+	for (const match of text.matchAll(ACRONYM_BEFORE)) {
+		const expansion = match[2].trim()
+		if (!/\s/.test(expansion) || expansion === expansion.toUpperCase()) continue
+		entries.push({ acronym: match[1], expansion, span: [match.index, match.index + match[0].length] })
+	}
+	return entries
+		.sort((a, b) => a.span[0] - b.span[0])
+		.map((entry) => ({ acronym: entry.acronym, expansion: entry.expansion, sentence_id: sentenceIdAt(sentences, entry.span[0]), span: entry.span }))
+}
+
+function snapshotText(input) {
+	if (Array.isArray(input.pages)) return input.pages.join("\f")
+	if (typeof input.text === "string") return input.text
+	if (typeof input.html === "string") return snapshotFromHtml(input.html)
+	throw new TypeError("writeSnapshot needs text, pages, or html")
+}
+
+function checkInput(sourceId, input) {
+	if (!SOURCE_ID.test(String(sourceId))) throw new TypeError(`source id must be S<n>, got ${sourceId}`)
+	if (!EXTRACTOR.test(String(input.extractor))) throw new TypeError(`extractor must be tool:source-snapshot@1, model, or extractor:<name>, got ${input.extractor}`)
+	if (typeof (input.url ?? input.path) !== "string") throw new TypeError("writeSnapshot needs a url or a path")
+	if (input.kind !== undefined && !KINDS.has(input.kind)) throw new TypeError(`kind must be page, command, or document, got ${input.kind}`)
+	if (input.provenance !== undefined && !PROVENANCE.has(input.provenance)) throw new TypeError(`provenance must be primary, secondary, or unknown, got ${input.provenance}`)
+}
+
+/**
+ * Write <sourcesDir>/<sourceId>/ for one source; returns { dir, sha256 } with sha256 over text.txt.
+ * input: { url | path, text | pages | html, extractor, observed_at?, revision?, kind?, provenance? }.
+ * Re-writing the same text is a no-op change; a different text over an existing snapshot throws
+ * snapshot_exists, because ledger rows pin the old hash.
+ */
+export function writeSnapshot(sourcesDir, sourceId, input) {
+	checkInput(sourceId, input)
+	const text = snapshotText(input)
+	const sha256 = sha256Of(Buffer.from(text, "utf8"))
+	const dir = join(sourcesDir, sourceId)
+	const textPath = join(dir, "text.txt")
+	if (existsSync(textPath) && sha256Of(readFileSync(textPath)) !== sha256) {
+		throw new Error(`snapshot_exists: ${sourceId} already holds a different text.txt`)
+	}
+	mkdirSync(dir, { recursive: true })
+	writeFileSync(textPath, text)
+	if (typeof input.html === "string") writeFileSync(join(dir, "source.html"), input.html)
+	const meta = {
+		source_id: sourceId,
+		url: input.url ?? input.path,
+		observed_at: input.observed_at ?? new Date().toISOString(),
+		sha256,
+		extractor: input.extractor,
+		revision: input.revision ?? null,
+		kind: input.kind ?? (input.url !== undefined || typeof input.html === "string" ? "page" : "document"),
+		provenance: input.provenance ?? "unknown",
+	}
+	writeFileSync(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`)
+	const sentences = indexSentences(text, sourceId)
+	writeFileSync(join(dir, "sentences.jsonl"), sentences.map((row) => `${JSON.stringify(row)}\n`).join(""))
+	const acronyms = { schemaVersion: 1, source_id: sourceId, snapshot_sha256: sha256, entries: findAcronyms(text, sentences) }
+	writeFileSync(join(dir, "acronyms.json"), `${JSON.stringify(acronyms, null, 2)}\n`)
+	return { dir, sha256 }
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/text-normalize.mjs

@@ -0,0 +1,82 @@
+// text-normalize.mjs - text normalization and raw-offset matching for fidelity checks.
+//
+// normalizeText applies NFC, maps curly and CJK quote glyphs to straight quotes, collapses
+// whitespace runs to one space, and trims. findNormalized matches a needle against the
+// normalized haystack and returns offsets into the RAW haystack through an offset map built
+// during normalization. Plain Node ESM, no dependencies.
+
+const DOUBLE_QUOTES = new Set([
+	"\u201C", "\u201D", "\u201E", "\u201F", "\u00AB", "\u00BB", "\u300C", "\u300D", "\u300E", "\u300F",
+	"\u301D", "\u301E", "\u301F", "\uFF02", "\u2033",
+])
+const SINGLE_QUOTES = new Set(["\u2018", "\u2019", "\u201A", "\u201B", "\u2039", "\u203A", "\uFF07", "\u2032"])
+// Combining marks and conjoining Hangul medial/final jamo attach to the preceding code point,
+// so a decomposed syllable is normalized as one unit.
+const JOINS_PREVIOUS = /^[\p{M}\u1160-\u11FF\uD7B0-\uD7FF]$/u
+const WHITESPACE = /^\s+$/u
+const TOKEN_SEPARATOR = /[^\p{L}\p{N}\p{M}]+/u
+
+function mapQuote(ch) {
+	if (DOUBLE_QUOTES.has(ch)) return '"'
+	if (SINGLE_QUOTES.has(ch)) return "'"
+	return ch
+}
+
+function clusters(raw) {
+	const out = []
+	let at = 0
+	for (const ch of raw) {
+		const last = out[out.length - 1]
+		if (last && JOINS_PREVIOUS.test(ch)) last[1] += ch.length
+		else out.push([at, at + ch.length])
+		at += ch.length
+	}
+	return out
+}
+
+// Returns { text, starts, ends }: text[k] came from raw.slice(starts[k], ends[k]).
+function normalizeWithMap(raw) {
+	const source = String(raw ?? "")
+	let text = ""
+	const starts = []
+	const ends = []
+	for (const [start, end] of clusters(source)) {
+		const piece = Array.from(source.slice(start, end).normalize("NFC"), mapQuote).join("")
+		if (WHITESPACE.test(piece)) {
+			if (text !== "" && !text.endsWith(" ")) {
+				text += " "
+				starts.push(start)
+				ends.push(end)
+			}
+			continue
+		}
+		for (let k = 0; k < piece.length; k++) {
+			starts.push(start)
+			ends.push(end)
+		}
+		text += piece
+	}
+	if (text.endsWith(" ")) {
+		text = text.slice(0, -1)
+		starts.pop()
+		ends.pop()
+	}
+	return { text, starts, ends }
+}
+
+export function normalizeText(s) {
+	return normalizeWithMap(s).text
+}
+
+export function tokenize(s) {
+	return normalizeText(s).split(TOKEN_SEPARATOR).filter((token) => token !== "")
+}
+
+export function findNormalized(hay, needle) {
+	const target = normalizeText(needle)
+	if (target === "") return null
+	const map = normalizeWithMap(hay)
+	const at = map.text.indexOf(target)
+	if (at === -1) return null
+	return { start: map.starts[at], end: map.ends[at + target.length - 1] }
+}

package/packages/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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
+}