oh-my-opencode 5.1.48 → 5.1.54

package/dist/skills/ulw-research/scripts/contracts-validation.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test"
+
+import { SCHEMA_VERSION, normalizeManifest, validateOutcomeManifest, validateRepairState } from "./contracts.mjs"
+
+function fourGateManifest() {
+	const manifest = sampleManifest()
+	const { fidelity: _dropped, ...gates } = manifest.gates
+	return { ...manifest, gates }
+}
+
+function sampleManifest() {
+	return {
+		schemaVersion: SCHEMA_VERSION,
+		sessionDir: "/tmp/session/20260101-120000",
+		startedAt: "2026-01-01T12:00:00.000Z",
+		finishedAt: null,
+		elapsedMinutes: null,
+		lane: "no-format",
+		interview: null,
+		deliverables: [
+			{ format: "pdf", status: "pending", promised: true, updatedAt: "2026-01-01T12:00:00.000Z" },
+		],
+		renders: [],
+		gates: { static: "not_run", fidelity: "not_run", layout: "not_run", visual: "not_run", proofread: "not_run" },
+		residualDefects: [],
+		repair: null,
+		sources: null,
+	}
+}
+
+describe("validateOutcomeManifest", () => {
+	test("#given an empty object #when validated #then it fails naming schemaVersion", () => {
+		const result = validateOutcomeManifest({})
+		expect(result.ok).toBe(false)
+		expect(result.errors.some((e) => e.includes("schemaVersion"))).toBe(true)
+	})
+
+	test("#given a well-formed manifest #when validated #then it passes", () => {
+		expect(validateOutcomeManifest(sampleManifest())).toEqual({ ok: true, errors: [] })
+	})
+
+	test("#given a deliverable with an unknown status #when validated #then the error names the row", () => {
+		const m = sampleManifest()
+		m.deliverables[0].status = "done"
+		const result = validateOutcomeManifest(m)
+		expect(result.ok).toBe(false)
+		expect(result.errors.join("\n")).toMatch(/deliverables\[0\]\.status/)
+	})
+
+	test("#given a manifest written before the fidelity gate #when validated raw and after normalizeManifest #then only the normalized copy passes, with fidelity not_run", () => {
+		const old = fourGateManifest()
+		expect(validateOutcomeManifest(old).ok).toBe(false)
+		const normalized = normalizeManifest(old)
+		expect(normalized.gates.fidelity).toBe("not_run")
+		expect(normalized.gates.static).toBe("not_run")
+		expect(validateOutcomeManifest(normalized)).toEqual({ ok: true, errors: [] })
+		expect(old.gates).not.toHaveProperty("fidelity")
+		const failed = { ...old, gates: { ...old.gates, visual: "fail" } }
+		expect(normalizeManifest(failed).gates.visual).toBe("fail")
+	})
+
+	test("#given a gate with an unknown value #when validated #then it fails", () => {
+		const m = sampleManifest()
+		m.gates.static = "ok"
+		expect(validateOutcomeManifest(m).ok).toBe(false)
+	})
+})
+
+describe("validateRepairState", () => {
+	test("#given a well-formed state #when validated #then it passes, and a bad measure fails", () => {
+		const good = {
+			schemaVersion: SCHEMA_VERSION,
+			startedAt: "2026-01-01T12:00:00.000Z",
+			budget: { maxAttempts: 3, plateauLimit: 2, wallClockMs: 900_000 },
+			attempts: [{ at: "2026-01-01T12:01:00.000Z", measure: [1, 2, 0], signature: "em_dash_in_prose|unsourced_number" }],
+			consecutiveNonProgress: 0,
+			seenSignatures: ["em_dash_in_prose|unsourced_number"],
+		}
+		expect(validateRepairState(good)).toEqual({ ok: true, errors: [] })
+		const bad = { ...good, attempts: [{ at: "x", measure: [1, 2], signature: "" }] }
+		expect(validateRepairState(bad).ok).toBe(false)
+	})
+})

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

