lazycodex-ai 5.1.44 → 5.1.46

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

@@ -0,0 +1,221 @@
+// fact-ledger-schema.mjs - the fact ledger's vocabulary and validation: row fields and defaults,
+// kinds, statuses, qualifiers, and validateLedger over rows, status events, and their history.
+// The grammar it encodes is references/fact-ledger-grammar.md; every per-kind column rule lives in
+// 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, 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"
+
+export const LEDGER_SCHEMA_VERSION = 1
+export const FACT_KINDS = Object.freeze(["measured", "quote", "derived", "assumed", "converted"])
+export const FACT_STATUSES = Object.freeze(["active", "superseded", "retracted"])
+export const OPERATIONS = Object.freeze(["sum", "diff", "growth", "ratio", "share", "convert", "expr"])
+/** Canonical qualifier terms; surface forms in either language map onto these. */
+export const QUALIFIERS = Object.freeze([
+	"upper_inclusive",
+	"lower_inclusive",
+	"approximate",
+	"near",
+	"lower_exclusive",
+	"upper_exclusive",
+])
+
+export const ROW_DEFAULTS = Object.freeze({
+	value: null,
+	unit: null,
+	value_span: null,
+	source_id: null,
+	locator: null,
+	locate_hint: null,
+	snapshot_sha256: null,
+	valid_at: null,
+	qualifier: null,
+	entity: null,
+	sentence_id: null,
+	observation_id: null,
+	fuzzy: false,
+	outside_floor: false,
+	population: null,
+	missing_rule: null,
+	accounting_basis: null,
+	snapshot_window: null,
+	revision: null,
+	exact: null,
+	render: null,
+	operation: null,
+	operands: [],
+	derived_from: [],
+	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)])
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+const LABEL = /^[a-z0-9_-]{1,32}$/
+const FACT_REF = /^[FQ]\d+$/
+
+function check(errors, condition, message) {
+	if (!condition) errors.push(message)
+}
+
+function nullOr(value, test) {
+	return value === null || test(value)
+}
+
+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, 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(", ")}`)
+	// 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`)
+	check(errors, row.observed_at === undefined || (isString(row.observed_at) && ISO_DATE.test(row.observed_at)), `${at}.observed_at must be an ISO timestamp`)
+	check(errors, row.label === undefined || (isString(row.label) && LABEL.test(row.label)), `${at}.label must match [a-z0-9_-]{1,32}`)
+	const span = row.value_span
+	check(errors, span === undefined || nullOr(span, (v) => Array.isArray(v) && v.length === 2 && v.every(isCount) && v[0] <= v[1]), `${at}.value_span must be null or [start, end]`)
+	for (const key of ["locate_hint", "valid_at", "entity", "observation_id", "missing_rule", "accounting_basis", "formula", "render"]) {
+		if (row[key] !== undefined) check(errors, nullOr(row[key], isString), `${at}.${key} must be null or a string`)
+	}
+	for (const key of ["population", "snapshot_window", "revision"]) {
+		if (row[key] !== undefined) check(errors, nullOr(row[key], (v) => isString(v) || isObject(v)), `${at}.${key} must be null, a string, or an object`)
+	}
+	if (row.qualifier !== undefined) check(errors, nullOr(row.qualifier, (v) => QUALIFIERS.includes(v)), `${at}.qualifier must be null or one of ${QUALIFIERS.join(", ")}`)
+	if (row.sentence_id !== undefined) check(errors, nullOr(row.sentence_id, (v) => isString(v) && /^S\d+:s\d+$/.test(v)), `${at}.sentence_id must be null or S<n>:s<k>`)
+	for (const key of ["fuzzy", "outside_floor"]) {
+		if (row[key] !== undefined) check(errors, typeof row[key] === "boolean", `${at}.${key} must be a boolean`)
+	}
+	if (row.operation !== undefined) check(errors, nullOr(row.operation, (v) => OPERATIONS.includes(v)), `${at}.operation must be null or one of ${OPERATIONS.join(", ")}`)
+	for (const key of ["operands", "derived_from"]) {
+		if (row[key] !== undefined) check(errors, Array.isArray(row[key]) && row[key].every((v) => isString(v) && FACT_REF.test(v)), `${at}.${key} must be an array of fact ids`)
+	}
+	if (row.factor !== undefined) check(errors, nullOr(row.factor, (v) => isString(v) && DECIMAL.test(v)), `${at}.factor must be null or a decimal string`)
+	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([]) })
+const EVENT_FIELDS = Object.freeze(["fact_id", "from", "to", "replacement", "reason"])
+
+/**
+ * @param {Map<string, string>} statuses each fact's status at the event's position
+ * @returns {string | null} why the event is not a legal transition, or null
+ */
+export function transitionError(statuses, event) {
+	if (!isObject(event)) return "an event must be an object"
+	const id = event.fact_id
+	if (!statuses.has(id)) return `no ledger row ${id}`
+	if (EVENT_FIELDS.some((key) => !Object.hasOwn(event, key)) || Object.keys(event).some((key) => !EVENT_FIELDS.includes(key))) {
+		return `${id}: an event has exactly the fields ${EVENT_FIELDS.join(", ")}`
+	}
+	const current = statuses.get(id)
+	if (event.from !== current) return `${id} is ${current}, but the event moves it from ${event.from}`
+	if (!TRANSITIONS[current].includes(event.to)) return `${id} cannot move from ${current} to ${event.to}`
+	if (event.to === "superseded") {
+		if (event.replacement === null) return `supersede ${id} needs a replacement row; use retract for a fact with no replacement`
+		if (event.replacement === id) return `${id} cannot be its own replacement`
+		if (!statuses.has(event.replacement)) return `no replacement row ${event.replacement} for ${id}`
+		if (statuses.get(event.replacement) !== "active") return `replacement row ${event.replacement} is ${statuses.get(event.replacement)} (superseding ${id})`
+	} else if (event.replacement !== null) return `${id} is ${event.to} but names replacement ${event.replacement}`
+	if (!isNonEmpty(event.reason)) return `a reason is required to mark ${id} ${event.to}`
+	return null
+}
+
+/** Replay every event from all-active; each row's status must be where its event chain leaves it. */
+function validateHistory(ledger, errors) {
+	const statuses = new Map(ledger.rows.filter(isObject).map((row) => [row.fact_id, "active"]))
+	const counts = new Map()
+	ledger.events.forEach((event, index) => {
+		const problem = transitionError(statuses, event)
+		if (problem) errors.push(`events[${index}]: ${problem}`)
+		if (!isObject(event) || !statuses.has(event.fact_id) || !FACT_STATUSES.includes(event.to)) return
+		statuses.set(event.fact_id, event.to)
+		counts.set(event.fact_id, (counts.get(event.fact_id) ?? 0) + 1)
+	})
+	ledger.rows.forEach((row, index) => {
+		if (!isObject(row) || !FACT_STATUSES.includes(row.status)) return
+		const to = statuses.get(row.fact_id)
+		if (!counts.has(row.fact_id)) check(errors, row.status === "active", `rows[${index}]: ${row.fact_id} is ${row.status} but has no status event`)
+		else check(errors, to === row.status, `rows[${index}]: ${row.fact_id} has status ${row.status} but its last event moves it to ${to}`)
+	})
+}
+
+/** operands and derived_from name existing rows, never the row itself, and close no cycle. */
+export function provenanceErrors(rows) {
+	const errors = []
+	const refs = new Map()
+	for (const row of rows) if (isObject(row)) refs.set(row.fact_id, [row.operands, row.derived_from].flatMap((list) => (Array.isArray(list) ? list : [])))
+	rows.forEach((row, index) => {
+		for (const key of ["operands", "derived_from"]) {
+			if (!isObject(row) || !Array.isArray(row[key])) continue
+			for (const ref of row[key]) {
+				if (ref === row.fact_id) errors.push(`rows[${index}].${key}: ${ref} references itself`)
+				else check(errors, refs.has(ref), `rows[${index}].${key}: ${row.fact_id} references ${ref}, which has no ledger row`)
+			}
+		}
+	})
+	const state = new Map()
+	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 })
+		}
+	}
+	return errors
+}
+
+/** @returns {string[]} every schema error; empty when the ledger is valid. */
+export function validateLedger(ledger) {
+	const errors = []
+	if (!isObject(ledger)) return ["ledger must be an object"]
+	check(errors, ledger.schemaVersion === LEDGER_SCHEMA_VERSION, `schemaVersion must be ${LEDGER_SCHEMA_VERSION}`)
+	if (!Array.isArray(ledger.rows)) return [...errors, "rows must be an array"]
+	ledger.rows.forEach((row, index) => validateRow(row, index, errors))
+	const ids = new Set()
+	const labels = new Set()
+	ledger.rows.forEach((row, index) => {
+		if (!isObject(row)) return
+		check(errors, !ids.has(row.fact_id), `rows[${index}].fact_id ${row.fact_id} is a duplicate`)
+		check(errors, row.label === undefined || !labels.has(row.label), `rows[${index}]: ${row.fact_id} has duplicate label ${row.label}`)
+		ids.add(row.fact_id)
+		labels.add(row.label)
+	})
+	errors.push(...provenanceErrors(ledger.rows))
+	if (Array.isArray(ledger.events)) validateHistory(ledger, errors)
+	else errors.push("events must be an array")
+	return errors
+}

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

