oh-my-opencode 5.1.45 → 5.1.47

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

@@ -5,6 +5,11 @@
 // Also the value primitives the schema shares. Pure functions with no IO; node: builtins only.
 
 import { isCliEntry } from "./entry-guard.mjs"
+import { canonicalUnit, inputScale, RuleError } from "./unit-algebra.mjs"
+import { metadataErrors } from "./unit-metadata.mjs"
+import { mul } from "./rational.mjs"
+import { placesOf, roundPlaces, toBig } from "./unit-precision.mjs"
+import { OPERATION_RULES } from "./unit-rules.mjs"
 
 export const DECIMAL = /^-?\d+(?:\.\d+)?$/
 const INTEGER = /^-?\d+$/
@@ -16,7 +21,15 @@ export const isString = (value) => typeof value === "string"
 export const isNonEmpty = (value) => typeof value === "string" && value.length > 0
 export const isCount = (value) => Number.isInteger(value) && value >= 0
 const isDecimal = (value) => isString(value) && DECIMAL.test(value)
-const isRational = (exact) => isObject(exact) && isString(exact.num) && isString(exact.den) && INTEGER.test(exact.num) && /^\d+$/.test(exact.den) && !/^0+$/.test(exact.den)
+export function isRational(exact) {
+	if (!isObject(exact) || Object.keys(exact).sort().join(",") !== "den,num" || !isString(exact.num) || !isString(exact.den) || !INTEGER.test(exact.num) || !/^[1-9]\d*$/.test(exact.den)) return false
+	let a = BigInt(exact.num)
+	let b = BigInt(exact.den)
+	if (String(a) !== exact.num) return false
+	if (a < 0n) a = -a
+	while (b !== 0n) [a, b] = [b, a % b]
+	return a === 1n
+}
 
 /** The exact rational of a decimal string, reduced. */
 export function exactFromDecimal(value) {
@@ -72,22 +85,27 @@ export const RULES = Object.freeze({
 		test: (v, row) => isRational(v) && (!isDecimal(row.value) || (v.num === exactFromDecimal(row.value).num && v.den === exactFromDecimal(row.value).den)),
 	},
 	rational_or_null: { cell: "rational or null", says: "null or { num: integer string, den: positive integer string }", test: orNull(isRational) },
-	by_derive: { cell: "written by derive (rational or null)", says: "null or { num: integer string, den: positive integer string }", test: orNull(isRational) },
+	by_derive: { cell: "reduced rational", says: "a reduced { num: integer string, den: positive integer string }", test: isRational },
+	context_by_derive: { cell: "written by derive (object or null)", says: "null or an object", test: orNull(isObject) },
+	derived_operation: { cell: "sum/diff/growth/share/ratio/expr", says: "a derived operation", test: (v) => Object.hasOwn(OPERATION_RULES, v) && OPERATION_RULES[v].kind === "derived" },
+	convert_operation: { cell: "`convert`", says: "convert", test: (v) => Object.hasOwn(OPERATION_RULES, v) && OPERATION_RULES[v].kind === "converted" },
+	precision: { cell: "`{ places, sigfigs }`", says: "nonnegative places and positive sigfigs", test: (v) => isObject(v) && Object.keys(v).sort().join(",") === "places,sigfigs" && Number.isSafeInteger(v.places) && v.places >= 0 && Number.isSafeInteger(v.sigfigs) && v.sigfigs >= 1 },
+	compatibility: { cell: "checked or unchecked (expr)", says: "the operation's compatibility", test: (v, r) => Object.hasOwn(OPERATION_RULES, r.operation) && v === OPERATION_RULES[r.operation].compatibility },
 })
 
 /** The grammar's per-kind columns, in table order; `exact` follows `value` because it reads it. */
-export const KIND_COLUMNS = Object.freeze(["fact_id", "value", "source_id", "locator", "snapshot_sha256", "rationale", "exact"])
+export const KIND_COLUMNS = Object.freeze(["fact_id", "value", "source_id", "locator", "snapshot_sha256", "rationale", "exact", "context", "operation", "precision", "compatibility"])
 
 const sourced = { source_id: "source", locator: "locator", snapshot_sha256: "sha256" }
 const unsourced = { source_id: "source_or_null", locator: "locator_or_null", snapshot_sha256: "sha256_or_null" }
