oh-my-opencode 5.1.45 → 5.1.47

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

@@ -1,6 +1,5 @@
-// 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"
@@ -86,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
@@ -94,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
 }
 

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

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

@@ -0,0 +1,170 @@
+// polish-rules.mjs - the one rule set behind polish-apply (per edit) and polish-diff (whole document).
+//
+// polishDefects(beforeHtml, afterHtml, ledger, {ordered}) compares the visible projections
+// (html-markup.markupParts, then polish-project.project) and returns {code, message} per failure.
+// Polish may change text nodes only. The primary rule is the whole-document skeleton comparison
+// (html-markup.skeletonChange): every markup token (tags, comments, bogus comments and frozen
+// script/style/template content) and every character reference of a text node must be byte-identical
+// in document order; an edited span holds no skeleton token, so any difference is polish_diff_fail
+// naming the first differing token and its offset. The remaining checks compare the projections:
+//   polish_diff_fail: fact spans (id + rendered markup), numerals outside fact spans (with units),
+//     tickers (TICKER: 1-5 capitals with an optional ".XX" class, or a 6-digit KRX code), or a
+//     table's row count changed; any tag, attribute, comment, declaration, or script/style/template
+//     content changed; protected tokens also stay within their original text-node boundaries;
+//   polish_hedging_decreased: a hedge or qualifier the before text holds and must keep is gone;
+//   polish_text_churn: more than POLISH_CHURN_LIMIT of the normalized visible prose changed;
+//   polish_link_changed: href values changed or an internal #target stopped resolving;
+//   polish_name_changed: a proper noun (POLISH_NAME) of a ledger quote, present before, is gone.
+// A document holding a construct html-markup.ambiguousMarkup lists (</ + non-letter, <!-- inside
+// script/style, <![CDATA[, <?, --!>, or < inside a tag) is refused first with polish_diff_fail
+// "ambiguous markup": the byte comparison is only trusted where the tokenizer is exact.
+// ordered (polish-apply) also refuses a reordering of fact spans, numerals, tickers and links;
+// without it they compare as multisets. Severity lives only in contracts.DEFECT_CODES.
+// No IO, no model. Plain Node ESM.
+
+import { ambiguousMarkup, markupParts, skeletonChange, tagAttributes } from "./html-markup.mjs"
+import { missingTerms, numeralKeys, project, requiredTerms, termCounts, textOf } from "./polish-project.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+import { normalizeText } from "./text-normalize.mjs"
+
+/** The codes polishDefects can emit, in report order. */
+export const POLISH_CODES = Object.freeze(["polish_diff_fail", "polish_hedging_decreased", "polish_text_churn", "polish_link_changed", "polish_name_changed"])
+export const TICKER = /(?<![\p{L}\p{N}])(?:[A-Z]{1,5}(?:\.[A-Z]{1,2})?|\d{6})(?![\p{L}\p{N}])/gu
+/** The capitalized-token heuristic for proper nouns in ledger quotes. */
+export const POLISH_NAME = /\p{Lu}[\p{L}\p{N}&'-]+/gu
+/** Above this share of changed normalized prose a polish composed instead of proofreading. */
+export const POLISH_CHURN_LIMIT = 0.5
+/** Above this many cells a gap counts as fully rewritten instead of running the quadratic distance. */
+const DISTANCE_CELLS = 25_000_000
+
+const sorted = (list) => [...list].sort()
+const same = (a, b) => a.length === b.length && a.every((item, k) => item === b[k])
+
+/** null when unchanged; a reorder counts only when ordered. */
+function listChange(label, before, after, ordered) {
+	if (same(before, after)) return null
+	const remaining = sorted(before)
+	const added = []
+	for (const item of after) {
+		const at = remaining.indexOf(item)
+		if (at === -1) added.push(item)
+		else remaining.splice(at, 1)
+	}
+	if (remaining.length > 0 || added.length > 0) return `${label} changed: removed [${remaining.join(", ")}], added [${added.join(", ")}]`
+	return ordered ? `${label} reordered: [${before.join(", ")}] became [${after.join(", ")}]` : null
+}
+
+const tableRows = (html) => html.split(/<table\b/i).slice(1).map((part) => (part.split(/<\/table\s*>/i)[0].match(/<tr\b/gi) ?? []).length)
+
+function levenshtein(a, b) {
+	if (a === b) return 0
+	if (a.length * b.length > DISTANCE_CELLS) return Math.max(a.length, b.length)
+	let previous = Array.from({ length: b.length + 1 }, (_, k) => k)
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i]
+		for (let j = 1; j <= b.length; j++) {
+			current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+		}
+		previous = current
+	}
+	return previous[b.length]
+}
+
+/** Changed share of normalized prose: edit distance over unmatched sentence runs / longer length. */
+export function churnRatio(beforeText, afterText) {
+	const [a, b] = [normalizeText(beforeText), normalizeText(afterText)]
+	const longest = Math.max(a.length, b.length)
+	if (longest === 0) return 0
+	const [sa, sb] = [splitSentences(a).map((s) => s.text), splitSentences(b).map((s) => s.text)]
+	const lcs = Array.from({ length: sa.length + 1 }, () => new Array(sb.length + 1).fill(0))
+	for (let i = sa.length - 1; i >= 0; i--) {
+		for (let j = sb.length - 1; j >= 0; j--) lcs[i][j] = sa[i] === sb[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1])
+	}
+	let distance = 0
+	let gap = [[], []]
+	const flush = () => {
+		distance += levenshtein(gap[0].join(" "), gap[1].join(" "))
+		gap = [[], []]
+	}
+	let [i, j] = [0, 0]
+	while (i < sa.length || j < sb.length) {
+		if (i < sa.length && j < sb.length && sa[i] === sb[j]) {
+			flush()
+			i++
+			j++
+		} else if (j >= sb.length || (i < sa.length && lcs[i + 1][j] >= lcs[i][j + 1])) gap[0].push(sa[i++])
+		else gap[1].push(sb[j++])
+	}
+	flush()
+	return distance / longest
+}
+
+function linkChange(from, to, before, after, ordered) {
+	const change = listChange("href and data-claim values", from.links, to.links, ordered)
+	if (change) return change
+	const ids = (html) => new Set(tagAttributes(html).flatMap(({ attrs }) => (Object.hasOwn(attrs, "id") ? [attrs.id] : [])))
+	const [idsBefore, idsAfter] = [ids(before), ids(after)]
+	const targets = to.links.filter((link) => link.startsWith("href=#")).map((link) => link.slice(5))
+	const broken = targets.filter((href) => idsBefore.has(href.slice(1)) && !idsAfter.has(href.slice(1)))
+	return broken.length > 0 ? `internal link targets stopped resolving: [${[...new Set(broken)].join(", ")}]` : null
+}
+
+/** Capitalized tokens of the ledger quotes, minus each sentence's first word. */
+function ledgerNames(rows) {
+	const names = new Set()
+	for (const row of rows) {
+		for (const { text } of splitSentences(row.quote ?? "")) {
+			const first = text.match(/^\P{L}*\p{L}+/u)?.[0].length ?? 0
+			for (const match of text.matchAll(POLISH_NAME)) if (match.index >= first) names.add(match[0])
+		}
+	}
+	return names
+}
+
+const hasWord = (text, word) => new RegExp(`(?<![\\p{L}\\p{N}])${word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\p{L}\\p{N}])`, "u").test(text)
+
+/**
+ * @param {string} beforeHtml
+ * @param {string} afterHtml
+ * @param {{ rows: object[] }} ledger
+ * @param {{ ordered?: boolean }} [options]
+ * @returns {{ code: string, message: string }[]} in POLISH_CODES order
+ */
+export function polishDefects(beforeHtml, afterHtml, ledger, { ordered = false } = {}) {
+	const ambiguous = [...new Set([...ambiguousMarkup(beforeHtml), ...ambiguousMarkup(afterHtml)])]
+	if (ambiguous.length > 0) return [{ code: "polish_diff_fail", message: `ambiguous markup: ${ambiguous.join(", ")}` }]
+	const [beforeParts, afterParts] = [markupParts(beforeHtml), markupParts(afterHtml)]
+	const [before, after] = [beforeParts.source, afterParts.source]
+	const [from, to] = [project(before), project(after)]
+	const rows = ledger?.rows ?? []
+	const defects = []
+	const note = (code, message) => message && defects.push({ code, message })
+	const factKey = (fact) => `${fact.id} ${fact.html}`
+	const tickers = (text) => text.match(TICKER) ?? []
+	const markupEqual = same(beforeParts.markup, afterParts.markup)
+	note("polish_diff_fail", markupEqual ? null : "markup changed")
+	note("polish_diff_fail", skeletonChange(beforeHtml, afterHtml))
+	note("polish_diff_fail", listChange("fact spans", from.facts.map(factKey), to.facts.map(factKey), ordered))
+	note("polish_diff_fail", listChange("numerals outside fact spans", numeralKeys(from.masked), numeralKeys(to.masked), ordered))
+	note("polish_diff_fail", listChange("tickers", tickers(from.masked), tickers(to.masked), ordered))
+	const [rowsBefore, rowsAfter] = [tableRows(before), tableRows(after)]
+	if (!same(rowsBefore, rowsAfter)) note("polish_diff_fail", `table row counts changed: [${rowsBefore}] became [${rowsAfter}]`)
+	const required = requiredTerms(from, new Map(rows.map((row) => [row.fact_id, row])))
+	if (markupEqual) {
+		for (const [index, raw] of beforeParts.text.entries()) {
+			const [a, b] = [raw, afterParts.text[index]].map(textOf)
+			note("polish_diff_fail", listChange("text-node numerals", numeralKeys(a), numeralKeys(b), ordered))
+			note("polish_diff_fail", listChange("text-node tickers", tickers(a), tickers(b), ordered))
+			const lost = missingTerms(termCounts(a, [...required.keys()]), b)
+			if (lost.length) note("polish_hedging_decreased", `text-node hedges removed: ${lost.join(", ")}`)
+		}
+	}
+	const missing = missingTerms(required, to.visible)
+	if (missing.length > 0) note("polish_hedging_decreased", `hedges or qualifiers removed: ${missing.map((term) => `"${term}"`).join(", ")}`)
+	const ratio = churnRatio(from.visible, to.visible)
+	if (ratio > POLISH_CHURN_LIMIT) note("polish_text_churn", `${(ratio * 100).toFixed(1)} percent of the normalized prose changed`)
+	note("polish_link_changed", linkChange(from, to, before, after, ordered))
+	const lost = [...ledgerNames(rows)].filter((name) => hasWord(from.visible, name) && !hasWord(to.visible, name))
+	if (lost.length > 0) note("polish_name_changed", `ledger-quote names missing after polish: ${lost.join(", ")}`)
+	return defects.sort((a, b) => POLISH_CODES.indexOf(a.code) - POLISH_CODES.indexOf(b.code))
+}