lazycodex-ai 5.1.43 → 5.1.45

package/packages/shared-skills/skills/ulw-research/scripts/contracts.mjs

@@ -39,12 +39,69 @@ export const DEFECT_CODES = deepFreeze({
 	layout_scroll_container: { severity: "minor", integrity: false, hint: "Scrolling content prints clipped; make the content fit or wrap the table in a scroll wrapper only for HTML deliverables." },
 	layout_image_distorted: { severity: "major", integrity: false, hint: "Preserve the image aspect ratio (object-fit: contain inside a fixed container)." },
 	layout_sibling_overlap: { severity: "major", integrity: false, hint: "Separate the overlapping elements (margins, grid, or a slide split)." },
+	unresolved_placeholder: { severity: "blocker", integrity: true, hint: "Register the fact with fact add or remove the sentence; a placeholder is never filled with a guess." },
+	value_mismatch: { severity: "blocker", integrity: true, hint: "Re-run fact fill; never edit a filled value by hand." },
+	unit_mismatch: { severity: "blocker", integrity: true, hint: "Re-run fact fill, or derive a converted row with fact derive --op convert." },
+	quote_not_verbatim: { severity: "blocker", integrity: true, hint: "Re-insert the quote through its {{Q<n>}} placeholder; after a second failure the sentence is replaced by the quote." },
+	claim_status_invalid: { severity: "blocker", integrity: true, hint: "The claim id is unknown, refuted, unresolved, or not in verified-claims; move the sentence to Gaps or Contradictions, or remove it." },
+	incompatible_operands: { severity: "blocker", integrity: true, hint: "The operands differ in unit, population, period, or basis for this operation; fix the rows or declare the operation that fits." },
+	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." },
+	polish_diff_fail: { severity: "blocker", integrity: true, hint: "The polish pass changed numbers, tickers, or table rows; 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." },
+	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." },
+	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." },
+	untraceable_number: { severity: "major", integrity: false, hint: "Replace the typed number with a {{F<n>}} placeholder backed by a ledger row, or register it as assumed with a rationale." },
+	unsupported_verification: { severity: "major", integrity: false, hint: "The sentence claims a tool check that no recorded command output backs; link the recorded output row or remove the claim." },
+	conflicting_readings: { severity: "major", integrity: false, hint: "Two ledger rows with different periods or qualifiers are cited as one fact; split the sentence or retire one row." },
+	hedge_dropped: { severity: "major", integrity: false, hint: "Restore the qualifier the source uses (estimated, about, not yet)." },
+	direction_flipped: { severity: "major", integrity: false, hint: "The source states the opposite direction; rewrite from the quote." },
+	causality_added: { severity: "major", integrity: false, hint: "The source states no cause; state the correlation or quote the source." },
+	qualifier_dropped: { severity: "major", integrity: false, hint: "The source bounds this value (up to, at least, about); restore the qualifier or use :q." },
+	unbound_sentence: { severity: "major", integrity: false, hint: "Bind the sentence to a fact, a quote, a citation, or a claim-graph node with data-claim." },
+	meaning_drift_confirmed: { severity: "major", integrity: false, hint: "Two independent readers found the same drift; rewrite from the quote or dispute with a reason." },
+	polish_edit_rejected: { severity: "major", integrity: false, hint: "The edit changed a number, a hedge, a qualifier, a link, or a claim id; re-propose the language fix only." },
+	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." },
+	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." },
+	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." },
+	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." },
+	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." },
+	polish_link_changed: { severity: "minor", integrity: false, hint: "A link was altered or removed during polish; restore it." },
+	polish_name_changed: { severity: "minor", integrity: false, hint: "A proper noun changed during polish; restore it." },
 })
 
