oh-my-opencode 5.1.48 → 5.1.54

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

@@ -6,18 +6,24 @@
 // rejected (major) or unlocated (minor) edit leaves its region unchanged and is listed with its
 // index and reason so the orchestrator can re-send it; every rejection reason is printed verbatim, one
 // line per rejected edit (index and the first 60 characters of its before), in the summary and in
-// data.rejected_reasons. It exits 0 whenever it wrote the output.
+// data.rejected_reasons. It exits 0 whenever it wrote the output; json.applied is false when
+// any edit was rejected or unlocated, independently of data.applied's accepted-edit count.
+// polish-apply never rewrites a fill map: it checks that the edition's map (fillMapOf) records the
+// input's bytes, refusing otherwise, and writes `<out>.polished.fill-map.json` beside the output
+// (artifact = the polished file, its hash, and polishedFrom = the fill map's path and sha256).
 // polish-diff is the whole-document backstop (polish-diff.mjs) between the pre-polish artifact
-// and any later copy; it exits 1 on a blocker. pairsChangedSince keeps only the pairs whose
-// sentence text (normalized) is not in the pre-polish artifact that a fill map names, so the
-// meaning readers re-check exactly what polish rewrote. No model, no network.
+// and any later copy; it exits 1 on a blocker. pairsChangedSince always reads the pre-polish fill
+// map (following a polished map's polishedFrom) and keeps only the pairs whose sentence text
+// (normalized) is not in the artifact it names, so the meaning readers re-check exactly what
+// changed; when that artifact no longer hashes to the map (polished in place, or edited) nothing
+// can be ruled out and every pair is kept. No model, no network.
 
 import { existsSync, readFileSync } from "node:fs"
 import { join, resolve } from "node:path"
 
 import { CliError, parseArgs, readJsonFile, sha256Of, writeJsonAtomic, writeTextAtomic } from "./cli-support.mjs"
 import { countDefects, DEFECT_CODES } from "./contracts.mjs"
-import { editionFormatOf, ledgerFrom, markdownAsHtml, sessionOf } from "./fact-commands-verify.mjs"
+import { editionFormatOf, fillMapOf, ledgerFrom, markdownAsHtml, sessionOf } from "./fact-commands-verify.mjs"
 import { extractPairs } from "./fact-pairs.mjs"
 import { lockedBrief } from "./fidelity-policy.mjs"
 import { applyEdits, POLISH_EDIT_FIELDS, validatePolishEdits } from "./polish-apply.mjs"
