lazycodex-ai 5.1.45 → 5.1.46

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

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { locateFind, locateMatch, locatePageLine, locateTable } from "./fact-locate.mjs"
+import { snapshotFromHtml } from "./source-snapshot.mjs"
+
+const FIXTURES = join(import.meta.dir, "tests", "fixtures", "fidelity", "sources")
+const S4_HTML = readFileSync(join(FIXTURES, "S4.html"), "utf8")
+const S4_TEXT = snapshotFromHtml(S4_HTML)
+const S9_TEXT = readFileSync(join(FIXTURES, "S9.txt"), "utf8")
+const MAX = "\uCD5C\uB300"
+
+type Located = {
+	value: string | null
+	unit: string | null
+	raw: string
+	quote: string
+	value_span: [number, number] | null
+	sentence_id: string
+	qualifier: string | null
+	fuzzy?: boolean
+	locator: { artifact: string; char_start: number; char_end: number; page?: number; line: number; table?: string; row_label?: string; col_label?: string }
+}
+
+function expectAnchored(text: string, result: Located): void {
+	expect(text.slice(result.locator.char_start, result.locator.char_end)).toBe(result.quote)
+	if (result.value_span) expect(result.quote.slice(result.value_span[0], result.value_span[1])).toBe(result.raw)
+}
+
+describe("locateFind", () => {
+	test("#given an anchor followed by a quantity #when located #then the value, unit, sentence and locator bind to the snapshot", () => {
+		const result = locateFind(S4_TEXT, { find: "Span length", sourceId: "S4" })
+		expect(result).toMatchObject({ value: "320", unit: "m", raw: "320 m", quote: "Span length: 320 m", qualifier: null })
+		expect(result.sentence_id).toMatch(/^S4:s\d+$/)
+		expect(result.locator.artifact).toBe("S4/text.txt")
+		expectAnchored(S4_TEXT, result)
+	})
+
+	test("#given an expected unit that differs #when located #then unit_expected_mismatch", () => {
+		expect(locateFind(S4_TEXT, { find: "Span length", unitExpected: "mm", sourceId: "S4" })).toMatchObject({ error: "unit_expected_mismatch" })
+		expect(locateFind(S4_TEXT, { find: "Span length", unitExpected: "meters", sourceId: "S4" })).toMatchObject({ value: "320" })
+	})
+
+	test("#given a Korean anchor before a scaled amount #when located #then the first numeral after the anchor is the value and the anchor is the qualifier", () => {
+		const result = locateFind(S9_TEXT, { find: MAX, sourceId: "S9" })
+		expect(result).toMatchObject({ value: "4200000000000", unit: "KRW", qualifier: MAX, sentence_id: "S9:s1" })
+		expectAnchored(S9_TEXT, result)
+	})
+
+	test("#given an English bounding phrase before the value #when located #then it is the qualifier", () => {
+		const text = "The contract costs up to 40 million USD in total."
+		expect(locateFind(text, { find: "costs", sourceId: "S3" })).toMatchObject({ value: "40000000", unit: "USD", qualifier: "up to" })
+	})
+
+	test("#given an anchor that occurs twice #when located #then fact_ambiguous lists both candidates", () => {
+		const result = locateFind(S4_TEXT, { find: "span cost", sourceId: "S4" })
+		expect(result.error).toBe("fact_ambiguous")
+		expect(result.candidates).toHaveLength(2)
+	})
+
+	test("#given a missing anchor, or no numeral within the anchor's sentence #when located #then fact_not_located", () => {
+		expect(locateFind(S4_TEXT, { find: "nonexistent", sourceId: "S4" })).toMatchObject({ error: "fact_not_located", candidates: [] })
+		expect(locateFind("Total reached.\nIt was 12 m.", { find: "Total", sourceId: "S1" })).toMatchObject({ error: "fact_not_located" })
+		expect(locateFind(`Delta ${"x".repeat(90)} 7 m`, { find: "Delta", sourceId: "S1" })).toMatchObject({ error: "fact_not_located" })
+	})
+})
+
+describe("locateTable", () => {
+	test("#given a table found by a header label #when the row and column labels match #then the cell value binds to its text.txt line", () => {
+		const result = locateTable(S4_HTML, { table: "Length", row: "Span", col: "Length", sourceId: "S4" })
+		expect(result).toMatchObject({ value: "320", unit: "m", quote: "320 m", locator: { table: "Length", row_label: "Span", col_label: "Length" } })
+		expect(result.sentence_id).toMatch(/^S4:s\d+$/)
+		expectAnchored(S4_TEXT, result)
+		expect(locateTable(S4_HTML, { table: "dimensions", row: "Approach", col: "Length", sourceId: "S4" })).toMatchObject({ value: "85" })
+	})
+
+	test("#given an unknown table, row or column, or a duplicated row label #when located #then it fails without guessing", () => {
+		expect(locateTable(S4_HTML, { table: "Width", row: "Span", col: "Length", sourceId: "S4" })).toMatchObject({ error: "fact_not_located" })
+		expect(locateTable(S4_HTML, { table: "Length", row: "Deck", col: "Length", sourceId: "S4" })).toMatchObject({ error: "fact_not_located" })
+		const twice = "<table><tr><th>Item</th><th>Cost</th></tr><tr><td>Span</td><td>3</td></tr><tr><td>Span</td><td>4</td></tr></table>"
+		expect(locateTable(twice, { table: "Cost", row: "Span", col: "Cost", sourceId: "S5" })).toMatchObject({ error: "fact_ambiguous" })
+	})
+})
+
+describe("locatePageLine", () => {
+	const text = "Intro line\nRevenue: 15 %\fCost: 3 m\nBetween 1 m and 2 m"
+
+	test("#given a page and line holding one quantity #when located #then it binds with its page and line", () => {
+		const result = locatePageLine(text, { page: 1, line: 2, sourceId: "S6" })
+		expect(result).toMatchObject({ value: "15", unit: "%", quote: "Revenue: 15 %", locator: { line: 2 } })
+		expectAnchored(text, result)
+		expect(locatePageLine(text, { page: 2, line: 1, sourceId: "S6" })).toMatchObject({ value: "3", locator: { page: 2, line: 1 } })
+	})
+
+	test("#given a line with two quantities or a missing page #when located #then ambiguous or not located", () => {
+		expect(locatePageLine(text, { page: 2, line: 2, sourceId: "S6" })).toMatchObject({ error: "fact_ambiguous" })
+		expect(locatePageLine(text, { page: 3, line: 1, sourceId: "S6" })).toMatchObject({ error: "fact_not_located" })
+	})
+})
+
+describe("locateMatch", () => {
+	test("#given an exact match #when located #then raw is the snapshot bytes, the quote is the whole sentence, and there is no value span", () => {
+		const result = locateMatch(S4_TEXT, { match: "no  earlier than 2027", sourceId: "S4" })
+		expect(result).toMatchObject({ raw: "no earlier than 2027", quote: "After the delay, we estimate completion no earlier than 2027.", value_span: null, value: null, fuzzy: false })
+		expectAnchored(S4_TEXT, result)
+	})
+
+	test("#given a near match at or above 0.95 similarity #when located #then the window returns with fuzzy true; below it, fact_not_located", () => {
+		const near = locateMatch(S4_TEXT, { match: "we estimate completion no earlier then 2027", sourceId: "S4" })
+		expect(near).toMatchObject({ raw: "we estimate completion no earlier than 2027", fuzzy: true })
+		expect(locateMatch(S4_TEXT, { match: "completion is certain by 2026", sourceId: "S4" })).toMatchObject({ error: "fact_not_located" })
+	})
+
+	test("#given a phrase that occurs twice #when located #then fact_ambiguous", () => {
+		expect(locateMatch(S4_TEXT, { match: "span cost", sourceId: "S4" })).toMatchObject({ error: "fact_ambiguous" })
+	})
+})

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