+/** Codes only the fidelity verifier raises (fact ledger, fill, verify, meaning, polish). */
+export const FIDELITY_CODES = Object.freeze([
+	"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", "snapshot_hash_mismatch",
+	"chart_value_untraceable", "quote_unbound", "edition_unverified", "untraceable_number", "unsupported_verification",
+	"conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added", "qualifier_dropped", "unbound_sentence",
+	"meaning_drift_confirmed", "polish_edit_rejected", "polish_hedging_decreased", "polish_text_churn", "snapshot_mismatch",
+	"join_integrity_fail", "quote_stale_version", "quote_fuzzy_match", "name_outside_quote", "scope_widened_warn",
+	"particle_unverified", "fallback_without_entity", "meaning_drift_warn", "polish_edit_unlocated", "polish_link_changed",
+	"polish_name_changed",
+])
+const FIDELITY_SET = new Set(FIDELITY_CODES)
+
 const LAYOUT_PREFIX = "layout_"
 /** Codes checkStatic can raise (G1-G17). */
 export const STATIC_CODES = Object.freeze(
-	Object.keys(DEFECT_CODES).filter((code) => !code.startsWith(LAYOUT_PREFIX) && code !== "missing_promised_deliverable"),
+	Object.keys(DEFECT_CODES).filter(
+		(code) => !code.startsWith(LAYOUT_PREFIX) && code !== "missing_promised_deliverable" && !FIDELITY_SET.has(code),
+	),
 )
 /** Codes checkLayout can raise (L1-L5). */
 export const LAYOUT_CODES = Object.freeze(Object.keys(DEFECT_CODES).filter((code) => code.startsWith(LAYOUT_PREFIX)))