@@ -58,7 +64,7 @@ const rejectionLine = (entry, edit) => `  rejected edit ${entry.index} ("${befor
 function runPolishApply(args) {
 	const [report] = args.positionals
 	const { flags } = args
-	if (!report || flags.edits === undefined || flags.out === undefined) throw new CliError("usage: fact polish-apply <report.html> --edits polish-edits.json --out <report.polished.html> [--ledger F] [--brief brief.md] [--session-dir D]")
+	if (!report || flags.edits === undefined || flags.out === undefined) throw new CliError("usage: fact polish-apply <report.html> --edits polish-edits.json --out <report.polished.html> [--fill-map F] [--ledger F] [--brief brief.md] [--session-dir D]")
 	if (editionFormatOf(report, flags.format) === "md") throw new CliError("fact polish-apply takes the filled HTML edition; polish a Markdown edition through its HTML source")
 	const { refusal } = lockedBrief("fact polish-apply", flags)
 	if (refusal) return refusal
@@ -71,13 +77,18 @@ function runPolishApply(args) {
 		throw new CliError(`${flags.edits} must be an array of {${Object.keys(POLISH_EDIT_FIELDS).join(", ")}} objects: ${error.message}`)
 	}
 	const result = applyEdits(html, edits, ledgerFrom(flags))
+	const mapPath = fillMapOf(report, html, flags["fill-map"])
+	const map = mapPath === null ? null : readJsonFile(mapPath)
+	if (map !== null && map.artifact_sha256 !== sha256Of(html)) throw new CliError(`${mapPath} does not record the bytes of ${report} (artifact_sha256 differs); refusing to carry its brief binding to the polished edition`)
+	const polishedFrom = map?.polishedFrom ?? (map && { map: resolve(mapPath), sha256: sha256Of(readText(mapPath)) })
 	writeTextAtomic(flags.out, result.out)
+	if (map) writeJsonAtomic(`${resolve(flags.out)}.polished.fill-map.json`, { ...map, artifact: resolve(flags.out), artifact_sha256: sha256Of(result.out), polishedFrom })
 	const defects = [...result.rejected, ...result.unlocated].sort((a, b) => a.index - b.index).map(withSeverity)
 	const counts = { applied: result.applied.length, rejected: result.rejected.length, unlocated: result.unlocated.length }
 	const data = { out: resolve(flags.out), ...counts, applied_indexes: result.applied, input_sha256: sha256Of(html), edits_sha256: sha256Of(editsText), out_sha256: sha256Of(result.out) }
 	const rejected_reasons = result.rejected.map((entry) => rejectionLine(entry, edits[entry.index]))
 	const summary = [`fact polish-apply: ${counts.applied} applied, ${counts.rejected} rejected, ${counts.unlocated} unlocated of ${edits.length} edit(s)`, ...rejected_reasons].join("\n")
-	return { json: { command: "fact polish-apply", status: "pass", exitCode: 0, defects, data: { ...data, rejected_reasons } }, summary, exitCode: 0 }
+	return { json: { command: "fact polish-apply", status: "pass", exitCode: 0, applied: counts.rejected === 0 && counts.unlocated === 0, defects, data: { ...data, rejected_reasons } }, summary, exitCode: 0 }
 }
 
 function runPolishDiff(args) {
@@ -100,29 +111,40 @@ function runPolishDiff(args) {
 
 const pairKey = (pair) => [pair.kind, pair.sentence_key, pair.claim_id ?? "", normalizeText(pair.sentence)].join("\u0000")
 
+/** The pre-polish fill map behind --changed-since: a polished map leads to it through polishedFrom, whose sha256 it must still match. */
+function prePolishMap(mapPath) {
+	const given = readJsonFile(mapPath)
+	if (given.polishedFrom === undefined) return { path: resolve(mapPath), map: given }
+	const { map: path, sha256 } = given.polishedFrom
+	if (typeof path !== "string" || sha256Of(readText(path)) !== sha256) throw new CliError(`${path} changed after polish wrote ${mapPath}; --changed-since needs the pre-polish fill map it names`)
+	return { path, map: readJsonFile(path) }
+}
+
 /**
- * The pairs whose sentence text changed since the pre-polish artifact a fill map names: a pair is
- * kept unless the same (kind, sentence key, normalized sentence) occurs in that artifact. The map
- * must carry the artifact's `artifact_sha256` and the bytes must still match it, so the filter is
- * fail-closed on a hand-made or stale map.
+ * The pairs whose sentence text changed since the pre-polish artifact the fill map names: a pair is
+ * kept unless the same (kind, sentence key, normalized sentence) occurs in that artifact. Only bytes
+ * that still hash to the map's `artifact_sha256` narrow the set; otherwise (the report was polished
+ * in place, or edited) every pair is kept, so nothing changed escapes the meaning re-check.
  * @param {object[]} pairs extractPairs output on the polished edition
- * @param {string} mapPath the pre-polish fill map (fact fill's `<out>.fill-map.json`)
+ * @param {string} mapPath fact fill's `<out>.fill-map.json`, or polish-apply's `<out>.polished.fill-map.json`
+ * @returns {{ pairs: object[], fill_map: string, narrowed: boolean }}
  */
 export function pairsChangedSince(pairs, mapPath, ledger, claims) {
-	const map = readJsonFile(mapPath)
-	if (typeof map.artifact !== "string" || !existsSync(map.artifact)) throw new CliError(`${mapPath} names no readable pre-polish artifact`)
-	const text = readText(map.artifact)
-	if (typeof map.artifact_sha256 !== "string") throw new CliError(`${mapPath} fill map has no artifact_sha256; --changed-since needs the pre-polish hash`)
-	if (sha256Of(text) !== map.artifact_sha256) throw new CliError(`${map.artifact} changed after fill; --changed-since needs the pre-polish bytes`)
+	const { path, map } = prePolishMap(mapPath)
+	if (typeof map.artifact !== "string") throw new CliError(`${path} names no pre-polish artifact`)
+	if (typeof map.artifact_sha256 !== "string") throw new CliError(`${path} fill map has no artifact_sha256; --changed-since needs the pre-polish hash`)
+	const text = existsSync(map.artifact) ? readText(map.artifact) : null
+	if (text === null || sha256Of(text) !== map.artifact_sha256) return { pairs, fill_map: path, narrowed: false }
 	const html = map.format === "md" ? markdownAsHtml(text, map.entries, ledger).html : text
 	const before = new Map()
 	for (const pair of extractPairs(html, ledger, claims)) before.set(pairKey(pair), (before.get(pairKey(pair)) ?? 0) + 1)
-	return pairs.filter((pair) => {
+	const kept = pairs.filter((pair) => {
 		const left = before.get(pairKey(pair)) ?? 0
 		if (left === 0) return true
 		before.set(pairKey(pair), left - 1)
 		return false
 	})
+	return { pairs: kept, fill_map: path, narrowed: true }
 }
 
 /** @param {string[]} argv the arguments after `fact polish-apply` or `fact polish-diff` */

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

@@ -8,10 +8,12 @@
 // escaped HTML projection (same line numbers) and checked with its fill map, which is the only
 // record of where its values sit; LaTeX is verified through its Markdown source.
 //
-// The locked brief is re-judged here, not only at fill: the edition's fill map (--fill-map, else
-// `<report>.fill-map.json` when present) must carry the current brief's brief_sha256
-// (brief_changed), and policyErrors re-runs over every data-fact the edition carries, so an
-// edition that violates the current derived-numbers or source-floor rule fails here too.
+// The locked brief is re-judged here, not only at fill: every edition (HTML or Markdown) needs its
+// fill map (fillMapOf: --fill-map, else whichever of `<report>.fill-map.json` and the
+// `<report>.polished.fill-map.json` polish-apply writes records the edition's bytes), and that map
+// must carry the current brief's brief_sha256; no map, or another hash, is brief_changed. policyErrors
+// re-runs over every data-fact the edition carries, so an edition that violates the current
+// derived-numbers or source-floor rule fails here too.
 //
 // The delivery barrier that reads these records (and every other fidelity record) is
 // fidelity-records.mjs.
@@ -66,8 +68,8 @@ function entryHtml(text, entry, rows) {
 	if (entry.translates) return `<span data-translates="${escapeHtml(entry.translates)}">${projectMarkdownInline(body.replace(/^<!--[\s\S]*?-->\s*/u, ""))}</span>`
 	if (!row) return `<data data-fact="${escapeHtml(entry.fact_id)}">${escapeHtml(body)}</data>`
 	const quoted = row.kind === "quote" ? parseRenderedQuote(body) : null
-	if (quoted) return renderQuote(row, entry.selector ?? "full", quoted.text, "html")
-	return row.kind === "quote" ? null : renderValueHtml(row, body)
+	if (quoted) return renderQuote(row, entry.selector ?? "full", quoted.text, "html", entry.claimKind)
+	return row.kind === "quote" ? null : renderValueHtml(row, body, { mode: entry.mode, claimKind: entry.claimKind ?? null })
 }
 
 /** [from, to) of the filled text as HTML, each intact fill-map entry rebuilt as its fill element. */
@@ -149,6 +151,17 @@ const MARKDOWN_EXTENSION = /\.(md|markdown)$/iu
 /** The edition format: the explicit flag, else md for a .md or .markdown path (any case), else html. */
 export const editionFormatOf = (path, flag) => flag ?? (MARKDOWN_EXTENSION.test(path) ? "md" : "html")
 
+/**
+ * An edition's fill map path: --fill-map, else whichever of fact fill's `<report>.fill-map.json` and
+ * polish-apply's `<report>.polished.fill-map.json` records these bytes as its artifact_sha256, else the
+ * first of them that exists; null when neither exists.
+ */
+export function fillMapOf(report, text, flag) {
+	if (flag !== undefined) return flag
+	const found = [`${report}.fill-map.json`, `${report}.polished.fill-map.json`].filter((path) => existsSync(path))
+	return found.find((path) => readJsonFile(path).artifact_sha256 === sha256Of(text)) ?? found[0] ?? null
+}
+
 /** The report's format (from --format or its extension) and, for Markdown, its fill map entries. */
 export function readEdition(report, flags) {
 	const format = editionFormatOf(report, flags.format)
@@ -174,19 +187,23 @@ export function runFactVerify(args) {
 	const briefPath = flags.brief ?? join(sessionDir, "brief.md")
 	const ledger = readLedger(sessionDir)
 	const projected = edition.format === "md" ? markdownAsHtml(edition.text, edition.entries, ledger) : null
+	// The entries whose element is in the checked HTML: an HTML edition's own map, or the projection's intact entries.
+	const ownMap = flags["fill-map"] ?? `${report}.fill-map.json`
+	const fillEntries = projected ? edition.entries.filter((entry) => !projected.stale.includes(entry)) : existsSync(ownMap) ? readJsonFile(ownMap).entries : null
 	const result = checkFidelity(projected?.html ?? edition.text, {
 		ledger,
 		sourcesDir: resolve(flags.sources ?? join(sessionDir, "sources")),
 		claims: flags.claims !== undefined || existsSync(claimsPath) ? readJsonFile(claimsPath) : null,
 		fillMap: projected?.stale ?? edition.entries,
+		fillEntries,
 		brief: existsSync(briefPath) ? readText(briefPath) : "",
 		baseDir: dirname(resolve(report)),
 		recompute,
 	})
 	const checked = projected?.html ?? edition.text
 	const pointers = [...checked.matchAll(/\bdata-fact="([^"]+)"/gu)].map((match) => ({ token: match[0], start: match.index, parsed: { id: match[1] } }))
-	const mapPath = flags["fill-map"] ?? `${report}.fill-map.json`
-	const bound = existsSync(mapPath) ? briefBindingErrors(readJsonFile(mapPath), mapPath, parsed) : []
+	const mapPath = fillMapOf(report, edition.text, flags["fill-map"])
+	const bound = briefBindingErrors(mapPath === null ? null : readJsonFile(mapPath), mapPath ?? `${report}.fill-map.json`, parsed)
 	const defects = [...bound, ...policyErrors(checked, pointers, ledger, sessionDir, policy).errors, ...result.defects]
 	const counts = countDefects(defects)
 	const status = defects.some(blocksDelivery) ? "fail" : "pass"

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

@@ -10,11 +10,14 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join, resolve } from "node:path"
 
 import { CliError, parseArgs, sha256Of } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { alteredIn } from "./conversion-probe.mjs"
 import { derive } from "./fact-derive.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 { exportRows } from "./fidelity-values.mjs"
+import { rawLocated } from "./raw-locator.mjs"
 import { pointedFlag, sessionDirOf, snapshotOf } from "./source-commands.mjs"
 
 const CONTEXT = 60
@@ -30,26 +33,30 @@ function readText(path) {
 	}
 }
 
-function nowIso(flags) {
-	const date = flags.now === undefined ? new Date() : new Date(flags.now)
+/** A caller-supplied --now value as ISO; parsing only, never the clock. */
+function isoOf(text) {
+	const date = new Date(text)
 	if (Number.isNaN(date.getTime())) throw new CliError("--now requires an ISO timestamp")
 	return date.toISOString()
 }
 
+const nowIso = (flags) => (flags.now === undefined ? new Date().toISOString() : isoOf(flags.now))
+
 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) {
+/** Every locator reads the view text (visible text nodes for a page), never raw markup. */
+function locate(flags, view, 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 (quote) return locateMatch(view.text, { match: flags.match, sourceId })
+	if (flags.find !== undefined) return locateFind(view.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 (view.root === null) throw new CliError(`source ${id} is not an HTML page snapshot; --table needs one`)
+		return locateTable(view, { 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 })
+	if (flags.page !== undefined) return locatePageLine(view.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")
 }
 
@@ -76,11 +83,17 @@ function runAdd(args, quote) {
 	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)
+	const { meta, view, sha256, drift } = snapshotOf(sessionDir, id)
+	const converted = view.mode === "converted"
+	if (drift.length > 0) return failure(command, "snapshot_hash_mismatch", { message: `${id}: ${drift.join("; ")}` })
+	if (view.mode === "legacy") return failure(command, "snapshot_not_raw", { message: `${id} is a legacy text.txt snapshot without raw.bin; snapshot the source again under a new id` })
+	if (converted && !quote) return failure(command, "snapshot_not_raw", { message: `${id} is converted-only (no raw bytes); measured rows need source snapshot --raw <original> --text <extraction>` })
+	const located = locate(flags, view, id, quote)
+	const found = rawLocated(view, located)
 	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 altered = alteredIn(join(sessionDir, "sources", id), [found.raw, found.quote])
+	if (altered.length > 0) return failure(command, "conversion_altered_number", { message: `${id}'s conversion altered ${[...new Set(altered)].join(", ")} (sources/${id}/conversion.json); the converted text cannot back this number, even where the source also shows it unaltered: write a verified text of the source and run \`source snapshot --id ${id} --text <verified.txt> --replace\`, then add the fact again`, tokens: altered, hint: DEFECT_CODES.conversion_altered_number.hint })
 	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)
