oh-my-opencode 5.1.48 → 5.1.51

package/packages/omo-codex/plugin/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/packages/omo-codex/plugin/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/packages/omo-codex/plugin/skills/ulw-research/scripts/raw-decode.mjs

@@ -0,0 +1,110 @@
+// raw-decode.mjs - decode a source's raw bytes in their declared encoding and keep a byte map.
+//
+// decodeRaw returns { text, encoding, bytes } where bytes[i] is the raw byte offset at which UTF-16
+// unit i of `text` starts and bytes[text.length] === raw.length, so any text range maps back to the
+// bytes the source actually holds (never to a lossy UTF-8 re-encode). The encoding comes from a
+// BOM, then the caller's declared charset (HTTP header or meta.json), then an HTML <meta> charset,
+// and defaults to UTF-8. node: builtins only (TextDecoder).
+
+const SNIFF_BYTES = 1024
+const META_CHARSET = /<meta\b[^>]*?charset\s*=\s*["']?\s*([\w.:-]+)/i
+
+/** The WHATWG encoding name for a label, or null when the runtime does not know it. */
+export function encodingOf(label) {
+	if (typeof label !== "string" || label.trim() === "") return null
+	try {
+		return new TextDecoder(label.trim()).encoding
+	} catch {
+		return null
+	}
+}
+
+/** charset=... from a Content-Type header value, as an encoding name, or null. */
+export function headerCharset(contentType) {
+	const match = /charset\s*=\s*["']?([\w.:-]+)/i.exec(String(contentType ?? ""))
+	return match ? encodingOf(match[1]) : null
+}
+
+function bomOf(raw) {
+	if (raw[0] === 0xef && raw[1] === 0xbb && raw[2] === 0xbf) return { encoding: "utf-8", skip: 3 }
+	if (raw[0] === 0xff && raw[1] === 0xfe) return { encoding: "utf-16le", skip: 2 }
+	if (raw[0] === 0xfe && raw[1] === 0xff) return { encoding: "utf-16be", skip: 2 }
+	return null
+}
+
+/** BOM, then the declared charset, then (for markup) a <meta> charset in the first 1 KiB, then UTF-8. */
+export function detectEncoding(raw, declared = null, markup = false) {
+	const bom = bomOf(raw)
+	if (bom) return bom.encoding
+	const given = encodingOf(declared)
+	if (given) return given
+	if (markup) {
+		const sniffed = META_CHARSET.exec(Buffer.from(raw.subarray(0, SNIFF_BYTES)).toString("latin1"))
+		const named = sniffed ? encodingOf(sniffed[1]) : null
+		// A page that is already decoded to UTF-16 cannot declare a UTF-16 charset in ASCII bytes.
+		if (named && !named.startsWith("utf-16")) return named
+	}
+	return "utf-8"
+}
+
+function utf8Map(text, bytes, from) {
+	let at = from
+	for (let i = 0; i < text.length; i++) {
+		bytes[i] = at
+		const code = text.charCodeAt(i)
+		if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+			bytes[++i] = at
+			at += 4
+		} else at += code < 0x80 ? 1 : code < 0x800 ? 2 : 3
+	}
+	return at
+}
+
+/** Byte-at-a-time streaming decode: correct for any encoding, used when no shortcut applies. */
+function streamMap(raw, encoding, from) {
+	const decoder = new TextDecoder(encoding)
+	const units = []
+	const starts = []
+	let pending = from
+	for (let i = from; i < raw.length; i++) {
+		const out = decoder.decode(raw.subarray(i, i + 1), { stream: true })
+		if (out.length === 0) continue
+		// A replacement for an earlier broken sequence can arrive with this byte's own character.
+		const own = out.length > 1 && raw[i] < 0x80 ? 1 : 0
+		for (let k = 0; k < out.length; k++) starts.push(k >= out.length - own ? i : pending)
+		units.push(out)
+		pending = i + 1
+	}
+	const tail = decoder.decode()
+	for (let k = 0; k < tail.length; k++) starts.push(pending)
+	units.push(tail)
+	return { text: units.join(""), starts }
+}
+
+/** Decode raw bytes; bytes is an Int32Array of length text.length + 1 (see the file comment). */
+export function decodeRaw(raw, declared = null, markup = false) {
+	const buffer = Buffer.from(raw)
+	const encoding = detectEncoding(buffer, declared, markup)
+	const skip = bomOf(buffer)?.encoding === encoding ? bomOf(buffer).skip : 0
+	if (encoding === "utf-8") {
+		try {
+			const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer.subarray(skip))
+			const bytes = new Int32Array(text.length + 1)
+			bytes[text.length] = utf8Map(text, bytes, skip)
+			return { text, encoding, bytes }
+		} catch {
+			// invalid UTF-8: fall through to the streaming map, which counts each broken byte once
+		}
+	}
+	if (encoding !== "utf-8" && !encoding.startsWith("utf-16")) {
+		const text = new TextDecoder(encoding).decode(buffer.subarray(skip))
+		if (text.length === buffer.length - skip) {
+			const bytes = new Int32Array(text.length + 1)
+			for (let i = 0; i <= text.length; i++) bytes[i] = skip + i
+			return { text, encoding, bytes }
+		}
+	}
+	const { text, starts } = streamMap(buffer, encoding, skip)
+	const bytes = Int32Array.from([...starts, buffer.length])
+	return { text, encoding, bytes }
+}

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

