lazycodex-ai 5.1.44 → 5.1.46

package/packages/shared-skills/skills/ulw-research/scripts/md-lite.mjs

@@ -0,0 +1,193 @@
+// md-lite.mjs - a light Markdown block model for md/post deliverables.
+//
+// parseMarkdown(text) returns { blocks } in document order, each block one of heading,
+// paragraph, list_item, table_row, code, blockquote, with start/end offsets into the raw text
+// so text.slice(start, end) === block.text (table cells carry their own offsets). Headings carry
+// level 1-6. Code blocks are fenced (``` or ~~~); an unterminated fence runs to the end of the
+// text and is reported in problems as unterminated_fence, which a caller must refuse rather than
+// skip. Callers skip kind 'code' when they look for numbers. sectionKindsMd(blocks) classifies
+// sections with the gates-static classifier itself (sectionKind, closingTest). It never renders
+// HTML. Plain Node ESM, sibling imports only.
+
+import { closingTest, sectionKind } from "./gates-static.mjs"
+
+export { closingTest, sectionKind }
+
+/** A fence opener: a backtick fence's info string holds no backtick (else it is an inline span). */
+const FENCE = /^ {0,3}(?:(`{3,})[^`]*|(~{3,}).*)$/
+const HEADING = /^ {0,3}(#{1,6})(?=[ \t]|$)/
+const BLOCKQUOTE = /^ {0,3}> ?/
+/** A bullet or an ordered marker (digits, then . or ), then a space); group 1 is the number. */
+const LIST_ITEM = /^[ \t]*(?:[-*+]|(\d{1,9})[.)])[ \t]+/
+const TABLE_SEPARATOR = /^[ \t]*\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$/
+const CLOSING_HASHES = /[ \t]+#+[ \t]*$|^#+[ \t]*$/
+const THEMATIC_BREAK = /^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/
+
+/** The Markdown block grammar, one named pattern per syntax. */
+export const MD_BLOCK_PATTERNS = Object.freeze({ FENCE, HEADING, BLOCKQUOTE, LIST_ITEM, TABLE_SEPARATOR, CLOSING_HASHES, THEMATIC_BREAK })
+
+/** Split into lines with offsets; end excludes the newline and a trailing carriage return. */
+function linesOf(text) {
+	const lines = []
+	let start = 0
+	while (start <= text.length) {
+		const newline = text.indexOf("\n", start)
+		const next = newline === -1 ? text.length + 1 : newline + 1
+		let end = newline === -1 ? text.length : newline
+		if (end > start && text[end - 1] === "\r") end--
+		lines.push({ start, end, next, raw: text.slice(start, end) })
+		start = next
+	}
+	return lines
+}
+
+/** Narrow [start, end) to its non-whitespace core. */
+function trimRange(text, start, end) {
+	let from = start
+	let to = end
+	while (from < to && /\s/.test(text[from])) from++
+	while (to > from && /\s/.test(text[to - 1])) to--
+	return { start: from, end: to }
+}
+
+function block(text, kind, range, extra = {}) {
+	return { kind, ...extra, text: text.slice(range.start, range.end), start: range.start, end: range.end }
+}
+
+function isSeparator(line) {
+	return line !== undefined && line.raw.includes("-") && TABLE_SEPARATOR.test(line.raw)
+}
+
+/** Cells split on unescaped pipes, outer pipes dropped, each cell trimmed with offsets. */
+function tableCells(text, range) {
+	const bounds = []
+	for (let k = range.start; k < range.end; k++) {
+		let slashes = 0
+		while (k - slashes - 1 >= range.start && text[k - slashes - 1] === "\\") slashes++
+		if (text[k] === "|" && slashes % 2 === 0) bounds.push(k)
+	}
+	const edges = [range.start - 1, ...bounds, range.end]
+	if (bounds[0] === range.start) edges.shift()
+	if (bounds.at(-1) === range.end - 1 && bounds.length > 0) edges.pop()
+	const cells = []
+	for (let k = 0; k + 1 < edges.length; k++) {
+		const cell = trimRange(text, edges[k] + 1, edges[k + 1])
+		cells.push({ text: text.slice(cell.start, cell.end), start: cell.start, end: cell.end })
+	}
+	return cells
+}
+
+function headingBlock(text, line, marker) {
+	const after = line.start + line.raw.indexOf(marker) + marker.length
+	const range = trimRange(text, after, line.end)
+	const closing = text.slice(range.start, range.end).match(CLOSING_HASHES)
+	if (closing) range.end = trimRange(text, range.start, range.start + (closing.index ?? 0)).end
+	return block(text, "heading", range, { level: marker.length })
+}
+
+/**
+ * Parse Markdown into a flat block list.
+ * @param {string} text
+ * @returns {{ blocks: { kind: string, level?: number, text: string, start: number, end: number,
+ *   cells?: { text: string, start: number, end: number }[] }[],
+ *   problems: { code: "unterminated_fence", line: number, start: number }[] }}
+ */
+export function parseMarkdown(text) {
+	const source = String(text ?? "")
+	const lines = linesOf(source)
+	const blocks = []
+	const problems = []
+	let paragraph = null
+	let inTable = false
+	const flush = () => {
+		if (paragraph) blocks.push(block(source, "paragraph", paragraph))
+		paragraph = null
+	}
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]
+		const fence = line.raw.match(FENCE)
+		if (fence) {
+			flush()
+			inTable = false
+			const open = fence[1] ?? fence[2]
+			const codeStart = Math.min(line.next, source.length)
+			let close = lines.length
+			for (let k = i + 1; k < lines.length; k++) {
+				const candidate = lines[k].raw.trim()
+				if (candidate.startsWith(open[0].repeat(open.length)) && /^(`+|~+)$/.test(candidate)) {
+					close = k
+					break
+				}
+			}
+			let codeEnd = source.length
+			if (close === lines.length) problems.push({ code: "unterminated_fence", line: i + 1, start: line.start })
+			else {
+				codeEnd = Math.max(codeStart, lines[close].start - 1)
+				if (codeEnd > codeStart && source[codeEnd - 1] === "\r") codeEnd--
+			}
+			blocks.push(block(source, "code", { start: codeStart, end: codeEnd }))
+			i = close
+			continue
+		}
+		if (line.raw.trim() === "") {
+			flush()
+			inTable = false
+			continue
+		}
+		const range = trimRange(source, line.start, line.end)
+		if (!inTable && line.raw.includes("|") && isSeparator(lines[i + 1])) inTable = true
+		if (inTable && line.raw.includes("|")) {
+			flush()
+			if (!isSeparator(line)) blocks.push(block(source, "table_row", range, { cells: tableCells(source, range) }))
+			continue
+		}
+		inTable = false
+		const heading = line.raw.match(HEADING)
+		if (heading) {
+			flush()
+			blocks.push(headingBlock(source, line, heading[1]))
+			continue
+		}
+		if (THEMATIC_BREAK.test(line.raw)) {
+			flush()
+			continue
+		}
+		const marker = line.raw.match(BLOCKQUOTE) ?? line.raw.match(LIST_ITEM)
+		// Only an ordered marker numbered 1 may interrupt a paragraph (CommonMark); else it is text.
+		const continues = paragraph !== null && marker?.[1] !== undefined && Number(marker[1]) !== 1
+		if (marker && !continues) {
+			flush()
+			const kind = BLOCKQUOTE.test(line.raw) ? "blockquote" : "list_item"
+			const content = trimRange(source, line.start + marker[0].length, line.end)
+			if (content.end > content.start) blocks.push(block(source, kind, content))
+			continue
+		}
+		if (paragraph) paragraph.end = range.end
+		else paragraph = { start: range.start, end: range.end }
+	}
+	flush()
+	return { blocks, problems }
+}
+
+/**
+ * Section kind of every block, parallel to blocks: an h2 opens a section whose kind comes from
+ * its heading text (sources, closing, toc, appendix, glossary, or null for findings); an h3 that
+ * reads as a closing heading marks its blocks closing until the next h2 or h3, as in gates-static.
+ * @param {{ kind: string, level?: number, text: string }[]} blocks
+ * @param {{ closingPattern?: RegExp|string }} [options] extra closing heading pattern (the spec's)
+ * @returns {(string|null)[]}
+ */
+export function sectionKindsMd(blocks, options = {}) {
+	const isClosing = closingTest(options.closingPattern)
+	let section = null
+	let closingH3 = false
+	return blocks.map((entry) => {
+		if (entry.kind === "heading" && entry.level === 2) {
+			section = sectionKind(entry.text, isClosing)
+			closingH3 = false
+		} else if (entry.kind === "heading" && entry.level === 3) {
+			closingH3 = isClosing(entry.text)
+		}
+		return closingH3 ? "closing" : section
+	})
+}

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

@@ -0,0 +1,271 @@
+import { describe, expect, test } from "bun:test"
+
+import * as gatesStatic from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+import * as mdLite from "./md-lite.mjs"
+import { parseMarkdown, sectionKindsMd } from "./md-lite.mjs"
+
+type Cell = { text: string; start: number; end: number }
+type Block = { kind: string; level?: number; text: string; start: number; end: number; cells?: Cell[] }
+
+const FIXTURE = [
+	"# 반도체 시장 보고서",
+	"",
+	"매출은 {{F1}}로 집계됐다. Revenue grew",
+	"across two quarters.",
+	"",
+	"## Findings",
+	"",
+	"- 첫 번째 항목 120억 원",
+	"* Second item 3.2 m",
+	"1. Ordered item 45%",
+	"",
+	"| 지표 | Value |",
+	"| --- | ---: |",
+	"| 매출 | 100억 원 |",
+	"",
+	"> 원문 인용 그대로다.",
+	"",
+	"```js",
+	"const total = 9999",
+	"```",
+	"",
+	"## Sources",
+	"",
+	"S1 example.org",
+	"",
+	"## 출처",
+	"",
+	"## Closing",
+	"",
+	"### Method",
+	"",
+	"## 마무리",
+	"",
+].join("\n")
+
+function blocksOf(text: string): Block[] {
+	return (parseMarkdown(text) as { blocks: Block[] }).blocks
+}
+
+function expectSlices(text: string, blocks: Block[]): void {
+	for (const block of blocks) {
+		expect(text.slice(block.start, block.end)).toBe(block.text)
+		for (const cell of block.cells ?? []) expect(text.slice(cell.start, cell.end)).toBe(cell.text)
+	}
+}
+
+describe("parseMarkdown", () => {
+	test("#given a Korean+English fixture #when parsed #then block kinds come in document order", () => {
+		// given
+		const text = FIXTURE
+		// when
+		const blocks = blocksOf(text)
+		// then
+		expect(blocks.map((b) => b.kind)).toEqual([
+			"heading",
+			"paragraph",
+			"heading",
+			"list_item",
+			"list_item",
+			"list_item",
+			"table_row",
+			"table_row",
+			"blockquote",
+			"code",
+			"heading",
+			"paragraph",
+			"heading",
+			"heading",
+			"heading",
+			"heading",
+		])
+	})
+
+	test("#given the fixture #when parsed #then every block and cell slices exactly from start to end", () => {
+		// given
+		const text = FIXTURE
+		// when
+		const blocks = blocksOf(text)
+		// then
+		expectSlices(text, blocks)
+		expect(blocks[0]).toMatchObject({ kind: "heading", level: 1, text: "반도체 시장 보고서" })
+		expect(blocks[1]?.text).toBe("매출은 {{F1}}로 집계됐다. Revenue grew\nacross two quarters.")
+		expect(blocks.filter((b) => b.kind === "list_item").map((b) => b.text)).toEqual([
+			"첫 번째 항목 120억 원",
+			"Second item 3.2 m",
+			"Ordered item 45%",
+		])
+		expect(blocks.find((b) => b.kind === "blockquote")?.text).toBe("원문 인용 그대로다.")
+	})
+
+	test("#given a table with a separator row #when parsed #then rows carry trimmed cells and the separator is skipped", () => {
+		// given
+		const text = FIXTURE
+		// when
+		const rows = blocksOf(text).filter((b) => b.kind === "table_row")
+		// then
+		expect(rows.map((r) => (r.cells ?? []).map((c) => c.text))).toEqual([
+			["지표", "Value"],
+			["매출", "100억 원"],
+		])
+		expectSlices(text, rows)
+	})
+
+	test("#given a fenced code block with numerals #when parsed #then the numerals sit only in a block of kind code", () => {
+		// given
+		const text = FIXTURE
+		// when
+		const blocks = blocksOf(text)
+		// then
+		const holders = blocks.filter((b) => b.text.includes("9999"))
+		expect(holders.map((b) => b.kind)).toEqual(["code"])
+		expect(holders[0]?.text).toBe("const total = 9999")
+	})
+
+	test("#given an unterminated code fence #when parsed #then it is code to EOF and an unterminated_fence problem names its line", () => {
+		// given
+		const text = "Intro 12.\n\n```\nlet a = 1\n## not a heading\n"
+		// when
+		const { blocks, problems } = parseMarkdown(text) as { blocks: Block[]; problems: { code: string; line: number }[] }
+		// then
+		expect(blocks.map((b) => b.kind)).toEqual(["paragraph", "code"])
+		expect(blocks[1]?.text).toBe("let a = 1\n## not a heading\n")
+		expectSlices(text, blocks)
+		expect(problems).toEqual([expect.objectContaining({ code: "unterminated_fence", line: 3 })])
+	})
+
+	test("#given closed fences only #when parsed #then problems is empty", () => {
+		// given
+		const text = FIXTURE
+		// when
+		const { problems } = parseMarkdown(text) as { problems: unknown[] }
+		// then
+		expect(problems).toEqual([])
+	})
+
+	const NUMBER_LINES: [string, string, string[][]][] = [
+		["a year-led continuation line", "Revenue rose 12% in\n2024. Costs fell 3%.", [["paragraph", "Revenue rose 12% in\n2024. Costs fell 3%."]]],
+		["a bare number at line start", "Sales grew in\n2024 revenue rose 4%.", [["paragraph", "Sales grew in\n2024 revenue rose 4%."]]],
+		["a 1. marker after a paragraph", "Intro line\n1. x", [["paragraph", "Intro line"], ["list_item", "x"]]],
+		["a 2) marker after a paragraph", "Intro line\n2) y", [["paragraph", "Intro line\n2) y"]]],
+		["a 2) marker after a blank line", "Intro line\n\n2) y", [["paragraph", "Intro line"], ["list_item", "y"]]],
+		["a later ordered item in a list", "1. x\n2. y", [["list_item", "x"], ["list_item", "y"]]],
+	]
+	test.each(NUMBER_LINES)("#given %s #when parsed #then no number drops out of the block text", (_label, text, expected) => {
+		// given / when
+		const blocks = blocksOf(text)
+		// then
+		expect(blocks.map((b) => [b.kind, b.text])).toEqual(expected)
+		expectSlices(text, blocks)
+	})
+
+	test("#given a line that opens with an inline triple-backtick span #when parsed #then it stays a paragraph and later claims are not code", () => {
+		// given
+		const text = "```inline``` code at start\n\nLater 42% claim."
+		// when
+		const { blocks, problems } = parseMarkdown(text) as { blocks: Block[]; problems: unknown[] }
+		// then
+		expect(blocks.map((b) => [b.kind, b.text])).toEqual([
+			["paragraph", "```inline``` code at start"],
+			["paragraph", "Later 42% claim."],
+		])
+		expect(problems).toEqual([])
+	})
+
+	test("#given a tilde fence with an info string containing backticks #when parsed #then it is still a fence", () => {
+		// given
+		const text = "~~~ js `x`\nconst n = 5\n~~~\nAfter 6."
+		// when
+		const blocks = blocksOf(text)
+		// then
+		expect(blocks.map((b) => [b.kind, b.text])).toEqual([
+			["code", "const n = 5"],
+			["paragraph", "After 6."],
+		])
+	})
+
+	test("#given a table cell ending in an escaped backslash #when parsed #then the following pipe still splits cells", () => {
+		// given
+		const text = "| a\\\\| b \\| c |\n| --- | --- |\n| 1 | 2 |"
+		// when
+		const rows = blocksOf(text).filter((b) => b.kind === "table_row")
+		// then
+		expect((rows[0]?.cells ?? []).map((c) => c.text)).toEqual(["a\\\\", "b \\| c"])
+		expectSlices(text, rows)
+	})
+})
+
+describe("sectionKindsMd", () => {
+	test("#given h2 headings in English and Korean #when classified #then sources and closing kinds match gates-static", () => {
+		// given
+		const blocks = blocksOf(FIXTURE)
+		// when
+		const kinds = sectionKindsMd(blocks) as (string | null)[]
+		// then
+		const byHeading: Record<string, string | null | undefined> = {}
+		blocks.forEach((b, i) => {
+			if (b.kind === "heading") byHeading[b.text] = kinds[i]
+		})
+		expect(byHeading.Findings).toBeNull()
+		expect(byHeading.Sources).toBe("sources")
+		expect(byHeading["출처"]).toBe("sources")
+		expect(byHeading.Closing).toBe("closing")
+		expect(byHeading["마무리"]).toBe("closing")
+		expect(kinds).toHaveLength(blocks.length)
+	})
+
+	test("#given md-lite #when its section classifier is read #then it is the gates-static export itself", () => {
+		// given / when / then
+		expect(typeof gatesStatic.sectionKind).toBe("function")
+		expect(mdLite.sectionKind).toBe(gatesStatic.sectionKind)
+		expect(typeof gatesStatic.closingTest).toBe("function")
+		expect(mdLite.closingTest).toBe(gatesStatic.closingTest)
+	})
+
+	test("#given one heading set as Markdown h2s and HTML h2s #when classified #then both editions give the same kinds", () => {
+		// given
+		const headings = ["Findings", "Sources", "\uCD9C\uCC98", "Closing", "\uB9C8\uBB34\uB9AC", "Methodology", "Contents", "Appendix A", "Glossary", "Closing the gap: GPU prices"]
+		const md = headings.map((h) => `## ${h}\n\nBody.`).join("\n\n")
+		const html = `<html><body>${headings.map((h) => `<h2>${h}</h2><p>Body.</p>`).join("")}</body></html>`
+		// when
+		const blocks = blocksOf(md)
+		const kinds = sectionKindsMd(blocks) as (string | null)[]
+		const mdKinds = blocks.flatMap((b, i) => (b.kind === "heading" ? [kinds[i]] : []))
+		const htmlKinds = gatesStatic.buildContext(parseHtml(html), {}).sections.map((s: { kind: string | null }) => s.kind)
+		// then
+		expect(mdKinds).toEqual(htmlKinds)
+		expect(mdKinds).toEqual([null, "sources", "sources", "closing", "closing", "closing", "toc", "appendix", "glossary", null])
+	})
+
+	test("#given a findings heading that only starts with Closing #when classified #then it is not a closing section", () => {
+		// given
+		const blocks = blocksOf("## Closing the gap: GPU prices\n\nPrices fell 8%.\n\n### Closing remarks on supply\n\nSupply rose 2%.")
+		// when
+		const kinds = sectionKindsMd(blocks) as (string | null)[]
+		// then
+		expect(kinds).toEqual([null, null, null, null])
+	})
+
+	test("#given a caller closing pattern given as a string #when classified #then it is applied as in gates-static", () => {
+		// given
+		const blocks = blocksOf("## Wrap-up\n\nDone.")
+		// when
+		const kinds = sectionKindsMd(blocks, { closingPattern: "wrap-up" }) as (string | null)[]
+		// then
+		expect(kinds).toEqual(["closing", "closing"])
+	})
+
+	test("#given body blocks under a section #when classified #then they inherit the enclosing h2 kind", () => {
+		// given
+		const blocks = blocksOf(FIXTURE)
+		// when
+		const kinds = sectionKindsMd(blocks) as (string | null)[]
+		// then
+		const codeIndex = blocks.findIndex((b) => b.kind === "code")
+		const sourceLine = blocks.findIndex((b) => b.text === "S1 example.org")
+		expect(kinds[codeIndex]).toBeNull()
+		expect(kinds[sourceLine]).toBe("sources")
+		expect(kinds[0]).toBeNull()
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/meaning-check.mjs

@@ -0,0 +1,196 @@
+// meaning-check.mjs - ingest the meaning readers' verdicts over fact-pairs output.
+//
+// ingestVerdicts reads verdict files written by separate reader lanes (cheap and strong tiers),
+// keeps a drift verdict only when its pair exists, its tier and drift_kind are in the closed sets,
+// and both its fragment (from the sentence) and source_fragment (from the quote or statement) are
+// non-empty substrings after whitespace normalization; every other verdict is dropped and logged.
+// Both tiers naming the same drift_kind (not "other") on a pair is meaning_drift_confirmed (major,
+// never integrity); one tier is meaning_drift_warn (minor). Each flagged pair yields one
+// calibration line; a dispute is recorded there and never removes the defect. Coverage is
+// fail-closed: every pair no reader judged, and every force_strong pair no strong reader judged,
+// is listed in `unverified`, so a gate can tell a clean check apart from a pair nobody read.
+// No model, no fetch.
+
+import { appendFileSync, readFileSync } from "node:fs"
+
+import { DEFECT_CODES } from "./contracts.mjs"
+
+export const DRIFT_KINDS = Object.freeze([
+	"subject_changed", "scope_widened", "hedge_dropped", "certainty_added", "causality_added",
+	"direction_flipped", "population_changed", "evidence_grade_raised", "other",
+])
+export const MODEL_TIERS = Object.freeze(["cheap", "strong"])
+export const VERDICTS = Object.freeze(["drift", "ok"])
+export const isDriftKind = (kind) => DRIFT_KINDS.includes(kind)
+/** The machine-read verdict contract a reader lane receives with pairs.json; built from the registries above. */
+export const VERDICT_SCHEMA = Object.freeze({
+	model_tier: MODEL_TIERS,
+	verdict: VERDICTS,
+	drift_kind: DRIFT_KINDS,
+	required: Object.freeze(["pair_id", "verdict"]),
+	drift_required: Object.freeze(["drift_kind", "fragment", "source_fragment"]),
+})
+
+/** NFC, every whitespace run collapsed to one space, trimmed. */
+const squash = (text) => String(text ?? "").normalize("NFC").replace(/\s+/gu, " ").trim()
+
+/** Read a verdict file, mapping an unreadable path or invalid JSON to a short typed error. */
+function parseFile(path) {
+	let text
+	try {
+		text = readFileSync(path, "utf8")
+	} catch {
+		throw new TypeError(`${path}: cannot read the verdict file`)
+	}
+	try {
+		return JSON.parse(text)
+	} catch {
+		throw new TypeError(`${path}: the verdict file is not valid JSON`)
+	}
+}
+
+function verdictsOf(input) {
+	const label = typeof input === "string" ? input : "<inline>"
+	const parsed = typeof input === "string" ? parseFile(input) : input
+	const list = Array.isArray(parsed) ? parsed : parsed?.verdicts
+	if (!Array.isArray(list)) throw new TypeError(`${label}: a verdict file is an array of verdicts or { verdicts: [...] }`)
+	const tier = Array.isArray(parsed) ? undefined : parsed.model_tier
+	return list.map((verdict) => ({ verdict: tier === undefined || verdict?.model_tier !== undefined ? verdict : { ...verdict, model_tier: tier }, file: label }))
+}
+
+/** The reason a verdict is dropped, or null when it is accepted. */
+function dropReason(verdict, pair) {
+	if (verdict === null || typeof verdict !== "object") return "malformed_verdict"
+	if (!pair) return "unknown_pair"
+	if (!VERDICTS.includes(verdict.verdict)) return "invalid_verdict"
+	if (!MODEL_TIERS.includes(verdict.model_tier)) return "invalid_model_tier"
+	if (verdict.verdict === "ok") return null
+	if (!isDriftKind(verdict.drift_kind)) return "unknown_drift_kind"
+	const [fragment, sourceFragment] = [squash(verdict.fragment), squash(verdict.source_fragment)]
+	if (fragment === "" || sourceFragment === "") return "empty_fragment"
+	if (!squash(pair.sentence).includes(fragment)) return "fragment_not_found"
+	const source = pair.kind === "claim" ? pair.statement : pair.quote
+	if (!squash(source).includes(sourceFragment)) return "source_fragment_not_found"
+	return null
+}
+
+function defect(code, pair, driftKind, tiers, verdicts) {
+	const entry = DEFECT_CODES[code]
+	// The fragment must come from the verdict whose drift_kind is being reported, not from whichever
+	// verdict happened to arrive first on the pair.
+	const first = verdicts.find((verdict) => verdict.drift_kind === driftKind) ?? verdicts[0]
+	return {
+		code,
+		severity: entry.severity,
+		integrity: entry.integrity,
+		pair_id: pair.pair_id,
+		sentence_key: pair.sentence_key ?? null,
+		drift_kind: driftKind,
+		tiers,
+		fragment: first.fragment,
+		source_fragment: first.source_fragment,
+		selector: null,
+		line: null,
+		message: `${pair.pair_id}: ${tiers.join(" and ")} reader${tiers.length > 1 ? "s" : ""} found ${driftKind} at "${squash(first.fragment)}"`,
+		hint: entry.hint,
+	}
+}
+
+/** One meaning_unverified defect per coverage gap, so blocksDelivery sees an unread pair through the registry. */
+export function unverifiedDefects(unverified) {
+	const entry = DEFECT_CODES.meaning_unverified
+	return unverified.map((gap) => ({
+		code: "meaning_unverified",
+		severity: entry.severity,
+		integrity: entry.integrity,
+		pair_id: gap.pair_id,
+		reason: gap.reason,
+		selector: null,
+		line: null,
+		message: `${gap.pair_id}: ${gap.reason === "no_strong_verdict" ? "no strong reader judged this force_strong pair" : "no reader judged this pair"}`,
+		hint: entry.hint,
+	}))
+}
+
+/** Pairs with no accepted verdict, and force_strong pairs with no accepted strong verdict, in pair order. */
+function coverageGaps(list, accepted) {
+	const tiersByPair = new Map()
+	for (const verdict of accepted) {
+		tiersByPair.set(verdict.pair_id, (tiersByPair.get(verdict.pair_id) ?? new Set()).add(verdict.model_tier))
+	}
+	const gaps = []
+	for (const pair of list) {
+		const tiers = tiersByPair.get(pair.pair_id)
+		if (tiers === undefined || tiers.size === 0) gaps.push({ pair_id: pair.pair_id, reason: "no_verdict" })
+		else if (pair.force_strong === true && !tiers.has("strong")) gaps.push({ pair_id: pair.pair_id, reason: "no_strong_verdict" })
+	}
+	return gaps
+}
+
+/** Group accepted drift verdicts per pair, then per tier. */
+function flaggedPairs(accepted) {
+	const byPair = new Map()
+	for (const verdict of accepted) {
+		if (verdict.verdict !== "drift") continue
+		const tiers = byPair.get(verdict.pair_id) ?? new Map()
+		tiers.set(verdict.model_tier, [...(tiers.get(verdict.model_tier) ?? []), verdict])
+		byPair.set(verdict.pair_id, tiers)
+	}
+	return byPair
+}
+
+/** The drift_kind both tiers named (never "other"), or null. */
+function agreedKind(tiers) {
+	const [cheap, strong] = MODEL_TIERS.map((tier) => tiers.get(tier) ?? [])
+	return cheap.map((verdict) => verdict.drift_kind).find((kind) => kind !== "other" && strong.some((verdict) => verdict.drift_kind === kind)) ?? null
+}
+
+/**
+ * @param {object[] | { pairs: object[] }} pairs extractPairs(...) output
+ * @param {(string | object[] | { verdicts: object[], model_tier?: string })[]} verdictFiles paths, or parsed verdict lists
+ * @param {{ dispute?: { pair_id: string, reason: string }, calibrationPath?: string }} [options]
+ *   calibrationPath: append each calibration line to this JSONL file (fidelity-calibration.jsonl)
+ * @returns {{ defects: object[], dropped: object[], unverified: { pair_id: string, reason: string }[], calibrationLines: string[] }}
+ *   unverified lists, in pair order, every pair no reader judged (`no_verdict`) and every
+ *   force_strong pair no strong reader judged (`no_strong_verdict`); a verdict that was dropped
+ *   does not count as read. A consumer MUST treat a non-empty list as blocking: the pairs were
+ *   never checked, so an empty `defects` list does not mean the report is clean.
+ * @throws {TypeError} when pairs is neither an array nor `{ pairs: [...] }` (fail closed: a missing
+ *   pairs input never reads as a fully verified report)
+ */
+export function ingestVerdicts(pairs, verdictFiles, options = {}) {
+	const list = Array.isArray(pairs) ? pairs : pairs?.pairs
+	if (!Array.isArray(list)) throw new TypeError("pairs: expected an array of pairs or { pairs: [...] }")
+	const byId = new Map(list.map((pair) => [pair.pair_id, pair]))
+	const accepted = []
+	const dropped = []
+	for (const input of verdictFiles) {
+		for (const { verdict, file } of verdictsOf(input)) {
+			const reason = dropReason(verdict, byId.get(verdict?.pair_id))
+			if (reason === null) accepted.push(verdict)
+			else dropped.push({ file, pair_id: verdict?.pair_id ?? null, model_tier: verdict?.model_tier ?? null, reason })
+		}
+	}
+	const dispute = options.dispute ?? null
+	const defects = []
+	const calibrationLines = []
+	const flagged = flaggedPairs(accepted)
+	for (const pair of list) {
+		const tiers = flagged.get(pair.pair_id)
+		if (!tiers) continue
+		const tierNames = MODEL_TIERS.filter((tier) => tiers.has(tier))
+		const agreed = agreedKind(tiers)
+		const verdicts = MODEL_TIERS.flatMap((tier) => tiers.get(tier) ?? [])
+		const kind = agreed ?? verdicts[0].drift_kind
+		const confirmed = agreed !== null
+		defects.push(defect(confirmed ? "meaning_drift_confirmed" : "meaning_drift_warn", pair, kind, tierNames, verdicts))
+		const disputed = dispute !== null && dispute.pair_id === pair.pair_id
+		calibrationLines.push(JSON.stringify({ kind: pair.kind, pair_id: pair.pair_id, tiers: tierNames, drift_kind: kind, confirmed, disputed, reason: disputed ? String(dispute.reason ?? "") : null }))
+	}
+	const unverified = coverageGaps(list, accepted)
+	if (dispute !== null && !flagged.has(dispute.pair_id)) {
+		dropped.push({ file: "<dispute>", pair_id: dispute.pair_id, model_tier: null, reason: "dispute_not_flagged" })
+	}
+	if (options.calibrationPath && calibrationLines.length > 0) appendFileSync(options.calibrationPath, `${calibrationLines.join("\n")}\n`)
+	return { defects, dropped, unverified, calibrationLines }
+}