@@ -89,9 +102,10 @@ function runAdd(args, quote) {
 		...(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,
+		context: found.context,
 		source_id: id,
 		locator: { ...found.locator, source_kind: meta.kind, url: meta.url, host, pointed: pointedFlag(sessionDir, meta.url) },
-		snapshot_sha256: meta.sha256,
+		snapshot_sha256: sha256,
 		sentence_id: found.sentence_id ?? null,
 		extracted_by: meta.extractor,
 		observed_at: nowIso(flags),
@@ -104,11 +118,14 @@ function runAdd(args, quote) {
 		fuzzy: found.fuzzy === true,
 	})
 	writeLedger(sessionDir, ledger)
-	const context = contextOf(snapshot.text, row)
-	const json = { command, status: "pass", exitCode: 0, defects: [], data: { row, context } }
+	const context = contextOf(view.text, located)
+	const { severity, integrity } = DEFECT_CODES.quote_converted_only
+	const defects = converted ? [{ code: "quote_converted_only", severity, integrity, message: `${id} is converted-only; the quote is not bound to the original fetched bytes` }] : []
+	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 }
+	const warnings = defects.map((defect) => `\n  warning ${defect.code}: ${defect.message}`).join("")
+	return { text: `${row.fact_id} ${row.label}: ${shown} [${id} ${row.sentence_id ?? "-"}]\n  ...${context.before}[${context.match}]${context.after}...${warnings}`, exitCode: 0 }
 }
 
 function runRetract(args) {
@@ -157,11 +174,13 @@ function runExport(args) {
 function runDerive(args) {
 	const { flags } = args
 	const op = args.required("op")
+	// Time is the caller's: without --now the CLI refuses with the library's missing_now code (exit 2) and never reads the clock.
+	if (flags.now === undefined) throw new CliError("missing_now: fact derive needs --now <ISO timestamp> (the row's observed_at); no row written")
 	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]])) }
