oh-my-opencode 5.1.45 → 5.1.47

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fidelity-records.mjs

@@ -0,0 +1,163 @@
+// fidelity-records.mjs - the fidelity record schema and the delivery barrier of `outcome verify`
+// and `outcome finish`.
+//
+// The table and the schema are the spec for the barrier. Every fidelity record is written through
+// writeFidelityRecord, which stamps one envelope (RECORD_ENVELOPE: record_kind, artifact_sha256,
+// report, written_at, defects) plus the fields its kind declares, and read through
+// readFidelityRecord, which refuses a missing, unknown, or ill-typed field (fail closed).
+// FIDELITY_RECORDS holds every per-record rule as a column: where the records are (targets), when a
+// delivered session must carry one (requiredWhen), which envelope field binds it to the delivered
+// bytes (bindsTo), and which defects block delivery (blocking). The barrier is one loop over the
+// table with no record-specific branch; a new fidelity step adds a row here and nothing else.
+//
+// HTML/PDF/DOCX need a gate record or an explicitly logged not_run reason, even without a ledger.
+// That logged exemption covers deliveries this harness never gated: once a ledger or any session
+// fidelity record exists, the barrier refuses the unverified edition regardless of it, and the same
+// exemption is the only way a required record may be absent.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { CliError, readJsonFile, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
+import { LEDGER_FILENAME } from "./fact-ledger.mjs"
+import { meaningCheckEnabled, requireLockedBrief } from "./fidelity-brief.mjs"
+import { blocksDelivery, deliveryBlockReason } from "./gates-fidelity.mjs"
+
+export const FIDELITY_RECORD = "fidelity-defects.json"
+export const MEANING_RECORD = "fidelity-meaning-defects.json"
+
+/** The fields every fidelity record carries, whatever its kind. */
+export const RECORD_ENVELOPE = Object.freeze(["record_kind", "artifact_sha256", "report", "written_at", "defects"])
+
+/** Formats that need a fidelity record even in a session with no ledger and no record. */
+const GATED_FORMATS = Object.freeze(["html", "pdf", "docx"])
+
+/** The meaning record is required unless the locked brief turns the check off; a malformed block cannot prove off. */
+function meaningRequired({ sessionDir }) {
+	const lock = requireLockedBrief(join(sessionDir, "brief.md"))
+	return lock.exitCode === 2 || (lock.locked && meaningCheckEnabled(lock.parsed))
+}
+
+const subjectOf = (row) => row.renderedFrom ?? row.path ?? null
+
+/** One record per delivered edition: the file its row names with --verified-by, bound to that edition's bytes. */
+const perEdition = (sessionDir, delivered) =>
+	delivered.map((row) => ({ path: row.verifiedBy ?? null, declared: row.verifiedBy !== undefined, format: row.format, at: `${row.format}: `, subjects: [subjectOf(row)].filter((subject) => subject !== null) }))
+
+/** One record per session, in the session directory, bound to any delivered edition's bytes. */
+const perSession = (file) => (sessionDir, delivered) => [{ path: join(sessionDir, file), declared: false, format: null, at: "", subjects: delivered.map(subjectOf).filter((subject) => subject !== null) }]
+
+/** Every fidelity record the barrier reads, in check order; each column is one rule the barrier applies. */
+export const FIDELITY_RECORDS = Object.freeze([
+	Object.freeze({
+		kind: "fidelity",
+		file: FIDELITY_RECORD,
+		step: "fidelity gate",
+		targets: perEdition,
+		requiredWhen: ({ hasFidelity }, target) => hasFidelity || GATED_FORMATS.includes(target.format),
+		remedy: (target) => `run fact verify on ${target.subjects[0] ?? "the edition"} and set it with --verified-by`,
+		bindsTo: "artifact_sha256",
+		blocking: blocksDelivery,
+		payload: Object.freeze(["command", "status", "exitCode", "format", "counts", "gatesRun"]),
+	}),
+	Object.freeze({
+		kind: "meaning",
+		file: MEANING_RECORD,
+		step: "meaning gate",
+		targets: perSession(MEANING_RECORD),
+		requiredWhen: meaningRequired,
+		remedy: () => "run fact pairs and fact meaning-check before delivery",
+		bindsTo: "artifact_sha256",
+		blocking: blocksDelivery,
+		payload: Object.freeze(["command", "status", "exitCode", "run_id", "pairs_sha256", "counts", "dropped", "unverified", "calibration_path", "calibration_written", "calibration_replaced", "promotion_eligibility"]),
+	}),
+])
+
+const entryOf = (kind) => {
+	const entry = FIDELITY_RECORDS.find((row) => row.kind === kind)
+	if (entry === undefined) throw new CliError(`unknown fidelity record kind ${kind}`)
+	return entry
+}
+
+/** Why a value is not a valid record of this kind, or null. */
+function envelopeProblem(record, entry) {
+	if (record === null || typeof record !== "object" || Array.isArray(record)) return "not a record object"
+	const missing = RECORD_ENVELOPE.filter((key) => !Object.hasOwn(record, key))
+	if (missing.length > 0) return `missing ${missing.join(", ")}`
+	const unknown = Object.keys(record).filter((key) => !RECORD_ENVELOPE.includes(key) && !entry.payload.includes(key))
+	if (unknown.length > 0) return `unknown field(s) ${unknown.join(", ")}`
+	if (record.record_kind !== entry.kind) return `record_kind ${JSON.stringify(record.record_kind)} is not ${entry.kind}`
+	if (typeof record.artifact_sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(record.artifact_sha256)) return "artifact_sha256 is not a sha256 hex digest"
+	if (typeof record.report !== "string" || record.report === "") return "report is not a path"
+	if (typeof record.written_at !== "string" || Number.isNaN(Date.parse(record.written_at))) return "written_at is not an ISO time"
+	if (!Array.isArray(record.defects) || !record.defects.every((defect) => typeof defect?.code === "string")) return "defects is not a list of coded defects"
+	return null
+}
+
+/**
+ * Write one fidelity record of a kind in the table: the envelope plus that kind's payload fields.
+ * @param {string} path
+ * @param {string} kind a FIDELITY_RECORDS kind
+ * @param {{ artifact_sha256: string, report: string, defects: object[], [field: string]: unknown }} fields the envelope values plus the kind's payload
+ */
+export function writeFidelityRecord(path, kind, { artifact_sha256, report, defects, ...payload }, now = new Date()) {
+	const entry = entryOf(kind)
+	const record = { record_kind: kind, artifact_sha256, report, written_at: now.toISOString(), defects, ...payload }
+	const problem = envelopeProblem(record, entry)
+	if (problem !== null) throw new CliError(`refusing to write a malformed ${kind} record: ${problem}`)
+	writeJsonAtomic(path, record)
+	return record
+}
+
+/** Read one fidelity record of a kind; anything but a valid envelope is a CliError naming the path. */
+export function readFidelityRecord(path, kind) {
+	const entry = entryOf(kind)
+	let record
+	try {
+		record = readJsonFile(path)
+	} catch (error) {
+		throw new CliError(`${kind} record ${path} is malformed: ${error.message}`)
+	}
+	const problem = envelopeProblem(record, entry)
+	if (problem !== null) throw new CliError(`${kind} record ${path} is malformed: ${problem}`)
+	return record
+}
+
+const unresolved = (format, codes, path) => ({ code: "fidelity_unresolved", format, codes, message: codes.map((code) => deliveryBlockReason({ code })).join("; "), path })
+const hashOf = (path) => (existsSync(path) ? sha256Of(readFileSync(path)) : null)
+
+/** Barrier problems for `outcome verify` and `outcome finish`; empty when nothing blocks delivery. */
+export function fidelityProblems(sessionDir, manifest) {
+	const delivered = manifest.deliverables.filter((row) => row.status === "delivered")
+	const hasFidelity = existsSync(join(sessionDir, LEDGER_FILENAME)) || FIDELITY_RECORDS.some((entry) => existsSync(join(sessionDir, entry.file)))
+	const lastFidelity = manifest.gateHistory?.findLast((entry) => entry.gate === "fidelity")
+	const exempt = !hasFidelity && manifest.gates.fidelity === "not_run" && lastFidelity?.status === "not_run" && Boolean(lastFidelity.reason?.trim())
+	const context = { sessionDir, hasFidelity }
+	const problems = []
+	const counted = new Set()
+	for (const entry of FIDELITY_RECORDS) {
+		for (const target of entry.targets(sessionDir, delivered)) {
+			const refuse = (message, path = target.path) => problems.push({ code: "edition_unverified", format: target.format, message: `${target.at}${message}`, path })
+			if (target.path === null || !existsSync(target.path)) {
+				if (target.declared) refuse(`${entry.kind} record ${target.path} is missing`)
+				else if (delivered.length > 0 && !exempt && entry.requiredWhen(context, target)) refuse(`${entry.step} not run; ${entry.remedy(target)}`, target.path ?? target.subjects[0] ?? null)
+				continue
+			}
+			let record
+			try {
+				record = readFidelityRecord(target.path, entry.kind)
+			} catch (error) {
+				refuse(error.message)
+				continue
+			}
+			if (target.subjects.length > 0 && !target.subjects.some((subject) => hashOf(subject) === record[entry.bindsTo])) {
+				refuse(`${entry.kind} record ${target.path} is for a different edition than ${target.subjects.join(", ")}`)
+			}
+			if (counted.has(target.path)) continue
+			counted.add(target.path)
+			const codes = [...new Set(record.defects.filter(entry.blocking).map((defect) => defect.code))].sort()
+			if (codes.length > 0) problems.push(unresolved(target.format, codes, target.path))
+		}
+	}
+	return problems
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fidelity-state.mjs

@@ -1,6 +1,7 @@
 // fidelity-state.mjs - per-sentence failure counts for the fidelity repair loop. A sentence is
 // keyed by its section slug and the sorted fact ids it cites, so a reworded sentence that
-// cites the same facts keeps its count. node: builtins only.
+// cites the same facts keeps its count. The exact slug and id rules are in the comment above
+// slugify in fact-fill.mjs. node: builtins only.
 
 import { existsSync } from "node:fs"
 import { join } from "node:path"

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fidelity-trace.mjs

@@ -0,0 +1,85 @@
+// fidelity-trace.mjs - the numeral and quotation trace of the deterministic fidelity gate.
+//
+// Every numeral in prose and table cells outside sources, toc and chart figures (dates included)
+// must sit in a data-fact, data-translates, q or blockquote element, or at the site of a fill-map
+// entry; otherwise untraceable_number. Quoted runs with no Q row are quote_unbound, and leftover
+// {{...}} pointers unresolved_placeholder. No model, no network.
+//
+// Fill-map assumption (fact-fill.mjs fill(), #11141): format "html" wraps every value and quote in
+// <data data-fact> / <q data-fact> / <blockquote data-fact>, which this trace skips by element, so
+// it needs no fill map. Format "md" writes bare text, and each fillMap entry is
+// { fact_id, rendered, start, end } with start/end indexing the filled Markdown, not the HTML this
+// gate reads. fill() pushes entries in output order and the Markdown-to-HTML step keeps text order,
+// so each entry, in array order, is matched to the next untraced occurrence of its rendered text in
+// document order that is a whole numeral and reads as the entry's row there (fits: "1,237 million"
+// is not F2's 1,237), and strips that one occurrence only. A copy of the same text that no entry
+// accounts for stays in the scan; an entry whose text is gone strips nothing.
+
+import { NOT_CLAIMS } from "./numerals.mjs"
+
+/** Structural numerals: versions, figure/table/section references, times (NOT_CLAIMS 7-11), pages, citations, placeholders. */
+export const STRUCTURAL = [...NOT_CLAIMS.slice(7, 12), /\b(?:p|pp|page|pages)\.?\s*\d+(?:\s*[-\u2013]\s*\d+)?/gi, /\[(?:S|Source\s*)\d+\]|\[\^\d+\]/gi, /\{\{[^}]*\}\}/g]
+const NUMERAL = /\d+(?:[.,\-/:]\d+)*/g
+const TRACED = "\u0000"
+const QUOTE_RUNS = [/"([^"]+)"/g, /\u201C([^\u201C\u201D]+)\u201D/g, /\u300C([^\u300C\u300D]+)\u300D/g, /\u300E([^\u300E\u300F]+)\u300F/g]
+
+export const clip = (text) => String(text).replace(/\s+/g, " ").trim().slice(0, 80)
+
+function ownerTexts(ctx, charts) {
+	const owners = new Map()
+	for (const entry of ctx.texts) {
+		const kind = ctx.kindOf(entry.scope)
+		if (kind === "sources" || kind === "toc") continue
+		if (charts.has(ctx.util.closest(entry.node, (cur) => cur.tag === "figure"))) continue
+		const hidden = ctx.util.closest(entry.node, (cur) => cur.attrs["data-fact"] !== undefined || cur.attrs["data-translates"] !== undefined || cur.tag === "q" || cur.tag === "blockquote")
+		owners.set(entry.owner, (owners.get(entry.owner) ?? "") + (hidden ? ` ${TRACED} ` : entry.node.text))
+	}
+	return owners
+}
+
+function scanOwner(ctx, owner, raw, flag) {
+	let text = raw
+	if (/^h[1-6]$/.test(owner.tag)) text = text.replace(/^\s*\d+(?:[.-]\d+)*[.):]?\s+/, " ")
+	if (text.includes("{{")) flag("unresolved_placeholder", owner, `leftover placeholder: "${clip(text.slice(text.indexOf("{{")))}"`)
+	for (const re of QUOTE_RUNS) {
+		for (const match of text.matchAll(re)) {
+			const inner = match[1].replaceAll(TRACED, " ").trim()
+			const after = text.slice(match.index + match[0].length).trim().split(/\s+/).slice(0, 6).join(" ")
+			if (inner && (inner.split(/\s+/).length >= 3 || ctx.util.citationMarker.test(after))) flag("quote_unbound", owner, `direct quotation with no Q row: "${clip(match[0])}"`)
+		}
+	}
+	const rest = STRUCTURAL.reduce((acc, re) => acc.replace(re, " "), text)
+	for (const match of rest.matchAll(NUMERAL)) flag("untraceable_number", owner, `number "${match[0]}" has no ledger row: "${clip(rest.slice(Math.max(0, match.index - 30), match.index + 30))}"`)
+}
+
+/** Strip each fill-map entry at its own fill site: the next untraced occurrence after the previous entry's site. */
+function traceFills(owners, fillMap, fits) {
+	const keys = [...owners.keys()]
+	const texts = [...owners.values()]
+	let [index, from] = [0, 0]
+	for (const entry of fillMap ?? []) {
+		const { rendered } = entry
+		if (!rendered) continue
+		for (let i = index, at = from; i < texts.length; i += 1, at = 0) {
+			let hit = texts[i].indexOf(rendered, at)
+			const glued = (pos) => /\d/.test(texts[i][pos - 1] ?? "") || /\d/.test(texts[i][pos + rendered.length] ?? "")
+			while (hit !== -1 && (glued(hit) || !fits(entry, texts[i].slice(hit)))) hit = texts[i].indexOf(rendered, hit + 1)
+			if (hit === -1) continue
+			texts[i] = `${texts[i].slice(0, hit)}${TRACED}${texts[i].slice(hit + rendered.length)}`
+			;[index, from] = [i, hit + TRACED.length]
+			break
+		}
+	}
+	return new Map(keys.map((key, i) => [key, texts[i]]))
+}
+
+/**
+ * @param {object} ctx buildContext(...) from gates-static.mjs
+ * @param {Map<object, unknown>} charts chart figures, whose numerals chart checks own
+ * @param {{ fact_id: string, rendered: string, start?: number, end?: number }[] | null} fillMap Markdown fill map, or null
+ * @param {(code: string, node: object, message: string) => void} flag
+ * @param {(entry: object, tail: string) => boolean} fits whether the text from a candidate site on reads as the entry's row
+ */
+export function traceChecks(ctx, charts, fillMap, flag, fits) {
+	for (const [owner, text] of traceFills(ownerTexts(ctx, charts), fillMap, fits)) scanOwner(ctx, owner, text, flag)
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fidelity-values.mjs

@@ -0,0 +1,229 @@
+// fidelity-values.mjs - value, quote, and chart checks of the deterministic fidelity gate.
+//
+// Each data-fact element must match its ledger row, and each Q element the script's
+// reconstruction of its selection (report text never gets a fuzzy pass). Cited rows, table rows,
+// snapshots, and chart CSVs are rechecked; the numeral and quotation trace is fidelity-trace.mjs,
+// and the claim-kind checks (data-claim-kind, unsupported_verification) are fidelity-claims.mjs.
+// No model, no network.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join, resolve, sep } from "node:path"
+
+import { sha256Of } from "./cli-support.mjs"
+import { sameValue, unitKey } from "./fidelity-binding.mjs"
+import { claimChecks } from "./fidelity-claims.mjs"
+import { STRUCTURAL, clip, traceChecks } from "./fidelity-trace.mjs"
+import { parseHtml, proseText } from "./html-lite.mjs"
+import { parseNumeral } from "./numerals.mjs"
+import { div, fromDecimal, sub } from "./rational.mjs"
+import { normalizeText } from "./text-normalize.mjs"
+
+const DECIMAL = /^-?\d+(?:\.\d+)?$/
+
+const bare = (text) => normalizeText(String(text ?? "").replace(/\s*\[(?:S|Source\s*)\d+\]\s*$/i, "")).replace(/\u2026/g, "...").replace(/\s*\.\.\.\s*/g, "...").replace(/^["']+|["']+$/g, "").trim()
+
+/** The text fill renders for a quote selection: full, lead=<n>, or from=<a>;to=<b> (placeholder form accepted). */
+export function selectQuote(quote, selector) {
+	const text = String(quote ?? "").trim()
+	if (selector === "full") return text
+	const lead = /^lead=(\d+)$/.exec(selector)
+	const words = text.split(/\s+/)
+	if (lead) return words.length <= Number(lead[1]) ? text : `${words.slice(0, Number(lead[1])).join(" ")}...`
+	const range = /^from=(.+);to=(.+)$/.exec(selector) ?? /^from="(.+)":to="(.+)"$/.exec(selector)
+	if (!range) return null
+	const once = (anchor) => text.indexOf(anchor) !== -1 && text.indexOf(anchor) === text.lastIndexOf(anchor)
+	if (!once(range[1]) || !once(range[2])) return null
+	const start = text.indexOf(range[1])
+	const end = text.indexOf(range[2]) + range[2].length
+	if (end <= start) return null
+	return `${start > 0 ? "..." : ""}${text.slice(start, end)}${end < text.length ? "..." : ""}`
+}
+
+function quoteProblem(row, shown, selector) {
+	const want = selectQuote(row.quote, selector)
+	if (want === null) return ["quote_not_verbatim", `selection "${selector}" does not resolve in ${row.fact_id}'s quote`]
+	return bare(shown) === bare(want) ? null : ["quote_not_verbatim", `"${clip(shown)}" is not the ${selector} selection of ${row.fact_id}: "${clip(want)}"`]
+}
+
+function factProblem(row, shown, attrs = {}) {
+	if (attrs["data-unit"] !== undefined && unitKey(attrs["data-unit"]) !== unitKey(row.unit)) return ["unit_mismatch", `data-unit "${attrs["data-unit"]}" but ${row.fact_id} is in "${row.unit}"`]
+	if (attrs.value !== undefined && !sameValue(attrs.value, row.value)) return ["value_mismatch", `value="${attrs.value}" but ${row.fact_id} is ${row.value}`]
+	const text = normalizeText(shown)
+	const forms = [row.raw, row.render, row.value, row.unit && `${row.value} ${row.unit}`].filter(Boolean).map(normalizeText)
+	if (forms.some((form) => text === form || (text.endsWith(` ${form}`) && !/\d/.test(text.slice(0, -form.length))))) return null
+	const parsed = parseNumeral(text)
+	if (!parsed) return unitKey(text) === unitKey(row.unit) ? null : ["value_mismatch", `"${clip(shown)}" shows no value of ${row.fact_id} (${row.value})`]
+	if (!sameValue(parsed.value, row.value)) return ["value_mismatch", `"${clip(shown)}" reads ${parsed.value}, but ${row.fact_id} is ${row.value}`]
+	if (parsed.unitRaw && unitKey(parsed.unitRaw) !== unitKey(row.unit)) return ["unit_mismatch", `"${clip(shown)}" is in ${parsed.unitRaw}, but ${row.fact_id} is in ${row.unit}`]
+	return null
+}
+
+/** Whether a candidate fill site reads as what fill wrote there or as the entry's row ("1,237 million" is neither 1,237 nor F2). */
+const fillSiteFits = (rows) => (entry, tail) => {
+	const [row, site, own] = [rows.get(entry.fact_id), parseNumeral(tail, 0), parseNumeral(entry.rendered, 0)]
+	if (!row || row.kind === "quote" || !site || !own) return true
+	if (sameValue(site.value, own.value) && unitKey(site.unitRaw ?? "") === unitKey(own.unitRaw ?? "")) return true
+	return factProblem(row, tail.slice(0, Math.max(entry.rendered.length, site.span[1]))) === null
+}
+
+const withoutFooter = (node) => proseText({ children: node.children.filter((child) => child.tag !== "footer") })
+
+/** One row per active value row, as `fact export --csv` writes it. */
+export function exportRows(ledger) {
+	return (ledger?.rows ?? []).filter((row) => row.status === "active" && row.kind !== "quote" && row.value !== null).map((row) => ({ fact_id: row.fact_id, label: row.label, plot_value: row.value, unit: row.unit ?? "" }))
+}
+
+function readCsv(path) {
+	if (!existsSync(path)) return null
+	const lines = readFileSync(path, "utf8").split(/\r?\n/).filter((line) => line.trim() !== "")
+	const cells = (line) => line.split(",").map((cell) => cell.trim().replace(/^"(.*)"$/, "$1"))
+	const head = cells(lines[0] ?? "")
+	const [id, value, unit] = ["fact_id", "plot_value", "unit"].map((name) => head.indexOf(name))
+	if (id < 0 || value < 0 || unit < 0 || lines.length < 2) return null
+	return lines.slice(1).map((line) => cells(line)).map((c) => ({ fact_id: c[id], plot_value: c[value], unit: c[unit] ?? "" }))
+}
+
+const walk = (node) => node.children.filter((child) => child.tag !== "#text").flatMap((child) => [child, ...walk(child)])
+
+/** SVG text nodes of a chart: data labels, or ticks with their declared grid. */
+function svgLabels(raw) {
+	return walk(parseHtml(raw)).filter((node) => node.tag === "text").map((node) => {
+		let tick = null
+		for (let cur = node.parent; cur && !tick; cur = cur.parent) if (cur.tag === "g" && /(?:^|\s)ticks(?:\s|$)/.test(cur.attrs.class ?? "")) tick = cur.attrs
+		return { text: proseText(node), tick }
+	})
+}
+
+function onGrid(value, tick) {
+	const [step, min, max] = [tick["data-tick-step"], tick["data-tick-min"], tick["data-tick-max"]]
+	if (![value, step, min, max].every((v) => DECIMAL.test(String(v ?? ""))) || /^-?0+(?:\.0+)?$/.test(step)) return false
+	const offset = sub(fromDecimal(value), fromDecimal(min))
+	return offset.num >= 0n && sub(fromDecimal(max), fromDecimal(value)).num >= 0n && div(offset, fromDecimal(step)).den === 1n
+}
+
+function numerals(text) {
+	const out = []
+	for (let at = 0, n = parseNumeral(text, 0); n; at = n.span[1], n = parseNumeral(text, at)) out.push(n.value)
+	return out
+}
+
+function chartFigures(ctx) {
+	const charts = new Map()
+	for (const fig of ctx.all.filter((node) => node.tag === "figure")) {
+		const inner = ctx.util.descendants(fig)
+		const labels = inner.filter((node) => node.tag === "svg").flatMap((svg) => svgLabels(svg.raw ?? ""))
+		const marked = fig.attrs["data-chart-source"] !== undefined || ctx.util.classTokens(fig).includes("chart")
+		if (marked || inner.some((node) => node.tag === "img" && ctx.util.classTokens(node).includes("chart")) || labels.some((label) => /\d/.test(label.text))) charts.set(fig, labels)
+	}
+	return charts
+}
+
+function chartProblem(ctx, fig, labels, ledger) {
+	const source = fig.attrs["data-chart-source"]
+	if (!source) return "chart figure has no data-chart-source"
+	const csv = readCsv(resolve(ctx.baseDir ?? ".", source))
+	if (!csv) return `chart data ${source} is missing or lacks fact_id, plot_value, unit columns`
+	const exported = new Map(exportRows(ledger).map((row) => [row.fact_id, row]))
+	const drift = csv.find((row) => exported.get(row.fact_id)?.plot_value !== row.plot_value || exported.get(row.fact_id)?.unit !== row.unit)
+	if (drift) return `chart data row ${drift.fact_id} differs from the ledger export`
+	const plotted = (value) => csv.some((row) => sameValue(row.plot_value, value))
+	for (const label of labels) {
+		const bad = numerals(label.text).find((value) => (label.tick ? !onGrid(value, label.tick) : !plotted(value)))
+		if (bad !== undefined) return `${label.tick ? "tick" : "label"} "${label.text}" is not ${label.tick ? "on the declared tick grid" : `a plot_value of ${source}`}`
+	}
+	const caption = ctx.util.descendants(fig).find((node) => node.tag === "figcaption")
+	const stray = numerals(caption ? STRUCTURAL.reduce((text, re) => text.replace(re, " "), proseText(caption)) : "").find((value) => !plotted(value))
+	return stray === undefined ? null : `caption numeral ${stray} is not a plot_value of ${source}`
+}
+
+/**
+ * @param {object} ctx buildContext(...) from gates-static.mjs
+ * @param {{ rows: object[] }} ledger
+ * @param {{ fact_id: string, rendered: string, selector?: string }[] | null} fillMap Markdown fill map, or null
+ * @param {string | null} sourcesDir directory of <S-id>/{text.txt, meta.json} snapshots
+ * @param {{ recompute?: (ledger: object, row: object) => { ok: boolean }, asOf?: string | null }} options
+ */
+export function valueChecks(ctx, ledger, fillMap, sourcesDir, options = {}) {
+	const out = []
+	const flag = (code, node, message) => out.push(ctx.defect(code, node, message))
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const cited = new Map()
+	const check = (id, node, problemOf) => {
+		const row = rows.get(id)
+		if (!row) return flag("unresolved_placeholder", node, `${id} names no ledger row`)
+		if (!cited.has(id)) cited.set(id, node)
+		const problem = problemOf(row)
+		if (problem) flag(problem[0], node, problem[1])
+	}
+	for (const node of ctx.all.filter((cur) => cur.attrs["data-fact"] !== undefined)) {
+		const selector = node.attrs["data-quote-sel"] ?? "full"
+		check(node.attrs["data-fact"], node, (row) => (row.kind === "quote" ? quoteProblem(row, withoutFooter(node), selector) : factProblem(row, proseText(node), node.attrs)))
+	}
+	const docText = bare(proseText(ctx.body))
+	for (const entry of fillMap ?? []) {
+		check(entry.fact_id, ctx.body, (row) => {
+			const problem = row.kind === "quote" ? quoteProblem(row, entry.rendered, entry.selector ?? "full") : factProblem(row, entry.rendered)
+			if (problem || docText.includes(bare(entry.rendered))) return problem
+			return [row.kind === "quote" ? "quote_not_verbatim" : "value_mismatch", `filled text "${clip(entry.rendered)}" of ${row.fact_id} is no longer in the report`]
+		})
+	}
+	rowChecks(ctx, ledger, rows, cited, options, flag)
+	for (const tr of ctx.all.filter((node) => node.tag === "tr" && node.attrs["data-row-kind"] !== "comparison")) {
+		const groups = new Set(ctx.util.descendants(tr).map((node) => rows.get(node.attrs["data-fact"])?.observation_id).filter(Boolean))
+		if (groups.size > 1) flag("join_integrity_fail", tr, `one table row joins observations ${[...groups].join(", ")}`)
+	}
+	const meta = sourceChecks(ctx, rows, cited, sourcesDir, flag)
+	claimChecks(ctx, rows, (row) => provenance(sourcesDir, meta, row), flag)
+	const charts = chartFigures(ctx)
+	for (const { node, scope } of ctx.elements) {
+		const kind = ctx.kindOf(scope)
+		if ((node.tag === "q" || node.tag === "blockquote") && node.attrs["data-fact"] === undefined && kind !== "sources" && kind !== "toc") flag("quote_unbound", node, `<${node.tag}> with no Q row: "${clip(proseText(node))}"`)
+	}
+	traceChecks(ctx, charts, fillMap, flag, fillSiteFits(rows))
+	for (const [fig, labels] of charts) {
+		const problem = chartProblem(ctx, fig, labels, ledger)
+		if (problem) flag("chart_value_untraceable", fig, problem)
+	}
+	return out
+}
+
+function rowChecks(ctx, ledger, rows, cited, options, flag) {
+	// An as-of of "latest ..." or "... per snapshot" names no fixed revision, so quote_stale_version is skipped.
+	const asOf = options.asOf && !/^latest\b|per snapshot/i.test(options.asOf) ? options.asOf : null
+	for (const [id, node] of cited) {
+		const row = rows.get(id)
+		if (row.fuzzy === true) flag("quote_fuzzy_match", node, `${id} was registered from a similarity match on an OCR-noisy snapshot`)
+		const revision = typeof row.revision === "string" ? row.revision : (row.revision?.id ?? row.revision?.tag ?? null)
+		if (asOf && revision && !asOf.includes(revision)) flag("quote_stale_version", node, `${id} is from revision ${revision}; the brief targets "${asOf}"`)
+		if ((row.kind === "derived" || row.kind === "converted") && options.recompute?.(ledger, row)?.ok === false) flag("value_mismatch", node, `${id} does not recompute from its operands`)
+		const window = row.snapshot_window
+		if (window && typeof window === "object" && window.start && window.end) {
+			const [start, end] = [Date.parse(window.start), Date.parse(window.end)]
+			const outside = (row.operands ?? []).find((op) => !(Date.parse(rows.get(op)?.observed_at) >= start && Date.parse(rows.get(op)?.observed_at) < end))
+			if (outside) flag("snapshot_mismatch", node, `operand ${outside} of ${id} was observed outside ${window.start} to ${window.end}`)
+		}
+	}
+}
+
+/** meta.json kind of the snapshot holding the row's own locator artifact; undefined when the artifact is absent or escapes sources/<source_id>/. */
+function provenance(sourcesDir, meta, row) {
+	const artifact = row.locator?.artifact
+	if (!sourcesDir || typeof row.source_id !== "string" || typeof artifact !== "string") return undefined
+	const dir = resolve(sourcesDir, row.source_id)
+	const path = resolve(dir, artifact)
+	return path.startsWith(`${dir}${sep}`) && existsSync(path) ? meta.get(row.source_id)?.kind : undefined
+}
+
+function sourceChecks(ctx, rows, cited, sourcesDir, flag) {
+	const ids = new Set([...cited.keys()].map((id) => rows.get(id)?.source_id).filter(Boolean))
+	for (const match of proseText(ctx.body).matchAll(/\[S(\d+)\]/g)) ids.add(`S${match[1]}`)
+	const meta = new Map()
+	for (const id of sourcesDir ? ids : []) {
+		const [metaPath, textPath] = [join(sourcesDir, id, "meta.json"), join(sourcesDir, id, "text.txt")]
+		if (!existsSync(metaPath) || !existsSync(textPath)) continue
+		meta.set(id, JSON.parse(readFileSync(metaPath, "utf8")))
+		const actual = sha256Of(readFileSync(textPath))
+		if (meta.get(id).sha256 !== actual) flag("snapshot_hash_mismatch", ctx.body, `${id}/text.txt changed after its snapshot was pinned`)
+	}
+	return meta
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/gates-fidelity.mjs

@@ -0,0 +1,113 @@
+// gates-fidelity.mjs - the deterministic fidelity gate over a filled HTML report.
+//
+// checkFidelity refuses to judge a report whose brief has no locked `## Fidelity` block (one
+// fidelity_interview_incomplete defect). Otherwise it builds the static-gate document context
+// once and runs the value, binding, and lexicon checks over it, returning defects in the shape
+// `check` emits plus integrity, sorted blocker, major, minor, then line, selector, code. It never
+// calls a model or reads the network; the meaning verifier consumes its pairs separately.
+// Plain Node ESM, sibling imports only.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { DEFECT_CODES } from "./contracts.mjs"
+import { bindingChecks, proseSentences } from "./fidelity-binding.mjs"
+import { isLocked, parseFidelityBlock } from "./fidelity-brief.mjs"
+import { lexiconChecks } from "./fidelity-lexicon.mjs"
+import { valueChecks } from "./fidelity-values.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+
+/** Every code this gate can raise. */
+export const FIDELITY_GATE_CODES = Object.freeze([
+	"fidelity_interview_incomplete", "unresolved_placeholder", "value_mismatch", "unit_mismatch", "quote_not_verbatim",
+	"quote_unbound", "claim_status_invalid", "snapshot_hash_mismatch", "chart_value_untraceable", "untraceable_number",
+	"unsupported_verification", "conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added",
+	"qualifier_dropped", "unbound_sentence", "snapshot_mismatch", "join_integrity_fail", "quote_stale_version",
+	"quote_fuzzy_match", "name_outside_quote", "scope_widened_warn", "claim_kind_mismatch", "verification_claim_unmarked",
+])
+const RANK = { blocker: 0, major: 1, minor: 2 }
+
+/** The gate and delivery barrier share registry policy; caller severities cannot demote it. */
+export function blocksDelivery(defect) {
+	if (!Object.hasOwn(DEFECT_CODES, defect?.code)) return true
+	const entry = DEFECT_CODES[defect.code]
+	return entry.integrity || entry.severity !== "minor"
+}
+
+export function deliveryBlockReason(defect) {
+	return Object.hasOwn(DEFECT_CODES, defect?.code) ? `fidelity_unresolved: ${defect.code}` : `unknown defect code ${defect?.code}`
+}
+
+function withIntegrity(defect) {
+	const { code, severity, selector, line, message, hint } = defect
+	return { code, severity, integrity: DEFECT_CODES[code].integrity, selector, line, message, hint }
+}
+
+function compareDefects(a, b) {
+	const text = (x, y) => (x < y ? -1 : x > y ? 1 : 0)
+	return RANK[a.severity] - RANK[b.severity] || (a.line ?? 0) - (b.line ?? 0) || text(a.selector ?? "", b.selector ?? "") || text(a.code, b.code)
+}
+
+function readAcronyms(sourcesDir, sourceId, cache) {
+	if (!sourcesDir || !sourceId) return {}
+	if (!cache.has(sourceId)) {
+		const path = join(sourcesDir, sourceId, "acronyms.json")
+		cache.set(sourceId, existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {})
+	}
+	return cache.get(sourceId)
+}
+
+/** One (row quote, report sentence) pair per fact cited in a prose sentence outside sources and toc. */
+export function fidelityPairs(ctx, ledger, sourcesDir) {
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const cache = new Map()
+	const pairs = []
+	for (const block of proseSentences(ctx)) {
+		if (block.kind === "sources" || block.kind === "toc") continue
+		block.sentences.forEach((sentence, index) => {
+			for (const fact of sentence.facts) {
+				const row = rows.get(fact.id)
+				if (!row?.quote) continue
+				pairs.push({
+					pair_id: `${fact.id}@${block.owner.line}:${index + 1}`,
+					fact_id: fact.id,
+					quote: row.quote,
+					sentence: sentence.text,
+					span: [fact.start - sentence.start, fact.end - sentence.start],
+					qualifier: row.kind === "quote" ? null : row.qualifier,
+					acronyms: readAcronyms(sourcesDir, row.source_id, cache),
+					node: block.owner,
+				})
+			}
+		})
+	}
+	return pairs
+}
+
+function incomplete(parsed) {
+	const reasons = !parsed?.present ? "no ## Fidelity block" : [...(parsed.errors ?? []), ...parsed.missing.map((f) => `missing: ${f}`), ...parsed.pending.map((f) => `pending: ${f}`)].join("; ")
+	const entry = DEFECT_CODES.fidelity_interview_incomplete
+	return { code: "fidelity_interview_incomplete", severity: entry.severity, integrity: entry.integrity, selector: null, line: null, message: `fidelity interview incomplete (${reasons})`, hint: entry.hint }
+}
+
+/**
+ * @param {string} html the filled report
+ * @param {{ ledger: { rows: object[] }, sourcesDir?: string | null, claims?: object | null, fillMap?: object[] | null,
+ *   brief: string | object, baseDir?: string, recompute?: (ledger: object, row: object) => { ok: boolean } }} options
+ *   `brief` is the brief.md text or parseFidelityBlock output; `baseDir` resolves data-chart-source paths.
+ * @returns {{ defects: object[], gatesRun: string[] }}
+ */
+export function checkFidelity(html, { ledger, sourcesDir = null, claims = null, fillMap = null, brief, baseDir, recompute } = {}) {
+	const parsed = brief && typeof brief === "object" ? brief : parseFidelityBlock(String(brief ?? ""))
+	if (!isLocked(parsed)) return { defects: [incomplete(parsed)], gatesRun: ["fidelity_interview_incomplete"] }
+	const ctx = buildContext(parseHtml(html), { baseDir })
+	const defects = [
+		...valueChecks(ctx, ledger, fillMap, sourcesDir, { recompute, asOf: parsed.fields["as of"] }),
+		...bindingChecks(ctx, claims, ledger),
+	]
+	const pairs = fidelityPairs(ctx, ledger, sourcesDir)
+	const byId = new Map(pairs.map((pair) => [pair.pair_id, pair]))
+	for (const finding of lexiconChecks(pairs).findings) defects.push(ctx.defect(finding.code, byId.get(finding.pair_id).node, `${finding.pair_id}: ${finding.message}`))
+	return { defects: defects.map(withIntegrity).sort(compareDefects), gatesRun: [...FIDELITY_GATE_CODES] }
+}