lazycodex-ai 5.1.44 → 5.1.45

package/packages/omo-codex/plugin/skills/ulw-research/scripts/claims-index.mjs

@@ -0,0 +1,125 @@
+// claims-index.mjs - deterministic index of claim-graph.md: the one Markdown table whose header
+// names claim_id, statement, risk tier, and status, plus the ids listed under the
+// `## verified-claims` digest. Pure function of the text; node: builtins only.
+
+const CLAIM_ID = /^C\d+$/
+const REQUIRED_COLUMNS = Object.freeze({ claim_id: "claim_id", statement: "statement", risk: "risk tier", status: "status" })
+
+/** Split one table line on unescaped pipes; drops the leading and trailing border cells. */
+function splitRow(line) {
+	const cells = []
+	let current = ""
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index]
+		if (char === "\\" && line[index + 1] === "|") {
+			current += "|"
+			index += 1
+		} else if (char === "|") {
+			cells.push(current)
+			current = ""
+		} else current += char
+	}
+	cells.push(current)
+	const trimmed = cells.map((value) => value.trim())
+	if (line.trim().startsWith("|")) trimmed.shift()
+	if (line.trim().endsWith("|")) trimmed.pop()
+	return trimmed
+}
+
+function normalizeHeader(value) {
+	return value.replace(/`/g, "").trim().toLowerCase().replace(/[\s_-]+/g, " ")
+}
+
+function columnIndexes(header) {
+	const names = header.map(normalizeHeader)
+	const indexes = {}
+	for (const [key, name] of Object.entries(REQUIRED_COLUMNS)) indexes[key] = names.indexOf(normalizeHeader(name))
+	return Object.values(indexes).every((index) => index >= 0) ? indexes : null
+}
+
+function isSeparator(line) {
+	return /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/.test(line)
+}
+
+const DIGEST_HEADING = normalizeHeader("verified-claims")
+
+/** `offset` is the index of `lines[0]` in the document, for line numbers in errors. */
+function verifiedIds(lines, offset, errors) {
+	const ids = []
+	let inside = false
+	for (const [index, line] of lines.entries()) {
+		const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+		if (heading) {
+			const name = normalizeHeader(heading[2])
+			inside = name === DIGEST_HEADING
+			if (!inside && name.startsWith(DIGEST_HEADING)) {
+				errors.push(`line ${offset + index + 1}: heading "${line.trim()}" is not the digest heading "## verified-claims"; drop the suffix so its entries are read`)
+			}
+			continue
+		}
+		if (!inside) continue
+		// An entry is a list item or a table row; prose lines never verify. Only the id an entry
+		// starts with is verified; ids mentioned later in the line are not.
+		const leading = /^\s*(?:(?:[-*+]|\d+[.)])\s+|\|\s*)`?(C\d+)\b/.exec(line)
+		if (leading && !ids.includes(leading[1])) ids.push(leading[1])
+	}
+	return ids
+}
+
+/** Blank every line of a fenced code block (``` or ~~~, fences included) so nothing in it is read. */
+function unfenced(lines) {
+	let fence = null
+	return lines.map((line) => {
+		const marker = /^\s{0,3}(`{3,}|~{3,})/.exec(line)
+		if (fence === null) {
+			if (marker) fence = marker[1]
+			return marker ? "" : line
+		}
+		const closes = marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && line.trim() === marker[1]
+		if (closes) fence = null
+		return ""
+	})
+}
+
+/** @returns {{ claims: { claim_id: string, statement: string, risk: string, status: string, in_verified: boolean }[], errors: string[] }} */
+export function indexClaims(markdown) {
+	const lines = unfenced(markdown.split(/\r?\n/))
+	const errors = []
+	const headerAt = lines.findIndex((line) => line.trim().startsWith("|") && columnIndexes(splitRow(line)) !== null)
+	if (headerAt < 0) {
+		return { claims: [], errors: ["no claim table: a Markdown table with claim_id, statement, risk tier, and status columns is required"] }
+	}
+	const header = splitRow(lines[headerAt])
+	const columns = columnIndexes(header)
+	const hasSeparator = isSeparator(lines[headerAt + 1] ?? "")
+	if (!hasSeparator) errors.push(`line ${headerAt + 2}: claim table header must be followed by a separator row`)
+	const firstRow = headerAt + (hasSeparator ? 2 : 1)
+	const rows = []
+	let tableEnd = firstRow
+	for (let index = firstRow; index < lines.length && lines[index].trim().startsWith("|"); index += 1) {
+		tableEnd = index + 1
+		const cells = splitRow(lines[index])
+		const at = `line ${index + 1}`
+		if (cells.length !== header.length) {
+			errors.push(`${at}: expected ${header.length} cells, found ${cells.length}`)
+			continue
+		}
+		const claimId = cells[columns.claim_id].replace(/`/g, "")
+		if (!CLAIM_ID.test(claimId)) {
+			errors.push(`${at}: claim_id "${claimId}" must match C<n>`)
+			continue
+		}
+		if (rows.some((row) => row.claim_id === claimId)) {
+			errors.push(`${at}: duplicate claim_id ${claimId}`)
+			continue
+		}
+		rows.push({ claim_id: claimId, statement: cells[columns.statement], risk: cells[columns.risk], status: cells[columns.status] })
+	}
+	// The digest section ends at the claim table: scan each side on its own so it cannot carry across.
+	const verified = [...new Set([...verifiedIds(lines.slice(0, headerAt), 0, errors), ...verifiedIds(lines.slice(tableEnd), tableEnd, errors)])]
+	for (const id of verified) {
+		if (!rows.some((row) => row.claim_id === id)) errors.push(`verified-claims lists ${id}, which has no claim row`)
+	}
+	const claims = rows.map((row) => ({ ...row, in_verified: verified.includes(row.claim_id) }))
+	return { claims, errors }
+}

package/packages/omo-codex/plugin/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/omo-codex/plugin/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
+	}
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-ledger-schema.mjs