+	const spec = { op, now: isoOf(flags.now), ...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

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

@@ -3,7 +3,7 @@ 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 { canonicalUnit, inputScale, refuse, RuleError } 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"
@@ -29,7 +29,11 @@ function declaredUnit(spec, rule) {
 	return canonicalUnit(declared)
 }
 
+/** Refused before any work, under its own code: time is the caller's (spec.now), never the clock. */
+const MISSING_NOW = Object.freeze({ error: "missing_now", shape: "missing_now", expected: "an ISO timestamp in spec.now", detail: "derive needs a caller-supplied now timestamp" })
+
 export function derive(ledger, spec) {
+	if (object(spec) && typeof spec.now !== "string") return { ...MISSING_NOW }
 	try {
 		if (!object(spec)) refuse("spec must be an object")
 		const errors = validateLedger(ledger)
@@ -54,13 +58,14 @@ export function derive(ledger, spec) {
 		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(),
+			observed_at: spec.now,
 			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) {
+		if (!(error instanceof RuleError)) throw error
 		return { error: "incompatible_operands", ...refusal(error) }
 	}
 }

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

@@ -9,6 +9,7 @@ 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"
+import { CLAIM_KINDS } from "./claim-kinds.mjs"
 
 /** The output formats fill renders. */
 export const FILL_FORMATS = Object.freeze(["html", "md"])
@@ -24,7 +25,7 @@ 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 }
+	return { row, parsed, visible: text, rendered: format === "html" ? renderValueHtml(row, text, { mode: parsed.mode, claimKind: parsed.claimKind ?? null }) : text }
 }
 
 function resolveQuote(row, parsed, format) {
@@ -33,17 +34,18 @@ function resolveQuote(row, parsed, format) {
 	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)
+	const rendered = renderQuote(row, parsed.selector, selection.text, format, parsed.claimKind)
 	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 }
