oh-my-opencode 5.1.48 → 5.1.51

package/packages/omo-codex/plugin/skills/ulw-research/scripts/css-hiding.mjs

@@ -0,0 +1,158 @@
+// css-hiding.mjs - whether CSS hides an element of a page from every reader, from its inline style and
+// the page's own <style> rules (external stylesheets and scripts are not evaluated).
+//
+// Text counts as reader-visible when it is visible under at least one condition. So a rule can hide
+// only when it certainly applies: it sits outside every at-rule except @layer (and @media all), its
+// <style> element applies everywhere (no media other than all, CSS type, not in <noscript>), and its
+// selector is one tag (case-insensitive), one .class or one #id (case-sensitive). A rule that only
+// might apply (inside @media, @supports, @container, @scope, @starting-style, @document, @keyframes,
+// nested in another style rule, or with a compound, combinator, attribute or pseudo-class selector)
+// never hides, but it can make text visible when its subject could match and it outranks the hiding
+// declaration in the cascade (origin and importance, inline style, layer order, specificity, order).
+// Hiding properties: display:none and content-visibility:hidden remove the subtree;
+// visibility:hidden|collapse is inherited and a descendant's visibility:visible shows it again.
+// The hidden attribute (except hidden="until-found") and a closed <dialog> are the user-agent
+// display:none, which any author display declaration overrides. opacity, clip, zero size, font-size,
+// off-screen positions and colors do not hide: the text still renders or is read aloud.
+// Plain Node ESM, sibling imports only.
+
+import { scanRules } from "./css-lite.mjs"
+
+const PROPS = new Set(["display", "visibility", "content-visibility"])
+const INHERITED = new Set(["inherit", "unset", "revert", "revert-layer"])
+const IMPORTANT = /!\s*important\s*$/i
+const SIMPLE = /^(?:[.#][^\s.#:[\]>+~,()*"'\\]+|[a-z][a-z0-9-]*)$/iu
+const PSEUDO_ELEMENT = /::|:(?:before|after|first-line|first-letter)\b/i
+const NAME = "[^\\s.#:[\\]>+~,()*\"'\\\\]+"
+const STYLE_IN_SVG = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi
+
+/** [tier (0 user agent, 1 author, 2 author !important), inline, layer, specificity, order]: higher wins. */
+const outranks = (a, b) => {
+	for (let k = 0; k < a.length; k++) if (a[k] !== b[k]) return a[k] > b[k]
+	return false
+}
+
+function specificity(selector) {
+	const core = selector.replace(/\[[^\]]*\]/g, " [] ")
+	const ids = core.match(new RegExp(`#${NAME}`, "gu"))?.length ?? 0
+	const classes = (core.match(new RegExp(`\\.${NAME}`, "gu"))?.length ?? 0) + (core.match(/\[\]|:(?!:)[\w-]+/g)?.length ?? 0)
+	const tags = core.match(/(?:^|[\s>+~(])[a-z][\w-]*/gi)?.length ?? 0
+	return ids * 10000 + classes * 100 + tags
+}
+
+/** The subject compound of a selector: its tag, classes and ids (attribute and pseudo-class parts dropped). */
+function subject(selector) {
+	const compound = selector.trim().match(/(?:[^\s>+~[\]()]|\[[^\]]*\]|\([^)]*\))+$/)?.[0] ?? ""
+	const core = compound.replace(/\([^)]*\)/g, "").replace(/\[[^\]]*\]/g, "").replace(/:+[\w-]+/g, "")
+	const tag = core.match(/^[a-z][a-z0-9-]*/i)?.[0].toLowerCase() ?? null
+	const classes = [...core.matchAll(new RegExp(`\\.(${NAME})`, "gu"))].map((match) => match[1])
+	const ids = [...core.matchAll(new RegExp(`#(${NAME})`, "gu"))].map((match) => match[1])
+	return { tag, classes, ids, key: ids[0] ? `#${ids[0]}` : classes[0] ? `.${classes[0]}` : tag ?? "*" }
+}
+
+const classList = (node) => String(node.attrs?.class ?? "").split(/[ \t\n\f\r]+/).filter(Boolean)
+
+function matches(sub, node) {
+	if (sub.tag !== null && sub.tag !== node.tag) return false
+	const names = classList(node)
+	return sub.classes.every((name) => names.includes(name)) && sub.ids.every((id) => id === node.attrs?.id)
+}
+
+/** Whether every enclosing at-rule leaves the rule unconditional (@layer, @media all), its layer name, and keyframe steps. */
+function context(atRule) {
+	const entries = atRule ? atRule.split(/\s(?=@)/) : []
+	const layers = entries.filter((entry) => /^@layer\b/i.test(entry)).map((entry) => entry.slice(6).trim())
+	const conditional = entries.some((entry) => !/^@layer\b/i.test(entry) && !/^@media(?:\s+all)?\s*$/i.test(entry))
+	return { conditional, layer: layers.length ? layers.join(".") : null, keyframe: entries.some((entry) => /^@(?:-[a-z]+-)?keyframes\b/i.test(entry)) }
+}
+
+const declaration = (value) => ({ value: value.replace(IMPORTANT, "").trim().toLowerCase(), important: IMPORTANT.test(value) })
+
+/** Every <style> text that applies to the page, with whether it applies only under a condition. */
+function sheets(root) {
+	const found = []
+	const visit = (node, conditional) => {
+		if (node.tag === "template") return
+		const inner = conditional || node.tag === "noscript"
+		if (node.tag === "style") {
+			const type = String(node.attrs?.type ?? "").trim().toLowerCase()
+			const media = String(node.attrs?.media ?? "").trim().toLowerCase()
+			if (type === "" || type === "text/css") found.push({ css: String(node.raw ?? ""), conditional: inner || (media !== "" && media !== "all") })
+		}
+		if (node.tag === "svg") for (const match of String(node.raw ?? "").matchAll(STYLE_IN_SVG)) found.push({ css: match[1], conditional: inner })
+		for (const child of node.children ?? []) visit(child, inner)
+	}
+	visit(root, false)
+	return found
+}
+
+/** Index every rule declaring display, visibility or content-visibility by its subject key. */
+function indexRules(root) {
+	const index = new Map()
+	const layers = []
+	const layerRank = (name, important) => {
+		if (name === null) return important ? -1 : 1e6
+		if (!layers.includes(name)) layers.push(name)
+		return important ? 1e6 - layers.indexOf(name) : layers.indexOf(name)
+	}
+	let order = 0
+	for (const sheet of sheets(root)) {
+		const css = sheet.css.replace(/<!--|-->/g, " ")
+		for (const match of css.replace(/\/\*[\s\S]*?(?:\*\/|$)/g, "").matchAll(/@layer\s+([^{;]*)[{;]/gi)) {
+			for (const name of match[1].split(",").map((part) => part.trim())) if (name && !layers.includes(name)) layers.push(name)
+		}
+		for (const rule of scanRules(css)) {
+			const decls = rule.declarations.filter((entry) => PROPS.has(entry.prop))
+			if (!decls.length || rule.selector.startsWith("@")) continue
+			const { conditional, layer, keyframe } = context(rule.atRule)
+			if (keyframe) continue
+			for (const selector of rule.selector.split(/,(?![^()[\]]*[)\]])/).map((part) => part.trim())) {
+				if (!selector || PSEUDO_ELEMENT.test(selector)) continue
+				const sub = subject(selector)
+				const certain = !sheet.conditional && !conditional && !rule.nested && SIMPLE.test(selector)
+				const spec = specificity(selector)
+				for (const entry of decls) {
+					const { value, important } = declaration(entry.value)
+					const rank = [important ? 2 : 1, 0, layerRank(layer, important), spec, order++]
+					if (!index.has(sub.key)) index.set(sub.key, [])
+					index.get(sub.key).push({ sub, prop: entry.prop, value, rank, certain })
+				}
+			}
+		}
+	}
+	return index
+}
+
+/** The values a property can take on the element: the certain winner, plus every possible rule that outranks it. */
+function possible(candidates, prop) {
+	let top = null
+	for (const entry of candidates) if (entry.prop === prop && entry.certain && (top === null || outranks(entry.rank, top.rank))) top = entry
+	const values = [top === null ? "unset" : top.value]
+	for (const entry of candidates) if (entry.prop === prop && !entry.certain && (top === null || outranks(entry.rank, top.rank))) values.push(entry.value)
+	return values
+}
+
+/**
+ * cssVisibility(root) -> (node, parentShown) => null when CSS removes the element and its subtree from every
+ * rendering, else whether its own text can be seen (visibility, inherited from parentShown).
+ */
+export function cssVisibility(root) {
+	const index = indexRules(root)
+	return (node, parentShown) => {
+		const attrs = node.attrs ?? {}
+		const keys = ["*", node.tag, ...classList(node).map((name) => `.${name}`), attrs.id === undefined ? null : `#${attrs.id}`]
+		const candidates = []
+		for (const key of new Set(keys)) for (const entry of index.get(key) ?? []) if (matches(entry.sub, node)) candidates.push(entry)
+		const hiddenAttr = attrs.hidden !== undefined && String(attrs.hidden).trim().toLowerCase() !== "until-found"
+		if (hiddenAttr || (node.tag === "dialog" && attrs.open === undefined)) candidates.push({ prop: "display", value: "none", rank: [0, 0, 0, 0, -1], certain: true })
+		const inline = attrs.style ? (scanRules(`x{${attrs.style}}`)[0]?.declarations ?? []) : []
+		inline.forEach((entry, at) => {
+			if (!PROPS.has(entry.prop)) return
+			const { value, important } = declaration(entry.value)
+			candidates.push({ prop: entry.prop, value, rank: [important ? 2 : 1, 1, 0, 0, at], certain: true })
+		})
+		if (possible(candidates, "display").every((value) => value === "none")) return null
+		if (possible(candidates, "content-visibility").every((value) => value === "hidden")) return null
+		return possible(candidates, "visibility").some((value) => (INHERITED.has(value) ? parentShown : value !== "hidden" && value !== "collapse"))
+	}
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/css-lite.mjs

@@ -57,8 +57,9 @@ function parseDeclarations(text) {
 }
 
 /**
- * @returns {{ selector: string, declarations: { prop: string, value: string }[], atRule?: string }[]}
- * atRule is the chain of enclosing grouping at-rule preludes joined by a space.
+ * @returns {{ selector: string, declarations: { prop: string, value: string }[], atRule?: string, nested?: true }[]}
+ * atRule is the chain of enclosing grouping at-rule preludes joined by a space; nested is true for a
+ * rule written inside another style rule (CSS nesting).
  */
 export function scanRules(css) {
 	if (typeof css !== "string") return []
@@ -88,6 +89,7 @@ export function scanRules(css) {
 				const atChain = stack.filter((entry) => entry.group).map((entry) => entry.prelude)
 				const rule = { selector: frame.prelude, declarations: parseDeclarations(frame.body + buffer) }
 				if (atChain.length) rule.atRule = atChain.join(" ")
+				if (stack.some((entry) => !entry.group)) rule.nested = true
 				slots[frame.slot] = rule
 			}
 			buffer = ""

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

@@ -1,14 +1,23 @@
 // entities.mjs - HTML character reference decoding for html-lite.mjs.
 //
-// Supports a fixed set of named entities plus decimal and hex numeric references. Unknown or
-// malformed references stay verbatim. Single indexOf scan; plain Node ESM, no dependencies.
+// Supports a fixed set of named entities (NAMED_ENTITIES) plus decimal and hex numeric references.
+// Unknown or malformed references stay verbatim. Single indexOf scan; plain Node ESM, no dependencies.
 
+// Beyond the common set, every named reference whose character a number reader treats specially is
+// listed (signs, dashes, the space separators that group digits, and Markdown punctuation), so the
+// conversion probe reads `−5` and `1 234` as a converter does.
 const NAMED_ENTITIES = {
 	amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0", mdash: "\u2014", ndash: "\u2013",
 	hellip: "\u2026", copy: "\u00a9", reg: "\u00ae", times: "\u00d7", middot: "\u00b7",
+	minus: "\u2212", hyphen: "\u2010", dash: "\u2010", NonBreakingSpace: "\u00a0", thinsp: "\u2009",
+	ThinSpace: "\u2009", numsp: "\u2007", puncsp: "\u2008", hairsp: "\u200a", VeryThinSpace: "\u200a",
+	ensp: "\u2002", emsp: "\u2003", emsp13: "\u2004", emsp14: "\u2005", MediumSpace: "\u205f",
+	comma: ",", period: ".", plus: "+", lowbar: "_", UnderBar: "_", ast: "*", midast: "*", grave: "`",
+	DiacriticalGrave: "`", lpar: "(", rpar: ")", lsqb: "[", lbrack: "[", rsqb: "]", rbrack: "]",
 }
 
-function decodeOne(body) {
+/** One reference body (between `&` and `;`), or null when unsupported. */
+export function decodeOne(body) {
 	if (Object.hasOwn(NAMED_ENTITIES, body)) return NAMED_ENTITIES[body]
 	if (body[0] !== "#") return null
 	const hex = body[1] === "x" || body[1] === "X"
@@ -26,7 +35,7 @@ export function decodeEntities(text) {
 	let at = source.indexOf("&")
 	while (at !== -1) {
 		const semi = source.indexOf(";", at + 1)
-		const decoded = semi !== -1 && semi - at <= 12 ? decodeOne(source.slice(at + 1, semi)) : null
+		const decoded = semi !== -1 && semi - at <= 32 ? decodeOne(source.slice(at + 1, semi)) : null
 		if (decoded !== null) {
 			out += source.slice(last, at) + decoded
 			last = semi + 1

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

@@ -13,10 +13,13 @@ import { dirname, extname, resolve } from "node:path"
 
 import { CliError, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
 import { DEFECT_CODES } from "./contracts.mjs"
+import { markdownAsHtml } from "./fact-commands-verify.mjs"
 import { FILL_FORMATS, fill } from "./fact-fill.mjs"
 import { readLedger, writeLedger } from "./fact-ledger.mjs"
 import { briefHashOf, fillPolicy, lockedBrief, policyErrors } from "./fidelity-policy.mjs"
 import { readState, writeState } from "./fidelity-state.mjs"
+import { withBoundUnits } from "./fidelity-value-unit.mjs"
+import { parseMarkdown } from "./md-lite.mjs"
 import { findPlaceholders } from "./placeholder.mjs"
 import { sessionDirOf } from "./source-commands.mjs"
 
@@ -28,6 +31,13 @@ export const FILL_INPUT_FORMAT_RULES = Object.freeze({
 export const FILL_INPUT_FORMATS = Object.freeze([...FILL_FORMATS, ...Object.keys(FILL_INPUT_FORMAT_RULES.aliases)])
 const fillFormatOf = (format) => FILL_INPUT_FORMAT_RULES.aliases[format] ?? format
 
+/** Value-mode entries carry the unit fill saw bound to them (unit_bound), read off the edition verify will check. */
+function boundUnits(out, entries, ledger, format) {
+	if (!entries.some((entry) => entry.mode === "value")) return entries
+	const html = fillFormatOf(format) === "html" ? out : parseMarkdown(out).problems.length === 0 ? markdownAsHtml(out, entries, ledger).html : null
+	return html === null ? entries : withBoundUnits(html, entries, new Map(ledger.rows.map((row) => [row.fact_id, row])))
+}
+
 function readText(path) {
 	try {
 		return readFileSync(path, "utf8")
@@ -80,7 +90,7 @@ export function runFactFill(args) {
 	const artifact = sha256Of(out)
 	const map = `${resolve(flags.out)}.fill-map.json`
 	const brief = briefHashOf(parsed)
-	writeJsonAtomic(map, { schemaVersion: 1, format, artifact: resolve(flags.out), artifact_sha256: artifact, brief_sha256: brief, entries })
+	writeJsonAtomic(map, { schemaVersion: 1, format, artifact: resolve(flags.out), artifact_sha256: artifact, brief_sha256: brief, entries: boundUnits(out, entries, ledger, format) })
 	const data = { out: resolve(flags.out), map, artifact_sha256: artifact, brief_sha256: brief, occurrences: entries.length, warnings }
 	return { json: { command: "fact fill", status: "pass", exitCode: 0, defects: [], data }, summary: `fact fill: wrote ${flags.out} (${entries.length} pointer(s))`, exitCode: 0 }
 }

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

@@ -1,9 +1,10 @@
 // fact-commands-meaning.mjs - `fact pairs` and `fact meaning-check`, the script half of the
 // separate-session meaning verifier. fact pairs writes the (source, report sentence) pairs a
-// reader lane gets and nothing else (with --changed-since, only the pairs whose sentence polish
-// rewrote); it honours the brief's `meaning check` field and writes
+// reader lane gets and nothing else (with --changed-since, only the pairs whose sentence changed
+// since the pre-polish fill map's artifact, or all when those bytes are gone); it honours the brief's `meaning check` field and writes
 // `{ skipped: true }` when it is off. fact meaning-check ingests the readers' verdict files
-// (meaning-check.mjs), writes fidelity-meaning-defects.json (a fidelity record bound to the pairs'
+// (meaning-check.mjs), writes the meaning record of one edition (fidelity-meaning-defects.<format>.json
+// with --edition, else the legacy fidelity-meaning-defects.json; a fidelity record bound to the pairs'
 // artifact_sha256 and report, through writeFidelityRecord), and records the run in
 // fidelity-calibration.jsonl: a header with the promotion criterion on first write, then per run
 // one run line plus one line per flagged pair. The run id hashes the inputs only, so a rerun or a
@@ -15,13 +16,13 @@ import { existsSync, readFileSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 
 import { CliError, parseArgs, readJsonFile, sha256Of, writeJsonAtomic, writeTextAtomic } from "./cli-support.mjs"
-import { countDefects } from "./contracts.mjs"
+import { countDefects, DELIVERABLE_FORMATS } from "./contracts.mjs"
 import { ledgerFrom, markdownAsHtml, readEdition, sessionOf } from "./fact-commands-verify.mjs"
 import { pairsChangedSince } from "./fact-commands-polish.mjs"
 import { extractPairs, PAIR_KINDS } from "./fact-pairs.mjs"
 import { FIDELITY_INCOMPLETE } from "./fidelity-brief.mjs"
 import { briefPathOf, lockedBrief, meaningCheckEnabled } from "./fidelity-policy.mjs"
-import { MEANING_RECORD, writeFidelityRecord } from "./fidelity-records.mjs"
+import { MEANING_RECORD, meaningRecordName, writeFidelityRecord } from "./fidelity-records.mjs"
 import { blocksDelivery } from "./gates-fidelity.mjs"
 import { ingestVerdicts, unverifiedDefects, VERDICT_SCHEMA } from "./meaning-check.mjs"
 
@@ -57,10 +58,12 @@ function runPairs(args) {
 	const ledger = ledgerFrom(flags, session)
 	const html = edition.format === "md" ? markdownAsHtml(edition.text, edition.entries, ledger).html : edition.text
 	const all = extractPairs(html, ledger, claims)
-	const pairs = flags["changed-since"] === undefined ? all : pairsChangedSince(all, flags["changed-since"], ledger, claims)
+	const since = flags["changed-since"] === undefined ? null : pairsChangedSince(all, flags["changed-since"], ledger, claims)
+	const pairs = since?.pairs ?? all
 	const counts = { total: pairs.length, force_strong: pairs.filter((pair) => pair.force_strong).length }
 	for (const kind of PAIR_KINDS) counts[kind] = pairs.filter((pair) => pair.kind === kind).length
-	const record = { schemaVersion: 1, skipped: false, report: resolve(report), format: edition.format, artifact_sha256: sha256Of(edition.text), pairs_sha256: sha256Of(JSON.stringify(pairs)), counts, verdict_schema: VERDICT_SCHEMA, pairs }
+	const changed = since === null ? {} : { changed_since: { fill_map: since.fill_map, narrowed: since.narrowed } }
+	const record = { schemaVersion: 1, skipped: false, report: resolve(report), format: edition.format, artifact_sha256: sha256Of(edition.text), pairs_sha256: sha256Of(JSON.stringify(pairs)), counts, ...changed, verdict_schema: VERDICT_SCHEMA, pairs }
 	writeJsonAtomic(out, record)
 	const summary = `fact pairs: ${counts.total} pair(s), ${counts.force_strong} routed to the strong reader`
 	return { json: { command: "fact pairs", status: "pass", exitCode: 0, data: { out, ...record, pairs: undefined } }, summary, exitCode: 0 }
@@ -124,8 +127,9 @@ function skippedRefusal(flags, parsed) {
 
 function runMeaningCheck(args) {
 	const { flags } = args
-	const usage = "usage: fact meaning-check --pairs pairs.json --verdicts cheap.json [--verdicts strong.json] [--dispute P<n> --reason TEXT] [--run-id ID] [--calibration F] [--brief brief.md] [--out F]"
+	const usage = "usage: fact meaning-check --pairs pairs.json --verdicts cheap.json [--verdicts strong.json] [--dispute P<n> --reason TEXT] [--run-id ID] [--calibration F] [--brief brief.md] [--edition FORMAT] [--out F]"
 	if (flags.pairs === undefined || !Array.isArray(flags.verdicts)) throw new CliError(usage)
+	if (flags.edition !== undefined && !DELIVERABLE_FORMATS.includes(flags.edition)) throw new CliError(`--edition must be a deliverable format (${DELIVERABLE_FORMATS.join(", ")}), got ${flags.edition}`)
 	const session = sessionOf(flags)
 	const { parsed, refusal } = lockedBrief("fact meaning-check", flags)
 	if (refusal) return { ...refusal, json: { ...refusal.json, error: FIDELITY_INCOMPLETE } }
@@ -146,7 +150,7 @@ function runMeaningCheck(args) {
 	} catch (error) {
 		throw new CliError(`invalid verdict input: ${error.message}`)
 	}
-	const out = resolve(flags.out ?? inSession(session, MEANING_RECORD, "--out"))
+	const out = resolve(flags.out ?? inSession(session, flags.edition === undefined ? MEANING_RECORD : meaningRecordName(flags.edition), "--out"))
 	const calibration = resolve(flags.calibration ?? join(session ?? dirname(out), CALIBRATION_FILE))
 	const runId = flags["run-id"] ?? sha256Of([pairsText, ...verdictTexts].join("\0")).slice(0, 16)
 	const pairsSha = pairsDoc.pairs_sha256 ?? sha256Of(pairsText)

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