oh-my-opencode 5.1.47 → 5.1.51

package/dist/skills/ulw-research/scripts/outcome-start.mjs

@@ -0,0 +1,66 @@
+// outcome-start.mjs - the run clock (outcome.json startedAt). `outcome init` is its one writer and
+// records it once: --started-at from the orchestrator, else the startedAt of a valid manifest an
+// earlier init wrote (a re-init keeps the clock), else terminal-state.json.started_at when a
+// supervisor wrote one, else the YYYYMMDD-HHMMSS session dir name. A recorded value must be a real
+// ISO time with Z or an offset, not after `now`, and within a day of a stamped dir name; otherwise
+// init refuses instead of falling back. Never the interview's as-of date. No clock reads.
+import { readFileSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+
+const ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/
+const SESSION_STAMP = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})$/
+const DAY_MS = 86_400_000
+
+/** A real calendar time (no 2026-02-30, no T24:00), or null. */
+function strictIso(value) {
+	const match = typeof value === "string" ? ISO.exec(value) : null
+	if (!match) return null
+	const [y, mo, d, h, mi, s, oh = 0, om = 0] = match.slice(1).map((part) => Number(part ?? 0))
+	const day = new Date(Date.UTC(y, mo - 1, d))
+	if (day.getUTCMonth() !== mo - 1 || day.getUTCDate() !== d || h > 23 || mi > 59 || s > 59 || oh > 23 || om > 59) return null
+	const date = new Date(value)
+	return Number.isNaN(date.getTime()) ? null : date
+}
+
+/** Local start time from a YYYYMMDD-HHMMSS dir name, null when the name is not a stamp. */
+function dirStamp(sessionDir, fail) {
+	const match = SESSION_STAMP.exec(basename(sessionDir))
+	if (!match) return null
+	const [y, mo, d, h, mi, s] = match.slice(1).map(Number)
+	const date = new Date(y, mo - 1, d, h, mi, s)
+	if (date.getMonth() !== mo - 1 || date.getDate() !== d || date.getHours() !== h) fail(`session dir basename is not a real local time: ${sessionDir}`)
+	return date
+}
+
+function readJson(sessionDir, file) {
+	try {
+		return { data: JSON.parse(readFileSync(join(sessionDir, file), "utf8")) }
+	} catch (error) {
+		if (error.code === "ENOENT" || error.code === "ENOTDIR") return null
+		if (error instanceof SyntaxError) return { corrupt: `${join(sessionDir, file)} is not valid JSON (${error.message})` }
+		throw error
+	}
+}
+
+/**
+ * @param {{ sessionDir: string, startedAt?: string, now?: Date, validManifest: (data: unknown) => boolean, fail: (message: string) => never }} input
+ * @returns {Date}
+ */
+export function runStart({ sessionDir, startedAt, now, validManifest, fail }) {
+	const dir = dirStamp(sessionDir, fail)
+	const check = (value, location) => {
+		const date = strictIso(value)
+		if (!date) fail(`invalid run timestamp in ${location}: ${JSON.stringify(value)} is not a real ISO time with Z or an offset`)
+		if (now && date > now) fail(`run timestamp in ${location} (${value}) is after now (${now.toISOString()})`)
+		if (dir && Math.abs(date - dir) > DAY_MS) fail(`run timestamp in ${location} (${value}) is not within a day of the session dir name ${basename(sessionDir)}: a copied or stale value`)
+		return date
+	}
+	if (startedAt !== undefined) return check(startedAt, "--started-at")
+	const manifest = readJson(sessionDir, "outcome.json")
+	if (manifest?.data && validManifest(manifest.data) && resolve(String(manifest.data.sessionDir)) === resolve(sessionDir)) return check(manifest.data.startedAt, "outcome.json.startedAt")
+	const terminal = readJson(sessionDir, "terminal-state.json")
+	if (terminal?.corrupt) fail(terminal.corrupt)
+	if (terminal?.data?.started_at !== undefined) return check(terminal.data.started_at, "terminal-state.json.started_at")
+	if (dir) return dir
+	return fail(`missing run timestamp: pass --started-at <ISO>, record terminal-state.json.started_at, or name the session dir YYYYMMDD-HHMMSS (${sessionDir})`)
+}