+	if (parsed.error) return { code: "unresolved_placeholder", message: `${parsed.error}; for literal opening braces, write {{ instead of {{ (including in code spans)` }
 	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}"` }
+	if (parsed.claimKind && !CLAIM_KINDS[parsed.claimKind].rowKinds.includes(row.kind)) return { code: CLAIM_KINDS[parsed.claimKind].defect, message: `${parsed.claimKind} does not accept a ${row.kind} row (${parsed.id})` }
 	return parsed.kind === "Q" ? resolveQuote(row, parsed, format) : resolveValue(row, parsed, format)
 }
 
@@ -146,7 +148,7 @@ function assemble(text, parts, context) {
 		flush(part.start)
 		const start = context.out.length
 		if (part.parsed) {
-			const extra = part.selector === undefined ? {} : { selector: part.selector, quote_span: part.quote_span }
+			const extra = { ...(part.selector === undefined ? {} : { selector: part.selector, quote_span: part.quote_span }), ...(part.parsed.claimKind ? { claimKind: part.parsed.claimKind } : {}), ...(part.parsed.mode === "value" ? { mode: "value" } : {}) }
 			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 })

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

@@ -3,7 +3,6 @@
 // per-kind choices (id prefix, measured exact) from it, and the per-kind table in
 // references/fact-ledger-grammar.md is rendered from it (`node fact-ledger-kinds.mjs --render-grammar`).
 // 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"