@@ -0,0 +1,204 @@
+// fact-ledger-schema.mjs - the fact ledger's vocabulary and validation: row fields and defaults,
+// kinds, statuses, qualifiers, and validateLedger over rows, status events, and their history.
+// The grammar it encodes is references/fact-ledger-grammar.md; every per-kind column rule lives in
+// KIND_RULES (fact-ledger-kinds.mjs), never here.
+// Pure functions with no IO; fact-ledger.mjs owns reading, writing, and row changes. node: builtins only.
+
+import { DECIMAL, isCount, isNonEmpty, isObject, isString, kindRuleErrors } from "./fact-ledger-kinds.mjs"
+
+export { DECIMAL, isNonEmpty, isString } from "./fact-ledger-kinds.mjs"
+
+export const LEDGER_SCHEMA_VERSION = 1
+export const FACT_KINDS = Object.freeze(["measured", "quote", "derived", "assumed", "converted"])
+export const FACT_STATUSES = Object.freeze(["active", "superseded", "retracted"])
+export const OPERATIONS = Object.freeze(["sum", "diff", "growth", "ratio", "share", "convert", "expr"])
+/** Canonical qualifier terms; surface forms in either language map onto these. */
+export const QUALIFIERS = Object.freeze([
+	"upper_inclusive",
+	"lower_inclusive",
+	"approximate",
+	"near",
+	"lower_exclusive",
+	"upper_exclusive",
+])
+
+export const ROW_DEFAULTS = Object.freeze({
+	value: null,
+	unit: null,
+	value_span: null,
+	source_id: null,
+	locator: null,
+	locate_hint: null,
+	snapshot_sha256: null,
+	valid_at: null,
+	qualifier: null,
+	entity: null,
+	sentence_id: null,
+	observation_id: null,
+	fuzzy: false,
+	outside_floor: false,
+	population: null,
+	missing_rule: null,
+	accounting_basis: null,
+	snapshot_window: null,
+	revision: null,
+	exact: null,
+	render: null,
+	operation: null,
+	operands: [],
+	derived_from: [],
+	formula: null,
+	factor: null,
+	rationale: null,
+	status: "active",
+})
+const REQUIRED = ["fact_id", "kind", "raw", "quote", "extracted_by", "observed_at", "label"]
+export const ROW_FIELDS = Object.freeze([...REQUIRED, ...Object.keys(ROW_DEFAULTS)])
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
+const LABEL = /^[a-z0-9_-]{1,32}$/
+const FACT_REF = /^[FQ]\d+$/
+
+function check(errors, condition, message) {
+	if (!condition) errors.push(message)
+}
+
+function nullOr(value, test) {
+	return value === null || test(value)
+}
+
+function validateRow(row, index, errors) {
+	const at = `rows[${index}]`
+	if (!isObject(row)) return errors.push(`${at} must be an object`)
+	for (const key of ROW_FIELDS) check(errors, Object.hasOwn(row, key), `${at}.${key} is required`)
+	for (const key of Object.keys(row)) check(errors, ROW_FIELDS.includes(key), `${at}.${key} is not a ledger field`)
+	check(errors, FACT_KINDS.includes(row.kind), `${at}.kind must be one of ${FACT_KINDS.join(", ")}`)
+	errors.push(...kindRuleErrors(row, at))
+	check(errors, row.unit === undefined || nullOr(row.unit, isNonEmpty), `${at}.unit must be null or a non-empty token`)
+	for (const key of ["raw", "quote"]) check(errors, row[key] === undefined || isString(row[key]), `${at}.${key} must be a string`)
+	check(errors, row.extracted_by === undefined || isNonEmpty(row.extracted_by), `${at}.extracted_by must be a non-empty string`)
+	check(errors, row.observed_at === undefined || (isString(row.observed_at) && ISO_DATE.test(row.observed_at)), `${at}.observed_at must be an ISO timestamp`)
+	check(errors, row.label === undefined || (isString(row.label) && LABEL.test(row.label)), `${at}.label must match [a-z0-9_-]{1,32}`)
+	const span = row.value_span
+	check(errors, span === undefined || nullOr(span, (v) => Array.isArray(v) && v.length === 2 && v.every(isCount) && v[0] <= v[1]), `${at}.value_span must be null or [start, end]`)
+	for (const key of ["locate_hint", "valid_at", "entity", "observation_id", "missing_rule", "accounting_basis", "formula", "render"]) {
+		if (row[key] !== undefined) check(errors, nullOr(row[key], isString), `${at}.${key} must be null or a string`)
+	}
+	for (const key of ["population", "snapshot_window", "revision"]) {
+		if (row[key] !== undefined) check(errors, nullOr(row[key], (v) => isString(v) || isObject(v)), `${at}.${key} must be null, a string, or an object`)
+	}
+	if (row.qualifier !== undefined) check(errors, nullOr(row.qualifier, (v) => QUALIFIERS.includes(v)), `${at}.qualifier must be null or one of ${QUALIFIERS.join(", ")}`)
+	if (row.sentence_id !== undefined) check(errors, nullOr(row.sentence_id, (v) => isString(v) && /^S\d+:s\d+$/.test(v)), `${at}.sentence_id must be null or S<n>:s<k>`)
+	for (const key of ["fuzzy", "outside_floor"]) {
+		if (row[key] !== undefined) check(errors, typeof row[key] === "boolean", `${at}.${key} must be a boolean`)
+	}
+	if (row.operation !== undefined) check(errors, nullOr(row.operation, (v) => OPERATIONS.includes(v)), `${at}.operation must be null or one of ${OPERATIONS.join(", ")}`)
+	for (const key of ["operands", "derived_from"]) {
+		if (row[key] !== undefined) check(errors, Array.isArray(row[key]) && row[key].every((v) => isString(v) && FACT_REF.test(v)), `${at}.${key} must be an array of fact ids`)
+	}
+	if (row.factor !== undefined) check(errors, nullOr(row.factor, (v) => isString(v) && DECIMAL.test(v)), `${at}.factor must be null or a decimal string`)
+	check(errors, row.status === undefined || FACT_STATUSES.includes(row.status), `${at}.status must be one of ${FACT_STATUSES.join(", ")}`)
+}
+
+// The status machine and event rule of references/fact-ledger-grammar.md. validateLedger replays
+// events through transitionError, and every writer in fact-ledger.mjs calls it before appending.
+export const TRANSITIONS = Object.freeze({ active: Object.freeze(["retracted", "superseded"]), retracted: Object.freeze([]), superseded: Object.freeze([]) })
+const EVENT_FIELDS = Object.freeze(["fact_id", "from", "to", "replacement", "reason"])
+
+/**
+ * @param {Map<string, string>} statuses each fact's status at the event's position
+ * @returns {string | null} why the event is not a legal transition, or null
+ */
+export function transitionError(statuses, event) {
+	if (!isObject(event)) return "an event must be an object"
+	const id = event.fact_id
+	if (!statuses.has(id)) return `no ledger row ${id}`
+	if (EVENT_FIELDS.some((key) => !Object.hasOwn(event, key)) || Object.keys(event).some((key) => !EVENT_FIELDS.includes(key))) {
+		return `${id}: an event has exactly the fields ${EVENT_FIELDS.join(", ")}`
+	}
+	const current = statuses.get(id)
+	if (event.from !== current) return `${id} is ${current}, but the event moves it from ${event.from}`
+	if (!TRANSITIONS[current].includes(event.to)) return `${id} cannot move from ${current} to ${event.to}`
+	if (event.to === "superseded") {
+		if (event.replacement === null) return `supersede ${id} needs a replacement row; use retract for a fact with no replacement`
+		if (event.replacement === id) return `${id} cannot be its own replacement`
+		if (!statuses.has(event.replacement)) return `no replacement row ${event.replacement} for ${id}`
+		if (statuses.get(event.replacement) !== "active") return `replacement row ${event.replacement} is ${statuses.get(event.replacement)} (superseding ${id})`
+	} else if (event.replacement !== null) return `${id} is ${event.to} but names replacement ${event.replacement}`
+	if (!isNonEmpty(event.reason)) return `a reason is required to mark ${id} ${event.to}`
+	return null
+}
+
+/** Replay every event from all-active; each row's status must be where its event chain leaves it. */
+function validateHistory(ledger, errors) {
+	const statuses = new Map(ledger.rows.filter(isObject).map((row) => [row.fact_id, "active"]))
+	const counts = new Map()
+	ledger.events.forEach((event, index) => {
+		const problem = transitionError(statuses, event)
+		if (problem) errors.push(`events[${index}]: ${problem}`)
+		if (!isObject(event) || !statuses.has(event.fact_id) || !FACT_STATUSES.includes(event.to)) return
+		statuses.set(event.fact_id, event.to)
+		counts.set(event.fact_id, (counts.get(event.fact_id) ?? 0) + 1)
+	})
+	ledger.rows.forEach((row, index) => {
+		if (!isObject(row) || !FACT_STATUSES.includes(row.status)) return
+		const to = statuses.get(row.fact_id)
+		if (!counts.has(row.fact_id)) check(errors, row.status === "active", `rows[${index}]: ${row.fact_id} is ${row.status} but has no status event`)
+		else check(errors, to === row.status, `rows[${index}]: ${row.fact_id} has status ${row.status} but its last event moves it to ${to}`)
+	})
+}
+
+/** operands and derived_from name existing rows, never the row itself, and close no cycle. */
+export function provenanceErrors(rows) {
+	const errors = []
+	const refs = new Map()
+	for (const row of rows) if (isObject(row)) refs.set(row.fact_id, [row.operands, row.derived_from].flatMap((list) => (Array.isArray(list) ? list : [])))
+	rows.forEach((row, index) => {
+		for (const key of ["operands", "derived_from"]) {
+			if (!isObject(row) || !Array.isArray(row[key])) continue
+			for (const ref of row[key]) {
+				if (ref === row.fact_id) errors.push(`rows[${index}].${key}: ${ref} references itself`)
+				else check(errors, refs.has(ref), `rows[${index}].${key}: ${row.fact_id} references ${ref}, which has no ledger row`)
+			}
+		}
+	})
+	const state = new Map()
+	const visit = (id, path) => {
+		if (state.get(id) === "done") return null
+		if (state.get(id) === "open") return [...path.slice(path.indexOf(id)), id]
+		state.set(id, "open")
+		for (const next of refs.get(id)) {
+			const cycle = next !== id && refs.has(next) ? visit(next, [...path, id]) : null
+			if (cycle) return cycle
+		}
+		state.set(id, "done")
+		return null
+	}
+	for (const id of refs.keys()) {
+		const cycle = visit(id, [])
+		if (cycle) return [...errors, `${cycle[0]} derives from itself through ${cycle.join(" -> ")}`]
+	}
+	return errors
+}
+
+/** @returns {string[]} every schema error; empty when the ledger is valid. */
+export function validateLedger(ledger) {
+	const errors = []
+	if (!isObject(ledger)) return ["ledger must be an object"]
+	check(errors, ledger.schemaVersion === LEDGER_SCHEMA_VERSION, `schemaVersion must be ${LEDGER_SCHEMA_VERSION}`)
+	if (!Array.isArray(ledger.rows)) return [...errors, "rows must be an array"]
+	ledger.rows.forEach((row, index) => validateRow(row, index, errors))
+	const ids = new Set()
+	const labels = new Set()
+	ledger.rows.forEach((row, index) => {
+		if (!isObject(row)) return
+		check(errors, !ids.has(row.fact_id), `rows[${index}].fact_id ${row.fact_id} is a duplicate`)
+		check(errors, row.label === undefined || !labels.has(row.label), `rows[${index}]: ${row.fact_id} has duplicate label ${row.label}`)
+		ids.add(row.fact_id)
+		labels.add(row.label)
+	})
+	errors.push(...provenanceErrors(ledger.rows))
+	if (Array.isArray(ledger.events)) validateHistory(ledger, errors)
+	else errors.push("events must be an array")
+	return errors
+}