package/dist/skills/ulw-research/scripts/outcome-start.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { validateOutcomeManifest } from "./contracts.mjs"
+import { initManifest } from "./outcome.mjs"
+import { sampleManifest } from "./tests/contracts-support"
+
+const START = "2026-10-25T12:52:01.832Z"
+const cli = join(import.meta.dir, "report-tools.mjs")
+
+function directory(name = "E") {
+	const root = mkdtempSync(join(tmpdir(), "outcome-start-"))
+	onTestFinished(() => rmSync(root, { recursive: true, force: true }))
+	const dir = join(root, name)
+	mkdirSync(dir)
+	return dir
+}
+
+function init(dir: string, ...extra: string[]) {
+	return spawnSync("node", [cli, "outcome", "init", "--session-dir", dir, "--promised", "html", "--now", START, ...extra], { encoding: "utf8" })
+}
+const startedAt = (dir: string) => JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8")).startedAt
+const manifestAt = (dir: string, value: string) => writeFileSync(join(dir, "outcome.json"), JSON.stringify({ ...sampleManifest(), sessionDir: dir, startedAt: value }))
+
+describe("outcome init is the one writer of the run clock", () => {
+	test("#given --started-at from the orchestrator #when init runs in an unstamped dir #then that value is recorded", () => {
+		const dir = directory()
+		expect(init(dir, "--started-at", START).status).toBe(0)
+		expect(startedAt(dir)).toBe(START)
+	})
+
+	test("#given a supervisor's terminal-state.json #when init runs #then started_at is recorded", () => {
+		const dir = directory()
+		writeFileSync(join(dir, "terminal-state.json"), JSON.stringify({ started_at: START }))
+		expect(init(dir).status).toBe(0)
+		expect(startedAt(dir)).toBe(START)
+	})
+
+	test("#given no flag, no metadata, and no stamped dir name #when init runs #then it refuses and names every source", () => {
+		const result = init(directory())
+		expect(result.status).toBe(1)
+		expect(result.stderr).toMatch(/--started-at/)
+	})
+
+	test("#given only a stamped dir name #when init runs #then the dir name is the fallback clock", () => {
+		const dir = directory("20260101-120000")
+		expect(init(dir).status).toBe(0)
+		expect(startedAt(dir)).toMatch(/^2026-01-01T/)
+	})
+
+	test("#given a valid manifest from an earlier init #when init runs again #then the recorded clock survives", () => {
+		const dir = directory("20261025-120000")
+		const first = "2026-10-25T03:00:00.000Z"
+		manifestAt(dir, first)
+		expect(init(dir).status).toBe(0)
+		expect(startedAt(dir)).toBe(first)
+	})
+})
+
+describe("a recorded run clock is validated, never trusted raw", () => {
+	test("#given a manifest copied with a 2020 startedAt into a 20260104-120000 dir #when init runs #then it refuses", () => {
+		const dir = directory("20260104-120000")
+		manifestAt(dir, "2020-01-01T00:00:00.000Z")
+		const result = init(dir)
+		expect(result.status).toBe(1)
+		expect(result.stderr).toMatch(/outcome\.json\.startedAt/)
+	})
+
+	for (const value of ["not-a-time", "2099-01-01T00:00:00Z", "2026-02-30T12:00:00Z", "2026-10-25T24:00:00Z", "2026-10-25 12:00:00"]) {
+		test(`#given started_at ${value} with --now ${START} #when init runs #then it refuses without falling back`, () => {
+			const dir = directory("20261025-120000")
+			writeFileSync(join(dir, "terminal-state.json"), JSON.stringify({ started_at: value }))
+			const result = init(dir)
+			expect(result.status).toBe(1)
+			expect(result.stderr).toMatch(/terminal-state\.json\.started_at/)
+		})
+	}
+
+	test("#given a valid manifest copied from another session into an unstamped dir #when init runs #then its clock is not reused", () => {
+		const dir = directory()
+		writeFileSync(join(dir, "outcome.json"), JSON.stringify({ ...sampleManifest(), sessionDir: "/elsewhere/E", startedAt: "2020-01-01T00:00:00.000Z" }))
+		const result = init(dir)
+		expect(result.status).toBe(1)
+		expect(result.stderr).toMatch(/--started-at/)
+	})
+
+	test("#given a corrupt terminal-state.json #when init runs #then the error names the file", () => {
+		const dir = directory("20261025-120000")
+		writeFileSync(join(dir, "terminal-state.json"), "{")
+		const result = init(dir)
+		expect(result.status).toBe(1)
+		expect(result.stderr).toContain("terminal-state.json")
+	})
+
+	test("#given a corrupt outcome.json #when init runs #then init overwrites it, as before", () => {
+		const dir = directory("20261025-120000")
+		writeFileSync(join(dir, "outcome.json"), "{")
+		expect(init(dir).status).toBe(0)
+		expect(validateOutcomeManifest(JSON.parse(readFileSync(join(dir, "outcome.json"), "utf8"))).ok).toBe(true)
+	})
+
+	test("#given the legacy library call with a stamped dir #when initialized #then the manifest validates", () => {
+		const manifest = initManifest({ sessionDir: "/nonexistent/20260101-120000", promised: [], lane: null })
+		expect(validateOutcomeManifest(manifest)).toEqual({ ok: true, errors: [] })
+	})
+})

