lazycodex-ai 5.1.44 → 5.1.46

package/packages/shared-skills/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/shared-skills/skills/ulw-research/scripts/particles-ko.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test"
+
+import { finalReading, rewriteParticle } from "./particles-ko.mjs"
+
+describe("finalReading", () => {
+	test("given a value ending in a Hangul syllable when read then the final consonant decides", () => {
+		expect(finalReading("3조 8,000억 원", null)).toBe("closed")
+		expect(finalReading("5조", null)).toBe("open")
+		expect(finalReading("7달", null)).toBe("l")
+	})
+
+	test("given a value ending in a unit token when read then the unit's Korean reading decides", () => {
+		expect(finalReading("15.2%", null)).toBe("open")
+		expect(finalReading("3.1%p", null)).toBe("open")
+		expect(finalReading("320 m", null)).toBe("open")
+		expect(finalReading("12 kg", null)).toBe("closed")
+	})
+
+	test("given a value ending in a digit when read then the Sino-Korean reading decides", () => {
+		expect(finalReading("4,200", null)).toBe("closed")
+		expect(finalReading("1", null)).toBe("l")
+		expect(finalReading("2", null)).toBe("open")
+		expect(finalReading("3", null)).toBe("closed")
+		expect(finalReading("7", null)).toBe("l")
+		expect(finalReading("8", null)).toBe("l")
+		expect(finalReading("9", null)).toBe("open")
+		expect(finalReading("6.5", null)).toBe("open")
+	})
+
+	test("given an integer whose spoken end is jo when read then the magnitude decides, not the last zero", () => {
+		expect(finalReading("1000000000000", null)).toBe("open")
+		expect(finalReading("10,000", null)).toBe("closed")
+	})
+
+	test("given a round integer past one jo when read then the last 10^4 group word decides, not sip/baek/cheon", () => {
+		expect(finalReading("10000000000000", null)).toBe("open")
+		expect(finalReading("100000000000000", null)).toBe("open")
+		expect(finalReading("1000000000000000", null)).toBe("open")
+		expect(finalReading("100000", null)).toBe("closed")
+		expect(finalReading("1000000000", null)).toBe("closed")
+	})
+
+	test("given an explicit unit token when read then it overrides the value text", () => {
+		expect(finalReading("15.2", "%")).toBe("open")
+		expect(finalReading("15", "kg")).toBe("closed")
+	})
+
+	test("given an unknown trailing token when read then no reading is claimed", () => {
+		expect(finalReading("12 zorks", null)).toBeNull()
+	})
+})
+
+describe("rewriteParticle", () => {
+	test("given an object particle with a boundary after an open value when rewritten then it becomes the open form", () => {
+		expect(rewriteParticle("을 기록", "open")).toEqual({ text: "를 기록", applied: true, candidate: true })
+	})
+
+	test("given a bare particle at end of string when rewritten then it is applied", () => {
+		expect(rewriteParticle("은", "open")).toEqual({ text: "는", applied: true, candidate: true })
+	})
+
+	test("given a particle-like prefix with no boundary when rewritten then it stays untouched and is flagged as a candidate", () => {
+		expect(rewriteParticle("이상 기록", "closed")).toEqual({ text: "이상 기록", applied: false, candidate: true })
+		expect(rewriteParticle("이상.", "open")).toEqual({ text: "이상.", applied: false, candidate: true })
+	})
+
+	test("given English or a non-particle word when rewritten then nothing changes and it is not a candidate", () => {
+		expect(rewriteParticle(" is the span", "open")).toEqual({ text: " is the span", applied: false, candidate: false })
+		expect(rewriteParticle("기록했다", "open")).toEqual({ text: "기록했다", applied: false, candidate: false })
+	})
+
+	test("given each particle pair when rewritten then the reading picks the form", () => {
+		expect(rewriteParticle("이 올랐다", "open").text).toBe("가 올랐다")
+		expect(rewriteParticle("가 올랐다", "closed").text).toBe("이 올랐다")
+		expect(rewriteParticle("는,", "l").text).toBe("은,")
+		expect(rewriteParticle("과 함께", "open").text).toBe("와 함께")
+		expect(rewriteParticle("와 함께", "l").text).toBe("과 함께")
+		expect(rewriteParticle("로 늘었다", "closed").text).toBe("으로 늘었다")
+		expect(rewriteParticle("으로 늘었다", "l").text).toBe("로 늘었다")
+		expect(rewriteParticle("으로 늘었다", "open").text).toBe("로 늘었다")
+	})
+
+	test("given no reading when rewritten then a candidate is left unchanged", () => {
+		expect(rewriteParticle("을 기록", null)).toEqual({ text: "을 기록", applied: false, candidate: true })
+	})
+})