@@ -59,10 +116,10 @@ export const LANES = Object.freeze(["template-strict", "template-vibe", "no-form
 export const STATES = Object.freeze(["none", "partial", "complete"])
 export const DELIVERABLE_FORMATS = Object.freeze(["pdf", "docx", "html", "md", "latex", "slides", "post"])
 export const DELIVERABLE_STATUSES = Object.freeze(["pending", "delivered", "blocked_capability", "skipped", "failed"])
-export const GATE_NAMES = Object.freeze(["static", "layout", "visual", "proofread"])
+export const GATE_NAMES = Object.freeze(["static", "fidelity", "layout", "visual", "proofread"])
 export const GATE_STATUSES = Object.freeze(["pass", "fail", "not_run"])
 export const LINEAGE_MODES = Object.freeze(["inline", "section"])
-export const ANSWERED_BY = Object.freeze(["user", "default", "request"])
+export const ANSWERED_BY = Object.freeze(["user", "default", "request", "pending"])
 export const REPAIR_DEFAULTS = Object.freeze({ maxAttempts: 3, plateauLimit: 2, wallClockMs: 15 * 60 * 1000 })
 export const DESIGN_SPEC_SECTIONS = Object.freeze([
 	"Extracted from",
@@ -134,6 +191,14 @@ export function validateOutcomeManifest(manifest) {
 	return { ok: errors.length === 0, errors }
 }
 
+/** A copy of a manifest written before a gate existed: every absent gate key becomes not_run. */
+export function normalizeManifest(manifest) {
+	if (!isObject(manifest) || !isObject(manifest.gates)) return manifest
+	const gates = { ...manifest.gates }
+	for (const gate of GATE_NAMES) if (!Object.hasOwn(gates, gate)) gates[gate] = "not_run"
+	return { ...manifest, gates }
+}
+
 function isMeasure(value) {
 	return Array.isArray(value) && value.length === 3 && value.every((n) => Number.isInteger(n) && n >= 0)
 }

package/packages/shared-skills/skills/ulw-research/scripts/contracts.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, test } from "bun:test"
 
 import {
+	ANSWERED_BY,
 	DEFECT_CODES,
 	DELIVERABLE_FORMATS,
 	DELIVERABLE_STATUSES,
 	DESIGN_SPEC_SECTIONS,
+	FIDELITY_CODES,
 	GATE_NAMES,
 	GATE_STATUSES,
 	INTEGRITY_CODES,
@@ -16,6 +18,7 @@ import {
 	SCHEMA_VERSION,
 	STATES,
 	STATIC_CODES,
+	normalizeManifest,
 	validateOutcomeManifest,
 	validateRepairState,
 } from "./contracts.mjs"
@@ -49,6 +52,61 @@ const LAYOUT_CODES_EXPECTED = [
 	"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",
+	"snapshot_hash_mismatch",
+	"chart_value_untraceable",
+	"quote_unbound",
+	"edition_unverified",
+]
+const FIDELITY_MAJORS = [
+	"untraceable_number",
+	"unsupported_verification",
+	"conflicting_readings",
+	"hedge_dropped",
+	"direction_flipped",
+	"causality_added",
+	"qualifier_dropped",
+	"unbound_sentence",
+	"meaning_drift_confirmed",
+	"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",
+	"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 {
@@ -63,7 +121,7 @@ function sampleManifest() {
 			{ format: "pdf", status: "pending", promised: true, updatedAt: "2026-01-01T12:00:00.000Z" },
 		],
 		renders: [],
-		gates: { static: "not_run", layout: "not_run", visual: "not_run", proofread: "not_run" },
+		gates: { static: "not_run", fidelity: "not_run", layout: "not_run", visual: "not_run", proofread: "not_run" },
 		residualDefects: [],
 		repair: null,
 		sources: null,
@@ -72,7 +130,9 @@ function sampleManifest() {
 
 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].sort())
+		expect(Object.keys(DEFECT_CODES).sort()).toEqual(
+			[...STATIC_CODES_EXPECTED, "missing_promised_deliverable", ...LAYOUT_CODES_EXPECTED, ...FIDELITY_CODES_EXPECTED].sort(),
+		)
 		for (const [code, entry] of Object.entries(DEFECT_CODES)) {
 			expect(SEVERITIES.has(entry.severity), `${code} severity`).toBe(true)
 			expect(typeof entry.hint).toBe("string")
@@ -81,14 +141,17 @@ describe("DEFECT_CODES", () => {
 		}
 	})
 
-	test("#given the code table #when integrity codes are derived #then they are exactly the five blocker codes", () => {
-		expect([...INTEGRITY_CODES].sort()).toEqual([
-			"broken_asset_reference",
-			"missing_citation_section",
-			"missing_closing_section",
-			"missing_promised_deliverable",
-			"missing_required_section",
-		])
+	test("#given the code table #when integrity codes are derived #then they are exactly the blocker codes", () => {
+		expect([...INTEGRITY_CODES].sort()).toEqual(
+			[
+				"broken_asset_reference",
+				"missing_citation_section",
+				"missing_closing_section",
+				"missing_promised_deliverable",
+				"missing_required_section",
+				...FIDELITY_BLOCKERS,
+			].sort(),
+		)
 		for (const code of INTEGRITY_CODES) expect(DEFECT_CODES[code].severity).toBe("blocker")
 		for (const [code, entry] of Object.entries(DEFECT_CODES)) {
 			if (entry.severity === "blocker") expect(INTEGRITY_CODES.has(code), `${code} must be integrity`).toBe(true)
@@ -104,6 +167,13 @@ describe("DEFECT_CODES", () => {
 		}).toThrow()
 		expect(DEFECT_CODES.korean_no_keep_all.severity).toBe("major")
 	})
+
+	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])
+		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).not.toHaveProperty("incompatible_populations")
+	})
 })
 
 describe("code groups", () => {
@@ -111,10 +181,12 @@ 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"])
-		const union = [...STATIC_CODES, ...LAYOUT_CODES, ...MANIFEST_CODES].sort()
+		expect([...FIDELITY_CODES].sort()).toEqual(FIDELITY_CODES_EXPECTED.slice().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)
 		expect(Object.isFrozen(STATIC_CODES)).toBe(true)
+		expect(Object.isFrozen(FIDELITY_CODES)).toBe(true)
 	})
 })
 