-const row = (cells) => Object.freeze(Object.fromEntries(KIND_COLUMNS.map((column) => [column, cells[column]])))
+const row = (cells) => Object.freeze(Object.fromEntries(KIND_COLUMNS.map((column) => [column, cells[column] ?? (["precision", "compatibility"].includes(column) && cells.operation !== "null" ? column : "null")])))
 
 export const KIND_RULES = Object.freeze({
-	measured: row({ fact_id: "f_id", value: "decimal", ...sourced, rationale: "string_or_null", exact: "from_value" }),
-	quote: row({ fact_id: "q_id", value: "null", ...sourced, rationale: "string_or_null", exact: "null" }),
-	derived: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive" }),
-	assumed: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "non_empty", exact: "rational_or_null" }),
-	converted: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive" }),
+	measured: row({ fact_id: "f_id", value: "decimal", ...sourced, rationale: "string_or_null", exact: "from_value", context: "null", operation: "null" }),
+	quote: row({ fact_id: "q_id", value: "null", ...sourced, rationale: "string_or_null", exact: "null", context: "null", operation: "null" }),
+	derived: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive", context: "context_by_derive", operation: "derived_operation" }),
+	assumed: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "non_empty", exact: "rational_or_null", context: "null", operation: "null" }),
+	converted: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive", context: "context_by_derive", operation: "convert_operation" }),
 })
 
 /** The id prefix nextId assigns for a kind; an unknown kind gets F and fails validation later. */
@@ -100,15 +118,101 @@ export function exactComesFromValue(kind) {
 	return KIND_RULES[kind]?.exact === "from_value"
 }
 