package/packages/shared-skills/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/shared-skills/skills/ulw-research/scripts/placeholder.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test"
+
+import { findPlaceholders, lead, parsePlaceholder, subSpan } from "./placeholder.mjs"
+
+const QUOTE = "we estimate completion no earlier than 2027"
+
+describe("parsePlaceholder", () => {
+	test("value pointers: full, value, unit, q", () => {
+		expect(parsePlaceholder("{{F12:span_len}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "full" })
+		expect(parsePlaceholder("{{F12:span_len:value}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "value" })
+		expect(parsePlaceholder("{{F12:span_len:unit}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "unit" })
+		expect(parsePlaceholder("{{F12:span_len:q}}")).toEqual({ id: "F12", kind: "F", label: "span_len", mode: "q" })
+	})
+
+	test("quote pointers: full, lead, from/to with JSON anchors", () => {
+		expect(parsePlaceholder("{{Q7:completion}}")).toEqual({ id: "Q7", kind: "Q", label: "completion", mode: "full", selector: "full" })
+		expect(parsePlaceholder("{{Q7:completion:lead=18}}")).toEqual({ id: "Q7", kind: "Q", label: "completion", mode: "lead", lead: 18, selector: "lead=18" })
+		expect(parsePlaceholder('{{Q7:completion:from="no earlier":to="2027"}}')).toEqual({
+			id: "Q7",
+			kind: "Q",
+			label: "completion",
+			mode: "span",
+			from: "no earlier",
+			to: "2027",
+			selector: "from=no earlier;to=2027",
+		})
+	})
+
+	test("an anchor may contain a colon or an escaped quote", () => {
+		const parsed = parsePlaceholder('{{Q7:c:from="a:b":to="say \\"x\\""}}')
+		expect(parsed).toMatchObject({ mode: "span", from: "a:b", to: 'say "x"' })
+	})
+
+	test("malformed pointers carry an error and no id guess", () => {
+		for (const token of ["{{F12}}", "{{X1:a}}", "{{F12:a:lead=3}}", "{{Q7:a:value}}", "{{Q7:a:lead=0}}", '{{Q7:a:from="":to="b"}}', '{{Q7:a:from="a"}}', "{{F12:a:b:c}}"]) {
+			expect(parsePlaceholder(token)).toHaveProperty("error")
+		}
+	})
+})
+
+describe("findPlaceholders", () => {
+	test("returns every token with offsets that slice back to it", () => {
+		const text = 'Span {{F12:span_len}} and {{Q7:completion:from="a}}b":to="c"}} end'
+		const found = findPlaceholders(text)
+		expect(found.map((item) => item.token)).toEqual(["{{F12:span_len}}", '{{Q7:completion:from="a}}b":to="c"}}'])
+		for (const item of found) expect(text.slice(item.start, item.end)).toBe(item.token)
+		expect(found[1].parsed).toMatchObject({ from: "a}}b", to: "c" })
+	})
+
+	test("an unterminated pointer is reported, not skipped", () => {
+		const found = findPlaceholders("a {{F12:span_len\nb")
+		expect(found).toHaveLength(1)
+		expect(found[0].parsed).toHaveProperty("error")
+	})
+})
+
+describe("subSpan", () => {
+	test("inclusive sub-span with an ellipsis only at cut ends", () => {
+		expect(subSpan(QUOTE, "no earlier", "2027")).toEqual({ text: "\u2026no earlier than 2027", start: 23, end: 43 })
+		expect(subSpan(QUOTE, "we", "completion")).toEqual({ text: "we estimate completion\u2026", start: 0, end: 22 })
+		expect(subSpan(QUOTE, "estimate", "earlier").text).toBe("\u2026estimate completion no earlier\u2026")
+	})
+
+	test("an anchor that is missing, repeated, or reversed is null", () => {
+		expect(subSpan(QUOTE, "missing", "2027")).toBeNull()
+		expect(subSpan(QUOTE, "ti", "2027")).toBeNull()
+		expect(subSpan(QUOTE, "2027", "estimate")).toBeNull()
+	})
+})
+
+describe("lead", () => {
+	test("first n words plus an ellipsis, never cutting a word", () => {
+		expect(lead(QUOTE, 3)).toEqual({ text: "we estimate completion\u2026", start: 0, end: 22 })
+		expect(lead(QUOTE, 7)).toEqual({ text: QUOTE, start: 0, end: QUOTE.length })
+		expect(lead(QUOTE, 40)).toEqual({ text: QUOTE, start: 0, end: QUOTE.length })
+	})
+})

package/packages/shared-skills/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
+}