lazycodex-ai 5.1.44 → 5.1.46

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

@@ -1,12 +1,10 @@
-// outcome.mjs - the per-run outcome manifest (`outcome.json`) and the closing briefing.
-// Manifest functions are pure (they return a new manifest); the briefing reads only the
-// manifest, the sources-ledger text, and an injected `now`. node: builtins only.
+// outcome.mjs - the per-run outcome manifest (`outcome.json`) and the closing briefing. Manifest functions are pure (they return a new manifest).
+// The briefing reads only the manifest, the sources-ledger text, and an injected `now`. node: builtins only.
 
 import * as nodeFs from "node:fs"
 import { basename, dirname, join } from "node:path"
 
-import { DELIVERABLE_FORMATS, DELIVERABLE_STATUSES, GATE_NAMES, GATE_STATUSES, LANES } from "./contracts.mjs"
-import { MANIFEST_CODES, SCHEMA_VERSION, validateOutcomeManifest } from "./contracts.mjs"
+import { DELIVERABLE_FORMATS, DELIVERABLE_STATUSES, GATE_NAMES, GATE_STATUSES, LANES, MANIFEST_CODES, normalizeManifest, SCHEMA_VERSION, validateOutcomeManifest } from "./contracts.mjs"
 
 export const MANIFEST_FILENAME = "outcome.json"
 const MISSING = MANIFEST_CODES[0]