@@ -0,0 +1,47 @@
+// Byte locators over a source view (source-view.mjs) and exact, context-bound re-anchoring.
+// Matching always happens on the view's text (text nodes of a page, never markup); only the
+// stored offsets are bytes of the view's artifact. value_span remains quote-relative text.
+
+const chars = (text) => [...text]
+
+/** Context is copied before normalization, around the value (or the whole quote for Q rows). */
+export function quoteContext(text, start, end) {
+	return { prefix: chars(text.slice(0, start)).slice(-32).join(""), suffix: chars(text.slice(end)).slice(0, 32).join("") }
+}
+
+/** Convert a text-space locator from fact-locate.mjs into artifact byte offsets. */
+export function rawLocated(view, found) {
+	if (found.error) return found
+	const { char_start: start, char_end: end } = found.locator
+	const from = start + (found.value_span?.[0] ?? 0)
+	const to = found.value_span ? start + found.value_span[1] : end
+	const [byteStart, byteEnd] = view.byteSpan(start, end)
+	return {
+		...found,
+		context: quoteContext(view.text, from, to),
+		locator: { ...found.locator, artifact: view.artifact, unit: "bytes", char_start: byteStart, char_end: byteEnd },
+	}
+}
+
+function contextMatches(text, row, start, end) {
+	if (!row.context) return false
+	const from = row.value_span ? start + row.value_span[0] : start
+	const to = row.value_span ? start + row.value_span[1] : end
+	const { prefix, suffix } = row.context
+	return from >= prefix.length && text.slice(from - prefix.length, from) === prefix && text.slice(to, to + suffix.length) === suffix
+}
+
+/**
+ * The row's quote in the view: unchanged when an exact occurrence sits at the pinned byte range,
+ * else exactly one occurrence whose context matches (relocated), else null. Never rewrites the row.
+ */
+export function reanchor(view, row) {
+	const quote = String(row.quote ?? "")
+	if (quote === "" || !view.byteSpan) return null
+	const { char_start: start, char_end: end } = row.locator
+	const hits = []
+	for (let at = view.text.indexOf(quote); at !== -1; at = view.text.indexOf(quote, at + 1)) hits.push({ at, span: view.byteSpan(at, at + quote.length) })
+	if (hits.some(({ span }) => span[0] === start && span[1] === end)) return { start, end, relocated: false }
+	const matching = hits.filter(({ at }) => contextMatches(view.text, row, at, at + quote.length))
+	return matching.length === 1 ? { start: matching[0].span[0], end: matching[0].span[1], relocated: true } : null
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/report-tools-commands.mjs

@@ -133,7 +133,7 @@ export async function runOutcome(argv) {
 	switch (sub) {
 		case "init": {
 			const promised = args.required("promised").split(",").map((s) => s.trim()).filter(Boolean)
-			const manifest = outcome.initManifest({ sessionDir: sessionDirFrom(args.flags), promised, lane: args.flags.lane ?? null, now: nowFrom(args.flags) })
+			const manifest = outcome.initManifest({ sessionDir: sessionDirFrom(args.flags), promised, lane: args.flags.lane ?? null, now: nowFrom(args.flags), startedAt: args.flags["started-at"] })
 			outcome.writeManifest(file, manifest)
 			return { json: { command: "outcome init", path: file, deliverables: manifest.deliverables }, exitCode: 0 }
 		}

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

@@ -28,6 +28,8 @@ export const COMMANDS = Object.freeze([
 	"fact verify",
 	"fact derive",
 	"source snapshot",
+	"source refresh",
+	"source probe-conversion",
 	"claims index",
 ])
 
@@ -53,7 +55,11 @@ export async function run(argv) {
 			return (await import("./source-commands.mjs")).runClaims(rest)
 		case "--help":
 		case "help":
-			if (rest.includes("--json")) return { json: { commands: COMMANDS }, exitCode: 0 }
+			if (rest.includes("--json")) {
+				const { SNAPSHOT_USAGE } = await import("./source-commands.mjs")
+				const { REFRESH_USAGE } = await import("./source-refresh.mjs")
+				return { json: { commands: COMMANDS, usage: { "source snapshot": SNAPSHOT_USAGE, "source refresh": REFRESH_USAGE } }, exitCode: 0 }
+			}
 			return { text: `report-tools <command>\n${COMMANDS.map((name) => `  ${name}`).join("\n")}`, exitCode: 0 }
 		default:
 			throw new CliError(`usage: report-tools <${COMMANDS.join(" | ")}> (run --help)`)

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

@@ -1,9 +1,13 @@
-// source-commands.mjs - the `source snapshot` and `claims index` subcommands of report-tools.
-// A source dir is immutable: the same id with identical text is a no-op, different text fails
-// (exit 1, snapshot_exists), because ledger rows pin the old hash. `--url` fetches with plain
-// fetch (30 s timeout, no browser) and records extractor tool:source-snapshot@1; `--html` and
-// `--text` import a browser-lane capture and record extractor model (lower trust), or the named
-// extractor for `--text --extractor NAME@VERSION`; `--command` runs an argv without a shell and
+// source-commands.mjs - the `source snapshot`, `source refresh` and `claims index` subcommands of
+// report-tools. A source dir is immutable: the same id with identical bytes is a no-op, different
+// bytes fail (exit 1, snapshot_exists), because ledger rows pin the old hash; `source refresh`
+// (source-refresh.mjs) is the one explicit repin. `--replace` swaps in a corrected capture under the
+// same id (the conversion_altered_number recovery) only while no active ledger row cites the id
+// (exit 1, snapshot_pinned, listing them). `--url` fetches with plain fetch (30 s timeout,
+// no browser) and records extractor tool:source-snapshot@1; `--html` imports a browser-lane page
+// capture and `--raw` alone a saved file's bytes (extractor model). `--text` alone registers a converted-only source (no raw bytes:
+// quotes only); `--raw <bytes> --text <extraction> --extractor NAME@VERSION` keeps the original
+// bytes and declares the text their extraction. `--command` runs an argv without a shell and
 // snapshots its stdout, with the argv, cwd, exit status, and output hashes in command.json.
 // node: builtins and sibling imports only.
 
@@ -13,14 +17,18 @@ import { join, resolve } from "node:path"
 
 import { indexClaims } from "./claims-index.mjs"
 import { CliError, parseArgs, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
+import { runConversionProbe } from "./conversion-probe.mjs"
+import { readLedger } from "./fact-ledger.mjs"
 import { parseFidelityBlock } from "./fidelity-brief.mjs"
 import { parseSourceFloor } from "./fidelity-policy.mjs"
+import { encodingOf, headerCharset } from "./raw-decode.mjs"
 import { writeSnapshot } from "./source-snapshot.mjs"
+import { readSnapshot } from "./source-view.mjs"
 
 const FETCH_TIMEOUT_MS = 30_000
 const TOOL_EXTRACTOR = "tool:source-snapshot@1"
-const SNAPSHOT_USAGE =
-	"usage: source snapshot --id S<n> (--url <u> | --html <file> | --text <file> [--extractor NAME@VERSION] | --command '<argv json>' --cwd DIR) [--kind page|command|document] [--provenance primary|secondary] [--revision R] --session-dir D"
+export const SNAPSHOT_USAGE =
+	"usage: source probe-conversion <raw-file> <converted-file> | source snapshot --id S<n> (--url <u> | --html <file> | --raw <file> [--text <file> --extractor NAME@VERSION] | --text <file> (converted-only) | --command '<argv json>' --cwd DIR) [--charset NAME] [--kind page|command|document|converted-only] [--provenance primary|secondary] [--revision R] [--replace] --session-dir D"
 
 function readInput(path) {
 	try {
@@ -37,12 +45,15 @@ export function sessionDirOf(flags) {
 	return resolve(dir)
 }
 
-/** The snapshot of one source: meta.json, text.txt, and source.html when the source was a page. */
+/** The snapshot as source-view.mjs reads it ({ meta, raw, sha256, drift, view }); unreadable is a usage error. */
 export function snapshotOf(sessionDir, id) {
 	const dir = join(sessionDir, "sources", String(id))
 	if (!existsSync(join(dir, "meta.json"))) throw new CliError(`source ${id} has no snapshot; run source snapshot --id ${id} first`)
-	const html = join(dir, "source.html")
-	return { meta: JSON.parse(readInput(join(dir, "meta.json"))), text: readInput(join(dir, "text.txt")), html: existsSync(html) ? readInput(html) : null }
+	try {
+		return readSnapshot(dir)
+	} catch (error) {
+		throw new CliError(`source ${id}: ${error.message}`)
+	}
 }
 
 /**
@@ -72,10 +83,10 @@ async function fetchSource(url) {
 	const type = response.headers.get("content-type") ?? ""
 	if (/pdf/i.test(type)) {
 		await response.body?.cancel()
-		throw new CliError(`pdf response: ${url}; extract its text and use --text <file> --extractor NAME@VERSION`)
+		throw new CliError(`pdf response: ${url}; save the bytes and use --raw <file.pdf> --text <extracted.txt> --extractor NAME@VERSION`)
 	}
-	const body = await response.text()
-	return /html|xml/i.test(type) || /^\s*</.test(body) ? { url, html: body } : { url, text: body }
+	const raw = Buffer.from(await response.arrayBuffer())
+	return { url, raw, charset: headerCharset(type), markup: /html|xml/i.test(type) || /^\s*</.test(raw.subarray(0, 1024).toString("latin1")) }
 }
 
 function runCommand(argvJson, cwd) {
@@ -89,35 +100,76 @@ function runCommand(argvJson, cwd) {
 		throw new CliError("--command must be a non-empty JSON array of non-empty strings")
 	}
 	if (!cwd || cwd === true) throw new CliError("--command needs --cwd DIR")
-	const proc = spawnSync(argv[0], argv.slice(1), { cwd: resolve(cwd), encoding: "utf8", shell: false, maxBuffer: 64 * 1024 * 1024 })
+	const proc = spawnSync(argv[0], argv.slice(1), { cwd: resolve(cwd), shell: false, maxBuffer: 64 * 1024 * 1024 })
 	if (proc.error) throw new CliError(`--command could not start: ${proc.error.message}`)
 	const receipt = { argv, cwd: resolve(cwd), exit_status: proc.status, stdout_sha256: sha256Of(proc.stdout), stderr_sha256: sha256Of(proc.stderr) }
-	return { path: `command:${argv.join(" ")}`, text: proc.stdout, kind: "command", receipt }
+	return { path: `command:${argv.join(" ")}`, raw: proc.stdout, kind: "command", receipt }
+}
+
+function readBytes(path) {
+	try {
+		return readFileSync(path)
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
 }
 
-async function acquire(flags) {
+/** The snapshot input the flags describe; shared by `source snapshot` and `source refresh`. */
+export async function acquire(flags) {
 	const given = ["url", "html", "text", "command"].filter((name) => flags[name] !== undefined)
-	if (given.length !== 1) throw new CliError(SNAPSHOT_USAGE)
+	if (flags.raw !== undefined && given.some((name) => name !== "text")) throw new CliError("--raw goes alone or with --text (--url, --html and --command already keep the raw bytes)")
+	if (given.length + (flags.raw !== undefined && flags.text === undefined ? 1 : 0) !== 1) throw new CliError(SNAPSHOT_USAGE)
 	if (flags.extractor !== undefined && flags.text === undefined) throw new CliError("--extractor goes with --text only")
-	if (flags.url !== undefined) return { ...(await fetchSource(flags.url)), extractor: TOOL_EXTRACTOR }
-	if (flags.html !== undefined) return { path: resolve(flags.html), html: readInput(flags.html), extractor: "model" }
-	if (flags.text !== undefined) return { path: resolve(flags.text), text: readInput(flags.text), extractor: flags.extractor === undefined ? "model" : `extractor:${flags.extractor}` }
+	if (flags.charset !== undefined && encodingOf(flags.charset) === null) throw new CliError(`--charset ${flags.charset} is not a known encoding`)
+	const charset = flags.charset === undefined ? {} : { charset: encodingOf(flags.charset) }
+	if (flags.url !== undefined) return { ...(await fetchSource(flags.url)), ...charset, extractor: TOOL_EXTRACTOR }
+	if (flags.html !== undefined) return { path: resolve(flags.html), raw: readBytes(flags.html), markup: true, ...charset, extractor: "model" }
+	if (flags.raw !== undefined && flags.text === undefined) return { path: resolve(flags.raw), raw: readBytes(flags.raw), ...charset, extractor: "model" }
+	if (flags.text !== undefined) {
+		const extractor = flags.extractor === undefined ? "model" : `extractor:${flags.extractor}`
+		if (flags.raw !== undefined) return { path: resolve(flags.raw), raw: readBytes(flags.raw), text: readInput(flags.text), ...charset, extractor }
+		if (flags.kind !== undefined && flags.kind !== "converted-only") throw new CliError("--text without --raw registers a converted-only source; pass --raw <original bytes> to keep a measurable snapshot")
+		return { path: resolve(flags.text), text: readInput(flags.text), kind: "converted-only", extractor }
+	}
 	return { ...runCommand(flags.command, flags.cwd), extractor: TOOL_EXTRACTOR }
 }
 
+/**
+ * `--replace` with `--text` alone (the conversion_altered_number recovery) keeps the source's raw.bin and
+ * declares the verified text its extraction, so value rows locate in text.txt while the original bytes stay
+ * pinned; plain `--text` without `--replace`, or over an id with no raw.bin, stays converted-only.
+ */
+function declareOverKeptRaw(sourcesDir, id, input) {
+	const dir = join(sourcesDir, String(id))
+	if (input.kind !== "converted-only" || !existsSync(join(dir, "raw.bin")) || !existsSync(join(dir, "meta.json"))) return
+	const before = JSON.parse(readFileSync(join(dir, "meta.json"), "utf8"))
+	Object.assign(input, { url: before.url, raw: readFileSync(join(dir, "raw.bin")), kind: before.kind, declared: true })
+	delete input.path
+}
+
 export async function runSource(argv) {
 	const [sub, ...rest] = argv
+	if (sub === "refresh") return (await import("./source-refresh.mjs")).runRefresh(rest)
+	if (sub === "probe-conversion") return runConversionProbe(rest)
 	if (sub !== "snapshot") throw new CliError(SNAPSHOT_USAGE)
-	const args = parseArgs(rest)
+	const args = parseArgs(rest, { booleans: ["replace"] })
 	const id = args.required("id")
-	const sourcesDir = join(sessionDirOf(args.flags), "sources")
+	const sessionDir = sessionDirOf(args.flags)
+	const sourcesDir = join(sessionDir, "sources")
+	const replace = args.flags.replace === true
+	const pinned = replace ? readLedger(sessionDir).rows.filter((row) => row.source_id === id && (row.status ?? "active") === "active").map((row) => row.fact_id) : []
+	if (pinned.length > 0) {
+		const message = `${id} is cited by active row(s) ${pinned.join(", ")}; retract them first, or snapshot the corrected text under a new id`
+		return { json: { command: "source snapshot", status: "fail", exitCode: 1, error: "snapshot_pinned", message, rows: pinned }, summary: `source snapshot: ${message}`, exitCode: 1 }
+	}
 	const { receipt, ...input } = await acquire(args.flags)
+	if (replace) declareOverKeptRaw(sourcesDir, id, input)
 	if (args.flags.kind !== undefined) input.kind = args.flags.kind
 	if (args.flags.provenance !== undefined) input.provenance = args.flags.provenance
 	if (args.flags.revision !== undefined) input.revision = args.flags.revision
 	let written
 	try {
-		written = writeSnapshot(sourcesDir, id, input)
+		written = writeSnapshot(sourcesDir, id, input, { replace })
 	} catch (error) {
 		if (String(error.message).startsWith("snapshot_exists")) {
 			return { json: { command: "source snapshot", status: "fail", exitCode: 1, error: "snapshot_exists", message: error.message }, summary: `source snapshot: ${error.message}`, exitCode: 1 }
@@ -127,8 +179,9 @@ export async function runSource(argv) {
 	}
 	if (receipt) writeFileSync(join(written.dir, "command.json"), `${JSON.stringify(receipt, null, 2)}\n`)
 	const meta = JSON.parse(readFileSync(join(written.dir, "meta.json"), "utf8"))
-	const data = { source_id: id, directory: written.dir, snapshot_sha256: written.sha256, extractor: meta.extractor, kind: meta.kind, provenance: meta.provenance }
-	return { json: { command: "source snapshot", status: "pass", exitCode: 0, data }, summary: `source snapshot: ${id} ${written.sha256.slice(0, 12)} (${meta.extractor})`, exitCode: 0 }
+	const data = { source_id: id, directory: written.dir, snapshot_sha256: written.sha256, extractor: meta.extractor, kind: meta.kind, provenance: meta.provenance, text_source: meta.text_source, ...(written.altered ? { conversion_altered_numbers: written.altered } : {}) }
+	const probe = written.altered ? `; conversion ${written.altered.length} altered${written.altered.length ? ` (${written.altered.join(", ")}): fact add refuses those numbers` : ""}` : ""
+	return { json: { command: "source snapshot", status: "pass", exitCode: 0, data }, summary: `source snapshot: ${id} ${written.sha256.slice(0, 12)} (${meta.extractor}, ${meta.text_source})${probe}`, exitCode: 0 }
 }
 
 export function runClaims(argv) {

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

@@ -0,0 +1,82 @@
+// source-refresh.mjs - `source refresh <S<n>>`: the one explicit repin of a source snapshot.
+//
+// Re-fetches meta.url (or reads the new capture given with the source snapshot input flags),
+// replaces the snapshot, and re-anchors every active byte-located ledger row on that source by its
+// exact quote plus its stored context (raw-locator.mjs reanchor): a row found once gets the new
+// snapshot_sha256 and keeps its old locator, so `fact verify` then reports minor `relocated` with
+// the old and new byte offsets; a row whose quote is gone keeps its old pin, is reported as
+// quote_not_verbatim here, and stays a snapshot_hash_mismatch blocker until it is retracted or
+// re-added. A legacy text.txt row on the source (no byte locator) cannot be re-anchored: it is
+// listed as legacy_not_reanchored and stays a blocker. Exit 0 when every row re-anchored, 1 otherwise. node: builtins and sibling imports only.
+
+import { writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { CliError, parseArgs } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { readLedger, writeLedger } from "./fact-ledger.mjs"
+import { reanchor } from "./raw-locator.mjs"
+import { acquire, sessionDirOf, snapshotOf } from "./source-commands.mjs"
+import { writeSnapshot } from "./source-snapshot.mjs"
+
+export const REFRESH_USAGE =
+	"usage: source refresh S<n> [--url <u> | --html <file> | --raw <file> [--text <file> --extractor NAME@VERSION] | --text <file> | --command '<argv json>' --cwd DIR] [--charset NAME] --session-dir D (no input flag re-fetches the source's http(s) url)"
+
+const INPUTS = ["url", "html", "raw", "text", "command"]
+
+const defect = (code, message) => ({ code, severity: DEFECT_CODES[code].severity, integrity: DEFECT_CODES[code].integrity, message })
+
+export async function runRefresh(argv) {
+	const args = parseArgs(argv)
+	const id = args.positionals[0] ?? args.flags.id
+	if (!id || id === true) throw new CliError(REFRESH_USAGE)
+	const sessionDir = sessionDirOf(args.flags)
+	const before = snapshotOf(sessionDir, id)
+	const flags = { ...args.flags }
+	if (!INPUTS.some((name) => flags[name] !== undefined)) {
+		if (!/^https?:\/\//i.test(String(before.meta.url))) throw new CliError(`${id} was not fetched from an http(s) url; pass its new capture. ${REFRESH_USAGE}`)
+		flags.url = before.meta.url
+	}
+	const { receipt, ...input } = await acquire(flags)
+	input.kind ??= flags.kind ?? before.meta.kind
+	input.provenance = flags.provenance ?? before.meta.provenance
+	input.revision = flags.revision ?? before.meta.revision ?? undefined
+	let written
+	try {
+		written = writeSnapshot(join(sessionDir, "sources"), id, input, { replace: true })
+	} catch (error) {
+		if (error instanceof TypeError) throw new CliError(error.message)
+		throw error
+	}
+	if (receipt) writeFileSync(join(written.dir, "command.json"), `${JSON.stringify(receipt, null, 2)}\n`)
+	const after = snapshotOf(sessionDir, id)
+	const ledger = readLedger(sessionDir)
+	const rows = []
+	const defects = []
+	for (const row of ledger.rows) {
+		if (row.source_id !== id || row.status !== "active") continue
+		if (row.locator?.unit === undefined) {
+			rows.push({ fact_id: row.fact_id, status: "legacy_not_reanchored" })
+			defects.push(defect("snapshot_hash_mismatch", `${row.fact_id}: a legacy text.txt row has no byte locator to re-anchor on refreshed ${id}; add it again from the new snapshot or retract it`))
+			continue
+		}
+		if (row.locator.unit !== "bytes") continue
+		const anchor = row.locator.artifact === after.view.artifact ? reanchor(after.view, row) : null
+		const span = `${row.locator.char_start}:${row.locator.char_end}`
+		if (!anchor) {
+			rows.push({ fact_id: row.fact_id, status: "not_found", from: span })
+			defects.push(defect("quote_not_verbatim", `${row.fact_id}: its quote and context are not found once in refreshed ${id}; retract it or add it again from the new snapshot`))
+			continue
+		}
+		row.snapshot_sha256 = after.sha256
+		rows.push({ fact_id: row.fact_id, status: anchor.relocated ? "relocated" : "unchanged", from: span, to: `${anchor.start}:${anchor.end}` })
+		if (anchor.relocated) defects.push(defect("relocated", `${row.fact_id}: ${span} -> ${anchor.start}:${anchor.end} (bytes of ${id}/${after.view.artifact})`))
+	}
+	writeLedger(sessionDir, ledger)
+	const failed = rows.filter((row) => row.status === "not_found" || row.status === "legacy_not_reanchored").length
+	const exitCode = failed > 0 ? 1 : 0
+	const data = { source_id: id, previous_sha256: before.sha256, snapshot_sha256: after.sha256, text_source: after.view.mode, rows }
+	const json = { command: "source refresh", status: exitCode === 0 ? "pass" : "fail", exitCode, defects, data }
+	const moved = rows.filter((row) => row.status === "relocated").length
+	return { json, summary: `source refresh: ${id} ${before.sha256.slice(0, 12)} -> ${after.sha256.slice(0, 12)}; ${rows.length - failed} row(s) re-anchored (${moved} relocated), ${failed} not re-anchored`, exitCode }
+}