package/dist/skills/ulw-research/scripts/outcome.mjs

@@ -1,14 +1,13 @@
 // 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, MANIFEST_CODES, normalizeManifest, SCHEMA_VERSION, validateOutcomeManifest } from "./contracts.mjs"
+import { runStart } from "./outcome-start.mjs"
 
 export const MANIFEST_FILENAME = "outcome.json"
 const MISSING = MANIFEST_CODES[0]
-const SESSION_STAMP = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})$/
 const SOURCE_LINE = /^\[(S|Source )\d+\]/
 const URL_PATTERN = /https?:\/\/[^\s)<>\]"'`]+/g
 const DRAFT_MARKER = "STATUS: draft"
@@ -33,26 +32,20 @@ function assertOneOf(code, label, value, allowed) {
 
 const clone = (manifest) => structuredClone(manifest)
 const isMissing = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR"
-
 function stamp(now) {
 	return (now ?? new Date()).toISOString()
 }
-
-/** Local wall-clock start time from a `YYYYMMDD-HHMMSS` session dir basename. */
-export function parseSessionStart(sessionDir) {
-	const match = SESSION_STAMP.exec(basename(sessionDir))
-	if (!match) throw new OutcomeError("invalid_session_dir", `session dir basename must be YYYYMMDD-HHMMSS: ${sessionDir}`)
-	const [y, mo, d, h, mi, s] = match.slice(1).map(Number)
-	const date = new Date(y, mo - 1, d, h, mi, s)
-	if (date.getMonth() !== mo - 1 || date.getDate() !== d || date.getHours() !== h) {
-		throw new OutcomeError("invalid_session_dir", `session dir basename is not a real local time: ${sessionDir}`)
+/** The run clock outcome init records (outcome-start.mjs owns the contract). */
+export function parseSessionStart(sessionDir, { startedAt, now } = {}) {
+	const fail = (message) => {
+		throw new OutcomeError("invalid_session_dir", message)
 	}
-	return date
+	return runStart({ sessionDir, startedAt, now, validManifest: (data) => validateOutcomeManifest(normalizeManifest(data)).ok, fail })
 }
 
-/** @param {{ sessionDir: string, promised: string[], lane: string|null, interview?: object|null, now?: Date }} input */
-export function initManifest({ sessionDir, promised, lane, interview = null, now }) {
-	const startedAt = parseSessionStart(sessionDir).toISOString()
+/** @param {{ sessionDir: string, promised: string[], lane: string|null, interview?: object|null, now?: Date, startedAt?: string }} input */
+export function initManifest({ sessionDir, promised, lane, interview = null, now, startedAt: recorded }) {
+	const startedAt = parseSessionStart(sessionDir, { startedAt: recorded, now }).toISOString()
 	if (lane !== null && lane !== undefined) assertOneOf("unknown_lane", "lane", lane, LANES)
 	const formats = [...new Set(promised)]
 	for (const format of formats) assertOneOf("unknown_format", "deliverable format", format, DELIVERABLE_FORMATS)
@@ -74,9 +67,7 @@ export function initManifest({ sessionDir, promised, lane, interview = null, now
 	}
 }
 
-/**
- * Set one format's row; every other row is kept as is. An unpromised format gets a new
- * row with promised=false. The row's detail fields are replaced by the ones given.
+/** Set one format's row, keeping other rows. New formats have promised=false.
  * @param {{ path?: string, reason?: string, pages?: number, bytes?: number, now?: Date }} [detail]
  */
 export function setDeliverable(manifest, format, status, detail = {}) {
@@ -143,9 +134,7 @@ export function verifyManifest(manifest, fs = nodeFs) {
 	return { ok: problems.length === 0, problems }
 }
 
-/**
- * none = missing or empty file; partial = `STATUS: draft` in the first 5 lines, or the
- * manifest (given, else a sibling outcome.json) still has a pending row; else complete.
+/** Missing/empty = none; draft marker or pending manifest = partial; else complete.
  * @returns {"none"|"partial"|"complete"}
  */
 export function deliverableState(deliverablePath, manifestOrNull) {

package/dist/skills/ulw-research/scripts/page-source-locator.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { readLedger } from "./fact-ledger.mjs"
+import { run } from "./report-tools.mjs"
+
+const BRIEF = readFileSync(join(import.meta.dir, "tests/fixtures/fidelity-brief-locked.md"), "utf8")
+
+type Row = { fact_id: string; value: string; unit: string; quote: string; raw: string; sentence_id: string; locator: { artifact: string; unit: string; char_start: number; char_end: number } }
+type Defect = { code: string; message: string }
+
+/** {{F1}} -> {{F1:<its ledger label>}}: fill requires the label. */
+const labeled = (dir: string) => {
+	const labels = new Map(readLedger(dir).rows.map((row: { fact_id: string; label: string }) => [row.fact_id, row.label]))
+	return (placeholder: string) => placeholder.replace(/\{\{(\w+)\}\}/, (_, id) => `{{${id}:${labels.get(id)}}}`)
+}
+
+function session() {
+	const dir = mkdtempSync(join(tmpdir(), "page-source-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	writeFileSync(join(dir, "brief.md"), BRIEF)
+	return dir
+}
+
+async function snapshotPage(dir: string, bytes: Buffer | string, id = "S1") {
+	const file = join(dir, `${id}.capture.html`)
+	writeFileSync(file, bytes)
+	const result = await run(["source", "snapshot", "--id", id, "--html", file, "--session-dir", dir])
+	expect(result.exitCode).toBe(0)
+	return Buffer.from(bytes)
+}
+
+const find = (dir: string, anchor: string, id = "S1") => run(["fact", "add", "--session-dir", dir, "--source", id, "--find", anchor, "--json"])
+const quote = (dir: string, match: string) => run(["fact", "quote", "--session-dir", dir, "--source", "S1", "--match", match, "--json"])
+
+/** Fill a report citing every given placeholder, then verify it; returns the verify result and the filled html. */
+async function fillAndVerify(dir: string, placeholders: string[]) {
+	const body = [
+		'<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Bridge</title></head><body><h1>Bridge</h1>',
+		"<h2>Findings</h2>",
+		...placeholders.map(labeled(dir)).map((placeholder) => `<p>The source states ${placeholder} [S1].</p>`),
+		"<h2>How this report was made</h2><p>Collected from one cited public page [S1].</p>",
+		'<h2>Sources</h2><ol><li id="s1">[S1] Bridge page, retrieved 2026-10-01.</li></ol></body></html>',
+	].join("\n")
+	writeFileSync(join(dir, "report.src.html"), body)
+	const filled = await run(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), "--session-dir", dir])
+	expect(filled.exitCode).toBe(0)
+	const verified = await run(["fact", "verify", join(dir, "report.html"), "--session-dir", dir])
+	return { verified, html: readFileSync(join(dir, "report.html"), "utf8") }
+}
+
+const codes = (json: { defects: Defect[] }) => json.defects.map((defect) => defect.code)
+
+const PAGE = [
+	"<!doctype html><html><head><title>Deck 9 m</title><style>.deck{font-size:14px}</style><script>var span = 9;</script></head><body>",
+	'<p>The main deck spans <span title="9 m" data-v="320">320</span> m in total.</p>',
+	'<p>The upper deck spans <span style="font-size:14px">330</span> m.</p>',
+	"</body></html>",
+].join("")
+
+describe("page sources locate on visible text nodes only", () => {
+	test("#given numbers in title, data and style attributes #when fact add --find runs #then the text-node value is recorded and verifies", async () => {
+		const dir = session()
+		const raw = await snapshotPage(dir, PAGE)
+		const main = await find(dir, "main deck spans")
+		const upper = await find(dir, "upper deck spans")
+		expect(main.exitCode).toBe(0)
+		const row: Row = main.json.data.row
+		expect([row.value, row.unit, row.quote]).toEqual(["320", "m", "The main deck spans 320 m in total."])
+		expect(row.locator).toMatchObject({ artifact: "raw.bin", unit: "bytes" })
+		const span = raw.subarray(row.locator.char_start, row.locator.char_end).toString("utf8")
+		expect(span).toBe('The main deck spans <span title="9 m" data-v="320">320</span> m in total.')
+		expect([upper.json.data.row.value, upper.json.data.row.unit]).toEqual(["330", "m"])
+		const { verified, html } = await fillAndVerify(dir, ["{{F1}}", "{{F2}}"])
+		expect(verified.exitCode).toBe(0)
+		expect(html).toContain("320 m")
+		expect(html).not.toContain(">9 m<")
+	})
+
+	test("#given the same anchor in a hidden element and a visible paragraph #when --find runs #then only the visible number is located", async () => {
+		const dir = session()
+		const hidden = [
+			'<div style="display:none"><p>Visible length is 999 m.</p></div>',
+			'<div style="color:red; visibility: hidden"><p>Shadow length is 998 m.</p></div>',
+			'<p aria-hidden="true">Ghost length is 997 m.</p>',
+			"<p hidden>Secret length is 996 m.</p>",
+			"<noscript>Script length is 995 m.</noscript>",
+			"<template><p>Template length is 994 m.</p></template>",
+		].join("")
+		await snapshotPage(dir, `<html><head><script>Inline length is 993 m.</script><style>.x{}</style></head><body>${hidden}<p>Visible length is 410 m.</p></body></html>`)
+		const visible = await find(dir, "Visible length is")
+		expect(visible.exitCode).toBe(0)
+		expect(visible.json.data.row.value).toBe("410")
+		for (const anchor of ["Shadow length is", "Ghost length is", "Secret length is", "Script length is", "Template length is", "Inline length is"]) {
+			const result = await find(dir, anchor)
+			expect([anchor, result.json.error]).toEqual([anchor, "fact_not_located"])
+		}
+		expect(readFileSync(join(dir, "sources/S1/text.txt"), "utf8")).toBe("Visible length is 410 m.")
+	})
+
+	test("#given elements hidden by <style> rules on a class, an id, or a tag #when --find runs #then they are not located", async () => {
+		const dir = session()
+		const style = "<style>.d-none, .sr-only { display: none } #gone{visibility:hidden} footer{color:red;display:none} div p.keep{display:none}</style>"
+		const body = '<p class="lead d-none">Class length is 999 m.</p><p id="gone">Id length is 998 m.</p><footer>Tag length is 997 m.</footer><p class="keep">Kept length is 410 m.</p>'
+		await snapshotPage(dir, `<html><head>${style}</head><body>${body}</body></html>`)
+		for (const anchor of ["Class length is", "Id length is", "Tag length is"]) expect([anchor, (await find(dir, anchor)).json.error]).toEqual([anchor, "fact_not_located"])
+		expect((await find(dir, "Kept length is")).json.data.row.value).toBe("410")
+	})
+
+	test("#given rules inside @media (a responsive or a print copy) #when --find runs #then the text is located, and an unconditional rule still hides", async () => {
+		const dir = session()
+		const style = "<style>@media (max-width:600px){.desk{display:none}} @media print{.screen{display:none}} .d-none{display:none}</style>"
+		const body = '<p class="desk">Desktop length is 410 m.</p><p class="screen">Screen length is 411 m.</p><p class="d-none">Mobile length is 412 m.</p>'
+		await snapshotPage(dir, `<html><head>${style}</head><body>${body}</body></html>`)
+		const desktop = await find(dir, "Desktop length is")
+		expect(desktop.exitCode).toBe(0)
+		expect(desktop.json.data.row.value).toBe("410")
+		expect((await find(dir, "Screen length is")).json.data.row.value).toBe("411")
+		expect((await find(dir, "Mobile length is")).json.error).toBe("fact_not_located")
+	})
+
+	test("#given a quote across inline markup #when fact quote --match runs #then the quotation is that sentence, indexed like sentences.jsonl", async () => {
+		const dir = session()
+		await snapshotPage(dir, "<!doctype html><html><head><script>var x = 1;</script></head><body><p>Construction opens <em>no earlier</em> than 2027. Funding is pending.</p></body></html>")
+		const result = await quote(dir, "opens no earlier than 2027")
+		expect(result.exitCode).toBe(0)
+		const row: Row = result.json.data.row
+		expect(row.quote).toBe("Construction opens no earlier than 2027.")
+		const sentences = readFileSync(join(dir, "sources/S1/sentences.jsonl"), "utf8").trim().split("\n").map((line) => JSON.parse(line))
+		expect(sentences.find((entry: { sid: string }) => entry.sid === row.sentence_id)?.text).toBe(row.quote)
+		const { verified, html } = await fillAndVerify(dir, ["{{Q1}}"])
+		expect(verified.exitCode).toBe(0)
+		expect(html).toContain("Construction opens no earlier than 2027.")
+		expect(html).not.toContain("&lt;")
+	})
+
+	test("#given a table cell without </td> #when --table runs #then the quote is the cell text, not the rest of the document", async () => {
+		const dir = session()
+		const raw = await snapshotPage(dir, '<table id="sizes"><tr><th>Name</th><th>Length</th></tr><tr><td>Deck</td><td><b title="9">320</b> m</tr></table><p>Appendix 9 holds notes.</p>')
+		const result = await run(["fact", "add", "--session-dir", dir, "--source", "S1", "--table", "sizes", "--row", "Deck", "--col", "Length", "--json"])
+		expect(result.exitCode).toBe(0)
+		const row: Row = result.json.data.row
+		expect([row.value, row.unit, row.quote]).toEqual(["320", "m", "320 m"])
+		expect(raw.subarray(row.locator.char_start, row.locator.char_end).toString()).toBe('320</b> m')
+		expect((await fillAndVerify(dir, ["{{F1}}"])).verified.exitCode).toBe(0)
+	})
+})
+
+describe("byte offsets count the source's own encoding", () => {
+	const latin1 = (text: string) => Buffer.from(text, "latin1")
+
+	test("#given a declared ISO-8859-1 page with Caf\\xE9 before the value #when added and verified unchanged #then offsets hit the real bytes and verify is clean", async () => {
+		const dir = session()
+		const raw = await snapshotPage(dir, latin1('<html><head><meta charset="iso-8859-1"></head><body><p>Caf\u00e9. The span is 320 m.</p></body></html>'))
+		const result = await find(dir, "The span is")
+		const row: Row = result.json.data.row
+		expect(raw.subarray(row.locator.char_start, row.locator.char_end).toString("latin1")).toBe("The span is 320 m.")
+		const { verified } = await fillAndVerify(dir, ["{{F1}}"])
+		expect(verified.exitCode).toBe(0)
+		expect(codes(verified.json)).not.toContain("relocated")
+	})
+
+	test("#given an undeclared Latin-1 byte with more than 32 characters before the value #when verified unchanged #then no false relocation", async () => {
+		const dir = session()
+		await snapshotPage(dir, latin1("<p>Caf\u00e9 au lait is served here all day long. The span is 320 m.</p>"))
+		await find(dir, "The span is")
+		const { verified } = await fillAndVerify(dir, ["{{F1}}"])
+		expect(verified.exitCode).toBe(0)
+		expect(codes(verified.json)).toEqual([])
+	})
+
+	test("#given an EUC-KR page #when added and verified unchanged #then the locator spans the EUC-KR bytes and verify is clean", async () => {
+		const dir = session()
+		const bytes = Buffer.from("3c68746d6c3e3c686561643e3c6d65746120636861727365743d226575632d6b72223e3c2f686561643e3c626f64793e3c703ec1d620b1b3b7aec0c720b1e6c0ccb4c220333230206d20c0ccb4d92e3c2f703e3c2f626f64793e3c2f68746d6c3e", "hex")
+		const raw = await snapshotPage(dir, bytes)
+		const result = await find(dir, "\uae38\uc774\ub294")
+		expect(result.exitCode).toBe(0)
+		const row: Row = result.json.data.row
+		expect(row.value).toBe("320")
+		expect(raw.subarray(row.locator.char_start, row.locator.char_end).toString("hex")).toBe("c1d620b1b3b7aec0c720b1e6c0ccb4c220333230206d20c0ccb4d92e")
+		const { verified } = await fillAndVerify(dir, ["{{F1}}"])
+		expect(verified.exitCode).toBe(0)
+		expect(codes(verified.json)).toEqual([])
+	})
+})

package/dist/skills/ulw-research/scripts/placeholder.mjs

@@ -1,14 +1,16 @@
 // 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}}.
+// Claim prefixes from CLAIM_KINDS (V, D, A) precede any one pointer: {{D:F12:label:value}}, {{V:Q7:label:lead=18}}.
 // 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"
+import { CLAIM_KINDS } from "./claim-kinds.mjs"
 
 export const ELLIPSIS = "\u2026"
 
-const ID = /^([FQ])\d+$/
+const ID = /^([FQ])[1-9]\d*$/
 const LABEL = /^[^\s:{}"]+$/
 const VALUE_MODES = new Set(["value", "unit", "q"])
 const LEAD = /^lead=([1-9]\d*)$/
@@ -45,6 +47,12 @@ function parseAnchors(tail) {
 export function parsePlaceholder(token) {
 	if (!token.startsWith("{{") || !token.endsWith("}}")) return { error: "a placeholder is {{ID:label...}}" }
 	const body = token.slice(2, -2)
+	const marked = Object.entries(CLAIM_KINDS).find(([, entry]) => entry.prefix && body.startsWith(`${entry.prefix}:`))
+	if (marked) {
+		const [claimKind, entry] = marked
+		const parsed = parsePlaceholder(`{{${body.slice(entry.prefix.length + 1)}}}`)
+		return parsed.error || parsed.claimKind ? { error: "a claim prefix must precede one fact or quote pointer" } : { ...parsed, claimKind }
+	}
 	const colon = body.indexOf(":")
 	const id = colon === -1 ? body : body.slice(0, colon)
 	const idMatch = ID.exec(id)
@@ -130,7 +138,7 @@ export function lead(quote, n) {
 /** 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)
+	const valueText = unitText && row.raw.endsWith(unitText) ? row.raw.slice(0, -unitText.length).trimEnd() : row.raw
 	return { valueText, unitText: unitText ?? "" }
 }
 
@@ -156,15 +164,19 @@ export function escapeHtml(text) {
 /** 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) {
+/** `mode` "value" marks a bare value whose unit verify checks beside it; `claimKind` is the claim mark. */
+export function renderValueHtml(row, text, { mode = "full", claimKind = null } = {}) {
 	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>`
+	const marker = mode === "value" ? ' data-fact-mode="value"' : ""
+	const mark = claimKind === null ? "" : ` data-claim-kind="${escapeHtml(claimKind)}"`
+	return `<data class="fact" value="${escapeHtml(row.value)}" data-fact="${row.fact_id}"${unit}${marker}${mark} data-lineage="${LINEAGE[row.kind]}">${escapeHtml(text)}</data>`
 }
 
-export function renderQuote(row, selector, text, format) {
+export function renderQuote(row, selector, text, format, claimKind = null) {
 	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 mark = claimKind === null ? "" : ` data-claim-kind="${escapeHtml(claimKind)}"`
+	return `<q data-fact="${row.fact_id}"${mark} data-quote-sel="${escapeHtml(selector)}">${escapeHtml(text)}</q> ${marker}`
 }
 
 const RENDERED_MD_QUOTE = /^"([\s\S]*)" (\[S\d+\])$/u

package/dist/skills/ulw-research/scripts/polish-apply.mjs

@@ -54,9 +54,10 @@ export const POLISH_REFERENCE_REASON = "edit touches a character reference: rout
 /** 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
+		const stop = match.index + match[0].length
+		if (match.index < end && (stop > start || (stop === start && !match[0].endsWith(";")))) return true
 	}
-	return /&[#\w]*$/.test(html.slice(Math.max(0, start - 16), start))
+	return false
 }
 
 const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")

package/dist/skills/ulw-research/scripts/polish-markup.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test"
 
 import { markupParts, skeletonChange } from "./html-markup.mjs"
-import { applyEdits, POLISH_MARKUP_REASON, textOf } from "./polish-apply.mjs"
+import { applyEdits, POLISH_MARKUP_REASON, POLISH_REFERENCE_REASON, textOf } from "./polish-apply.mjs"
 import { diffPolish } from "./polish-diff.mjs"
 
 const LEDGER = { rows: [{ fact_id: "F1", quote: "Revenue may reach 320 m." }] }
@@ -147,6 +147,20 @@ describe("polish edits never carry markup characters", () => {
 const AMPD = "<p>We fund R&amp;D labs here.</p>"
 const TOM = "<p>Tom & Jerry ran.</p>"
 describe("polish keeps character references intact", () => {
+	test.each(["style", "p"])("#given a quoted greater-than in a %s end tag #when its quote changes #then diff blocks", (tag: string) => {
+		const before = `<${tag}>p{}</${tag} a='>'> trailing prose`
+		const after = before.replace(">'", ">x")
+		expect(diffPolish(before, after, LEDGER).map((item: { code: string }) => item.code)).toContain("polish_diff_fail")
+	})
+
+	test.each(["&amp.", `&${"a".repeat(24)}.`])("#given %s immediately before an edit #when extended #then the reference reason is actionable", (reference: string) => {
+		const html = `<p>${reference} next</p>`
+		const result = applyEdits(html, [{ before: " next", after: "later" }], LEDGER)
+		expect(result.rejected[0]?.reason).toContain(POLISH_REFERENCE_REASON)
+		expect(result.out).toBe(html)
+		expect(diffPolish(html, html.replace(" next", "later"), LEDGER).map((item: { code: string }) => item.code)).toContain("polish_diff_fail")
+	})
+
 	test.each([
 		["an edit starting inside an entity", AMPD, "amp;D labs", "lt;D labs"],
 		["an edit starting right after a bare ampersand", TOM, " Jerry ran", "lt; ran"],

package/dist/skills/ulw-research/scripts/polish-partial.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+
+describe("polish partial-apply CLI contract", () => {
+	test.each([
+		["boundary rejection", [{ before: "Fine <em>words", after: "Better words" }], false, 0, 1, 0],
+		["accepted wording", [{ before: "Fine", after: "Good" }], true, 1, 0, 0],
+		["mixed edits", [{ before: "Fine", after: "Good" }, { before: "<em>words", after: "words" }], false, 1, 1, 0],
+		["unlocated wording", [{ before: "Missing", after: "Better" }], false, 0, 0, 1],
+	] as const)("#given %s #when partially applied #then JSON distinguishes full application from output success", (_label, editsInput, applied, count, rejected, unlocated) => {
+		const dir = mkdtempSync(join(tmpdir(), "polish-boundary-"))
+		try {
+			const report = join(dir, "report.html")
+			const edits = join(dir, "edits.json")
+			const ledger = join(dir, "ledger.json")
+			const out = join(dir, "out.html")
+			const html = "<p>Fine <em>words</em> here.</p>"
+			writeFileSync(report, html)
+			writeFileSync(edits, JSON.stringify(editsInput))
+			writeFileSync(ledger, JSON.stringify({ schemaVersion: 1, rows: [], events: [] }))
+			const result = spawnSync("node", [
+				join(import.meta.dir, "report-tools.mjs"), "fact", "polish-apply", report,
+				"--edits", edits, "--ledger", ledger, "--out", out,
+				"--brief", join(import.meta.dir, "tests/fixtures/fidelity-brief-locked.md"),
+			], { encoding: "utf8" })
+			expect(result.error).toBeUndefined()
+			const json = JSON.parse(result.stdout)
+			expect(json.data).toMatchObject({ applied: count, rejected, unlocated })
+			expect(json.defects.map((defect: { code: string }) => defect.code)).toEqual(
+				rejected > 0 ? ["polish_edit_rejected"] : unlocated > 0 ? ["polish_edit_unlocated"] : [],
+			)
+			expect(readFileSync(out, "utf8")).toBe(count > 0 ? html.replace("Fine", "Good") : html)
+			expect(result.status).toBe(0)
+			expect(json.applied).toBe(applied)
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+})