+/** Columns added after schema version 1 shipped; a ledger written before them still loads (dimension 31). */
+export const LATER_COLUMNS = Object.freeze(["context", "precision", "compatibility"])
+const DERIVED_KINDS = Object.freeze(["derived", "converted"])
+const PRE_REGISTRY_COLUMNS = KIND_COLUMNS.slice(0, KIND_COLUMNS.indexOf("exact") + 1)
+
+/** A derived or converted row written before the later columns existed: loadable, never an operand. */
+export const isLegacyDerived = (row) => isObject(row) && DERIVED_KINDS.includes(row.kind) && LATER_COLUMNS.every((column) => !Object.hasOwn(row, column))
+/** A derived or converted row carrying this version's columns: the only rows checked strictly at read time. */
+export const isCurrentDerived = (row) => isObject(row) && DERIVED_KINDS.includes(row.kind) && !isLegacyDerived(row)
+
+/** An exact carrying keys beyond num and den: never normalized, never silently stripped, flagged on use. */
+export const hasUnknownExactKeys = (exact) => isObject(exact) && isString(exact.num) && isString(exact.den) && Object.keys(exact).sort().join(",") !== "den,num"
+/** Any integer pair dev's writer accepted, reduced: sign on num, no leading zeros, gcd 1; anything else as given. */
+function readExact(exact) {
+	if (!isObject(exact) || hasUnknownExactKeys(exact) || !isString(exact.num) || !isString(exact.den) || !INTEGER.test(exact.num) || !/^\d+$/.test(exact.den) || /^0+$/.test(exact.den)) return exact
+	const { num, den } = mul({ num: BigInt(exact.num), den: BigInt(exact.den) }, 1n)
+	return { num: String(num), den: String(den) }
+}
+
+const readDecimal = (value) => (isDecimal(value) ? value.replace(/^(-?)0+(?=\d)/, "$1") : value)
+
+/** A source unit read through the alias table; unknown, scaled, or unparseable text stays as given. */
+export function sourceUnit(unit) {
+	try {
+		const canonical = canonicalUnit(unit)
+		return isString(canonical) && !inputScale(unit) ? canonical : unit
+	} catch (error) {
+		if (error instanceof RuleError) return unit
+		throw error
+	}
+}
+
+/**
+ * A row as every reader sees it (dimension 31 wins at read time): rows not written by derive in this
+ * version get reduced exacts and decimals; source rows also get canonical units and null later columns.
+ * Current derived rows stay as stored so tampering is still detected. Idempotent.
+ */
+export function readRow(row) {
+	if (!isObject(row) || !Object.hasOwn(KIND_RULES, row.kind) || isCurrentDerived(row)) return row
+	const read = { ...row, value: readDecimal(row.value), exact: exactComesFromValue(row.kind) ? row.exact : readExact(row.exact) }
+	if (DERIVED_KINDS.includes(row.kind)) return read
+	read.unit = sourceUnit(row.unit)
+	for (const column of LATER_COLUMNS) if (!Object.hasOwn(read, column)) read[column] = null
+	return read
+}
+
+const carriesDerivation = (row) => row.operation !== null || row.operands?.length || row.derived_from?.length || row.formula !== null || row.factor !== null
+
+/** Dimension 32: a stored exact must equal the row's own value at the value's decimal places. */
+function valueExactDisagreement(row) {
+	const exact = readExact(row.exact)
+	const value = readDecimal(row.value)
+	if (!isRational(exact) || !isDecimal(value) || roundPlaces(toBig(exact), placesOf(value)) === value) return null
+	return `value ${value} disagrees with exact ${exact.num}/${exact.den} at ${placesOf(value)} decimal places`
+}
+function unitFlaw(unit) {
+	try {
+		return isString(unit) && (canonicalUnit(unit) !== unit || inputScale(unit)) ? `unit ${unit} has no canonical stored text` : null
+	} catch (error) {
+		if (error instanceof RuleError) return `unit ${unit}: ${error.message}`
+		throw error
+	}
+}
+
+/**
+ * What a loadable source row (read through readRow) still breaks under the strict dimensions: dev's
+ * writer accepted it, so it loads, but derive and recompute refuse it as an operand with this shape.
+ * addRow refuses a new row that has any. Empty for derived and converted rows.
+ */
+export function readFlaws(row) {
+	if (!isObject(row) || DERIVED_KINDS.includes(row.kind)) return []
+	const flaws = []
+	if (carriesDerivation(row)) flaws.push({ shape: "dimension 1", detail: "a source row carries an operation or derivation fields", expected: "null operation and empty derivation fields on measured, quote, and assumed rows" })
+	const unit = unitFlaw(row.unit)
+	if (unit) flaws.push({ shape: "dimension 6", detail: unit, expected: "a registered or canonical unit without scale" })
+	for (const detail of metadataErrors(row)) flaws.push({ shape: "dimension 18", detail, expected: "present, type-valid metadata; explicit null when unknown" })
+	const unknownKeys = hasUnknownExactKeys(row.exact)
+	const disagreement = unknownKeys ? null : valueExactDisagreement(row)
+	if (unknownKeys) flaws.push({ shape: "dimension 7", detail: `exact has unknown keys: ${Object.keys(row.exact).filter((key) => key !== "num" && key !== "den").join(", ")}`, expected: "an exact with exactly num and den (the stored row is kept as written)" })
+	if (disagreement) flaws.push({ shape: "dimension 32", detail: disagreement, expected: "an exact equal to value at the value's decimal places" })
+	return flaws
+}
+
 /** @returns {string[]} every per-kind column error of one row; empty for an unknown kind. */
 export function kindRuleErrors(candidate, at) {
 	const rules = KIND_RULES[candidate.kind]
 	if (rules === undefined) return []
 	const errors = []
-	for (const column of KIND_COLUMNS) {
-		const value = candidate[column]
-		if (value === undefined) continue
-		const rule = RULES[rules[column]]
+	const legacy = isLegacyDerived(candidate)
+	const columns = legacy ? PRE_REGISTRY_COLUMNS : isCurrentDerived(candidate) ? KIND_COLUMNS : KIND_COLUMNS.filter((column) => column !== "operation")
+	for (const column of columns) {
+		const value = candidate[column] === undefined && LATER_COLUMNS.includes(column) ? null : candidate[column]
+		const rule = RULES[legacy && column === "exact" ? "rational_or_null" : rules[column]]
+		// An exact with unknown keys loads as written (never stripped); readFlaws refuses it at use and at write.
+		if (column === "exact" && hasUnknownExactKeys(value) && !isCurrentDerived(candidate)) continue
 		if (rule.test(value, candidate)) continue
 		errors.push(`${at}.${column} must be ${rule.says} for a ${candidate.kind} row`)
 		if (rule.detail) errors.push(...rule.detail(value, `${at}.${column}`))
@@ -116,6 +220,16 @@ export function kindRuleErrors(candidate, at) {
 	return errors
 }
 
+/** At-rest rules of current derived rows; source rows answer to readFlaws at use and at write instead. */
+export function storedErrors(row) {
+	if (!isCurrentDerived(row)) return []
+	const errors = metadataErrors(row)
+	try {
+		if (canonicalUnit(row.unit) !== row.unit || inputScale(row.unit)) errors.push("unit must be canonical stored text")
+	} catch (error) { errors.push(error.message) }
+	return errors
+}
+
 export const KIND_TABLE_BEGIN = "<!-- kind-rules:begin (rendered from KIND_RULES; do not edit by hand) -->"
 export const KIND_TABLE_END = "<!-- kind-rules:end -->"
 

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

@@ -4,7 +4,8 @@
 // KIND_RULES (fact-ledger-kinds.mjs), never here.
 // Pure functions with no IO; fact-ledger.mjs owns reading, writing, and row changes. node: builtins only.
 
-import { DECIMAL, isCount, isNonEmpty, isObject, isString, kindRuleErrors } from "./fact-ledger-kinds.mjs"
+import { DECIMAL, isCount, isCurrentDerived, isNonEmpty, isObject, isString, kindRuleErrors, LATER_COLUMNS, readRow, storedErrors } from "./fact-ledger-kinds.mjs"
+import { malformed } from "./unit-rules.mjs"
 
 export { DECIMAL, isNonEmpty, isString } from "./fact-ledger-kinds.mjs"
 
@@ -50,8 +51,13 @@ export const ROW_DEFAULTS = Object.freeze({
 	formula: null,
 	factor: null,
 	rationale: null,
+	context: null,
+	precision: null,
+	compatibility: null,
 	status: "active",
 })
+/** Fields added after schema version 1 shipped: written on every new row, optional when reading an older ledger. */
+const OPTIONAL_FIELDS = new Set(LATER_COLUMNS)
 const REQUIRED = ["fact_id", "kind", "raw", "quote", "extracted_by", "observed_at", "label"]
 export const ROW_FIELDS = Object.freeze([...REQUIRED, ...Object.keys(ROW_DEFAULTS)])
 
@@ -70,10 +76,16 @@ function nullOr(value, test) {
 function validateRow(row, index, errors) {
 	const at = `rows[${index}]`
 	if (!isObject(row)) return errors.push(`${at} must be an object`)
-	for (const key of ROW_FIELDS) check(errors, Object.hasOwn(row, key), `${at}.${key} is required`)
+	for (const key of ROW_FIELDS) check(errors, OPTIONAL_FIELDS.has(key) || Object.hasOwn(row, key), `${at}.${key} is required`)
 	for (const key of Object.keys(row)) check(errors, ROW_FIELDS.includes(key), `${at}.${key} is not a ledger field`)
 	check(errors, FACT_KINDS.includes(row.kind), `${at}.kind must be one of ${FACT_KINDS.join(", ")}`)
-	errors.push(...kindRuleErrors(row, at))
+	// Dimension 31 wins at read time: per-kind rules see the row as readRow normalizes it.
+	errors.push(...kindRuleErrors(readRow(row), at))
+	errors.push(...storedErrors(row).map((e) => `${at}.${e}`))
+	if (isCurrentDerived(row)) {
+		const problem = malformed(row)
+		if (problem) errors.push(`${at}: ${problem}`)
+	}
 	check(errors, row.unit === undefined || nullOr(row.unit, isNonEmpty), `${at}.unit must be null or a non-empty token`)
 	for (const key of ["raw", "quote"]) check(errors, row[key] === undefined || isString(row[key]), `${at}.${key} must be a string`)
 	check(errors, row.extracted_by === undefined || isNonEmpty(row.extracted_by), `${at}.extracted_by must be a non-empty string`)
@@ -100,6 +112,12 @@ function validateRow(row, index, errors) {
 	check(errors, row.status === undefined || FACT_STATUSES.includes(row.status), `${at}.status must be one of ${FACT_STATUSES.join(", ")}`)
 }
 
+export function rowErrors(row) {
+	const errors = []
+	validateRow(row, 0, errors)
+	return errors
+}
+
 // The status machine and event rule of references/fact-ledger-grammar.md. validateLedger replays
 // events through transitionError, and every writer in fact-ledger.mjs calls it before appending.
 export const TRANSITIONS = Object.freeze({ active: Object.freeze(["retracted", "superseded"]), retracted: Object.freeze([]), superseded: Object.freeze([]) })
@@ -163,20 +181,19 @@ export function provenanceErrors(rows) {
 		}
 	})
 	const state = new Map()
-	const visit = (id, path) => {
-		if (state.get(id) === "done") return null
-		if (state.get(id) === "open") return [...path.slice(path.indexOf(id)), id]
-		state.set(id, "open")
-		for (const next of refs.get(id)) {
-			const cycle = next !== id && refs.has(next) ? visit(next, [...path, id]) : null
-			if (cycle) return cycle
+	for (const root of refs.keys()) {
+		const stack = [{ id: root, finish: false }]
+		const path = []
+		while (stack.length) {
+			const { id, finish } = stack.pop()
+			if (state.get(id) === "done") continue
+			if (finish) { state.set(id, "done"); path.pop(); continue }
+			if (state.get(id) === "open") return [...errors, `${id} derives from itself through cycle ${[...path, id].join(" -> ")}`]
+			state.set(id, "open")
+			path.push(id)
+			stack.push({ id, finish: true })
+			for (const next of refs.get(id)) if (next !== id && refs.has(next)) stack.push({ id: next, finish: false })
 		}
-		state.set(id, "done")
-		return null
-	}
-	for (const id of refs.keys()) {
-		const cycle = visit(id, [])
-		if (cycle) return [...errors, `${cycle[0]} derives from itself through ${cycle.join(" -> ")}`]
 	}
 	return errors
 }

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

@@ -7,8 +7,9 @@ import { existsSync } from "node:fs"
 import { join } from "node:path"
 
 import { CliError, readJsonFile, writeJsonAtomic } from "./cli-support.mjs"
-import { DECIMAL, exactComesFromValue, exactFromDecimal, idPrefix, isString } from "./fact-ledger-kinds.mjs"
+import { DECIMAL, exactComesFromValue, exactFromDecimal, idPrefix, isString, readFlaws, readRow } from "./fact-ledger-kinds.mjs"
 import { LEDGER_SCHEMA_VERSION, ROW_DEFAULTS, ROW_FIELDS, transitionError, validateLedger } from "./fact-ledger-schema.mjs"
+import { normalizeInput } from "./unit-algebra.mjs"
 
 export { exactFromDecimal } from "./fact-ledger-kinds.mjs"
 export { FACT_KINDS, FACT_STATUSES, LEDGER_SCHEMA_VERSION, OPERATIONS, QUALIFIERS, ROW_FIELDS, TRANSITIONS, transitionError, validateLedger } from "./fact-ledger-schema.mjs"
@@ -24,11 +25,24 @@ function assertValid(ledger) {
 	if (errors.length > 0) throw new CliError(`invalid fact ledger: ${errors.join("; ")}`)
 }
 
+/** The row's fields in ROW_FIELDS order, then any unknown field (which validation reports). */
+function ordered(row) {
+	const out = Object.fromEntries(ROW_FIELDS.filter((key) => Object.hasOwn(row, key)).map((key) => [key, row[key]]))
+	for (const key of Object.keys(row)) if (!ROW_FIELDS.includes(key)) out[key] = row[key]
+	return out
+}
+
+/**
+ * Every row comes back as readRow normalizes it (reduced exacts and decimals; source rows with canonical
+ * units and null later columns) before any strict rule runs; the file changes on the next write.
+ */
 export function readLedger(dir) {
 	const file = join(dir, LEDGER_FILENAME)
 	if (!existsSync(file)) return emptyLedger()
 	const ledger = readJsonFile(file)
 	assertValid(ledger)
+	ledger.rows = ledger.rows.map((row) => ordered(readRow(row)))
+	assertValid(ledger)
 	return ledger
 }
 
@@ -44,12 +58,12 @@ const ID_NUMBER = Object.freeze({ F: /^F(\d+)$/, Q: /^Q(\d+)$/ })
 /** The next id with the kind's prefix from KIND_RULES (F<n> for value rows, Q<n> for quotes). */
 export function nextId(ledger, kind) {
 	const prefix = idPrefix(kind)
-	let max = 0
+	let max = 0n
 	for (const row of ledger.rows) {
 		const match = ID_NUMBER[prefix].exec(row.fact_id ?? "")
-		if (match) max = Math.max(max, Number(match[1]))
+		if (match && BigInt(match[1]) > max) max = BigInt(match[1])
 	}
-	return `${prefix}${max + 1}`
+	return `${prefix}${max + 1n}`
 }
 
 /**
@@ -60,14 +74,20 @@ export function nextId(ledger, kind) {
  */
 export function addRow(ledger, row) {
 	const filled = { ...structuredClone(ROW_DEFAULTS), ...row, fact_id: row.fact_id ?? nextId(ledger, row.kind) }
+	if (!["derived", "converted"].includes(filled.kind)) {
+		const normalized = normalizeInput(filled.unit, filled.value)
+		if (normalized.value !== filled.value && filled.exact !== null) throw new CliError("scaled input must omit exact; it is computed after normalization")
+		Object.assign(filled, readRow({ ...filled, ...normalized }))
+	}
 	if (exactComesFromValue(filled.kind) && filled.exact === null && isString(filled.value) && DECIMAL.test(filled.value)) {
 		filled.exact = exactFromDecimal(filled.value)
 	}
-	const ordered = Object.fromEntries(ROW_FIELDS.filter((key) => Object.hasOwn(filled, key)).map((key) => [key, filled[key]]))
-	for (const key of Object.keys(filled)) if (!ROW_FIELDS.includes(key)) ordered[key] = filled[key]
-	assertValid({ ...ledger, rows: [...ledger.rows, ordered] })
-	ledger.rows.push(ordered)
-	return ordered
+	const added = ordered(filled)
+	const flaws = readFlaws(added)
+	if (flaws.length > 0) throw new CliError(`invalid fact ledger: ${flaws.map((flaw) => `${flaw.shape}: ${flaw.detail}`).join("; ")}`)
+	assertValid({ ...ledger, rows: [...ledger.rows, added] })
+	ledger.rows.push(added)
+	return added
 }
 
 /** Build the event from the row's current status and append it only if transitionError allows it. */

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

@@ -0,0 +1,231 @@
+// fact-locate.mjs - deterministic fact locators over a source snapshot.
+//
+// Each locator returns { value, unit, raw, quote, value_span, sentence_id, qualifier, locator } or
+// { error: "fact_not_located" | "fact_ambiguous", candidates }; it never guesses. `quote` is the
+// whole containing sentence, cell, or line of text.txt, `value_span` is [start, end] inside
+// `quote` with quote.slice(...value_span) === raw, and locator.char_start/char_end place `quote`
+// in text.txt. Every call takes `sourceId` (S<n>) so sentence ids match sentences.jsonl.
+// Plain Node ESM, sibling imports only; no network, no OCR.
+
+import { proseText } from "./html-lite.mjs"
+import { QUALIFIERS } from "./lexicon.mjs"
+import { parseNumeral } from "./numerals.mjs"
+import { indexSentences, snapshotBlocks } from "./source-snapshot.mjs"
+import { findNormalized, normalizeText, tokenize } from "./text-normalize.mjs"
+import { similarity } from "./text-similarity.mjs"
+import { normalizeUnit } from "./units.mjs"
+
+const FIND_WINDOW = 80
+const CONTEXT = 60
+const FUZZY_FLOOR = 0.95
+const PHRASES = QUALIFIERS.map((phrase) => phrase.split(" "))
+const SINGLE_QUALIFIERS = new Set(QUALIFIERS.filter((phrase) => !phrase.includes(" ")))
+
+const notLocated = (candidates = []) => ({ error: "fact_not_located", candidates })
+const ambiguous = (candidates) => ({ error: "fact_ambiguous", candidates })
+const label = (text) => normalizeText(text).toLowerCase()
+const clean = (token) => token.replace(/^[^\p{L}\p{N}%]+|[^\p{L}\p{N}%]+$/gu, "").toLowerCase()
+const sentenceAt = (sentences, offset) => sentences.find((row) => row.start <= offset && offset < row.end) ?? null
+
+function requireSource(sourceId) {
+	if (!/^S[1-9]\d*$/.test(String(sourceId))) throw new TypeError(`sourceId must be S<n>, got ${sourceId}`)
+}
+
+/** Every normalized occurrence of `needle`, as raw [start, end) offsets. */
+function findAll(text, needle) {
+	const hits = []
+	for (let from = 0; from < text.length; ) {
+		const hit = findNormalized(text.slice(from), needle)
+		if (!hit) break
+		hits.push({ start: from + hit.start, end: from + hit.end })
+		from += hit.start + 1
+	}
+	return hits
+}
+
+function locatorFor(text, sourceId, start, end, extra = {}) {
+	const before = text.slice(0, start)
+	const pageStart = before.lastIndexOf("\f") + 1
+	const page = text.includes("\f") ? { page: before.split("\f").length } : {}
+	return { artifact: `${sourceId}/text.txt`, ...page, line: before.slice(pageStart).split("\n").length, char_start: start, char_end: end, ...extra }
+}
+
+function candidate(text, sentences, start, end) {
+	return { sentence_id: sentenceAt(sentences, start)?.sid ?? null, char_start: start, char_end: end, context: text.slice(Math.max(0, start - CONTEXT), end + CONTEXT) }
+}
+
+/** A QUALIFIERS token ending within the 2 tokens before the value, or the 1 token right after it. */
+function qualifierAround(quote, [start, end]) {
+	const before = quote.slice(0, start).split(/\s+/).filter(Boolean).map(clean)
+	for (let skip = 0; skip < 2; skip++) {
+		for (const words of PHRASES) {
+			const stop = before.length - skip
+			if (stop - words.length >= 0 && before.slice(stop - words.length, stop).join(" ") === words.join(" ")) return words.join(" ")
+		}
+	}
+	const next = /^\s*(\S+)/.exec(quote.slice(end))
+	return next && SINGLE_QUALIFIERS.has(clean(next[1])) ? clean(next[1]) : null
+}
+
+/** A located quantity: `holder` is the quote's { sid, start, end, text }, `numeral` is parsed from holder.text. */
+function quantityResult(text, sourceId, holder, numeral, extra = {}, unitFallback = null) {
+	const unit = numeral.unitRaw ? (normalizeUnit(numeral.unitRaw) ?? numeral.unitRaw) : unitFallback
+	return {
+		value: numeral.value,
+		unit,
+		raw: numeral.raw,
+		quote: holder.text,
+		value_span: [numeral.span[0], numeral.span[1]],
+		sentence_id: holder.sid,
+		qualifier: qualifierAround(holder.text, numeral.span),
+		locator: locatorFor(text, sourceId, holder.start, holder.end, extra),
+	}
+}
+
+/** --find: one anchor occurrence, then the first numeral starting within 80 chars after it in the same sentence. */
+export function locateFind(text, { find, unitExpected, sourceId }) {
+	requireSource(sourceId)
+	const sentences = indexSentences(text, sourceId)
+	const hits = findAll(text, find)
+	if (hits.length === 0) return notLocated()
+	if (hits.length > 1) return ambiguous(hits.map((hit) => candidate(text, sentences, hit.start, hit.end)))
+	const [hit] = hits
+	const sentence = sentenceAt(sentences, hit.start)
+	if (!sentence || hit.end > sentence.end) return notLocated()
+	const from = hit.end - sentence.start
+	const numeral = parseNumeral(sentence.text, from)
+	if (!numeral || numeral.span[0] - from > FIND_WINDOW) return notLocated([candidate(text, sentences, hit.start, hit.end)])
+	const result = quantityResult(text, sourceId, sentence, numeral)
+	if (unitExpected === undefined) return result
+	const expected = normalizeUnit(unitExpected) ?? unitExpected
+	return result.unit === expected ? result : { error: "unit_expected_mismatch", expected, found: result.unit, candidates: [result] }
+}
+
+function cellsOf(row) {
+	const cells = []
+	for (const cell of row.children.filter((child) => child.tag === "td" || child.tag === "th")) {
+		const span = Math.max(1, Number.parseInt(cell.attrs.colspan ?? "1", 10) || 1)
+		for (let k = 0; k < span; k++) cells.push(cell)
+	}
+	return cells
+}
+
+function rowsOf(table) {
+	const rows = []
+	const walk = (node) => {
+		for (const child of node.children) {
+			if (child.tag === "tr") rows.push(child)
+			else if (child.tag !== "table" && child.tag !== "#text") walk(child)
+		}
+	}
+	walk(table)
+	return rows
+}
+
+function tablesOf(root) {
+	const tables = []
+	const walk = (node) => {
+		for (const child of node.children) {
+			if (child.tag === "table") tables.push(child)
+			if (child.tag !== "#text") walk(child)
+		}
+	}
+	walk(root)
+	return tables.map((table) => {
+		const rows = rowsOf(table)
+		const header = rows.find((row) => row.children.some((child) => child.tag === "th")) ?? rows[0]
+		const caption = table.children.find((child) => child.tag === "caption")
+		return { table, header, rows: rows.filter((row) => row !== header), caption: caption ? label(proseText(caption)) : null }
+	})
+}
+
+const cellLabel = (cell) => label(proseText(cell))
+const indexesOf = (labels, wanted) => labels.flatMap((value, index) => (value === wanted ? [index] : []))
+
+/** --table/--row/--col: the table by id, caption, or a header label; row and column by normalized label, never by index. */
+export function locateTable(sourceHtml, { table, row, col, sourceId }) {
+	requireSource(sourceId)
+	const { root, text, blocks } = snapshotBlocks(sourceHtml)
+	const key = label(table)
+	const tables = tablesOf(root).filter((entry) => entry.table.attrs.id === table || entry.caption === key || (entry.header && cellsOf(entry.header).map(cellLabel).includes(key)))
+	if (tables.length !== 1) return tables.length === 0 ? notLocated() : ambiguous(tables.map((entry) => ({ table: entry.table.attrs.id ?? entry.caption })))
+	const [{ header, rows }] = tables
+	const headerCells = header ? cellsOf(header) : []
+	const columns = indexesOf(headerCells.map(cellLabel), label(col))
+	const matches = rows.filter((candidateRow) => cellsOf(candidateRow).length > 0 && cellLabel(cellsOf(candidateRow)[0]) === label(row))
+	if (columns.length > 1 || matches.length > 1) return ambiguous([...columns.map((index) => ({ col: index })), ...matches.map((match) => ({ row_line: match.line }))])
+	const cell = columns.length === 1 && matches.length === 1 ? cellsOf(matches[0])[columns[0]] : null
+	const block = cell ? blocks.find((entry) => entry.node === cell) : null
+	if (!block) return notLocated()
+	const holder = { sid: sentenceAt(indexSentences(text, sourceId), block.start)?.sid ?? null, start: block.start, end: block.end, text: text.slice(block.start, block.end) }
+	const numeral = parseNumeral(holder.text)
+	if (!numeral) return notLocated()
+	const headerUnit = /\(([^()]+)\)\s*$/.exec(cellLabel(headerCells[columns[0]]))
+	return quantityResult(text, sourceId, holder, numeral, { table, row_label: row, col_label: col }, headerUnit ? normalizeUnit(headerUnit[1]) : null)
+}
+
+/** --page/--line: exactly one quantity on that line of that page (pages split on a form feed). */
+export function locatePageLine(text, { page, line, sourceId }) {
+	requireSource(sourceId)
+	const pages = text.split("\f")
+	if (!Number.isInteger(page) || page < 1 || page > pages.length) return notLocated()
+	const lines = pages[page - 1].split("\n")
+	if (!Number.isInteger(line) || line < 1 || line > lines.length) return notLocated()
+	let start = pages.slice(0, page - 1).reduce((sum, body) => sum + body.length + 1, 0)
+	for (const body of lines.slice(0, line - 1)) start += body.length + 1
+	const holder = { start, end: start + lines[line - 1].length, text: lines[line - 1] }
+	const numerals = []
+	for (let numeral = parseNumeral(holder.text); numeral; numeral = parseNumeral(holder.text, numeral.span[1])) numerals.push(numeral)
+	const sentences = indexSentences(text, sourceId)
+	if (numerals.length !== 1) return numerals.length === 0 ? notLocated() : ambiguous(numerals.map((numeral) => candidate(text, sentences, start + numeral.span[0], start + numeral.span[1])))
+	holder.sid = sentenceAt(sentences, start + numerals[0].span[0])?.sid ?? null
+	return quantityResult(text, sourceId, holder, numerals[0])
+}
+
+/** Token-aligned windows of `sentence` whose similarity to `match` reaches the fuzzy floor; best first. */
+function fuzzyWindow(sentence, match) {
+	const target = normalizeText(match).length
+	const wanted = new Set(tokenize(match))
+	const present = new Set(tokenize(sentence.text))
+	if (wanted.size === 0 || [...wanted].filter((token) => present.has(token)).length / wanted.size < 0.5) return null
+	const bounds = [...sentence.text.matchAll(/[\p{L}\p{N}]+/gu)].map((m) => [m.index, m.index + m[0].length])
+	let best = null
+	for (let i = 0; i < bounds.length; i++) {
+		for (let j = i; j < bounds.length; j++) {
+			const window = sentence.text.slice(bounds[i][0], bounds[j][1])
+			if (window.length > target * 1.06 + 2) break
+			if (window.length < target * 0.94 - 2) continue
+			const score = similarity(window, match)
+			if (score >= FUZZY_FLOOR && (!best || score > best.score)) best = { score, start: sentence.start + bounds[i][0], end: sentence.start + bounds[j][1] }
+		}
+	}
+	return best
+}
+
+function quoteResult(text, sourceId, sentences, start, end, fuzzy) {
+	const first = sentenceAt(sentences, start)
+	const last = sentenceAt(sentences, end - 1) ?? first
+	return {
+		value: null,
+		unit: null,
+		raw: text.slice(start, end),
+		quote: text.slice(first.start, last.end),
+		value_span: null,
+		sentence_id: first.sid,
+		qualifier: null,
+		fuzzy,
+		locator: locatorFor(text, sourceId, first.start, last.end),
+	}
+}
+
+/** --match: a normalized exact match (fuzzy false), else the one window with similarity >= 0.95 (fuzzy true). */
+export function locateMatch(text, { match, sourceId }) {
+	requireSource(sourceId)
+	const sentences = indexSentences(text, sourceId)
+	const hits = findAll(text, match)
+	if (hits.length > 1) return ambiguous(hits.map((hit) => candidate(text, sentences, hit.start, hit.end)))
+	if (hits.length === 1) return quoteResult(text, sourceId, sentences, hits[0].start, hits[0].end, false)
+	const windows = sentences.map((sentence) => fuzzyWindow(sentence, match)).filter(Boolean)
+	if (windows.length > 1) return ambiguous(windows.map((window) => candidate(text, sentences, window.start, window.end)))
+	return windows.length === 1 ? quoteResult(text, sourceId, sentences, windows[0].start, windows[0].end, true) : notLocated()
+}