oh-my-opencode 5.1.45 → 5.1.47

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

@@ -0,0 +1,241 @@
+// fact-commands.mjs - the `fact` subcommands of report-tools: add, quote, retract, export, fill,
+// derive, verify (fact-commands-verify.mjs), pairs and meaning-check (fact-commands-meaning.mjs), polish-apply and
+// polish-diff (fact-commands-polish.mjs). Every value reaches the ledger from a source
+// snapshot through a deterministic locator or from a declared derivation; nothing here accepts a
+// typed value. add and quote print the row with 60 chars of source context on each side (JSON
+// with --json). Exit 0 ok, 1 semantic failure (fact_not_located, fill errors, a refused
+// derivation), 2 usage. node: builtins and sibling imports only.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, extname, join, resolve } from "node:path"
+
+import { CliError, parseArgs, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { derive } from "./fact-derive.mjs"
+import { fill } from "./fact-fill.mjs"
+import { addRow, readLedger, retractRow, supersedeRow, writeLedger } from "./fact-ledger.mjs"
+import { locateFind, locateMatch, locatePageLine, locateTable } from "./fact-locate.mjs"
+import { QUALIFIER_FORMS } from "./fidelity-lexicon.mjs"
+import { readState, writeState } from "./fidelity-state.mjs"
+import { exportRows } from "./fidelity-values.mjs"
+import { pointedFlag, sessionDirOf, snapshotOf } from "./source-commands.mjs"
+
+const CONTEXT = 60
+const BOOLEANS = ["json", "csv", "md", "inline", "view", "replace-failed", "disjoint"]
+const QUALIFIER_OF = new Map(Object.entries(QUALIFIER_FORMS).flatMap(([term, forms]) => forms.map((form) => [form, term])))
+const slug = (text) => String(text).toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 32) || "fact"
+
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+function nowIso(flags) {
+	const date = flags.now === undefined ? new Date() : new Date(flags.now)
+	if (Number.isNaN(date.getTime())) throw new CliError("--now requires an ISO timestamp")
+	return date.toISOString()
+}
+
+function failure(command, error, detail) {
+	const json = { command, status: "fail", exitCode: 1, error, ...detail }
+	return { json, summary: `${command}: ${error}${detail.message ? ` (${detail.message})` : ""}`, exitCode: 1 }
+}
+
+function locate(flags, snapshot, id, quote) {
+	const sourceId = id
+	if (quote) return locateMatch(snapshot.text, { match: flags.match, sourceId })
+	if (flags.find !== undefined) return locateFind(snapshot.text, { find: flags.find, unitExpected: flags["unit-expected"], sourceId })
+	if (flags.table !== undefined) {
+		if (snapshot.html === null) throw new CliError(`source ${id} has no source.html; --table needs a page snapshot`)
+		return locateTable(snapshot.html, { table: flags.table, row: flags.row, col: flags.col, sourceId })
+	}
+	if (flags.page !== undefined) return locatePageLine(snapshot.text, { page: Number(flags.page), line: Number(flags.line), sourceId })
+	throw new CliError("usage: fact add --source S<n> (--find TEXT | --table T --row R --col C | --page P --line L) --label LABEL")
+}
+
+function contextOf(text, row) {
+	const start = row.locator.char_start + (row.value_span?.[0] ?? 0)
+	const end = row.value_span ? row.locator.char_start + row.value_span[1] : row.locator.char_end
+	return { before: text.slice(Math.max(0, start - CONTEXT), start), match: text.slice(start, end), after: text.slice(end, end + CONTEXT) }
+}
+
+/** `fact add --assumed V --rationale R`: a value nobody measured, rendered ASSUMED; the rationale is required. */
+function runAssumed(args) {
+	const sessionDir = sessionDirOf(args.flags)
+	const ledger = readLedger(sessionDir)
+	const value = String(args.flags.assumed)
+	const row = addRow(ledger, { kind: "assumed", value, unit: args.flags.unit ?? null, raw: value, quote: "", extracted_by: "model", observed_at: nowIso(args.flags), label: args.required("label"), rationale: args.required("rationale") })
+	writeLedger(sessionDir, ledger)
+	return { json: { command: "fact add", status: "pass", exitCode: 0, defects: [], data: { row } }, exitCode: 0 }
+}
+
+function runAdd(args, quote) {
+	const command = quote ? "fact quote" : "fact add"
+	const { flags } = args
+	if (!quote && flags.assumed !== undefined) return runAssumed(args)
+	const id = args.required("source")
+	if (quote) args.required("match")
+	const sessionDir = sessionDirOf(flags)
+	const snapshot = snapshotOf(sessionDir, id)
+	const found = locate(flags, snapshot, id, quote)
+	if (found.error === "unit_expected_mismatch") return failure(command, "unit_mismatch", { message: `expected ${found.expected}, found ${found.found}`, candidates: found.candidates })
+	if (found.error) return failure(command, found.error, { message: `no single match in ${id}`, candidates: found.candidates })
+	const { meta } = snapshot
+	const host = URL.canParse(meta.url) ? new URL(meta.url).hostname : null
+	const labelSource = flags.find ?? flags.match ?? (flags.table !== undefined ? `${flags.row}_${flags.col}` : `p${flags.page}_l${flags.line}`)
+	const ledger = readLedger(sessionDir)
+	const row = addRow(ledger, {
+		kind: quote ? "quote" : "measured",
+		...(quote ? {} : { value: found.value, unit: found.unit, value_span: found.value_span, qualifier: QUALIFIER_OF.get(found.qualifier) ?? null }),
+		raw: found.raw,
+		quote: found.quote,
+		source_id: id,
+		locator: { ...found.locator, source_kind: meta.kind, url: meta.url, host, pointed: pointedFlag(sessionDir, meta.url) },
+		snapshot_sha256: meta.sha256,
+		sentence_id: found.sentence_id ?? null,
+		extracted_by: meta.extractor,
+		observed_at: nowIso(flags),
+		label: flags.label ?? slug(labelSource),
+		entity: flags.entity ?? null,
+		valid_at: flags["valid-at"] ?? null,
+		population: flags.population ?? null,
+		accounting_basis: flags["accounting-basis"] ?? null,
+		observation_id: flags.observation ?? null,
+		fuzzy: found.fuzzy === true,
+	})
+	writeLedger(sessionDir, ledger)
+	const context = contextOf(snapshot.text, row)
+	const json = { command, status: "pass", exitCode: 0, defects: [], data: { row, context } }
+	if (flags.json) return { json, exitCode: 0 }
+	const shown = quote ? row.quote : `${row.raw} (value ${row.value}${row.unit ? `, unit ${row.unit}` : ""})`
+	return { text: `${row.fact_id} ${row.label}: ${shown} [${id} ${row.sentence_id ?? "-"}]\n  ...${context.before}[${context.match}]${context.after}...`, exitCode: 0 }
+}
+
+function runRetract(args) {
+	const [id] = args.positionals
+	if (!id) throw new CliError("usage: fact retract <F<n>|Q<n>> --reason TEXT [--replacement ID]")
+	const sessionDir = sessionDirOf(args.flags)
+	const ledger = readLedger(sessionDir)
+	const reason = args.required("reason")
+	const row = args.flags.replacement === undefined ? retractRow(ledger, id, reason) : supersedeRow(ledger, id, args.flags.replacement, reason)
+	writeLedger(sessionDir, ledger)
+	return { json: { command: "fact retract", status: "pass", exitCode: 0, data: { fact_id: id, status: row.status, replacement: args.flags.replacement ?? null } }, exitCode: 0 }
+}
+
+const csvCell = (value) => (/[",\n]/.test(String(value)) ? `"${String(value).replace(/"/g, '""')}"` : String(value))
+
+/** "N of M sources snapshotted, by extractor ...": M also counts sources-ledger ids not yet snapshotted. */
+function coverageLine(sessionDir) {
+	const dir = join(sessionDir, "sources")
+	const snapped = existsSync(dir) ? readdirSync(dir).filter((name) => existsSync(join(dir, name, "meta.json"))) : []
+	const ledgerFile = join(sessionDir, "sources-ledger.md")
+	const listed = existsSync(ledgerFile) ? [...readText(ledgerFile).matchAll(/^\[S(\d+)\]/gm)].map((match) => `S${match[1]}`) : []
+	const byExtractor = {}
+	for (const id of snapped) {
+		const extractor = JSON.parse(readText(join(dir, id, "meta.json"))).extractor
+		byExtractor[extractor] = (byExtractor[extractor] ?? 0) + 1
+	}
+	const total = new Set([...snapped, ...listed]).size
+	const parts = Object.entries(byExtractor).map(([name, count]) => `${name} ${count}`)
+	return `${snapped.length} of ${total} sources snapshotted, by extractor: ${parts.join(", ") || "none"}`
+}
+
+function runExport(args) {
+	const sessionDir = sessionDirOf(args.flags)
+	const ledger = readLedger(sessionDir)
+	const coverage = coverageLine(sessionDir)
+	let text
+	if (args.flags.csv) {
+		const rows = exportRows(ledger)
+		text = `${["fact_id,label,plot_value,unit", ...rows.map((row) => [row.fact_id, row.label, row.plot_value, row.unit].map(csvCell).join(","))].join("\n")}\n`
+	} else text = `${JSON.stringify({ schemaVersion: ledger.schemaVersion, rows: ledger.rows, coverage }, null, 2)}\n`
+	if (args.flags.out === undefined) return { text, summary: coverage, exitCode: 0 }
+	writeFileSync(args.flags.out, text)
+	return { json: { command: "fact export", status: "pass", exitCode: 0, data: { out: resolve(args.flags.out), format: args.flags.csv ? "csv" : "json", sha256: sha256Of(text), coverage } }, summary: coverage, exitCode: 0 }
+}
+
+/** The inline edition: local stylesheets and scripts inlined, relative image paths made absolute. */
+function inlineAssets(html, baseDir) {
+	const local = (ref) => !/^[a-z][a-z0-9+.-]*:|^\/\//i.test(ref)
+	return html
+		.replace(/<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi, (tag) => {
+			const href = /\bhref=["']([^"']+)["']/i.exec(tag)?.[1]
+			return href && local(href) ? `<style>${readText(resolve(baseDir, href))}</style>` : tag
+		})
+		.replace(/<script\b([^>]*)\bsrc=["']([^"']+)["']([^>]*)><\/script>/gi, (tag, pre, src, post) => (local(src) ? `<script${pre}${post}>${readText(resolve(baseDir, src))}</script>` : tag))
+		.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (tag, pre, src, post) => (local(src) && !src.startsWith("/") ? `${pre}${resolve(baseDir, src)}${post}` : tag))
+}
+
+function runFill(args) {
+	const [source] = args.positionals
+	const { flags } = args
+	if (!source || (flags.out === undefined && !flags.view)) throw new CliError("usage: fact fill <src> (--out <path> | --view) [--format html|md|tex] [--inline] [--replace-failed]")
+	const format = flags.format ?? ({ ".md": "md", ".tex": "tex" }[extname(source).toLowerCase()] ?? "html")
+	if (!["html", "md", "tex"].includes(format)) throw new CliError("--format must be html, md, or tex")
+	if (flags.inline && format !== "html") throw new CliError("--inline applies to the html edition only")
+	const sessionDir = sessionDirOf(flags)
+	const state = flags["replace-failed"] ? readState(sessionDir) : null
+	const result = fill(readText(source), readLedger(sessionDir), { format: format === "tex" ? "md" : format, view: flags.view === true, ...(state ? { replaceFailed: state } : {}) })
+	const warnings = result.warnings
+	if (result.out === null) {
+		const defects = result.errors.map((error) => ({ ...error, severity: DEFECT_CODES[error.code]?.severity ?? "blocker", hint: DEFECT_CODES[error.code]?.hint ?? null }))
+		return { json: { command: "fact fill", status: "fail", exitCode: 1, defects, warnings }, summary: `fact fill: FAIL - ${defects.length} error(s), nothing written`, exitCode: 1 }
+	}
+	const out = flags.inline ? inlineAssets(result.out, dirname(resolve(source))) : result.out
+	if (flags.view) return { text: out, summary: `fact fill --view: ${result.fillMap.length} pointer(s), ${warnings.length} warning(s)`, exitCode: 0 }
+	writeFileSync(flags.out, out)
+	if (state) writeState(sessionDir, state)
+	const artifact = sha256Of(out)
+	const map = `${resolve(flags.out)}.fill-map.json`
+	writeJsonAtomic(map, { schemaVersion: 1, format, artifact: resolve(flags.out), artifact_sha256: artifact, entries: result.fillMap })
+	const data = { out: resolve(flags.out), map, artifact_sha256: artifact, occurrences: result.fillMap.length, warnings }
+	return { json: { command: "fact fill", status: "pass", exitCode: 0, defects: [], data }, summary: `fact fill: wrote ${flags.out} (${result.fillMap.length} pointer(s))`, exitCode: 0 }
+}
+
+function runDerive(args) {
+	const { flags } = args
+	const op = args.required("op")
+	const sessionDir = sessionDirOf(flags)
+	const ledger = readLedger(sessionDir)
+	// The registry refuses any field outside the operation's inputFields, so only the given flags go in; --unit null declares a dimensionless result.
+	const picked = ["to", "from", "num", "den", "part", "whole", "reference", "rationale", "label"].filter((key) => flags[key] !== undefined)
+	const spec = { op, now: nowIso(flags), ...Object.fromEntries(picked.map((key) => [key, flags[key]])) }
+	if (op === "expr") spec.formula = args.positionals[0]
+	else if (args.positionals.length > 0) spec.operands = args.positionals
+	if (flags.disjoint === true) spec.disjoint = true
+	if (flags.unit !== undefined) spec.unit = flags.unit === "null" ? null : flags.unit
+	const result = derive(ledger, spec)
+	if (result.error) return failure("fact derive", result.error, { message: result.detail, ...(result.hint ? { hint: result.hint } : {}) })
+	writeLedger(sessionDir, ledger)
+	const { row } = result
+	const json = { command: "fact derive", status: "pass", exitCode: 0, defects: [], data: { row, compatibility: result.compatibility } }
+	return flags.json ? { json, exitCode: 0 } : { text: `${row.fact_id} ${row.label}: ${row.render} (${row.operation} of ${row.operands.join(", ")}, ${result.compatibility})`, exitCode: 0 }
+}
+
+export async function runFact(argv) {
+	const [sub, ...rest] = argv
+	if (sub === "pairs" || sub === "meaning-check") return (await import("./fact-commands-meaning.mjs")).runFactMeaning(sub, rest)
+	if (sub === "polish-apply" || sub === "polish-diff") return (await import("./fact-commands-polish.mjs")).runFactPolish(sub, rest)
+	const args = parseArgs(rest, { booleans: BOOLEANS })
+	switch (sub) {
+		case "add":
+			return runAdd(args, false)
+		case "quote":
+			return runAdd(args, true)
+		case "retract":
+			return runRetract(args)
+		case "export":
+			return runExport(args)
+		case "fill":
+			return runFill(args)
+		case "derive":
+			return runDerive(args)
+		case "verify":
+			return (await import("./fact-commands-verify.mjs")).runFactVerify(args)
+		default:
+			throw new CliError("usage: fact <add|quote|retract|export|fill|verify|derive|pairs|meaning-check|polish-apply|polish-diff> ...")
+	}
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-derive.mjs

@@ -0,0 +1,66 @@
+// Public append boundary: dispatch through the operation table, verify transitive trust, append only on success.
+import { leaves, parseExpr } from "./fact-expr.mjs"
+import { readRow } from "./fact-ledger-kinds.mjs"
+import { addRow, nextId, validateLedger } from "./fact-ledger.mjs"
+import { recompute, verifyGraph } from "./fact-recompute.mjs"
+import { canonicalUnit, inputScale, refuse } from "./unit-algebra.mjs"
+import { refusal } from "./unit-errors.mjs"
+import { object, sameDeclared } from "./unit-metadata.mjs"
+import { display, renderValue, resultPrecision, toText } from "./unit-precision.mjs"
+import { expectedUnit, renderPrecision, ruleOf, unitMismatch } from "./unit-rules.mjs"
+export { recompute, display }
+
+/** Arithmetic and generated fields are chosen exclusively by the registry. */
+export function compute(op, rows, unit, ast, context, formula = null) {
+	const rule = ruleOf(op)
+	const out = rule.calculate(rows, context, ast, formula)
+	const mode = renderPrecision(op, unit, ast)
+	const precision = resultPrecision(rows, ast ? leaves(ast).literals : [], out.exact, mode)
+	const value = renderValue(out.exact, precision, mode)
+	const render = rule.render(display(value, unit), rows)
+	return { exact: toText(out.exact), value, render, raw: render, formula: out.formula, factor: out.factor, precision, compatibility: rule.compatibility, ...rule.metadataResult(rows) }
+}
+
+function declaredUnit(spec, rule) {
+	const own = Object.hasOwn(spec, "unit")
+	if ((!own && !rule.defaultUnit) || (own && spec.unit === undefined)) refuse("declare the result unit: pass unit (null for a dimensionless result)", undefined, "missing_unit", "an explicit unit or null")
+	const declared = own ? spec.unit : rule.defaultUnit(spec)
+	if (inputScale(declared)) refuse(`${declared} needs rescaling: declare %p and scale the value`)
+	return canonicalUnit(declared)
+}
+
+export function derive(ledger, spec) {
+	try {
+		if (!object(spec)) refuse("spec must be an object")
+		const errors = validateLedger(ledger)
+		if (errors.length) refuse(errors.join("; "), undefined, "ledger_schema", "a ledger conforming to KIND_RULES and canonical storage")
+		const rule = ruleOf(spec.op)
+		const allowed = ["op", "unit", "rationale", "label", "now", "context", ...rule.inputFields]
+		if (Object.keys(spec).some((key) => !allowed.includes(key))) refuse("spec carries fields outside its operation", undefined, "spec_fields", allowed)
+		const ast = rule.expression ? parseExpr(spec.formula) : null
+		const ids = rule.operandIds(spec, ast)
+		if (!Array.isArray(ids) || !ids.every((id) => typeof id === "string")) refuse(`${spec.op} needs its operand fact ids`, undefined, "operands", "an array of existing fact ids")
+		const verified = verifyGraph(ledger, ids, true)
+		if (!verified.ok) return { error: "incompatible_operands", ...verified }
+		const byId = new Map(ledger.rows.map((r) => [r.fact_id, r]))
+		const rows = ids.map((id) => readRow(byId.get(id)))
+		const context = rule.context(spec)
+		if (Object.hasOwn(spec, "context") && !sameDeclared(spec.context, context)) refuse("supplied context differs from the operation's input fields", undefined, "context", context ?? "explicit null")
+		const shape = rule.shape({ operation: spec.op, operands: ids, formula: spec.formula, context })
+		if (shape) refuse(shape, undefined, "context_or_formula", "the operation's declared context and matching formula operand set")
+		const expected = expectedUnit(spec.op, rows, { ast, context: { ...context, rationale: spec.rationale ?? null } })
+		const declared = declaredUnit(spec, rule)
+		if (declared !== expected) refuse(unitMismatch(spec.op, rows, declared, expected), undefined, "result_unit", { unit: expected })
+		const result = compute(spec.op, rows, expected, ast, context, spec.formula)
+		const row = addRow(ledger, {
+			kind: rule.kind, unit: expected, quote: "", extracted_by: "fact-derive",
+			observed_at: spec.now ?? new Date().toISOString(),
+			label: spec.label ?? `${spec.op}-${nextId(ledger, rule.kind).toLowerCase()}`,
+			...result, operation: spec.op, operands: ids, derived_from: ids,
+			rationale: spec.rationale ?? null, context,
+		})
+		return { row, compatibility: rule.compatibility }
+	} catch (error) {
+		return { error: "incompatible_operands", ...refusal(error) }
+	}
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-expr.mjs

@@ -0,0 +1,108 @@
+// fact-expr.mjs - the expression language of `fact derive --op expr` (references/unit-rules.md, expr row).
+// Leaves are fact ids and decimal literals; nodes are + - * / and pct(x), the explicit dimensionless-to-% node.
+// evaluate() is exact rational arithmetic. Under * and / a child whose inferred unit is % or %p enters as its
+// fraction (20% as 0.2): that unit comes from the registry's inference over the operand rows, never from the row's
+// own declared unit.
+
+import { add, div, fromDecimal, mul, sub } from "./rational.mjs"
+import { isPercentish, refuse } from "./unit-algebra.mjs"
+
+const TOKEN = /\s*(?:(F\d+)|(\d+(?:\.\d+)?)|(pct)\b|([-+*/()]))/y
+const HUNDRED = fromDecimal("100")
+
+function tokenize(formula) {
+	const text = String(formula ?? "")
+	const tokens = []
+	TOKEN.lastIndex = 0
+	while (/\S/.test(text.slice(TOKEN.lastIndex))) {
+		const at = TOKEN.lastIndex
+		const match = TOKEN.exec(text)
+		if (!match) refuse(`unsupported expression text at ${at}: "${text.slice(at).trim().slice(0, 16)}"`)
+		tokens.push(match[1] ? { id: match[1] } : match[2] ? { literal: match[2] } : match[3] ? { fn: "pct" } : { op: match[4] })
+	}
+	if (tokens.length === 0) refuse("expr needs an expression")
+	return tokens
+}
+
+/** Shunting-yard parser: parentheses and AST depth do not consume the JS call stack. */
+export function parseExpr(formula) {
+	if (typeof formula !== "string") refuse("expr needs an expression")
+	const tokens = tokenize(formula)
+	const values = []
+	const ops = []
+	const precedence = (op) => op === "*" || op === "/" ? 2 : 1
+	const reduce = () => {
+		const op = ops.pop()
+		if (op === "pct") values.push({ fn: op, arg: values.pop() })
+		else { const right = values.pop(); values.push({ op, left: values.pop(), right }) }
+	}
+	let need = true
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i]
+		if (need) {
+			if (token.id || token.literal) { values.push(token); need = false }
+			else if (token.fn) {
+				if (tokens[i + 1]?.op !== "(") refuse("pct needs a parenthesized argument")
+				ops.push("pct")
+			} else if (token.op === "(") ops.push("(")
+			else refuse(`unexpected "${token.op}" in the expression`)
+		} else if (token.op === ")") {
+			while (ops.length && ops.at(-1) !== "(") reduce()
+			if (ops.pop() !== "(") refuse("unexpected closing parenthesis")
+			if (ops.at(-1) === "pct") reduce()
+		} else if (["+", "-", "*", "/"].includes(token.op)) {
+			while (ops.length && ops.at(-1) !== "(" && precedence(ops.at(-1)) >= precedence(token.op)) reduce()
+			ops.push(token.op)
+			need = true
+		} else refuse("unexpected text after the expression")
+	}
+	if (need) refuse("the expression ends early")
+	if (ops.includes("(")) refuse("the expression is missing a closing parenthesis")
+	while (ops.length) reduce()
+	return values[0]
+}
+
+const childrenOf = (node) => (node.op ? [node.left, node.right] : node.fn ? [node.arg] : [])
+
+export function leaves(node, found = { ids: [], literals: [] }) {
+	const ids = new Set(found.ids)
+	const stack = [node]
+	while (stack.length) {
+		const current = stack.pop()
+		if (current.id) ids.add(current.id)
+		if (current.literal) found.literals.push(current.literal)
+		stack.push(...childrenOf(current).reverse())
+	}
+	found.ids = [...ids]
+	return found
+}
+
+export function postorder(node) {
+	const stack = [node]
+	const order = []
+	while (stack.length) { const current = stack.pop(); order.push(current); stack.push(...childrenOf(current)) }
+	return order.reverse()
+}
+
+/** Exact value of the tree; `units` maps each node to its inferred canonical unit (inferExpr in unit-rules.mjs). */
+export function evaluate(node, values, units) {
+	const results = new Map()
+	for (const current of postorder(node)) {
+		let value
+		if (current.id) value = values.get(current.id)
+		else if (current.literal) value = fromDecimal(current.literal)
+		else if (current.fn === "pct") value = mul(results.get(current.arg), HUNDRED)
+		else {
+			const operand = (child) => {
+				const v = results.get(child)
+				return (current.op === "*" || current.op === "/") && isPercentish(units.get(child)) ? div(v, HUNDRED) : v
+			}
+			const left = operand(current.left)
+			const right = operand(current.right)
+			if (current.op === "/" && right.num === 0n) refuse("the expression divides by zero", undefined, "divides_by_zero", "a nonzero denominator")
+			value = { "+": add, "-": sub, "*": mul, "/": div }[current.op](left, right)
+		}
+		results.set(current, value)
+	}
+	return results.get(node)
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-fill.mjs

@@ -0,0 +1,194 @@
+// fact-fill.mjs - the fill step: substitute every fact pointer in a report source from the
+// ledger, all or nothing. Fatal errors (pointer_label_mismatch, unresolved_placeholder,
+// quote_anchor_unresolved, unit_duplicated) return out null; warnings (particle_unverified,
+// fallback_without_entity) never block. A twice-failed sentence can be replaced by an attributed
+// block quote of its source row (replaceFailed). No IO, but not pure: unless options.view is set,
+// it records each replaced sentence in options.replaceFailed through markReplaced. node: builtins only.
+
+import { finalReading, rewriteParticle } from "./particles-ko.mjs"
+import { failureCount, markReplaced, sentenceKey } from "./fidelity-state.mjs"
+import { findPlaceholders, lead, qualifiedText, renderBlockquote, renderQuote, renderValueHtml, subSpan, valueParts } from "./placeholder.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+
+const FORMATS = Object.freeze(["html", "md"])
+const TRANSLATION = Object.freeze({
+	html: /^\s*<span data-translates="(Q\d+)">[\s\S]*?<\/span>/u,
+	md: /^\s*<!-- translates: (Q\d+) -->[^\n]*/u,
+})
+const HEADING = Object.freeze({ html: /<h[1-6]\b([^>]*)>([\s\S]*?)<\/h[1-6]>/giu, md: /^#{1,6}[ \t]+(.+)$/gmu })
+
+const lineOf = (text, at) => text.slice(0, at).split("\n").length
+
+function resolveValue(row, parsed, format) {
+	const { valueText, unitText } = valueParts(row)
+	const text = { full: row.raw, value: valueText, unit: unitText, q: qualifiedText(row) }[parsed.mode]
+	if (text === null) return { code: "quote_anchor_unresolved", message: `${row.fact_id} has qualifier ${row.qualifier}, but its quote holds no qualifier beside "${row.raw}"` }
+	return { row, parsed, visible: text, rendered: format === "html" ? renderValueHtml(row, text) : text }
+}
+
+function resolveQuote(row, parsed, format) {
+	const whole = { text: row.quote, start: 0, end: row.quote.length }
+	const selection = parsed.mode === "lead" ? lead(row.quote, parsed.lead) : parsed.mode === "span" ? subSpan(row.quote, parsed.from, parsed.to) : whole
+	if (selection === null) {
+		return { code: "quote_anchor_unresolved", message: `from "${parsed.from}" and to "${parsed.to}" must each occur exactly once in ${row.fact_id}'s quote, in that order` }
+	}
+	const rendered = renderQuote(row, parsed.selector, selection.text, format)
+	return { row, parsed, visible: `[${row.source_id}]`, rendered, selector: parsed.selector, quote_span: [selection.start, selection.end] }
+}
+
+function resolve(found, rows, format) {
+	const { parsed } = found
+	if (parsed.error) return { code: "unresolved_placeholder", message: parsed.error }
+	const row = rows.get(parsed.id)
+	if (row === undefined) return { code: "unresolved_placeholder", message: `${parsed.id} is not in the fact ledger` }
+	if (row.status !== "active") return { code: "unresolved_placeholder", message: `${parsed.id} is ${row.status}; cite its replacement` }
+	if (row.label !== parsed.label) return { code: "pointer_label_mismatch", message: `${parsed.id} has label "${row.label}", not "${parsed.label}"` }
+	return parsed.kind === "Q" ? resolveQuote(row, parsed, format) : resolveValue(row, parsed, format)
+}
+
+/** A unit typed right after a pointer that already renders it: never absorbed, always an error. */
+function unitDuplicated(text, item) {
+	if (item.parsed.kind !== "F" || (item.parsed.mode !== "full" && item.parsed.mode !== "q")) return false
+	const suffix = item.row.raw.replace(/^[\s\S]*\d/u, "").trim()
+	const units = [item.row.unit, valueParts(item.row).unitText, suffix].filter((unit) => typeof unit === "string" && unit !== "")
+	const following = text.slice(item.end).replace(/^[ \t]+/u, "")
+	return units.some((unit) => following.startsWith(unit) && !/[A-Za-z0-9]/u.test(following[unit.length] ?? ""))
+}
+
+/*
+ * Sentence-key rules (fidelity-state.mjs sentenceKey(slug, ids)); any other producer of keys must match:
+ * - slug source: an HTML heading's id attribute wins over its text; md headings use their text.
+ * - slugify: strip tags, lowercase, turn each run of non-letters/digits (\p{L}\p{N}) into "-",
+ *   trim leading and trailing "-".
+ * - a sentence takes the nearest heading that starts strictly before the sentence's start offset;
+ *   a sentence before the first heading gets slug "".
+ * - fact ids cited in the sentence are de-duplicated before sentenceKey sorts them.
+ */
+function slugify(text) {
+	return text
+		.replace(/<[^>]*>/gu, "")
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}]+/gu, "-")
+		.replace(/^-+|-+$/gu, "")
+}
+
+function headings(text, format) {
+	return [...text.matchAll(HEADING[format])].map((match) => {
+		const id = format === "html" ? /\bid="([^"]*)"/u.exec(match[1])?.[1] : undefined
+		return { at: match.index, slug: slugify(id ?? match[match.length - 1]) }
+	})
+}
+
+/** Sentence offsets over the source with pointers, comments and (html) tags blanked to equal length. */
+function sentencesOf(text, found, format) {
+	let masked = text
+	for (const item of found) masked = masked.slice(0, item.start) + "x".repeat(item.end - item.start) + masked.slice(item.end)
+	const blank = (part) => part.replace(/[^\n]/gu, " ")
+	masked = masked.replace(/<!--[\s\S]*?-->/gu, blank)
+	if (format === "html") masked = masked.replace(/<[^>]*>/gu, blank)
+	return splitSentences(masked)
+}
+
+function replacements(text, found, items, options, warnings) {
+	const { format, replaceFailed: state } = options
+	const marks = headings(text, format)
+	const out = []
+	for (const sentence of sentencesOf(text, found, format)) {
+		const inside = items.filter((item) => item.start >= sentence.start && item.end <= sentence.end)
+		if (inside.length === 0) continue
+		const slug = marks.filter((mark) => mark.at < sentence.start).at(-1)?.slug ?? ""
+		const key = sentenceKey(slug, [...new Set(inside.map((item) => item.row.fact_id))])
+		if (failureCount(state, key) < 2) continue
+		const rows = inside.map((item) => item.row)
+		const source = rows.find((row) => row.kind === "quote") ?? rows.find((row) => row.source_id !== null && row.quote !== "")
+		if (source === undefined) continue
+		let rendered = options.fallback === "omit" ? "" : renderBlockquote(source, key, format)
+		if (rendered !== "" && format === "md") {
+			if (sentence.start > 0 && text[sentence.start - 1] !== "\n") rendered = `\n\n${rendered}`
+			if (sentence.end < text.length && text[sentence.end] !== "\n") rendered = `${rendered}\n\n`
+		}
+		if (rendered !== "" && source.entity === null) {
+			warnings.push({ code: "fallback_without_entity", token: key, line: lineOf(text, sentence.start), message: `${source.fact_id} has no entity; the block quote cites [${source.source_id}] alone` })
+		}
+		out.push({ start: sentence.start, end: sentence.end, key, source, rendered })
+	}
+	return out
+}
+
+/** The text after a pointer: rewrite a following Korean particle, and map a translation span. */
+function afterPlaceholder(segment, item, context) {
+	const { format, text, warnings, fillMap } = context
+	const probeEnd = format === "html" && segment.includes("<") ? segment.indexOf("<") : segment.length
+	const result = rewriteParticle(segment.slice(0, probeEnd), finalReading(item.visible, null))
+	let next = segment
+	if (result.applied) next = result.text + segment.slice(probeEnd)
+	else if (result.candidate) {
+		warnings.push({ code: "particle_unverified", token: item.token, line: lineOf(text, item.start), message: `the particle after ${item.token} was not rewritten; check it by eye` })
+	}
+	const translation = item.parsed.kind === "Q" ? TRANSLATION[format].exec(next) : null
+	if (translation !== null && translation[1] === item.row.fact_id) {
+		const span = translation[0].trimStart()
+		const start = context.out.length + translation[0].length - span.length
+		fillMap.push({ token: span, fact_id: translation[1], translates: translation[1], start, end: start + span.length, rendered: span })
+	}
+	return next
+}
+
+function assemble(text, parts, context) {
+	let cursor = 0
+	let previous = null
+	const flush = (until) => {
+		const segment = text.slice(cursor, until)
+		context.out += previous?.parsed ? afterPlaceholder(segment, previous, context) : segment
+	}
+	for (const part of parts) {
+		flush(part.start)
+		const start = context.out.length
+		if (part.parsed) {
+			const extra = part.selector === undefined ? {} : { selector: part.selector, quote_span: part.quote_span }
+			context.fillMap.push({ token: part.token, fact_id: part.row.fact_id, start, end: start + part.rendered.length, rendered: part.rendered, ...extra })
+		} else if (part.rendered !== "") {
+			context.fillMap.push({ token: null, fact_id: part.source.fact_id, replaced: part.key, start, end: start + part.rendered.length, rendered: part.rendered })
+		}
+		context.out += part.rendered
+		cursor = part.end
+		previous = part
+	}
+	flush(text.length)
+	return context.out
+}
+
+/**
+ * @param {string} sourceText the report source with {{F..}} / {{Q..}} pointers
+ * @param {{ rows: object[] }} ledger
+ * @param {{ format?: "html"|"md", replaceFailed?: object, fallback?: "quote"|"omit", view?: boolean }} [options]
+ * @returns {{ out: string|null, fillMap: object[], errors: object[], warnings: object[] }}
+ */
+export function fill(sourceText, ledger, options = {}) {
+	const format = options.format ?? "html"
+	if (!FORMATS.includes(format)) throw new TypeError(`format must be one of ${FORMATS.join(", ")}`)
+	const rows = new Map(ledger.rows.map((row) => [row.fact_id, row]))
+	const found = findPlaceholders(sourceText)
+	const errors = []
+	const warnings = []
+	const items = []
+	for (const pointer of found) {
+		const resolved = resolve(pointer, rows, format)
+		const line = lineOf(sourceText, pointer.start)
+		if (resolved.code) errors.push({ code: resolved.code, token: pointer.token, line, message: resolved.message })
+		else {
+			const item = { ...pointer, ...resolved }
+			if (unitDuplicated(sourceText, item)) {
+				errors.push({ code: "unit_duplicated", token: pointer.token, line, message: `${pointer.token} already renders its unit; use {{${item.row.fact_id}:${item.row.label}:value}}` })
+			} else items.push(item)
+		}
+	}
+	if (errors.length > 0) return { out: null, fillMap: [], errors, warnings }
+	const replaced = options.replaceFailed ? replacements(sourceText, found, items, { ...options, format }, warnings) : []
+	const kept = items.filter((item) => !replaced.some((block) => item.start >= block.start && item.end <= block.end))
+	const parts = [...kept, ...replaced].sort((a, b) => a.start - b.start)
+	const context = { format, text: sourceText, warnings, fillMap: [], out: "" }
+	const out = assemble(sourceText, parts, context)
+	if (!options.view) for (const block of replaced) markReplaced(options.replaceFailed, block.key)
+	return { out, fillMap: context.fillMap, errors, warnings }
+}