lazycodex-ai 5.1.45 → 5.1.46

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

@@ -0,0 +1,140 @@
+// source-commands.mjs - the `source snapshot` and `claims index` subcommands of report-tools.
+// A source dir is immutable: the same id with identical text is a no-op, different text fails
+// (exit 1, snapshot_exists), because ledger rows pin the old hash. `--url` fetches with plain
+// fetch (30 s timeout, no browser) and records extractor tool:source-snapshot@1; `--html` and
+// `--text` import a browser-lane capture and record extractor model (lower trust), or the named
+// extractor for `--text --extractor NAME@VERSION`; `--command` runs an argv without a shell and
+// snapshots its stdout, with the argv, cwd, exit status, and output hashes in command.json.
+// node: builtins and sibling imports only.
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+import { CliError, parseArgs, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
+import { parseFidelityBlock } from "./fidelity-brief.mjs"
+import { writeSnapshot } from "./source-snapshot.mjs"
+
+const FETCH_TIMEOUT_MS = 30_000
+const TOOL_EXTRACTOR = "tool:source-snapshot@1"
+const SNAPSHOT_USAGE =
+	"usage: source snapshot --id S<n> (--url <u> | --html <file> | --text <file> [--extractor NAME@VERSION] | --command '<argv json>' --cwd DIR) [--kind page|command|document] [--provenance primary|secondary] [--revision R] --session-dir D"
+
+function readInput(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+/** The session dir from --session-dir or SESSION_DIR; a usage error when neither is set. */
+export function sessionDirOf(flags) {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	if (!dir || dir === true) throw new CliError("--session-dir is required (or set SESSION_DIR)")
+	return resolve(dir)
+}
+
+/** The snapshot of one source: meta.json, text.txt, and source.html when the source was a page. */
+export function snapshotOf(sessionDir, id) {
+	const dir = join(sessionDir, "sources", String(id))
+	if (!existsSync(join(dir, "meta.json"))) throw new CliError(`source ${id} has no snapshot; run source snapshot --id ${id} first`)
+	const html = join(dir, "source.html")
+	return { meta: JSON.parse(readInput(join(dir, "meta.json"))), text: readInput(join(dir, "text.txt")), html: existsSync(html) ? readInput(html) : null }
+}
+
+/** Whether the brief's source floor lists this source as pointed at (`pointed only: a, b`). */
+export function pointedFlag(sessionDir, url) {
+	const brief = join(sessionDir, "brief.md")
+	const floor = existsSync(brief) ? (parseFidelityBlock(readInput(brief)).fields?.["source floor"] ?? "") : ""
+	const match = /^pointed only:\s*(.+)$/i.exec(floor.trim())
+	return match ? match[1].split(",").map((entry) => entry.trim()).includes(url) : false
+}
+
+async function fetchSource(url) {
+	if (!URL.canParse(url)) throw new CliError(`--url is not a URL: ${url}`)
+	let response
+	try {
+		response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+	} catch (error) {
+		throw new CliError(`fetch failed for ${url}: ${error.message}`)
+	}
+	if (!response.ok) {
+		await response.body?.cancel()
+		throw new CliError(`fetch failed: HTTP ${response.status} for ${url}`)
+	}
+	const type = response.headers.get("content-type") ?? ""
+	if (/pdf/i.test(type)) {
+		await response.body?.cancel()
+		throw new CliError(`pdf response: ${url}; extract its text and use --text <file> --extractor NAME@VERSION`)
+	}
+	const body = await response.text()
+	return /html|xml/i.test(type) || /^\s*</.test(body) ? { url, html: body } : { url, text: body }
+}
+
+function runCommand(argvJson, cwd) {
+	let argv
+	try {
+		argv = JSON.parse(argvJson)
+	} catch (error) {
+		throw new CliError(`--command must be a JSON array of strings: ${error.message}`)
+	}
+	if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string" && part.length > 0)) {
+		throw new CliError("--command must be a non-empty JSON array of non-empty strings")
+	}
+	if (!cwd || cwd === true) throw new CliError("--command needs --cwd DIR")
+	const proc = spawnSync(argv[0], argv.slice(1), { cwd: resolve(cwd), encoding: "utf8", shell: false, maxBuffer: 64 * 1024 * 1024 })
+	if (proc.error) throw new CliError(`--command could not start: ${proc.error.message}`)
+	const receipt = { argv, cwd: resolve(cwd), exit_status: proc.status, stdout_sha256: sha256Of(proc.stdout), stderr_sha256: sha256Of(proc.stderr) }
+	return { path: `command:${argv.join(" ")}`, text: proc.stdout, kind: "command", receipt }
+}
+
+async function acquire(flags) {
+	const given = ["url", "html", "text", "command"].filter((name) => flags[name] !== undefined)
+	if (given.length !== 1) throw new CliError(SNAPSHOT_USAGE)
+	if (flags.extractor !== undefined && flags.text === undefined) throw new CliError("--extractor goes with --text only")
+	if (flags.url !== undefined) return { ...(await fetchSource(flags.url)), extractor: TOOL_EXTRACTOR }
+	if (flags.html !== undefined) return { path: resolve(flags.html), html: readInput(flags.html), extractor: "model" }
+	if (flags.text !== undefined) return { path: resolve(flags.text), text: readInput(flags.text), extractor: flags.extractor === undefined ? "model" : `extractor:${flags.extractor}` }
+	return { ...runCommand(flags.command, flags.cwd), extractor: TOOL_EXTRACTOR }
+}
+
+export async function runSource(argv) {
+	const [sub, ...rest] = argv
+	if (sub !== "snapshot") throw new CliError(SNAPSHOT_USAGE)
+	const args = parseArgs(rest)
+	const id = args.required("id")
+	const sourcesDir = join(sessionDirOf(args.flags), "sources")
+	const { receipt, ...input } = await acquire(args.flags)
+	if (args.flags.kind !== undefined) input.kind = args.flags.kind
+	if (args.flags.provenance !== undefined) input.provenance = args.flags.provenance
+	if (args.flags.revision !== undefined) input.revision = args.flags.revision
+	let written
+	try {
+		written = writeSnapshot(sourcesDir, id, input)
+	} catch (error) {
+		if (String(error.message).startsWith("snapshot_exists")) {
+			return { json: { command: "source snapshot", status: "fail", exitCode: 1, error: "snapshot_exists", message: error.message }, summary: `source snapshot: ${error.message}`, exitCode: 1 }
+		}
+		if (error instanceof TypeError) throw new CliError(error.message)
+		throw error
+	}
+	if (receipt) writeFileSync(join(written.dir, "command.json"), `${JSON.stringify(receipt, null, 2)}\n`)
+	const meta = JSON.parse(readFileSync(join(written.dir, "meta.json"), "utf8"))
+	const data = { source_id: id, directory: written.dir, snapshot_sha256: written.sha256, extractor: meta.extractor, kind: meta.kind, provenance: meta.provenance }
+	return { json: { command: "source snapshot", status: "pass", exitCode: 0, data }, summary: `source snapshot: ${id} ${written.sha256.slice(0, 12)} (${meta.extractor})`, exitCode: 0 }
+}
+
+export function runClaims(argv) {
+	const [sub, ...rest] = argv
+	const args = parseArgs(rest)
+	const [graph] = args.positionals
+	if (sub !== "index" || !graph) throw new CliError("usage: claims index <claim-graph.md> --out claims.json")
+	const out = args.required("out")
+	const index = indexClaims(readInput(graph))
+	if (index.errors.length > 0) throw new CliError(`claims index ${graph}: ${index.errors.join("; ")}`)
+	writeJsonAtomic(out, { schemaVersion: 1, graph: resolve(graph), graph_sha256: sha256Of(readFileSync(graph)), ...index })
+	const verified = index.claims.filter((claim) => claim.in_verified).length
+	return { json: { command: "claims index", out: resolve(out), claims: index.claims.length, verified }, summary: `claims index: ${index.claims.length} claim(s), ${verified} verified`, exitCode: 0 }
+}

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/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
+}