@@ -0,0 +1,187 @@
+// fact-pairs.mjs - (source, report sentence) pairs for the meaning verifier.
+//
+// extractPairs walks the prose sentences of a filled HTML report and emits, in document order:
+// a quote pair per distinct ledger quote cited by a findings sentence (facts sharing one quote
+// share one pair), a claim pair per sentence bound only by data-claim (the statement comes from
+// the claim index), and a translation pair per data-translates span. force_strong routes a pair
+// to the strong reader when the lexicon raised name_outside_quote or scope_widened_warn, when the
+// hedge-position heuristic fired, or when the source hedges and the sentence's last six tokens do
+// not. No model, no IO: the readers run as separate lanes. Plain Node ESM; no Hangul here.
+
+import { isExemptKind, proseSentences } from "./fidelity-binding.mjs"
+import { isKoreanTerm, lexicalPattern, lexiconChecks } from "./fidelity-lexicon.mjs"
+import { sentenceKey } from "./fidelity-state.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml, proseText } from "./html-lite.mjs"
+import { HEDGES } from "./lexicon.mjs"
+import { normalizeText } from "./text-normalize.mjs"
+
+/** Every pair kind the producers below emit; consumers count and schema pairs by this list. */
+export const PAIR_KINDS = Object.freeze(["quote", "claim", "translation"])
+const TAIL = 6
+
+const lang = (text) => (isKoreanTerm(text) ? "ko" : "en")
+/** Sentence text with its fact spans cut out, so a Korean value does not make an English sentence Korean. */
+const outsideFacts = (sentence) => sentence.facts.reduceRight((text, fact) => text.slice(0, fact.start - sentence.start) + text.slice(fact.end - sentence.start), sentence.text)
+
+/** Latin hedges match whole words ("exact"); Korean hedges match as substrings, one syllable as a token prefix ("stem"). */
+const HEDGE_RES = HEDGES.map((term) => lexicalPattern(term, isKoreanTerm(term) ? "stem" : "exact"))
+
+/** Hedge terms that are also month names; capitalized and followed by a date number, they are months. */
+const MONTH_WORDS = new Set(["may"])
+
+/** A capitalized Latin match after the first word is a name or a month ("in May"), not a hedge. */
+const isHedgeAt = (text, match) => {
+	if (!/^\p{Lu}/u.test(match[0]) || isKoreanTerm(match[0])) return true
+	if (match.index !== 0) return false
+	// At the start of a text a capital is only sentence case, so the word still hedges - unless it is a
+	// month name followed by a date number ("May 2024 sales rose.").
+	return !(MONTH_WORDS.has(match[0].toLowerCase()) && /^\s+\p{Nd}/u.test(text.slice(match.index + match[0].length)))
+}
+
+export const hasHedge = (text) => {
+	const normal = normalizeText(text)
+	return HEDGE_RES.some((re) => [...normal.matchAll(re)].some((match) => isHedgeAt(normal, match)))
+}
+
+/** The source hedges and none of the sentence's last six tokens carries a hedge. */
+function tailDropsHedge(source, sentence) {
+	if (!hasHedge(source)) return false
+	return !hasHedge(normalizeText(sentence).split(/\s+/u).filter(Boolean).slice(-TAIL).join(" "))
+}
+
+function slugOf(scope) {
+	const heading = scope.section?.heading
+	if (!heading) return ""
+	return (heading.attrs.id ?? proseText(heading))
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}]+/gu, "-")
+		.replace(/^-+|-+$/gu, "")
+}
+
+function claimMap(claims) {
+	const list = Array.isArray(claims) ? claims : (claims?.claims ?? [])
+	return new Map(list.map((claim) => [claim.claim_id, claim]))
+}
+
+const idsOf = (attr) => String(attr ?? "").split(/[\s,]+/u).filter(Boolean)
+
+/** Claim ids that bind a sentence: on the block or an ancestor, or on an inner element whose text the sentence holds. */
+function claimIdsFor(ctx, block, sentence) {
+	const { closest, descendants } = ctx.util
+	const up = block.owner.attrs["data-claim"] !== undefined ? block.owner : closest(block.owner, (node) => node.attrs?.["data-claim"] !== undefined)
+	const ids = up ? idsOf(up.attrs["data-claim"]) : []
+	const text = normalizeText(sentence.text)
+	for (const node of descendants(block.owner)) {
+		if (node.attrs?.["data-claim"] === undefined) continue
+		const inner = normalizeText(proseText(node))
+		if (inner !== "" && text.includes(inner)) ids.push(...idsOf(node.attrs["data-claim"]))
+	}
+	return [...new Set(ids)]
+}
+
+function exempt(ctx, node) {
+	return isExemptKind(node.attrs["data-kind"]) || Boolean(ctx.util.closest(node, (cur) => isExemptKind(cur.attrs?.["data-kind"])))
+}
+
+/** Lexicon routing for every fact span of one quote group in one sentence. */
+function lexiconRouted(group, sentence) {
+	const probes = group.facts.map((fact, index) => ({
+		pair_id: String(index),
+		quote: group.quote,
+		sentence: sentence.text,
+		span: [fact.start - sentence.start, fact.end - sentence.start],
+		qualifier: group.row.kind === "quote" ? null : (group.rows.get(fact.id)?.qualifier ?? null),
+	}))
+	return lexiconChecks(probes).forceStrong.length > 0
+}
+
+function quotePairs(sentence, rows, filled, slug, reportLang) {
+	const groups = new Map()
+	for (const fact of sentence.facts) {
+		const row = rows.get(fact.id)
+		if (!row?.quote || (filled && !filled.has(fact.id))) continue
+		const group = groups.get(row.quote) ?? { quote: row.quote, row, rows, facts: [], ids: [] }
+		group.facts.push(fact)
+		if (!group.ids.includes(fact.id)) group.ids.push(fact.id)
+		groups.set(row.quote, group)
+	}
+	const allIds = [...new Set(sentence.facts.map((fact) => fact.id))]
+	return [...groups.values()].map((group) => ({
+		kind: "quote",
+		sentence_key: sentenceKey(slug, allIds),
+		fact_ids: [...group.ids].sort(),
+		quote: group.quote,
+		sentence: sentence.text,
+		source_lang: lang(group.quote),
+		report_lang: reportLang ?? lang(outsideFacts(sentence)),
+		force_strong: lexiconRouted(group, sentence) || tailDropsHedge(group.quote, sentence.text),
+	}))
+}
+
+function claimPairs(ctx, block, sentence, byClaim, slug, reportLang) {
+	if (sentence.facts.length > 0 || exempt(ctx, block.owner)) return []
+	return claimIdsFor(ctx, block, sentence)
+		.map((id) => byClaim.get(id))
+		.filter(Boolean)
+		.map((claim) => ({
+			kind: "claim",
+			sentence_key: sentenceKey(slug, [claim.claim_id]),
+			claim_id: claim.claim_id,
+			statement: claim.statement,
+			sentence: sentence.text,
+			source_lang: lang(claim.statement),
+			report_lang: reportLang ?? lang(sentence.text),
+			force_strong: lexiconChecks([{ pair_id: "c", quote: claim.statement, sentence: sentence.text }]).forceStrong.length > 0 || tailDropsHedge(claim.statement, sentence.text),
+		}))
+}
+
+function translationPair(node, rows, filled, slug, reportLang) {
+	const id = node.attrs["data-translates"]
+	const row = rows.get(id)
+	const text = proseText(node)
+	if (!row?.quote || text === "" || (filled && !filled.has(id))) return null
+	return {
+		kind: "translation",
+		sentence_key: sentenceKey(slug, [id]),
+		fact_ids: [id],
+		quote: row.quote,
+		sentence: text,
+		source_lang: lang(row.quote),
+		report_lang: reportLang ?? lang(text),
+		force_strong: tailDropsHedge(row.quote, text),
+	}
+}
+
+/**
+ * @param {string} html the filled report
+ * @param {{ rows: object[] }} ledger
+ * @param {{ claims: object[] } | object[] | null} claims indexClaims(...) output or its claims array
+ * @param {{ fact_id: string }[]} [fillMap] fact fill's map; when given, only facts it filled are paired
+ * @returns {object[]} pairs with pair_id P1, P2, ... in document order
+ */
+export function extractPairs(html, ledger, claims, fillMap) {
+	const ctx = buildContext(parseHtml(html), {})
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const filled = Array.isArray(fillMap) ? new Set(fillMap.map((entry) => entry.fact_id)) : null
+	const byClaim = claimMap(claims)
+	const htmlLang = ctx.all.find((node) => node.tag === "html")?.attrs.lang
+	const reportLang = htmlLang ? htmlLang.toLowerCase().split("-")[0] : null
+	const out = []
+	const seenSpans = new Set()
+	for (const block of proseSentences(ctx)) {
+		const findings = Boolean(block.scope.section) && block.kind === null
+		if (!findings) continue
+		const slug = slugOf(block.scope)
+		for (const sentence of block.sentences) {
+			out.push(...quotePairs(sentence, rows, filled, slug, reportLang), ...claimPairs(ctx, block, sentence, byClaim, slug, reportLang))
+		}
+		for (const node of ctx.util.descendants(block.owner)) {
+			if (node.attrs?.["data-translates"] === undefined || seenSpans.has(node)) continue
+			seenSpans.add(node)
+			const pair = translationPair(node, rows, filled, slug, reportLang)
+			if (pair) out.push(pair)
+		}
+	}
+	return out.map((pair, index) => ({ pair_id: `P${index + 1}`, ...pair }))
+}

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

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+import { extractPairs, hasHedge, PAIR_KINDS } from "./fact-pairs.mjs"
+import { fill } from "./fact-fill.mjs"
+
+type Row = Record<string, unknown> & { fact_id: string }
+type Pair = Record<string, unknown> & { pair_id: string; kind: string; sentence: string }
+
+const FIXTURES = join(import.meta.dir, "tests/fixtures/fidelity")
+const BASE = JSON.parse(readFileSync(join(FIXTURES, "ledger-basic.json"), "utf8")) as { schemaVersion: number; rows: Row[] }
+const Q7 = BASE.rows.find((row) => row.fact_id === "Q7")
+if (Q7 === undefined) throw new Error("ledger-basic.json lost Q7")
+const Q8 = { ...Q7, fact_id: "Q8", label: "outlook", quote: "Demand may recover in 2027" }
+const LEDGER = { ...BASE, rows: [...BASE.rows, Q8] }
+const CLAIMS = indexClaims(readFileSync(join(FIXTURES, "claim-graph.md"), "utf8"))
+
+const SOURCE = [
+	"<!doctype html><html lang=\"en\"><body>",
+	"<h1>Bridge report</h1>",
+	"<h2 id=\"findings\">Findings</h2>",
+	"<p>The span is {{F12:span_len:q}}, or {{F40:span_mm}} [S4].</p>",
+	"<p>The rate is {{F13:rate}} [S4].</p>",
+	"<p>The operator wrote {{Q8:outlook}}, so the recovery is certain and fully funded now.</p>",
+	"<p>The note says {{Q7:completion}}<span data-translates=\"Q7\">completion is not expected before 2027</span>.</p>",
+	"<p data-claim=\"C2\">Revenue grew 10 percent in 2025.</p>",
+	"<p data-kind=\"opinion\">This looks like a sound plan.</p>",
+	"<h2>Sources</h2>",
+	"<ol><li id=\"s4\">[S4] Bridge authority page, retrieved 2026-10-01. Its span is {{F13:rate}}.</li></ol>",
+	"</body></html>",
+].join("\n")
+
+function filled(): { out: string; fillMap: { fact_id: string }[] } {
+	const result = fill(SOURCE, LEDGER, { format: "html" })
+	if (result.out === null) throw new Error(`fixture failed to fill: ${JSON.stringify(result.errors)}`)
+	return { out: result.out, fillMap: result.fillMap as { fact_id: string }[] }
+}
+
+function pairs(): Pair[] {
+	const { out, fillMap } = filled()
+	return extractPairs(out, LEDGER, CLAIMS, fillMap) as Pair[]
+}
+
+describe("extractPairs: a filled report", () => {
+	test("#given the filled fixture #when extracted #then pairs come in document order with P ids", () => {
+		const result = pairs()
+		expect(result.map((pair) => [pair.pair_id, pair.kind])).toEqual([
+			["P1", "quote"],
+			["P2", "quote"],
+			["P3", "quote"],
+			["P4", "quote"],
+			["P5", "translation"],
+			["P6", "claim"],
+		])
+	})
+
+	test("#given the fixture that produces every pair kind #when extracted #then the kinds are exactly PAIR_KINDS", () => {
+		expect([...new Set(pairs().map((pair) => pair.kind))].sort()).toEqual([...PAIR_KINDS].sort())
+		expect(Object.isFrozen(PAIR_KINDS)).toBe(true)
+	})
+
+	test("#given two facts sharing one source quote #when extracted #then one quote pair names both", () => {
+		const [first] = pairs()
+		expect(first).toMatchObject({
+			kind: "quote",
+			sentence_key: "findings#F12,F40",
+			fact_ids: ["F12", "F40"],
+			quote: "The bridge has a main span of up to 320 m.",
+			source_lang: "en",
+			report_lang: "en",
+			force_strong: false,
+		})
+		expect(first.sentence).toContain("up to 320 m")
+	})
+
+	test("#given an unhedged quote with its value kept #when extracted #then force_strong stays false", () => {
+		expect(pairs()[1]).toMatchObject({ fact_ids: ["F13"], quote: "The rate reached 15.2% in May.", force_strong: false })
+	})
+
+	test("#given a hedged quote whose sentence ends without a hedge #when extracted #then force_strong is true", () => {
+		expect(pairs()[2]).toMatchObject({ fact_ids: ["Q8"], quote: "Demand may recover in 2027", force_strong: true })
+	})
+
+	test("#given a data-translates span #when extracted #then a translation pair carries the span text", () => {
+		const result = pairs()
+		expect(result[3]).toMatchObject({ kind: "quote", fact_ids: ["Q7"] })
+		expect(result[4]).toMatchObject({
+			kind: "translation",
+			fact_ids: ["Q7"],
+			quote: "we estimate completion no earlier than 2027",
+			sentence: "completion is not expected before 2027",
+		})
+	})
+
+	test("#given a sentence bound only by data-claim #when extracted #then a claim pair carries the node statement", () => {
+		expect(pairs()[5]).toMatchObject({
+			kind: "claim",
+			claim_id: "C2",
+			statement: "Revenue grew about 10 percent in 2025.",
+			sentence: "Revenue grew 10 percent in 2025.",
+			force_strong: true,
+		})
+	})
+
+	test("#given an opinion paragraph and a sources section #when extracted #then neither yields a pair", () => {
+		const sentences = pairs().map((pair) => pair.sentence)
+		expect(sentences.some((text) => text.includes("sound plan"))).toBe(false)
+		expect(sentences.some((text) => text.includes("Bridge authority"))).toBe(false)
+	})
+
+	test("#given a fill map that omits a fact #when extracted #then that hand-typed fact yields no pair", () => {
+		const { out, fillMap } = filled()
+		const kept = fillMap.filter((entry) => entry.fact_id !== "F13")
+		const result = extractPairs(out, LEDGER, CLAIMS, kept) as Pair[]
+		expect(result.some((pair) => Array.isArray(pair.fact_ids) && (pair.fact_ids as string[]).includes("F13"))).toBe(false)
+	})
+
+	test("#given no fill map #when extracted #then every data-fact element counts as filled", () => {
+		const { out } = filled()
+		expect((extractPairs(out, LEDGER, CLAIMS) as Pair[]).length).toBe(6)
+	})
+
+	test("#given a Hangul quote #when extracted #then source_lang is ko", () => {
+		const html = "<html><body><h2>Findings</h2><p>HBM revenue reached {{F21:hbm_rev}} [S5].</p></body></html>"
+		const result = fill(html, LEDGER, { format: "html" }) as { out: string; fillMap: { fact_id: string }[] }
+		const [pair] = extractPairs(result.out, LEDGER, CLAIMS, result.fillMap) as Pair[]
+		expect(pair).toMatchObject({ fact_ids: ["F21"], source_lang: "ko", report_lang: "en" })
+	})
+})
+
+describe("extractPairs: a fill map over translations", () => {
+	test("#given a fill map that omits the translated fact #when extracted #then no translation pair is emitted", () => {
+		const { out, fillMap } = filled()
+		const kept = fillMap.filter((entry) => entry.fact_id !== "Q7")
+		const result = extractPairs(out, LEDGER, CLAIMS, kept) as Pair[]
+		expect(result.some((pair) => pair.kind === "translation")).toBe(false)
+	})
+})
+
+describe("hasHedge: a month is not a hedge", () => {
+	test("#given a text that starts with the month May #when checked #then it does not count as hedged", () => {
+		expect(hasHedge("May 2024 sales rose.")).toBe(false)
+	})
+
+	test("#given a sentence-initial modal may #when checked #then it still counts as hedged", () => {
+		expect(hasHedge("May the figure hold through 2027.")).toBe(true)
+		expect(hasHedge("Demand may recover in 2027.")).toBe(true)
+	})
+})
+
+describe("extractPairs: determinism", () => {
+	test("#given the same filled report twice #when extracted #then both results are byte-for-byte equal", () => {
+		const { out, fillMap } = filled()
+		const first = JSON.stringify(extractPairs(out, LEDGER, CLAIMS, fillMap))
+		const second = JSON.stringify(extractPairs(out, LEDGER, CLAIMS, fillMap))
+		expect(second).toBe(first)
+	})
+})
+
+describe("extractPairs: the no-model contract", () => {
+	test("#given the module source #when read #then it never fetches or imports a network or model client", () => {
+		const text = readFileSync(join(import.meta.dir, "fact-pairs.mjs"), "utf8")
+		expect(text).not.toMatch(/\bfetch\s*\(|node:https?|node:net|from\s+"(?!\.\/|node:)/u)
+	})
+})

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

@@ -0,0 +1,89 @@
+// Iterative postorder verifier: one snapshot and one arithmetic evaluation per reachable node.
+import { compute } from "./fact-derive.mjs"
+import { parseExpr } from "./fact-expr.mjs"
+import { isLegacyDerived, kindRuleErrors, readFlaws, readRow } from "./fact-ledger-kinds.mjs"
+import { rowErrors } from "./fact-ledger-schema.mjs"
+import { refuse } from "./unit-algebra.mjs"
+import { refusal } from "./unit-errors.mjs"
+import { object, sameDeclared } from "./unit-metadata.mjs"
+import { expectedUnit, malformed, ruleOf, unitMismatch } from "./unit-rules.mjs"
+
+const derived = (row) => row.kind === "derived" || row.kind === "converted"
+const fail = (detail, shape, expected) => ({ ok: false, detail, shape, expected })
+function refuseLegacy(row) {
+	if (isLegacyDerived(row)) refuse(`${row.fact_id} was written before precision, compatibility, and context existed; regenerate it with derive`, undefined, "legacy derived row", "a derived row regenerated by derive")
+}
+
+function verifyRow(row, rows) {
+	const rule = ruleOf(row.operation)
+	const ast = rule.expression ? parseExpr(row.formula) : null
+	const context = { ...row.context, rationale: row.rationale }
+	const unit = expectedUnit(row.operation, rows, { ast, context })
+	const expected = { unit, ...compute(row.operation, rows, unit, ast, context, row.formula), derived_from: rows.map((r) => r.fact_id) }
+	if (row.unit !== unit) return fail(`${row.fact_id}: ${unitMismatch(row.operation, rows, row.unit, unit)}`, "result_unit", expected)
+	for (const field of Object.keys(expected)) {
+		if (!sameDeclared(row[field], expected[field])) return fail(`${row.fact_id}: stored ${field} differs from the recomputed result`, `${field}_mismatch`, expected)
+	}
+	return { ok: true, expected }
+}
+
+export function verifyGraph(ledger, roots, requireActive = false, override = null) {
+	try {
+		if (!object(ledger) || !Array.isArray(ledger.rows)) refuse("ledger rows must be an array")
+		const byId = new Map()
+		for (const r of ledger.rows) {
+			if (!object(r) || typeof r.fact_id !== "string" || byId.has(r.fact_id)) refuse("ledger rows need distinct fact ids", undefined, "identity", "distinct fact ids")
+			byId.set(r.fact_id, r)
+		}
+		if (override) byId.set(override.fact_id, override)
+		const states = new Map()
+		const snapshots = new Map()
+		const results = new Map()
+		const stack = roots.map((id) => ({ id, finish: false }))
+		while (stack.length) {
+			const { id, finish } = stack.pop()
+			if (states.get(id) === "done") continue
+			if (!finish) {
+				if (states.get(id) === "open") refuse(`${id}: operands form a cycle`, undefined, "cycle", "an acyclic dependency graph")
+				const original = byId.get(id)
+				if (!original) refuse(`no ledger row ${id}`, undefined, "missing_operand", "an existing fact id")
+				const row = { ...readRow(original) }
+				snapshots.set(id, row)
+				if (requireActive && row.status !== "active") refuse(`${id} is ${row.status}`, undefined, "inactive_dependency", "active dependencies at every depth")
+				const [flaw] = readFlaws(row)
+				if (flaw) refuse(`${id}: ${flaw.detail}`, undefined, flaw.shape, flaw.expected)
+				if (derived(row)) {
+					refuseLegacy(row)
+					const shape = malformed(row)
+					if (shape) refuse(`${id}: ${shape}`, undefined, "malformed_row", "the operation's registry row shape")
+				}
+				const errors = derived(row) ? kindRuleErrors(row, id) : rowErrors(row)
+				if (errors.length) refuse(errors.join("; "), undefined, "row_schema", "a canonical row matching its kind and operation")
+				if (row.exact === null || row.value === null) refuse(`${id} has no exact value to derive from`)
+				states.set(id, "open")
+				stack.push({ id, finish: true })
+				if (derived(row)) for (const dependency of row.operands) stack.push({ id: dependency, finish: false })
+			} else {
+				const row = snapshots.get(id)
+				if (derived(row)) {
+					const result = verifyRow(row, row.operands.map((ref) => snapshots.get(ref)))
+					if (!result.ok) return result
+					const errors = rowErrors(row)
+					if (errors.length) refuse(errors.join("; "), undefined, "row_schema", "a complete canonical row")
+					results.set(id, result)
+				}
+				states.set(id, "done")
+			}
+		}
+		return results.get(roots[0]) ?? { ok: true }
+	} catch (error) { return { ok: false, ...refusal(error) } }
+}
+
+export function recompute(ledger, row) {
+	try {
+		refuseLegacy(row)
+		const shape = malformed(row)
+		if (shape) refuse(shape, undefined, "malformed_row", "a valid derived or converted row")
+		return verifyGraph(ledger, [row.fact_id], false, row)
+	} catch (error) { return { ok: false, ...refusal(error) } }
+}