@@ -0,0 +1,123 @@
+// fact-ledger.mjs - the verbatim fact ledger: one row per measured, quoted, derived, assumed,
+// or converted value, with its source locator and exact rational. Rows are never deleted:
+// retract and supersede change status and append an event. Validation and the field vocabulary
+// live in fact-ledger-schema.mjs and are re-exported here. node: builtins only.
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+
+import { CliError, readJsonFile, writeJsonAtomic } from "./cli-support.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"
+
+export const LEDGER_FILENAME = "fact-ledger.json"
+
+export function emptyLedger() {
+	return { schemaVersion: LEDGER_SCHEMA_VERSION, rows: [], events: [] }
+}
+
+function assertValid(ledger) {
+	const errors = validateLedger(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
+}
+
+export function writeLedger(dir, ledger) {
+	assertValid(ledger)
+	const file = join(dir, LEDGER_FILENAME)
+	writeJsonAtomic(file, ledger)
+	return file
+}
+
+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 = 0n
+	for (const row of ledger.rows) {
+		const match = ID_NUMBER[prefix].exec(row.fact_id ?? "")
+		if (match && BigInt(match[1]) > max) max = BigInt(match[1])
+	}
+	return `${prefix}${max + 1n}`
+}
+
+/**
+ * Fill defaults, assign the next id, validate the whole ledger (provenance included), then append.
+ * Only kinds whose KIND_RULES exact is from_value (measured) get exact from their decimal:
+ * derived and converted rows carry the exact that derive computed from the operands and factor,
+ * never one read back from the rounded value.
+ */
+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 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. */
+function changeStatus(ledger, id, to, replacement, reason) {
+	const row = ledger.rows.find((candidate) => candidate.fact_id === id)
+	const event = { fact_id: id, from: row?.status ?? null, to, replacement: replacement ?? null, reason }
+	const problem = transitionError(new Map(ledger.rows.map((candidate) => [candidate.fact_id, candidate.status])), event)
+	if (problem) throw new CliError(problem)
+	ledger.events.push(event)
+	row.status = to
+	return row
+}
+
+export function retractRow(ledger, id, reason) {
+	return changeStatus(ledger, id, "retracted", null, reason)
+}
+
+export function supersedeRow(ledger, id, replacementId, reason) {
+	return changeStatus(ledger, id, "superseded", replacementId, reason)
+}
+
+function cell(value) {
+	return value === null || value === undefined ? "" : String(value).replace(/\|/g, "\\|").replace(/\n/g, " ")
+}
+
+/** The `--view` table: one line per row, retracted and superseded rows included. */
+export function renderLedgerMarkdown(ledger) {
+	const lines = ["| fact_id | kind | label | value | unit | source | status | raw |", "|---|---|---|---|---|---|---|---|"]
+	for (const row of ledger.rows) {
+		lines.push(`| ${[row.fact_id, row.kind, row.label, row.value, row.unit, row.source_id, row.status, row.raw].map(cell).join(" | ")} |`)
+	}
+	return `${lines.join("\n")}\n`
+}

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()
+}