@@ -124,7 +196,8 @@ describe("enums", () => {
 		expect(STATES).toEqual(["none", "partial", "complete"])
 		expect(DELIVERABLE_FORMATS).toEqual(["pdf", "docx", "html", "md", "latex", "slides", "post"])
 		expect(DELIVERABLE_STATUSES).toEqual(["pending", "delivered", "blocked_capability", "skipped", "failed"])
-		expect(GATE_NAMES).toEqual(["static", "layout", "visual", "proofread"])
+		expect(GATE_NAMES).toEqual(["static", "fidelity", "layout", "visual", "proofread"])
+		expect(ANSWERED_BY).toEqual(["user", "default", "request", "pending"])
 		expect(GATE_STATUSES).toEqual(["pass", "fail", "not_run"])
 		expect(LINEAGE_MODES).toEqual(["inline", "section"])
 		expect(DESIGN_SPEC_SECTIONS).toEqual([
@@ -155,6 +228,18 @@ describe("validateOutcomeManifest", () => {
 		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"

package/packages/shared-skills/skills/ulw-research/scripts/fact-ledger-grammar.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test"
+
+import { TRANSITIONS, addRow, emptyLedger, nextId, retractRow, supersedeRow, transitionError, validateLedger } from "./fact-ledger.mjs"
+
+// Property-style checks of references/fact-ledger-grammar.md: every ledger the writers build is
+// valid, and every single-invariant break the validator rejects is also refused by the writers.
+
+type Row = { fact_id: string; status: string; kind: string; label: string; operands: string[]; derived_from: string[] }
+type LedgerEvent = { fact_id: string; from: string; to: string; replacement?: string | null; reason?: string }
+type Ledger = { rows: Row[]; events: LedgerEvent[] }
+
+function measured(label: string) {
+	return {
+		kind: "measured",
+		value: "320",
+		unit: "m",
+		raw: "320 m",
+		quote: "The span is 320 m.",
+		value_span: [12, 15],
+		source_id: "S1",
+		locator: { artifact: "sources/S1/text.txt", line: 3, char_start: 40, char_end: 62 },
+		snapshot_sha256: "a".repeat(64),
+		extracted_by: "fact add --find",
+		observed_at: "2026-10-23T08:00:00Z",
+		label,
+	}
+}
+
+function quoteRow(label: string) {
+	return { ...measured(label), kind: "quote", value: null, unit: null, value_span: null }
+}
+
+function derivedRow(label: string, from: string[], kind = "derived") {
+	return {
+		kind,
+		value: "2",
+		raw: "2",
+		quote: "",
+		extracted_by: "fact derive",
+		observed_at: "2026-10-23T08:00:00Z",
+		label,
+		operation: kind === "converted" ? "convert" : "sum",
+		operands: [...from],
+		derived_from: [...from],
+		factor: kind === "converted" ? "1000" : null,
+		exact: { num: "2", den: "1" },
+	}
+}
+
+/** mulberry32: a fixed seed gives the same ledger on every run. */
+function prng(seed: number) {
+	let state = seed >>> 0
+	return () => {
+		state = (state + 0x6d2b79f5) >>> 0
+		let t = state
+		t = Math.imul(t ^ (t >>> 15), t | 1)
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+function pick<T>(random: () => number, list: T[]): T {
+	return list[Math.floor(random() * list.length)]
+}
+
+const ids = (ledger: Ledger, keep: (row: Row) => boolean) => ledger.rows.filter(keep).map((row) => row.fact_id)
+
+/** Writes the writers must refuse on any ledger; each returns nothing and must throw. */
+function illegalWrites(ledger: Ledger, random: () => number): (() => unknown)[] {
+	const active = ids(ledger, (row) => row.status === "active")
+	const ended = ids(ledger, (row) => row.status !== "active")
+	const writes: (() => unknown)[] = [() => addRow(ledger, derivedRow("dangling", ["F999"])), () => addRow(ledger, measured(pick(random, ledger.rows).label))]
+	if (active.length > 0) {
+		const id = pick(random, active)
+		writes.push(() => supersedeRow(ledger, id, id, "self"), () => supersedeRow(ledger, id, null, "none"), () => retractRow(ledger, id, ""))
+		if (ended.length > 0) writes.push(() => supersedeRow(ledger, id, pick(random, ended), "to an ended row"))
+	}
+	if (ended.length > 0) writes.push(() => retractRow(ledger, pick(random, ended), "again"))
+	return writes
+}
+
+/** Random addRow / retractRow / supersedeRow sequences from an empty ledger, with refused writes mixed in. */
+function randomLedger(seed: number) {
+	const random = prng(seed)
+	const ledger: Ledger = emptyLedger()
+	const steps = 4 + Math.floor(random() * 14)
+	for (let step = 0; step < steps; step += 1) {
+		const active = ids(ledger, (row) => row.status === "active")
+		const values = ids(ledger, (row) => row.fact_id.startsWith("F"))
+		const roll = random()
+		if (roll < 0.3 || values.length < 2) addRow(ledger, measured(`m${step}`))
+		else if (roll < 0.4) addRow(ledger, quoteRow(`q${step}`))
+		else if (roll < 0.6) addRow(ledger, derivedRow(`d${step}`, [...new Set([pick(random, values), pick(random, values)])], pick(random, ["derived", "converted"])))
+		else if (roll < 0.8 && active.length > 0) retractRow(ledger, pick(random, active), "wrong page")
+		else if (active.length > 1) {
+			const id = pick(random, active)
+			supersedeRow(ledger, id, pick(random, active.filter((other: string) => other !== id)), "newer filing")
+		}
+		const before = JSON.stringify(ledger)
+		const write = pick(random, illegalWrites(ledger, random))
+		expect(write).toThrow()
+		expect(JSON.stringify(ledger)).toBe(before)
+	}
+	return ledger
+}
+
+const LEDGERS = Array.from({ length: 200 }, (_, index) => randomLedger(index + 1))
+
+describe("every ledger the writers build is valid", () => {
+	test("200 seeded random write sequences all validate, and refused writes leave the ledger unchanged", () => {
+		for (const ledger of LEDGERS) expect(validateLedger(ledger)).toEqual([])
+		const events = LEDGERS.flatMap((ledger) => ledger.events)
+		expect(events.some((event) => event.to === "superseded")).toBe(true)
+		expect(events.some((event) => event.to === "retracted")).toBe(true)
+		expect(LEDGERS.some((ledger) => ledger.rows.some((row) => row.kind === "converted"))).toBe(true)
+	})
+})
+
+type Break = { name: string; mutate: (ledger: Ledger) => string | null; rejects: RegExp; write: (ledger: Ledger) => unknown; refuses: RegExp }
+
+const firstEvent = (ledger: Ledger, to?: string) => ledger.events.find((event) => to === undefined || event.to === to) as LedgerEvent
+const firstRow = (ledger: Ledger, keep: (row: Row) => boolean) => ledger.rows.find(keep) as Row
+const activeId = (ledger: Ledger) => firstRow(ledger, (row) => row.status === "active")?.fact_id
+
+const BREAKS: Break[] = [
+	{ name: "superseded event with a null replacement", mutate: (l) => { const e = firstEvent(l, "superseded"); if (!e || !activeId(l)) return null; e.replacement = null; return e.fact_id }, rejects: /needs a replacement row/, write: (l) => supersedeRow(l, activeId(l), null, "x"), refuses: /needs a replacement row/ },
+	{ name: "self replacement", mutate: (l) => { const e = firstEvent(l, "superseded"); if (!e || !activeId(l)) return null; e.replacement = e.fact_id; return e.fact_id }, rejects: /cannot be its own replacement/, write: (l) => supersedeRow(l, activeId(l), activeId(l), "x"), refuses: /cannot be its own replacement/ },
+	{ name: "duplicate transition", mutate: (l) => { const e = firstEvent(l); if (!e) return null; l.events.push({ ...e }); return e.fact_id }, rejects: /but the event moves it from active/, write: (l) => retractRow(l, firstEvent(l).fact_id, "x"), refuses: /cannot move from (retracted|superseded)/ },
+	{ name: "from mismatch", mutate: (l) => { const e = firstEvent(l); if (!e) return null; e.from = e.to; return e.fact_id }, rejects: /is active, but the event moves it from/, write: (l) => supersedeRow(l, firstEvent(l).fact_id, activeId(l) ?? "F1", "x"), refuses: /cannot move from|own replacement/ },
+	{ name: "active row with events", mutate: (l) => { const r = firstRow(l, (row) => row.status !== "active"); if (!r) return null; r.status = "active"; return r.fact_id }, rejects: /has status active but its last event moves it to/, write: (l) => { const r = firstRow(l, (row) => row.status !== "active"); const problem = transitionError(new Map([[r.fact_id, r.status]]), { fact_id: r.fact_id, from: r.status, to: "active", replacement: null, reason: "x" }); if (problem) throw new Error(problem) }, refuses: /cannot move from (retracted|superseded) to active/ },
+	{ name: "non-active row without events", mutate: (l) => { const e = firstEvent(l); if (!e) return null; l.events = l.events.filter((event) => event.fact_id !== e.fact_id); return e.fact_id }, rejects: /but has no status event/, write: (l) => addRow(l, { ...measured("fresh"), status: "retracted" }), refuses: /but has no status event/ },
+	{ name: "dangling operand", mutate: (l) => { const r = firstRow(l, (row) => row.operands.length > 0); if (!r) return null; r.operands[0] = "F999"; return r.fact_id }, rejects: /references F999, which has no ledger row/, write: (l) => addRow(l, derivedRow("fresh", ["F999"])), refuses: /references F999, which has no ledger row/ },
+	{ name: "self derived_from", mutate: (l) => { const r = firstRow(l, (row) => row.derived_from.length > 0); if (!r) return null; r.derived_from.push(r.fact_id); return r.fact_id }, rejects: /references itself/, write: (l) => addRow(l, { ...derivedRow("fresh", []), derived_from: [nextId(l, "derived")] }), refuses: /references itself/ },
+	{ name: "cyclic derived_from", mutate: (l) => { const r = firstRow(l, (row) => row.derived_from.length > 0); if (!r) return null; firstRow(l, (row) => row.fact_id === r.derived_from[0]).derived_from.push(r.fact_id); return r.fact_id }, rejects: /derives from itself through/, write: (l) => addRow(l, derivedRow("fresh", [`F${l.rows.length + 5}`])), refuses: /which has no ledger row/ },
+	{ name: "duplicate label", mutate: (l) => { if (l.rows.length < 2) return null; l.rows[1].label = l.rows[0].label; return l.rows[1].fact_id }, rejects: /has duplicate label/, write: (l) => addRow(l, measured(l.rows[0].label)), refuses: /has duplicate label/ },
+]
+
+describe("every single-invariant break is rejected by the validator and refused by the writers", () => {
+	for (const broken of BREAKS) {
+		test(broken.name, () => {
+			let applied = 0
+			for (const valid of LEDGERS) {
+				const ledger = structuredClone(valid)
+				const factId = broken.mutate(ledger)
+				if (factId === null) continue
+				applied += 1
+				const errors = validateLedger(ledger)
+				expect(errors.some((error: string) => broken.rejects.test(error) && error.includes(factId))).toBe(true)
+				const untouched = structuredClone(valid)
+				expect(() => broken.write(untouched)).toThrow(broken.refuses)
+				expect(untouched).toEqual(valid)
+			}
+			expect(applied).toBeGreaterThan(10)
+		})
+	}
+
+	test("no transition leads back to active", () => {
+		for (const targets of Object.values(TRANSITIONS)) expect(targets).not.toContain("active")
+	})
+})
+
+function twoRows() {
+	const ledger = emptyLedger()
+	addRow(ledger, measured("a"))
+	addRow(ledger, measured("b"))
+	return ledger
+}
+
+describe("validateLedger is as strict as the writers (review r5 MEDIUM)", () => {
+	test("a superseded event with a null replacement is rejected", () => {
+		const ledger = twoRows()
+		supersedeRow(ledger, "F1", "F2", "newer filing")
+		ledger.events[0].replacement = null
+		expect(validateLedger(ledger).some((e: string) => e.includes("F1") && e.includes("replacement"))).toBe(true)
+	})
+
+	test("a row superseded by itself is rejected", () => {
+		const ledger = twoRows()
+		supersedeRow(ledger, "F1", "F2", "newer filing")
+		ledger.events[0].replacement = "F1"
+		expect(validateLedger(ledger).some((e: string) => e.includes("F1") && e.includes("replacement"))).toBe(true)
+	})
+
+	test("two events that both move F1 from active to retracted are rejected", () => {
+		const ledger = twoRows()
+		retractRow(ledger, "F1", "wrong page")
+		ledger.events.push({ ...ledger.events[0] })
+		expect(validateLedger(ledger).some((e: string) => e.includes("events[1]") && e.includes("F1"))).toBe(true)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/fact-ledger-kinds.mjs

@@ -0,0 +1,136 @@
+// fact-ledger-kinds.mjs - the per-kind column rules of the fact ledger as one table, KIND_RULES.
+// validateLedger checks every per-kind column through kindRuleErrors, the writers read their
+// per-kind choices (id prefix, measured exact) from it, and the per-kind table in
+// references/fact-ledger-grammar.md is rendered from it (`node fact-ledger-kinds.mjs --render-grammar`).
+// Also the value primitives the schema shares. Pure functions with no IO; node: builtins only.
+
+import { isCliEntry } from "./entry-guard.mjs"
+
+export const DECIMAL = /^-?\d+(?:\.\d+)?$/
+const INTEGER = /^-?\d+$/
+const SHA256 = /^[0-9a-f]{64}$/
+const SOURCE_ID = /^S\d+$/
+
+export const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+export const isString = (value) => typeof value === "string"
+export const isNonEmpty = (value) => typeof value === "string" && value.length > 0
+export const isCount = (value) => Number.isInteger(value) && value >= 0
+const isDecimal = (value) => isString(value) && DECIMAL.test(value)
+const isRational = (exact) => isObject(exact) && isString(exact.num) && isString(exact.den) && INTEGER.test(exact.num) && /^\d+$/.test(exact.den) && !/^0+$/.test(exact.den)
+
+/** The exact rational of a decimal string, reduced. */
+export function exactFromDecimal(value) {
+	const [whole, fraction = ""] = value.replace(/^-/, "").split(".")
+	let num = BigInt(whole + fraction)
+	let den = 10n ** BigInt(fraction.length)
+	let a = num
+	let b = den
+	while (b !== 0n) [a, b] = [b, a % b]
+	if (a > 1n) [num, den] = [num / a, den / a]
+	return { num: `${value.startsWith("-") && num !== 0n ? "-" : ""}${num}`, den: `${den}` }
+}
+
+/** @returns {string[]} what is wrong with a locator object, each message prefixed with `at`. */
+export function locatorErrors(locator, at) {
+	const errors = []
+	if (!isObject(locator)) return errors
+	if (!isNonEmpty(locator.artifact)) errors.push(`${at}.artifact must be a non-empty string`)
+	if (!(isCount(locator.char_start) && isCount(locator.char_end) && locator.char_start <= locator.char_end)) errors.push(`${at}.char_start/char_end must be integers with start <= end`)
+	for (const key of ["page", "line"]) {
+		if (locator[key] !== undefined && !(Number.isInteger(locator[key]) && locator[key] >= 1)) errors.push(`${at}.${key} must be an integer >= 1`)
+	}
+	for (const key of ["table", "row_label", "col_label"]) {
+		if (locator[key] !== undefined && !isString(locator[key])) errors.push(`${at}.${key} must be a string`)
+	}
+	return errors
+}
+
+const isLocator = (value) => isObject(value) && locatorErrors(value, "").length === 0
+const orNull = (test) => (value, row) => value === null || test(value, row)
+const locatorDetail = (value, at) => locatorErrors(value, at)
+
+/**
+ * Every rule a KIND_RULES cell may name: `cell` is its text in the grammar table, `says` ends the
+ * error message, `test(value, row)` decides it, and `prefix` (id rules only) is what nextId uses.
+ */
+export const RULES = Object.freeze({
+	f_id: { cell: "`F<n>`", says: "F<n>", prefix: "F", test: (v) => isString(v) && /^F\d+$/.test(v) },
+	q_id: { cell: "`Q<n>`", says: "Q<n>", prefix: "Q", test: (v) => isString(v) && /^Q\d+$/.test(v) },
+	decimal: { cell: "decimal", says: "a decimal string", test: isDecimal },
+	null: { cell: "null", says: "null", test: (v) => v === null },
+	source: { cell: "`S<n>`", says: "S<n>", test: (v) => isString(v) && SOURCE_ID.test(v) },
+	source_or_null: { cell: "`S<n>` or null", says: "S<n> or null", test: orNull((v) => isString(v) && SOURCE_ID.test(v)) },
+	locator: { cell: "object", says: "a locator object", test: isLocator, detail: locatorDetail },
+	locator_or_null: { cell: "object or null", says: "a locator object or null", test: orNull(isLocator), detail: locatorDetail },
+	sha256: { cell: "sha256", says: "a sha256 hex digest", test: (v) => isString(v) && SHA256.test(v) },
+	sha256_or_null: { cell: "sha256 or null", says: "a sha256 hex digest or null", test: orNull((v) => isString(v) && SHA256.test(v)) },
+	string_or_null: { cell: "string or null", says: "null or a string", test: orNull(isString) },
+	non_empty: { cell: "non-empty", says: "a non-empty string (required for this kind)", test: isNonEmpty },
+	from_value: {
+		cell: "from `value`",
+		says: "the reduced exact rational of value",
+		test: (v, row) => isRational(v) && (!isDecimal(row.value) || (v.num === exactFromDecimal(row.value).num && v.den === exactFromDecimal(row.value).den)),
+	},
+	rational_or_null: { cell: "rational or null", says: "null or { num: integer string, den: positive integer string }", test: orNull(isRational) },
+	by_derive: { cell: "written by derive (rational or null)", says: "null or { num: integer string, den: positive integer string }", test: orNull(isRational) },
+})
+
+/** The grammar's per-kind columns, in table order; `exact` follows `value` because it reads it. */
+export const KIND_COLUMNS = Object.freeze(["fact_id", "value", "source_id", "locator", "snapshot_sha256", "rationale", "exact"])
+
+const sourced = { source_id: "source", locator: "locator", snapshot_sha256: "sha256" }
+const unsourced = { source_id: "source_or_null", locator: "locator_or_null", snapshot_sha256: "sha256_or_null" }
+const row = (cells) => Object.freeze(Object.fromEntries(KIND_COLUMNS.map((column) => [column, cells[column]])))
+
+export const KIND_RULES = Object.freeze({
+	measured: row({ fact_id: "f_id", value: "decimal", ...sourced, rationale: "string_or_null", exact: "from_value" }),
+	quote: row({ fact_id: "q_id", value: "null", ...sourced, rationale: "string_or_null", exact: "null" }),
+	derived: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive" }),
+	assumed: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "non_empty", exact: "rational_or_null" }),
+	converted: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive" }),
+})
+
+/** The id prefix nextId assigns for a kind; an unknown kind gets F and fails validation later. */
+export function idPrefix(kind) {
+	return RULES[KIND_RULES[kind]?.fact_id ?? "f_id"].prefix
+}
+
+/** Whether addRow computes the row's exact from its decimal value. */
+export function exactComesFromValue(kind) {
+	return KIND_RULES[kind]?.exact === "from_value"
+}
+
+/** @returns {string[]} every per-kind column error of one row; empty for an unknown kind. */
+export function kindRuleErrors(candidate, at) {
+	const rules = KIND_RULES[candidate.kind]
+	if (rules === undefined) return []
+	const errors = []
+	for (const column of KIND_COLUMNS) {
+		const value = candidate[column]
+		if (value === undefined) continue
+		const rule = RULES[rules[column]]
+		if (rule.test(value, candidate)) continue
+		errors.push(`${at}.${column} must be ${rule.says} for a ${candidate.kind} row`)
+		if (rule.detail) errors.push(...rule.detail(value, `${at}.${column}`))
+	}
+	return errors
+}
+
+export const KIND_TABLE_BEGIN = "<!-- kind-rules:begin (rendered from KIND_RULES; do not edit by hand) -->"
+export const KIND_TABLE_END = "<!-- kind-rules:end -->"
+
+/** The grammar's per-kind Markdown table, one line per column, ending in a newline. */
+export function renderKindTable() {
+	const kinds = Object.keys(KIND_RULES)
+	const lines = [`| field | ${kinds.join(" | ")} |`, `|${"---|".repeat(kinds.length + 1)}`]
+	for (const column of KIND_COLUMNS) lines.push(`| \`${column}\` | ${kinds.map((kind) => RULES[KIND_RULES[kind][column]].cell).join(" | ")} |`)
+	return `${lines.join("\n")}\n`
+}
+
+if (isCliEntry(import.meta.url)) {
+	if (process.argv[2] === "--render-grammar" && process.argv.length === 3) process.stdout.write(renderKindTable())
+	else {
+		process.stderr.write("usage: node fact-ledger-kinds.mjs --render-grammar\n")
+		process.exitCode = 2
+	}
+}