@@ -15,7 +14,6 @@ export const DECIMAL = /^-?\d+(?:\.\d+)?$/
 const INTEGER = /^-?\d+$/
 const SHA256 = /^[0-9a-f]{64}$/
 const SOURCE_ID = /^S\d+$/
-
 export const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
 export const isString = (value) => typeof value === "string"
 export const isNonEmpty = (value) => typeof value === "string" && value.length > 0
@@ -48,6 +46,7 @@ export function locatorErrors(locator, at) {
 	const errors = []
 	if (!isObject(locator)) return errors
 	if (!isNonEmpty(locator.artifact)) errors.push(`${at}.artifact must be a non-empty string`)
+	if (locator.unit !== undefined && locator.unit !== "bytes") errors.push(`${at}.unit must be bytes`)
 	if (!(isCount(locator.char_start) && isCount(locator.char_end) && locator.char_start <= locator.char_end)) errors.push(`${at}.char_start/char_end must be integers with start <= end`)
 	for (const key of ["page", "line"]) {
 		if (locator[key] !== undefined && !(Number.isInteger(locator[key]) && locator[key] >= 1)) errors.push(`${at}.${key} must be an integer >= 1`)
@@ -87,6 +86,7 @@ export const RULES = Object.freeze({
 	rational_or_null: { cell: "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) },
+	source_context: { cell: "quote context or null (legacy)", says: "null or { prefix, suffix } up to 32 characters each", test: orNull((v) => isObject(v) && Object.keys(v).sort().join(",") === "prefix,suffix" && [v.prefix, v.suffix].every((s) => isString(s) && [...s].length <= 32)) },
 	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 },
@@ -101,14 +101,13 @@ const unsourced = { source_id: "source_or_null", locator: "locator_or_null", sna
 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", context: "null", operation: "null" }),
-	quote: row({ fact_id: "q_id", value: "null", ...sourced, rationale: "string_or_null", exact: "null", context: "null", operation: "null" }),
+	measured: row({ fact_id: "f_id", value: "decimal", ...sourced, rationale: "string_or_null", exact: "from_value", context: "source_context", operation: "null" }),
+	quote: row({ fact_id: "q_id", value: "null", ...sourced, rationale: "string_or_null", exact: "null", context: "source_context", 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. */
 export function idPrefix(kind) {
 	return RULES[KIND_RULES[kind]?.fact_id ?? "f_id"].prefix
 }
@@ -169,7 +168,7 @@ const carriesDerivation = (row) => row.operation !== null || row.operands?.lengt
 /** 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)
+	const value = isString(row.value) ? readDecimal(row.value).replace(/^-(0+(?:\.0+)?)$/, "$1") : 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`
 }
@@ -212,7 +211,7 @@ export function kindRuleErrors(candidate, at) {
 		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 (column === "exact" && rules[column] !== "null" && 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}`))

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

@@ -1,10 +1,12 @@
-// fact-locate.mjs - deterministic fact locators over a source snapshot.
+// fact-locate.mjs - deterministic fact locators over a source snapshot's locator text.
 //
 // 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.
+// whole containing sentence, cell, or line of the view text (source-view.mjs: the visible text
+// nodes of a page, never markup), `value_span` is [start, end] inside `quote` with
+// quote.slice(...value_span) === raw, and locator.char_start/char_end place `quote` in that text;
+// raw-locator.mjs turns them into bytes. Every call takes `sourceId` (S<n>) so sentence ids match
+// sentences.jsonl, which indexes the same text.
 // Plain Node ESM, sibling imports only; no network, no OCR.
 
 import { proseText } from "./html-lite.mjs"
@@ -101,7 +103,8 @@ export function locateFind(text, { find, unitExpected, sourceId }) {
 	return result.unit === expected ? result : { error: "unit_expected_mismatch", expected, found: result.unit, candidates: [result] }
 }
 
-function cellsOf(row) {
+/** A row's cells by visual column (a colspan cell repeats). */
+export 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)
@@ -110,7 +113,7 @@ function cellsOf(row) {
 	return cells
 }
 
-function rowsOf(table) {
+export function rowsOf(table) {
 	const rows = []
 	const walk = (node) => {
 		for (const child of node.children) {
@@ -142,10 +145,13 @@ function tablesOf(root) {
 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 }) {
+/**
+ * --table/--row/--col: the table by id, caption, or a header label; row and column by normalized label,
+ * never by index. `source` is page html or an extracted view ({ root, text, blocks }) of one.
+ */
+export function locateTable(source, { table, row, col, sourceId }) {
 	requireSource(sourceId)
-	const { root, text, blocks } = snapshotBlocks(sourceHtml)
+	const { root, text, blocks } = typeof source === "string" ? snapshotBlocks(source) : source
 	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 })))

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fidelity-claims.mjs

@@ -14,6 +14,7 @@
 import { CLAIM_ATTRIBUTE, CLAIM_KINDS, claimSatisfied, unmarkedKinds, unmarkedRequires } from "./claim-kinds.mjs"
 import { proseSentences } from "./fidelity-binding.mjs"
 import { clip } from "./fidelity-trace.mjs"
+import { isClaimSegment } from "./sources-citation.mjs"
 import { proseText } from "./html-lite.mjs"
 
 const marked = (node) => node.attrs?.[CLAIM_ATTRIBUTE] !== undefined
@@ -63,7 +64,7 @@ export function claimChecks(ctx, rows, provenanceOf, flag) {
 		const id = fact.attrs["data-fact"]
 		if (!nearest) {
 			const need = unmarkedRequires(rows.get(id))
-			const mark = need && `{{${CLAIM_KINDS[need].prefix}:${id}}} (${CLAIM_ATTRIBUTE}="${need}")`
+			const mark = need && `{{${CLAIM_KINDS[need].prefix}:${id}:${rows.get(id).label}}} (${CLAIM_ATTRIBUTE}="${need}")`
 			if (need) flag("claim_kind_mismatch", fact, `${id} is a ${rows.get(id).kind} row cited with no mark; an unmarked numeral reads as a fact, so mark it ${mark}`)
 			continue
 		}
@@ -77,8 +78,8 @@ export function claimChecks(ctx, rows, provenanceOf, flag) {
 		flag(entry.defect, fact, `${row.fact_id} is marked ${name}, but it is a ${row.kind} row${source}`)
 	}
 	for (const block of proseSentences(ctx)) {
-		if (block.kind === "sources" || block.kind === "toc") continue
-		for (const sentence of block.sentences) {
+		if (block.kind === "toc") continue
+		for (const sentence of block.kind === "sources" ? block.sentences.filter((s) => isClaimSegment(s.text)) : block.sentences) {
 			for (const name of unmarkedKinds(sentence.text)) {
 				const covered = sentence.facts.length > 0 ? sentence.facts.every((fact) => nearestKind(fact.node) === name) : nearestKind(block.owner) === name
 				if (covered) continue

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fidelity-csv.mjs

@@ -0,0 +1,32 @@
+// Read fact export CSV records, including quoted commas, escaped quotes and newlines.
+import { existsSync, readFileSync } from "node:fs"
+
+export function readCsv(path) {
+	if (!existsSync(path)) return null
+	const text = readFileSync(path, "utf8")
+	const records = []
+	let cells = []
+	let cell = ""
+	let quoted = false
+	for (let i = 0; i <= text.length; i++) {
+		const char = text[i]
+		if (char === '"') {
+			if (quoted && text[i + 1] === '"') {
+				cell += '"'
+				i++
+			} else quoted = !quoted
+		} else if (!quoted && (char === "," || char === "\n" || char === undefined)) {
+			cells.push(cell.trim())
+			cell = ""
+			if (char !== ",") {
+				if (cells.some((value) => value !== "")) records.push(cells)
+				cells = []
+			}
+		} else if (char !== undefined) cell += char
+	}
+	if (quoted) return null
+	const [head = [], ...rows] = records
+	const [id, value, unit] = ["fact_id", "plot_value", "unit"].map((name) => head.indexOf(name))
+	if (id < 0 || value < 0 || unit < 0 || rows.length === 0) return null
+	return rows.map((c) => ({ fact_id: c[id], plot_value: c[value], unit: c[unit] ?? "" }))
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fidelity-lexicon.mjs

@@ -4,7 +4,7 @@
 // causality_added, qualifier_dropped (six-token window around the fact span; a :q rendering puts
 // the qualifier inside the span), scope_widened_warn, and the acronym-aware name_outside_quote.
 // The hedge-position heuristic never yields a code; it only sets force_strong for the meaning
-// verifier, as do name_outside_quote and scope_widened_warn. Latin terms match whole words (terms
+// verifier; name_outside_quote and scope_widened_warn also emit minor defects. Latin terms match whole words (terms
 // of four or more letters also match their inflections); Korean terms match as substrings, single
 // syllables as tokens. No model, no IO. Plain Node ESM; Korean strings are \u escapes.