@@ -31,7 +31,7 @@ export const DEFECT_CODES = deepFreeze({
 	en_dash_in_prose: { severity: "minor", integrity: false, hint: "Use a hyphen for compounds; keep the en dash only between numbers." },
 	heading_too_long: { severity: "minor", integrity: false, hint: "Shorten the heading to one line (26 Korean characters or 12 English words)." },
 	heading_generic: { severity: "minor", integrity: false, hint: "Make the heading carry the section's claim instead of a generic label." },
-	unsourced_number: { severity: "major", integrity: false, hint: "Tag the number MEASURED / ASSUMED / DERIVED or cite its source in the same paragraph." },
+	unsourced_number: { severity: "major", integrity: false, hint: "Tag the number MEASURED / ASSUMED / DERIVED or cite its source in the same paragraph; under Sources only citation-field numbers and names (a hash, #12, GPT-4, Q3, 10-Q) are exempt, so quote a reference title that carries a code or a figure, or wrap it in <cite>: an unquoted one is checked, and 10-K / 8-K stay numerals because K is a multiplier. A slashed N/M reads as a month/day, so a fraction or a score (2/3, 7/12) under Sources is not checked (#11386): write it as a percent or tag it." },
 	chart_without_figure: { severity: "major", integrity: false, hint: "Wrap the image or chart in a figure container with a caption." },
 	chart_svg_no_text: { severity: "major", integrity: false, hint: "Give the chart a title, axis labels, units, and value labels as SVG text." },
 	chart_svg_missing_labels: { severity: "minor", integrity: false, hint: "Add the missing title, axis ticks, or unit label to the chart." },
@@ -58,12 +58,14 @@ export const DEFECT_CODES = deepFreeze({
 	pointer_label_mismatch: { severity: "blocker", integrity: true, hint: "The placeholder's label is not the row's label; check the id, then the label." },
 	quote_anchor_unresolved: { severity: "blocker", integrity: true, hint: "A from or to anchor is missing or occurs more than once in the quote; pick unique anchor words." },
 	unit_duplicated: { severity: "blocker", integrity: true, hint: "The unit after the placeholder repeats the row's unit; use :value or remove the unit." },
+	conversion_altered_number: { severity: "blocker", integrity: true, hint: "The source conversion altered this number (sources/S<n>/conversion.json lists it); snapshot a verified text of the source over it with `source snapshot --id S<n> --text <verified.txt> --replace` (refused while an active row cites S<n>; then retract those rows or use a new id), then re-add the fact." },
 	polish_diff_fail: { severity: "blocker", integrity: true, hint: "The polish pass changed numbers, tickers, table rows, claim ids, markup, or hidden content; revert to the pre-polish artifact and apply the language fixes only." },
 	fidelity_interview_incomplete: { severity: "blocker", integrity: true, hint: "A fidelity field is pending or missing in brief.md; answer the open question or record its default, then rerun." },
 	derived_not_allowed: { severity: "blocker", integrity: true, hint: "The brief allows no derived or assumed numbers; cite a source row directly or change the brief with the requester." },
 	source_outside_floor: { severity: "blocker", integrity: true, hint: "The row's source is outside the source floor the brief records; use a source the brief allows or remove the fact." },
 	brief_changed: { severity: "blocker", integrity: true, hint: "The edition's fill map was not written under the current ## Fidelity block (it changed after fill, or the map predates the binding); re-run fact fill, then fact verify." },
-	snapshot_hash_mismatch: { severity: "blocker", integrity: true, hint: "The source snapshot changed after it was pinned; re-snapshot the source and re-register its rows." },
+	snapshot_hash_mismatch: { severity: "blocker", integrity: true, hint: "The source snapshot changed after it was pinned or cannot be read; restore it, or run source refresh to re-anchor its rows." },
+	snapshot_not_raw: { severity: "blocker", integrity: true, hint: "Measured rows need the original bytes: snapshot the source with --url, --html, or --raw <bytes> --text <extraction>; converted-only sources support warned quotations only." },
 	chart_value_untraceable: { severity: "blocker", integrity: true, hint: "A chart value, tick, or data file does not match its ledger-backed data source; re-render the chart from the exported data." },
 	quote_unbound: { severity: "blocker", integrity: true, hint: "A direct quotation has no ledger quote row; register it with fact quote and insert it through its placeholder." },
 	edition_unverified: { severity: "blocker", integrity: true, hint: "The delivered file has no matching fact verify record; run fact verify on that edition and record it with --verified-by." },
@@ -82,13 +84,18 @@ export const DEFECT_CODES = deepFreeze({
 	polish_hedging_decreased: { severity: "major", integrity: false, hint: "The polish pass removed qualifiers; restore them." },
 	polish_text_churn: { severity: "major", integrity: false, hint: "More than half the text changed during polish; the pass composed instead of proofreading." },
 	snapshot_mismatch: { severity: "major", integrity: false, hint: "The operands come from different collection windows; use rows from one window or state the windows separately." },
+	operand_timestamp_missing: { severity: "major", integrity: false, hint: "Record the operand's observed_at timestamp before checking its collection window." },
+	operand_missing: { severity: "major", integrity: false, hint: "A windowed operation names an operand that is not in the fact ledger; restore the row or re-derive from existing rows." },
 	join_integrity_fail: { severity: "major", integrity: false, hint: "A table row combines facts from different source observations; keep each row to one observation or split it." },
 	quote_stale_version: { severity: "major", integrity: false, hint: "The quoted source revision differs from the revision the report targets; re-snapshot the target revision or date the quote." },
 	quote_fuzzy_match: { severity: "minor", integrity: false, hint: "The source text is OCR-noisy; confirm the snapshot and prefer the raw document." },
+	relocated: { severity: "minor", integrity: false, hint: "After source refresh the exact quote and context sit at one new byte range; review the old and new offsets (verification never rewrites the row)." },
+	quote_converted_only: { severity: "minor", integrity: false, hint: "The quote comes from a converted-only source with no raw bytes; re-snapshot the original with --raw and --text, or keep the warned quote." },
 	name_outside_quote: { severity: "minor", integrity: false, hint: "A name in the sentence is not in the cited quote; add the source or remove the name." },
 	verification_claim_unmarked: { severity: "minor", integrity: false, hint: "The sentence reads as a check we ran but carries no verified mark; mark it {{V:F<n>:label}} on a recorded command-output row, or reword it." },
 	scope_widened_warn: { severity: "minor", integrity: false, hint: "The sentence uses a broader scope word than the quote; confirm the scope or narrow it." },
 	particle_unverified: { severity: "minor", integrity: false, hint: "The particle after this value could not be checked; read it aloud and fix it by hand if wrong." },
+	unit_unbound: { severity: "minor", integrity: false, hint: "Use the full fact placeholder, or write the unit right after :value (with or without a space; a Korean particle may follow), as its :unit element, or in the matching table column header." },
 	fallback_without_entity: { severity: "minor", integrity: false, hint: "The replacement quote has no entity for attribution; set one on the row." },
 	meaning_drift_warn: { severity: "minor", integrity: false, hint: "A separate reader found the sentence changes scope, subject, or certainty; rewrite from the quote." },
 	polish_edit_unlocated: { severity: "minor", integrity: false, hint: "The edit's before-text was not found exactly once; re-propose against the current text." },
@@ -98,15 +105,17 @@ export const DEFECT_CODES = deepFreeze({
 
 /** Codes only the fidelity verifier raises (fact ledger, fill, verify, meaning, polish). */
 export const FIDELITY_CODES = Object.freeze([
+	"unit_unbound",
 	"unresolved_placeholder", "value_mismatch", "unit_mismatch", "quote_not_verbatim", "claim_status_invalid",
 	"incompatible_operands", "pointer_label_mismatch", "quote_anchor_unresolved", "unit_duplicated", "polish_diff_fail",
 	"fidelity_interview_incomplete", "derived_not_allowed", "source_outside_floor", "brief_changed", "snapshot_hash_mismatch",
+	"conversion_altered_number",
 	"chart_value_untraceable", "quote_unbound", "edition_unverified", "untraceable_number", "unsupported_verification", "claim_kind_mismatch",
 	"conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added", "qualifier_dropped", "unbound_sentence",
 	"meaning_drift_confirmed", "meaning_unverified", "polish_edit_rejected", "polish_hedging_decreased", "polish_text_churn", "snapshot_mismatch",
-	"join_integrity_fail", "quote_stale_version", "quote_fuzzy_match", "name_outside_quote", "verification_claim_unmarked", "scope_widened_warn",
+	"operand_timestamp_missing", "operand_missing", "join_integrity_fail", "quote_stale_version", "quote_fuzzy_match", "name_outside_quote", "verification_claim_unmarked", "scope_widened_warn",
 	"particle_unverified", "fallback_without_entity", "meaning_drift_warn", "polish_edit_unlocated", "polish_link_changed",
-	"polish_name_changed",
+	"polish_name_changed", "snapshot_not_raw", "relocated", "quote_converted_only",
 ])
 const FIDELITY_SET = new Set(FIDELITY_CODES)
 

package/dist/skills/ulw-research/scripts/contracts.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test } from "bun:test"
-
 import {
 	ANSWERED_BY,
 	DEFECT_CODES,
@@ -22,120 +21,14 @@ import {
 	validateOutcomeManifest,
 	validateRepairState,
 } from "./contracts.mjs"
+import { SEVERITIES, STATIC_CODES_EXPECTED, LAYOUT_CODES_EXPECTED, FIDELITY_BLOCKERS, FIDELITY_MAJORS, FIDELITY_MINORS, FIDELITY_CODES_EXPECTED, fourGateManifest, sampleManifest } from "./tests/contracts-support"
 
-const SEVERITIES = new Set(["blocker", "major", "minor"])
-const STATIC_CODES_EXPECTED = [
-	"korean_no_keep_all",
-	"palette_off_token",
-	"emoji_in_prose",
-	"em_dash_in_prose",
-	"en_dash_in_prose",
-	"heading_too_long",
-	"heading_generic",
-	"unsourced_number",
-	"chart_without_figure",
-	"chart_svg_no_text",
-	"chart_svg_missing_labels",
-	"report_without_visual",
-	"image_missing_alt",
-	"korean_serif_font",
-	"section_without_citation",
-	"missing_closing_section",
-	"missing_citation_section",
-	"broken_asset_reference",
-	"missing_required_section",
-]
-const LAYOUT_CODES_EXPECTED = [
-	"layout_overflow",
-	"layout_text_clipped",
-	"layout_scroll_container",
-	"layout_image_distorted",
-	"layout_sibling_overlap",
-]
-// Fidelity vocabulary contract (#11009): severity and integrity per code are fixed here.
-const FIDELITY_BLOCKERS = [
-	"unresolved_placeholder",
-	"value_mismatch",
-	"unit_mismatch",
-	"quote_not_verbatim",
-	"claim_status_invalid",
-	"incompatible_operands",
-	"pointer_label_mismatch",
-	"quote_anchor_unresolved",
-	"unit_duplicated",
-	"polish_diff_fail",
-	"fidelity_interview_incomplete",
-	"derived_not_allowed",
-	"source_outside_floor",
-	"brief_changed",
-	"snapshot_hash_mismatch",
-	"chart_value_untraceable",
-	"quote_unbound",
-	"edition_unverified",
-]
-const FIDELITY_MAJORS = [
-	"untraceable_number",
-	"unsupported_verification",
-	"claim_kind_mismatch",
-	"conflicting_readings",
-	"hedge_dropped",
-	"direction_flipped",
-	"causality_added",
-	"qualifier_dropped",
-	"unbound_sentence",
-	"meaning_drift_confirmed",
-	"meaning_unverified",
-	"polish_edit_rejected",
-	"polish_hedging_decreased",
-	"polish_text_churn",
-	"snapshot_mismatch",
-	"join_integrity_fail",
-	"quote_stale_version",
-]
-const FIDELITY_MINORS = [
-	"quote_fuzzy_match",
-	"name_outside_quote",
-	"verification_claim_unmarked",
-	"scope_widened_warn",
-	"particle_unverified",
-	"fallback_without_entity",
-	"meaning_drift_warn",
-	"polish_edit_unlocated",
-	"polish_link_changed",
-	"polish_name_changed",
-]
-const FIDELITY_CODES_EXPECTED = [...FIDELITY_BLOCKERS, ...FIDELITY_MAJORS, ...FIDELITY_MINORS]
-
-function fourGateManifest() {
-	const manifest = sampleManifest()
-	const { fidelity: _dropped, ...gates } = manifest.gates
-	return { ...manifest, gates }
-}
 
-function sampleManifest() {
-	return {
-		schemaVersion: SCHEMA_VERSION,
-		sessionDir: "/tmp/session/20260101-120000",
-		startedAt: "2026-01-01T12:00:00.000Z",
-		finishedAt: null,
-		elapsedMinutes: null,
-		lane: "no-format",
-		interview: null,
-		deliverables: [
-			{ format: "pdf", status: "pending", promised: true, updatedAt: "2026-01-01T12:00:00.000Z" },
-		],
-		renders: [],
-		gates: { static: "not_run", fidelity: "not_run", layout: "not_run", visual: "not_run", proofread: "not_run" },
-		residualDefects: [],
-		repair: null,
-		sources: null,
-	}
-}
 
 describe("DEFECT_CODES", () => {
 	test("#given the code table #when every code is inspected #then it has a severity, a hint, and an integrity flag", () => {
 		expect(Object.keys(DEFECT_CODES).sort()).toEqual(
-			[...STATIC_CODES_EXPECTED, "missing_promised_deliverable", ...LAYOUT_CODES_EXPECTED, ...FIDELITY_CODES_EXPECTED].sort(),
+			[...STATIC_CODES_EXPECTED, "missing_promised_deliverable", ...LAYOUT_CODES_EXPECTED, ...FIDELITY_CODES_EXPECTED, "conversion_altered_number", "unit_unbound"].sort(),
 		)
 		for (const [code, entry] of Object.entries(DEFECT_CODES)) {
 			expect(SEVERITIES.has(entry.severity), `${code} severity`).toBe(true)
@@ -154,6 +47,7 @@ describe("DEFECT_CODES", () => {
 				"missing_promised_deliverable",
 				"missing_required_section",
 				...FIDELITY_BLOCKERS,
+				"conversion_altered_number",
 			].sort(),
 		)
 		for (const code of INTEGRITY_CODES) expect(DEFECT_CODES[code].severity).toBe("blocker")
@@ -174,8 +68,10 @@ describe("DEFECT_CODES", () => {
 
 	test("#given the fidelity codes #when inspected #then each carries its fixed severity and integrity flag", () => {
 		for (const code of FIDELITY_BLOCKERS) expect([code, DEFECT_CODES[code]?.severity, DEFECT_CODES[code]?.integrity]).toEqual([code, "blocker", true])
+		expect([DEFECT_CODES.conversion_altered_number?.severity, DEFECT_CODES.conversion_altered_number?.integrity]).toEqual(["blocker", true])
 		for (const code of FIDELITY_MAJORS) expect([code, DEFECT_CODES[code]?.severity, DEFECT_CODES[code]?.integrity]).toEqual([code, "major", false])
 		for (const code of FIDELITY_MINORS) expect([code, DEFECT_CODES[code]?.severity, DEFECT_CODES[code]?.integrity]).toEqual([code, "minor", false])
+		expect([DEFECT_CODES.unit_unbound?.severity, DEFECT_CODES.unit_unbound?.integrity]).toEqual(["minor", false])
 		expect(DEFECT_CODES).not.toHaveProperty("incompatible_populations")
 	})
 })
@@ -185,7 +81,7 @@ describe("code groups", () => {
 		expect([...STATIC_CODES].sort()).toEqual(STATIC_CODES_EXPECTED.slice().sort())
 		expect([...LAYOUT_CODES].sort()).toEqual(LAYOUT_CODES_EXPECTED.slice().sort())
 		expect([...MANIFEST_CODES]).toEqual(["missing_promised_deliverable"])
-		expect([...FIDELITY_CODES].sort()).toEqual(FIDELITY_CODES_EXPECTED.slice().sort())
+		expect([...FIDELITY_CODES].sort()).toEqual([...FIDELITY_CODES_EXPECTED, "conversion_altered_number", "unit_unbound"].sort())
 		const union = [...STATIC_CODES, ...LAYOUT_CODES, ...MANIFEST_CODES, ...FIDELITY_CODES].sort()
 		expect(union).toEqual(Object.keys(DEFECT_CODES).sort())
 		expect(new Set(union).size).toBe(union.length)

package/dist/skills/ulw-research/scripts/conversion-altered.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { CliError } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { run } from "./report-tools.mjs"
+import { writeSnapshot } from "./source-snapshot.mjs"
+
+type Json = Record<string, unknown> & { data?: Record<string, unknown>; error?: string }
+const PAGE = "<p>USD 4.2<sup>2</sup> billion in revenue.</p><p>Staff grew to 1,250 people.</p>"
+
+function session() {
+	const dir = mkdtempSync(join(tmpdir(), "conversion-altered-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
+}
+
+async function snapshot(dir: string, html = PAGE) {
+	const file = join(dir, "page.html")
+	writeFileSync(file, html)
+	return (await run(["source", "snapshot", "--id", "S1", "--html", file, "--session-dir", dir])) as { exitCode: number; json: Json; summary: string }
+}
+
+describe("the conversion probe result is consumed", () => {
+	test("#given a page whose conversion altered a number #when snapshotted #then the JSON and the summary report it", async () => {
+		const result = await snapshot(session())
+		expect(result.exitCode).toBe(0)
+		expect(result.json.data?.conversion_altered_numbers).toEqual(["4.22"])
+		expect(result.summary).toContain("1 altered")
+	})
+
+	test("#given an altered 4.22 in conversion.json #when fact add --find locates it #then it refuses with conversion_altered_number and writes no row", async () => {
+		const dir = session()
+		await snapshot(dir)
+		const result = (await run(["fact", "add", "--source", "S1", "--find", "USD", "--label", "usd_bn", "--session-dir", dir, "--json"])) as { exitCode: number; json: Json }
+		expect(result.exitCode).toBe(1)
+		expect(result.json.error).toBe("conversion_altered_number")
+		expect(existsSync(join(dir, "fact-ledger.json"))).toBe(false)
+		expect(DEFECT_CODES.conversion_altered_number).toMatchObject({ severity: "blocker", integrity: true })
+	})
+
+	test("#given an unaltered number in the same snapshot #when fact add --find locates it #then it registers", async () => {
+		const dir = session()
+		await snapshot(dir)
+		const result = (await run(["fact", "add", "--source", "S1", "--find", "Staff grew to", "--label", "staff", "--session-dir", dir, "--json"])) as { exitCode: number; json: Json }
+		expect(result.exitCode).toBe(0)
+		expect((result.json.data?.row as { value: string }).value).toBe("1250")
+	})
+
+	test("#given a non-ISO observed_at #when writeSnapshot runs #then it throws before writing anything", () => {
+		const dir = join(session(), "sources")
+		expect(() => writeSnapshot(dir, "S1", { path: "p.html", html: PAGE, extractor: "model", observed_at: "yesterday" })).toThrow(TypeError)
+		expect(existsSync(join(dir, "S1"))).toBe(false)
+	})
+
+	test("#given an image named chart-109.png beside a glued 10<sup>9</sup> #when fact add --find locates it #then it refuses and registers nothing", async () => {
+		const dir = session()
+		const snap = await snapshot(dir, '<p>Output reached 10<sup>9</sup> kWh</p><p><img src="chart-109.png"></p>')
+		expect(snap.json.data?.conversion_altered_numbers).toEqual(["109"])
+		const result = (await run(["fact", "add", "--source", "S1", "--find", "Output reached", "--label", "output", "--session-dir", dir, "--json"])) as { exitCode: number; json: Json }
+		expect(result.exitCode).toBe(1)
+		expect(result.json.error).toBe("conversion_altered_number")
+		expect(existsSync(join(dir, "fact-ledger.json"))).toBe(false)
+	})
+})
+
+test("#given a genuine 4.22 beside a glued 4.2<sup>2</sup> #when fact add --find locates the genuine one #then the refusal names the --replace recovery", async () => {
+	const dir = session()
+	await snapshot(dir, "<p>USD 4.2<sup>2</sup> billion in revenue.</p><p>Margin was 4.22 points.</p>")
+	const result = (await run(["fact", "add", "--source", "S1", "--find", "Margin was", "--label", "margin", "--session-dir", dir, "--json"])) as { exitCode: number; json: Json & { message?: string } }
+	expect(result.exitCode).toBe(1)
+	expect(result.json.error).toBe("conversion_altered_number")
+	expect(result.json.message).toContain("source snapshot --id S1 --text <verified.txt> --replace")
+})
+
+describe("the documented recovery: source snapshot --replace with a verified text", () => {
+	const s = (dir: string) => ["--session-dir", dir]
+
+	test("#given a refused 4.22 #when the verified text replaces S1 #then fact add registers 4.2 billion and the filled report verifies clean", async () => {
+		const dir = session()
+		await snapshot(dir)
+		const verified = join(dir, "verified.txt")
+		writeFileSync(verified, "USD 4.2 billion in revenue.\nStaff grew to 1,250 people.\n")
+		const replaced = (await run(["source", "snapshot", "--id", "S1", "--text", verified, "--replace", ...s(dir)])) as { exitCode: number; json: Json }
+		expect(replaced.exitCode).toBe(0)
+		expect(existsSync(join(dir, "sources", "S1", "conversion.json"))).toBe(false)
+		const added = (await run(["fact", "add", "--source", "S1", "--find", "USD", "--label", "usd_bn", ...s(dir), "--json"])) as { exitCode: number; json: Json }
+		expect(added.exitCode).toBe(0)
+		expect((added.json.data?.row as { value: string }).value).toBe("4200000000")
+		copyFileSync(join(import.meta.dir, "tests", "fixtures", "fidelity-brief-locked.md"), join(dir, "brief.md"))
+		writeFileSync(join(dir, "report.src.html"), [
+			'<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Revenue</title></head><body><h1>Revenue</h1>',
+			"<h2>Findings</h2><p>Revenue was {{F1:usd_bn}} [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] Revenue page, retrieved 2026-10-01.</li></ol></body></html>',
+		].join("\n"))
+		const filled = (await run(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s(dir)])) as { exitCode: number }
+		expect(filled.exitCode).toBe(0)
+		const verifiedReport = (await run(["fact", "verify", join(dir, "report.html"), "--sources", join(dir, "sources"), "--brief", join(dir, "brief.md"), ...s(dir)])) as { exitCode: number; json: { defects?: unknown[] } }
+		expect(verifiedReport.json.defects).toEqual([])
+		expect(verifiedReport.exitCode).toBe(0)
+	})
+
+	test("#given an active row pinning S1 #when --replace runs #then it refuses with snapshot_pinned and keeps the old text", async () => {
+		const dir = session()
+		await snapshot(dir)
+		await run(["fact", "add", "--source", "S1", "--find", "Staff grew to", "--label", "staff", ...s(dir), "--json"])
+		const verified = join(dir, "verified.txt")
+		writeFileSync(verified, "USD 4.2 billion in revenue.\n")
+		const replaced = (await run(["source", "snapshot", "--id", "S1", "--text", verified, "--replace", ...s(dir)])) as { exitCode: number; json: Json }
+		expect(replaced.exitCode).toBe(1)
+		expect(replaced.json.error).toBe("snapshot_pinned")
+		expect(existsSync(join(dir, "sources", "S1", "conversion.json"))).toBe(true)
+	})
+})
+
+test("#given --html whose conversion altered 4.22 #when fact add is refused, the verified text replaces S1, and the row is added, filled and verified #then the replacement is declared text over the kept raw.bin and every step passes", async () => {
+	const dir = session()
+	const s = ["--session-dir", dir]
+	await snapshot(dir)
+	const refused = (await run(["fact", "add", "--source", "S1", "--find", "USD", "--label", "usd_bn", ...s, "--json"])) as { exitCode: number; json: Json }
+	expect([refused.exitCode, refused.json.error]).toEqual([1, "conversion_altered_number"])
+	const verified = join(dir, "verified.txt")
+	writeFileSync(verified, "USD 4.2 billion in revenue.\nStaff grew to 1,250 people.\n")
+	const replaced = (await run(["source", "snapshot", "--id", "S1", "--text", verified, "--replace", ...s])) as { exitCode: number; json: Json }
+	expect([replaced.exitCode, replaced.json.data?.text_source, replaced.json.data?.kind]).toEqual([0, "declared", "page"])
+	expect(existsSync(join(dir, "sources", "S1", "raw.bin"))).toBe(true)
+	const added = (await run(["fact", "add", "--source", "S1", "--find", "USD", "--label", "usd_bn", ...s, "--json"])) as { exitCode: number; json: Json & { message?: string } }
+	expect([added.exitCode, added.json.error, added.json.message]).toEqual([0, undefined, undefined])
+	const row = added.json.data?.row as { value: string; locator: { artifact: string; unit: string } }
+	expect([row.value, row.locator.artifact, row.locator.unit]).toEqual(["4200000000", "text.txt", "bytes"])
+	copyFileSync(join(import.meta.dir, "tests", "fixtures", "fidelity-brief-locked.md"), join(dir, "brief.md"))
+	writeFileSync(join(dir, "report.src.html"), [
+		'<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Revenue</title></head><body><h1>Revenue</h1>',
+		"<h2>Findings</h2><p>Revenue was {{F1:usd_bn}} [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] Revenue page, retrieved 2026-10-01.</li></ol></body></html>',
+	].join("\n"))
+	expect(((await run(["fact", "fill", join(dir, "report.src.html"), "--out", join(dir, "report.html"), ...s])) as { exitCode: number }).exitCode).toBe(0)
+	const report = (await run(["fact", "verify", join(dir, "report.html"), "--sources", join(dir, "sources"), "--brief", join(dir, "brief.md"), ...s])) as { exitCode: number; json: { defects?: unknown[] } }
+	expect([report.exitCode, report.json.defects]).toEqual([0, []])
+	expect((JSON.parse(readFileSync(join(dir, "fidelity-defects.json"), "utf8")) as { defects: { code: string }[] }).defects.map((d) => d.code)).not.toContain("snapshot_not_raw")
+})
+
+test("#given a malformed conversion.json #when fact add reads it #then it is a usage error naming the file, not a crash", async () => {
+	const dir = session()
+	await snapshot(dir)
+	writeFileSync(join(dir, "sources", "S1", "conversion.json"), "{not json")
+	const added = run(["fact", "add", "--source", "S1", "--find", "Staff grew to", "--label", "staff", "--session-dir", dir, "--json"])
+	await expect(added).rejects.toBeInstanceOf(CliError)
+	await expect(added).rejects.toThrow(/conversion\.json/)
+})