@@ -87,7 +85,7 @@ export function setDeliverable(manifest, format, status, detail = {}) {
 	const next = clone(manifest)
 	const index = next.deliverables.findIndex((row) => row.format === format)
 	const row = { format, status, promised: index >= 0 ? next.deliverables[index].promised : false, updatedAt: stamp(detail.now) }
-	for (const key of ["path", "reason", "pages", "bytes"]) {
+	for (const key of ["path", "reason", "pages", "bytes", "verifiedBy", "renderedFrom"]) {
 		if (detail[key] !== undefined) row[key] = detail[key]
 	}
 	if (index >= 0) next.deliverables[index] = row
@@ -95,11 +93,13 @@ export function setDeliverable(manifest, format, status, detail = {}) {
 	return next
 }
 
-export function setGate(manifest, gate, status) {
+export function setGate(manifest, gate, status, detail = {}) {
 	assertOneOf("unknown_gate", "gate", gate, GATE_NAMES)
 	assertOneOf("unknown_gate_status", "gate status", status, GATE_STATUSES)
+	if (gate === "fidelity" && status === "not_run" && (typeof detail.reason !== "string" || !detail.reason.trim())) throw new OutcomeError("gate_reason_required", "fidelity not_run requires a non-empty --reason")
 	const next = clone(manifest)
 	next.gates[gate] = status
+	next.gateHistory = [...(next.gateHistory ?? []), { gate, status, ...(detail.reason !== undefined ? { reason: detail.reason.trim() } : {}), at: stamp(detail.now) }]
 	return next
 }
 
@@ -226,7 +226,7 @@ function assertValid(manifest, where) {
 export function readManifest(file) {
 	let manifest
 	try {
-		manifest = JSON.parse(nodeFs.readFileSync(file, "utf8"))
+		manifest = normalizeManifest(JSON.parse(nodeFs.readFileSync(file, "utf8")))
 	} catch (error) {
 		if (error instanceof SyntaxError) throw new OutcomeError("invalid_manifest", `${file}: not valid JSON (${error.message})`)
 		throw error

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

@@ -0,0 +1,108 @@
+// Korean particle normalization after a filled value: read the value's final sound, then pick the
+// particle form. Hangul and the particle table are \u escapes (this directory ships no Hangul).
+
+// Unit token -> reading of its Korean name. Duplicated from the planned units.koreanReadingOf so this
+// module has no dependency on a sibling not yet landed; the units module reconciles the two tables.
+// Hangul unit words (won, dalleo, jo, eok, ...) need no row: they are read by code point.
+const UNIT_READINGS = new Map([
+	["%", "open"], // peosenteu
+	["%p", "open"], // peosenteu pointeu
+	["pp", "open"], // peosenteu pointeu
+	["m", "open"], // miteo
+	["mm", "open"], // millimiteo
+	["cm", "open"], // sentimiteo
+	["km", "open"], // killomiteo
+	["kg", "closed"], // killogeuraem
+	["g", "closed"], // geuraem
+	["t", "closed"], // ton
+	["s", "open"], // cho
+	["ms", "open"], // millicho
+	["min", "closed"], // bun
+	["h", "closed"], // sigan
+	["B", "open"], // baiteu
+	["KB", "open"], // killobaiteu
+	["MB", "open"], // megabaiteu
+	["GB", "open"], // gigabaiteu
+	["TB", "open"], // terabaiteu
+	["C", "open"], // do
+	["\u00B0C", "open"], // do
+	["F", "open"], // do
+	["\u00B0F", "open"], // do
+	["USD", "open"], // dalleo
+	["$", "open"], // dalleo
+	["KRW", "closed"], // won
+	["EUR", "open"], // yuro
+	["JPY", "closed"], // en
+	["x", "open"], // bae
+	["\u00D7", "open"], // bae
+])
+
+// Sino-Korean digit readings: yeong il i sam sa o yuk chil pal gu.
+const DIGIT_READINGS = Object.freeze(["closed", "l", "open", "closed", "open", "open", "closed", "l", "l", "open"])
+
+// Spoken ending of a power of ten beyond the units digit: sip baek cheon, then the 10^4 group markers
+// man eok jo gyeong. Only jo (10^12) is open.
+const TEN_POWER_READINGS = Object.freeze(["closed", "closed", "closed"])
+const GROUP_READINGS = Object.freeze({ 4: "closed", 8: "closed", 12: "open", 16: "closed" })
+
+// [particle, form after an open vowel, form after final l, form after another final consonant]
+const PARTICLES = Object.freeze([
+	Object.freeze(["\uC73C\uB85C", "\uB85C", "\uB85C", "\uC73C\uB85C"]),
+	Object.freeze(["\uB85C", "\uB85C", "\uB85C", "\uC73C\uB85C"]),
+	Object.freeze(["\uC740", "\uB294", "\uC740", "\uC740"]),
+	Object.freeze(["\uB294", "\uB294", "\uC740", "\uC740"]),
+	Object.freeze(["\uC774", "\uAC00", "\uC774", "\uC774"]),
+	Object.freeze(["\uAC00", "\uAC00", "\uC774", "\uC774"]),
+	Object.freeze(["\uC744", "\uB97C", "\uC744", "\uC744"]),
+	Object.freeze(["\uB97C", "\uB97C", "\uC744", "\uC744"]),
+	Object.freeze(["\uC640", "\uC640", "\uACFC", "\uACFC"]),
+	Object.freeze(["\uACFC", "\uC640", "\uACFC", "\uACFC"]),
+])
+const FORM_INDEX = Object.freeze({ open: 1, l: 2, closed: 3 })
+
+const HANGUL_FIRST = 0xac00
+const HANGUL_LAST = 0xd7a3
+const BOUNDARY = /^[\s\p{P}]/u
+const TRAILING_DIGITS = /([0-9][0-9,]*)(?:\.([0-9]+))?$/
+
+function hangulReading(char) {
+	const code = char.codePointAt(0)
+	if (code === undefined || code < HANGUL_FIRST || code > HANGUL_LAST) return null
+	const finalConsonant = (code - HANGUL_FIRST) % 28
+	if (finalConsonant === 0) return "open"
+	return finalConsonant === 8 ? "l" : "closed"
+}
+
+function numberReading(text) {
+	const match = TRAILING_DIGITS.exec(text)
+	if (!match) return null
+	// Decimals read digit by digit: 6.50 ends on yeong, so a trailing 0 after the point is closed.
+	if (match[2] !== undefined) return DIGIT_READINGS[Number(match[2].at(-1))]
+	const digits = match[1].replaceAll(",", "")
+	const trailingZeros = digits.length - digits.replace(/0+$/, "").length
+	if (trailingZeros === 0 || trailingZeros === digits.length) return DIGIT_READINGS[Number(digits.at(-1))]
+	// From 10^4 up the spoken end is the last non-zero group word (sipjo ends on jo), not sip/baek/cheon.
+	if (trailingZeros >= 4) return GROUP_READINGS[trailingZeros - (trailingZeros % 4)] ?? null
+	return TEN_POWER_READINGS[trailingZeros - 1]
+}
+
+export function finalReading(valueText, unitToken) {
+	if (unitToken !== null && unitToken !== undefined) return UNIT_READINGS.get(unitToken) ?? hangulReading(unitToken.at(-1) ?? "")
+	const text = valueText.trimEnd()
+	const last = text.at(-1)
+	if (last === undefined) return null
+	const hangul = hangulReading(last)
+	if (hangul !== null) return hangul
+	if (last >= "0" && last <= "9") return numberReading(text)
+	const token = /[^\s0-9.,]+$/u.exec(text)?.[0] ?? ""
+	return UNIT_READINGS.get(token) ?? null
+}
+
+export function rewriteParticle(following, reading) {
+	const entry = PARTICLES.find(([particle]) => following.startsWith(particle))
+	if (entry === undefined) return { text: following, applied: false, candidate: false }
+	const rest = following.slice(entry[0].length)
+	const index = FORM_INDEX[reading]
+	if ((rest !== "" && !BOUNDARY.test(rest)) || index === undefined) return { text: following, applied: false, candidate: true }
+	return { text: entry[index] + rest, applied: true, candidate: true }
+}

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

@@ -0,0 +1,184 @@
+// placeholder.mjs - the fact pointer grammar of the fill step and its render helpers.
+// Value pointers: {{F12:label}}, {{F12:label:value}}, {{F12:label:unit}}, {{F12:label:q}}.
+// Quote pointers: {{Q7:label}}, {{Q7:label:lead=18}}, {{Q7:label:from="x":to="y"}} (anchors are
+// JSON strings, so they may hold a colon or an escaped quote). Labels are compared exactly by the
+// caller; this module never guesses an id. Pure functions; node: builtins only.
+
+import { parseNumeral } from "./numerals.mjs"
+
+export const ELLIPSIS = "\u2026"
+
+const ID = /^([FQ])\d+$/
+const LABEL = /^[^\s:{}"]+$/
+const VALUE_MODES = new Set(["value", "unit", "q"])
+const LEAD = /^lead=([1-9]\d*)$/
+const LINEAGE = Object.freeze({ measured: "MEASURED", assumed: "ASSUMED", derived: "DERIVED", converted: "DERIVED" })
+
+/** End index (exclusive) of a JSON string starting at `at`, or -1 when it is not closed on its line. */
+function jsonStringEnd(text, at) {
+	let i = at + 1
+	while (i < text.length && text[i] !== '"' && text[i] !== "\n") i += text[i] === "\\" ? 2 : 1
+	return text[i] === '"' ? i + 1 : -1
+}
+
+function readJsonString(text, at) {
+	if (text[at] !== '"') return null
+	const end = jsonStringEnd(text, at)
+	if (end === -1) return null
+	try {
+		return { value: JSON.parse(text.slice(at, end)), end }
+	} catch {
+		return null
+	}
+}
+
+function parseAnchors(tail) {
+	if (!tail.startsWith("from=")) return null
+	const from = readJsonString(tail, 5)
+	if (from === null || !tail.startsWith(":to=", from.end)) return null
+	const to = readJsonString(tail, from.end + 4)
+	if (to === null || to.end !== tail.length || from.value === "" || to.value === "") return null
+	return { from: from.value, to: to.value }
+}
+
+/** @returns the parsed pointer, or { error } for a malformed one. */
+export function parsePlaceholder(token) {
+	if (!token.startsWith("{{") || !token.endsWith("}}")) return { error: "a placeholder is {{ID:label...}}" }
+	const body = token.slice(2, -2)
+	const colon = body.indexOf(":")
+	const id = colon === -1 ? body : body.slice(0, colon)
+	const idMatch = ID.exec(id)
+	if (idMatch === null) return { error: `"${id}" is not an F<n> or Q<n> id` }
+	if (colon === -1) return { error: `${id} has no label; write {{${id}:label}}` }
+	const rest = body.slice(colon + 1)
+	const second = rest.indexOf(":")
+	const label = second === -1 ? rest : rest.slice(0, second)
+	if (!LABEL.test(label)) return { error: `"${label}" is not a label` }
+	const tail = second === -1 ? null : rest.slice(second + 1)
+	const base = { id, kind: idMatch[1], label }
+	if (idMatch[1] === "F") {
+		if (tail === null) return { ...base, mode: "full" }
+		return VALUE_MODES.has(tail) ? { ...base, mode: tail } : { error: `"${tail}" is not a value mode (value, unit, q)` }
+	}
+	if (tail === null) return { ...base, mode: "full", selector: "full" }
+	const lead = LEAD.exec(tail)
+	if (lead !== null) return { ...base, mode: "lead", lead: Number(lead[1]), selector: `lead=${lead[1]}` }
+	const anchors = parseAnchors(tail)
+	if (anchors === null) return { error: `"${tail}" is not a quote selector (lead=N or from="..":to="..")` }
+	return { ...base, mode: "span", ...anchors, selector: `from=${anchors.from};to=${anchors.to}` }
+}
+
+/** End index (exclusive) of the pointer opened at `at`, or -1 when it is not closed on its line. */
+function placeholderEnd(text, at) {
+	let i = at + 2
+	while (i < text.length && text[i] !== "\n") {
+		if (text[i] === '"') {
+			const end = jsonStringEnd(text, i)
+			if (end === -1) return -1
+			i = end
+		} else if (text.startsWith("}}", i)) return i + 2
+		else i++
+	}
+	return -1
+}
+
+/** Every `{{...}}` pointer in source order: [{ token, start, end, parsed }]. */
+export function findPlaceholders(text) {
+	const found = []
+	let at = text.indexOf("{{")
+	while (at !== -1) {
+		const end = placeholderEnd(text, at)
+		if (end === -1) {
+			found.push({ token: text.slice(at, text.indexOf("\n", at) === -1 ? text.length : text.indexOf("\n", at)), start: at, end: at + 2, parsed: { error: "the placeholder is not closed on its line" } })
+			at = text.indexOf("{{", at + 2)
+			continue
+		}
+		const token = text.slice(at, end)
+		found.push({ token, start: at, end, parsed: parsePlaceholder(token) })
+		at = text.indexOf("{{", end)
+	}
+	return found
+}
+
+function occurrences(text, needle) {
+	let count = 0
+	for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + 1)) count++
+	return count
+}
+
+function cut(quote, start, end) {
+	return { text: `${start > 0 ? ELLIPSIS : ""}${quote.slice(start, end)}${end < quote.length ? ELLIPSIS : ""}`, start, end }
+}
+
+/** The contiguous span from `from` through `to`; each anchor must occur exactly once, in order. */
+export function subSpan(quote, from, to) {
+	if (occurrences(quote, from) !== 1 || occurrences(quote, to) !== 1) return null
+	const start = quote.indexOf(from)
+	const toAt = quote.indexOf(to)
+	if (toAt < start || toAt + to.length < start + from.length) return null
+	return cut(quote, start, toAt + to.length)
+}
+
+/** The first `n` whitespace-delimited words, with an ellipsis when words were cut. */
+export function lead(quote, n) {
+	const words = [...quote.matchAll(/\S+/g)]
+	if (words.length <= n) return { text: quote, start: 0, end: quote.length }
+	const last = words[n - 1]
+	return cut(quote, 0, last.index + last[0].length)
+}
+
+/** The value and unit parts of a row's raw text ("4.2 eok won" -> value "4.2 eok", unit "won"). */
+export function valueParts(row) {
+	const unitText = parseNumeral(row.raw)?.unitRaw ?? row.unit
+	const valueText = unitText && row.raw.endsWith(unitText) ? row.raw.slice(0, -unitText.length).trimEnd() : (row.value ?? row.raw)
+	return { valueText, unitText: unitText ?? "" }
+}
+
+/** The quote interval holding the row's qualifier and its raw quantity, or null if absent. */
+export function qualifiedText(row) {
+	if (row.qualifier === null) return row.raw
+	for (let numeral = parseNumeral(row.quote); numeral !== null; numeral = parseNumeral(row.quote, numeral.span[1])) {
+		if (numeral.raw !== row.raw || numeral.qualifierRaw === null) continue
+		const [start, end] = numeral.span
+		const before = row.quote.lastIndexOf(numeral.qualifierRaw, start)
+		const between = before === -1 ? [] : row.quote.slice(before + numeral.qualifierRaw.length, start).split(/\s+/u).filter(Boolean)
+		if (before !== -1 && between.length <= 1) return row.quote.slice(before, end)
+		const after = row.quote.indexOf(numeral.qualifierRaw, end)
+		if (after !== -1) return row.quote.slice(start, after + numeral.qualifierRaw.length)
+	}
+	return null
+}
+
+export function escapeHtml(text) {
+	return String(text).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;")
+}
+
+/** The elements the renderers below emit as fact spans; recognizers build their patterns from this. */
+export const FACT_ELEMENT_TAGS = Object.freeze(["data", "q", "blockquote"])
+
+export function renderValueHtml(row, text) {
+	const unit = row.unit === null ? "" : ` data-unit="${escapeHtml(row.unit)}"`
+	return `<data class="fact" value="${escapeHtml(row.value)}" data-fact="${row.fact_id}"${unit} data-lineage="${LINEAGE[row.kind]}">${escapeHtml(text)}</data>`
+}
+
+export function renderQuote(row, selector, text, format) {
+	const marker = `[${row.source_id}]`
+	if (format === "md") return `"${text}" ${marker}`
+	return `<q data-fact="${row.fact_id}" data-quote-sel="${escapeHtml(selector)}">${escapeHtml(text)}</q> ${marker}`
+}
+
+const RENDERED_MD_QUOTE = /^"([\s\S]*)" (\[S\d+\])$/u
+
+/** The quote text and source marker of bytes renderQuote wrote for md, or null for any other layout. */
+export function parseRenderedQuote(body) {
+	const match = RENDERED_MD_QUOTE.exec(body)
+	return match ? { text: match[1], marker: match[2] } : null
+}
+
+/** The attributed block that replaces a twice-failed sentence; entity and valid_at stay outside the quote. */
+export function renderBlockquote(row, key, format) {
+	const attribution = row.entity === null ? "" : `, on ${row.entity}${row.valid_at === null ? "" : ` (${row.valid_at})`}`
+	const footer = `[${row.source_id}]${attribution}`
+	if (format === "md") return `> "${row.quote}"\n> ${footer}`
+	return `<blockquote data-fact="${row.fact_id}" data-replaced="${escapeHtml(key)}">"${escapeHtml(row.quote)}" <footer>${escapeHtml(footer)}</footer></blockquote>`
+}

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

@@ -0,0 +1,115 @@
+// polish-apply.mjs - checked, per-edit application of a proofread lane's polish edits.
+//
+// An edit whose before or after holds <, > or & is polish_edit_rejected (POLISH_MARKUP_REASON)
+// before anything else, so no edit can create, alter, close or escape a tag, comment,
+// bogus comment, CDATA section, entity or script, whatever the tokenizer models; a located region
+// that overlaps a character reference or opens one (it starts inside `&name`) is rejected with
+// POLISH_REFERENCE_REASON, so an edit can neither change nor complete an existing reference.
+// Those two guards are the early, actionable refusals; the guarantee itself is the whole-document
+// skeleton comparison (html-markup.skeletonChange) that polish-rules runs in both gates: every
+// markup token and every character reference stays byte-identical, and an accepted edit's span
+// holds no skeleton token, so any difference refuses the edit and reports polish_diff_fail.
+// applyEdits(html, edits, ledger) applies each {before, after, reason} edit in edits-file order,
+// against the output of the edits accepted before it. `before` must occur exactly once (runs of
+// whitespace match any whitespace run) and must not cut through a fact span; otherwise the edit is
+// polish_edit_unlocated. A located edit is applied whole or not at all: it is polish_edit_rejected
+// when polish-rules.polishDefects(..., {ordered: true}) finds any defect between the current
+// document and the document with the edit (per edit), or between the ORIGINAL input and the
+// document with the edit (whole document: the baseline polish-diff uses). Ordered is stricter than
+// polish-diff's multiset comparison and the last accepted candidate is the output, so a clean run
+// is always polish-diff clean: no cross-edit case is left to the backstop. The rules see the
+// text-node projection and freeze every markup byte, including script/style/template content.
+// validatePolishEdits and POLISH_EDIT_FIELDS are the edit
+// contract every caller (the CLI included) uses. No IO, no model. Plain Node ESM.
+
+import { CHARACTER_REFERENCE } from "./html-markup.mjs"
+import { factSpans } from "./polish-project.mjs"
+import { polishDefects } from "./polish-rules.mjs"
+
+export { numeralKeys, project, SLOT, termCounts, textOf } from "./polish-project.mjs"
+
+/** The fields of one polish edit: before and after are required strings, reason an optional string. */
+export const POLISH_EDIT_FIELDS = Object.freeze({ before: "required", after: "required", reason: "optional" })
+
+/** Throws a TypeError naming the first edit that breaks POLISH_EDIT_FIELDS; returns the edits. */
+export function validatePolishEdits(edits) {
+	if (!Array.isArray(edits)) throw new TypeError("edits must be an array")
+	edits.forEach((edit, index) => {
+		if (edit === null || typeof edit !== "object" || Array.isArray(edit)) throw new TypeError(`edit ${index} must be an object`)
+		for (const [field, need] of Object.entries(POLISH_EDIT_FIELDS)) {
+			if (need === "optional" && edit[field] === undefined) continue
+			if (typeof edit[field] !== "string") throw new TypeError(`edit ${index} needs ${need === "optional" ? "a string" : "string"} ${field}`)
+		}
+	})
+	return edits
+}
+
+/** Characters an edit's before and after may never contain. */
+export const POLISH_MARKUP_CHARACTERS = /[<>&]/
+/** The actionable rejection reason for an edit holding a markup character. */
+export const POLISH_MARKUP_REASON = "edit contains markup characters (<, >, &): route this section through the full fidelity gates"
+/** The actionable rejection reason for a located region touching a character reference. */
+export const POLISH_REFERENCE_REASON = "edit touches a character reference: route this section through the full fidelity gates"
+
+/** True when [start, end) overlaps a character reference of html or starts inside one. */
+export function touchesReference(html, start, end) {
+	for (const match of String(html).matchAll(CHARACTER_REFERENCE)) {
+		if (match.index < end && match.index + match[0].length > start) return true
+	}
+	return /&[#\w]*$/.test(html.slice(Math.max(0, start - 16), start))
+}
+
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/** The single whitespace-normalized match of `before` in html as {start, end}, or {count} otherwise. */
+function locate(html, before) {
+	if (before.trim() === "") return { count: 0 }
+	const pattern = new RegExp(before.split(/\s+/).map(escape).join("\\s+"), "g")
+	const hits = [...html.matchAll(pattern)]
+	return hits.length === 1 ? { count: 1, start: hits[0].index, end: hits[0].index + hits[0][0].length } : { count: hits.length }
+}
+
+/** The id of a fact span the region [start, end) cuts through (overlaps without containing), or null. */
+export function cutSpan(html, start, end) {
+	return factSpans(html).find((span) => span.start < end && span.end > start && !(start <= span.start && span.end <= end))?.id ?? null
+}
+
+/**
+ * @param {string} html the filled report
+ * @param {{ before: string, after: string, reason?: string }[]} edits in edits-file order
+ * @param {{ rows: object[] }} ledger
+ * @returns {{ out: string, applied: number[], rejected: { index: number, code: string, reason: string }[],
+ *   unlocated: { index: number, code: string, reason: string }[] }}
+ */
+export function applyEdits(html, edits, ledger) {
+	validatePolishEdits(edits)
+	const original = String(html)
+	const result = { out: original, applied: [], rejected: [], unlocated: [] }
+	const defects = (candidate) => {
+		const messages = [result.out, original].flatMap((base) => polishDefects(base, candidate, ledger, { ordered: true }).map((d) => d.message))
+		return [...new Set(messages)]
+	}
+	edits.forEach((edit, index) => {
+		const touches = POLISH_MARKUP_CHARACTERS.test(edit.before) || POLISH_MARKUP_CHARACTERS.test(edit.after)
+		const where = locate(result.out, edit.before)
+		if (where.count !== 1 && !touches) {
+			result.unlocated.push({ index, code: "polish_edit_unlocated", reason: `before matches ${where.count} times; it must match exactly once` })
+			return
+		}
+		const reasons = touches ? [POLISH_MARKUP_REASON] : []
+		const candidate = where.count === 1 ? result.out.slice(0, where.start) + edit.after + result.out.slice(where.end) : result.out
+		if (where.count === 1) {
+			const cut = cutSpan(result.out, where.start, where.end)
+			if (touchesReference(result.out, where.start, where.end)) reasons.push(POLISH_REFERENCE_REASON)
+			reasons.push(...defects(candidate))
+			if (cut !== null) reasons.push(`the edit cuts through fact span ${cut}`)
+		}
+		if (reasons.length > 0) {
+			result.rejected.push({ index, code: "polish_edit_rejected", reason: reasons.join("; ") })
+			return
+		}
+		result.out = candidate
+		result.applied.push(index)
+	})
+	return result
+}

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

@@ -0,0 +1,31 @@
+// polish-diff.mjs - whole-document backstop between a pre-polish artifact and its polished result.
+//
+// diffPolish(beforeHtml, afterHtml, ledger) runs the polish-rules.mjs rule set (the same rules
+// polish-apply runs per edit) over the whole document, as multisets, and returns at most one defect
+// per code. Severity is looked up in contracts.DEFECT_CODES for every emitted code; a code missing
+// there throws. polish-apply checks every edit against this same whole-document baseline (ordered,
+// so stricter), so a clean polish-apply run is clean here; this catches hand edits. No IO, no model.
+// Plain Node ESM.
+
+import { DEFECT_CODES } from "./contracts.mjs"
+import { POLISH_CODES, polishDefects } from "./polish-rules.mjs"
+
+export { churnRatio, TICKER } from "./polish-rules.mjs"
+
+/** The DEFECT_CODES entry of a polish code; refuses a code the registry does not define. */
+function registryEntry(code) {
+	if (!Object.hasOwn(DEFECT_CODES, code)) throw new Error(`polish code ${code} is not in DEFECT_CODES`)
+	return DEFECT_CODES[code]
+}
+
+/**
+ * @param {string} beforeHtml the pre-polish artifact
+ * @param {string} afterHtml the polished artifact
+ * @param {{ rows: object[] }} ledger
+ * @returns {{ code: string, severity: string, message: string }[]} at most one defect per code
+ */
+export function diffPolish(beforeHtml, afterHtml, ledger) {
+	const found = new Map()
+	for (const { code, message } of polishDefects(beforeHtml, afterHtml, ledger)) found.set(code, [...(found.get(code) ?? []), message])
+	return POLISH_CODES.filter((code) => found.has(code)).map((code) => ({ code, severity: registryEntry(code).severity, message: found.get(code).join("; ") }))
+}

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

@@ -0,0 +1,125 @@
+// polish-project.mjs - the protected projection of report markup that every polish check compares.
+//
+// project(markup) yields the ordered fact spans {id, html}, the visible text, the masked text (each
+// fact span replaced by SLOT) and the ordered href values. Callers pass markup already reduced by
+// html-markup.markupParts().source, with frozen script/style/template content omitted. Fact spans are the
+// placeholder.mjs FACT_ELEMENT_TAGS elements carrying data-fact (any quoting), found by
+// html-markup.elementSpans (a same-name nested element and a quoted ">" stay inside). Hedge and
+// qualifier terms come from fidelity-lexicon (guardedTerms, lexicalPattern "guard" mode).
+// No IO, no model. Plain Node ESM.
+
+import { decodeEntities } from "./entities.mjs"
+import { guardedTerms, lexicalPattern, QUALIFIER_FORMS } from "./fidelity-lexicon.mjs"
+import { elementSpans, markupParts, tagAttributes } from "./html-markup.mjs"
+import { HEDGES } from "./lexicon.mjs"
+import { parseNumeral } from "./numerals.mjs"
+import { FACT_ELEMENT_TAGS } from "./placeholder.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+import { normalizeUnit } from "./units.mjs"
+
+/** The link attributes polish_link_changed owns; a data-claim id change is a markup (fact-binding) change. */
+export const POLISH_LINK_ATTRIBUTES = Object.freeze(["href"])
+/** The bare digit runs compared outside fact spans when no quantity parses around them. */
+export const POLISH_DIGITS = /\d+(?:[.,]\d+)*/g
+/** Stands in for one fact span in masked text; a private-use char, so no numeral or word matches it. */
+export const SLOT = "\uE000"
+const FACT_TAGS = new Set(FACT_ELEMENT_TAGS)
+const isFactElement = (name, attrs) => FACT_TAGS.has(name) && (attrs["data-fact"] ?? "") !== ""
+
+/** Each fact span of the markup as {id, start, end, html}, in order; an unclosed one runs to the end. */
+export function factSpans(markup) {
+	const src = String(markup)
+	return elementSpans(src, isFactElement).map(({ start, end, tag }) => ({ id: tag.attrs["data-fact"], start, end, html: src.slice(start, end) }))
+}
+
+/**
+ * Visible text of an HTML fragment: the scanner's text slots joined by a space (so a quoted ">"
+ * inside a tag stays markup), entities decoded, whitespace collapsed. One tokenization is shared
+ * with the markup rules; no second tag-stripping regex.
+ */
+export function textOf(html) {
+	return decodeEntities(markupParts(html).text.join(" ")).replace(/\s+/g, " ")
+}
+
+/** The protected projection of (already visible) markup; see the header. */
+export function project(markup) {
+	const facts = []
+	let visible = ""
+	let masked = ""
+	let at = 0
+	for (const span of factSpans(markup)) {
+		const outside = textOf(markup.slice(at, span.start))
+		facts.push({ id: span.id, html: span.html.replace(/\s+/g, " ") })
+		visible += `${outside}${textOf(span.html)}`
+		masked += `${outside} ${SLOT} `
+		at = span.end
+	}
+	const rest = textOf(markup.slice(at))
+	const links = tagAttributes(markup).flatMap(({ attrs }) =>
+		POLISH_LINK_ATTRIBUTES.filter((name) => Object.hasOwn(attrs, name)).map((name) => `${name}=${attrs[name]}`),
+	)
+	return { facts, visible: (visible + rest).replace(/\s+/g, " ").trim(), masked: (masked + rest).replace(/\s+/g, " ").trim(), links }
+}
+
+const unitKey = (raw) => (raw === null ? "" : (normalizeUnit(raw) ?? raw.toLowerCase()))
+
+/** Ordered numeral keys: a parsed quantity as "value unit" (once), any other digit run as written. */
+export function numeralKeys(text) {
+	const quantities = []
+	for (let found = parseNumeral(text); found !== null; found = parseNumeral(text, found.span[1])) quantities.push(found)
+	const keys = []
+	let k = 0
+	for (const match of text.matchAll(POLISH_DIGITS)) {
+		while (k < quantities.length && quantities[k].span[1] <= match.index) k++
+		const quantity = quantities[k]
+		if (!quantity || quantity.span[0] > match.index) keys.push(match[0])
+		else if (!quantity.counted) {
+			quantity.counted = true
+			keys.push(`${quantity.value}${quantity.range ? `~${quantity.valueEnd}` : ""} ${unitKey(quantity.unitRaw)}`.trim())
+		}
+	}
+	return keys
+}
+
+/** term -> occurrence count of each listed term in the text (guard mode of the lexical engine). */
+export function termCounts(text, terms = guardedTerms()) {
+	const counts = new Map()
+	for (const term of terms) {
+		const n = [...text.matchAll(lexicalPattern(term, "guard"))].length
+		if (n > 0) counts.set(term, n)
+	}
+	return counts
+}
+
+const add = (into, term, n) => into.set(term, (into.get(term) ?? 0) + n)
+
+/**
+ * The hedge and qualifier tokens the text before a polish holds and must keep (term -> count), per
+ * sentence of the masked text: a sentence without fact spans keeps all its guarded tokens; a
+ * sentence with fact spans keeps those of its tokens that the referenced rows' quote hedges or
+ * qualifier forms name. A ledger term the sentence never held is never required.
+ */
+export function requiredTerms(projection, rows) {
+	const required = new Map()
+	let cursor = 0
+	for (const { text } of splitSentences(projection.masked)) {
+		const slots = text.split(SLOT).length - 1
+		const facts = projection.facts.slice(cursor, cursor + slots)
+		cursor += slots
+		const present = termCounts(text)
+		const sourced = new Set()
+		for (const { id } of facts) {
+			const row = rows.get(id)
+			for (const term of termCounts(row?.quote ?? "", HEDGES).keys()) sourced.add(term)
+			for (const form of QUALIFIER_FORMS[row?.qualifier] ?? []) sourced.add(form)
+		}
+		for (const [term, n] of present) if (slots === 0 || sourced.has(term)) add(required, term, n)
+	}
+	return required
+}
+
+/** Required terms the text no longer holds as many times, as "term" names. */
+export function missingTerms(required, text) {
+	const have = termCounts(text, [...required.keys()])
+	return [...required].filter(([term, n]) => (have.get(term) ?? 0) < n).map(([term]) => term)
+}