lazycodex-ai 5.1.44 → 5.1.46

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

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test"
+
+import { splitSentences } from "./sentence-split.mjs"
+
+type Sentence = { sid: string; start: number; end: number; text: string }
+
+function at(records: Sentence[], index: number): Sentence {
+	const record = records[index]
+	if (record === undefined) throw new Error(`no sentence at index ${index}`)
+	return record
+}
+
+function expectSlices(text: string, records: Sentence[]): void {
+	for (const record of records) expect(text.slice(record.start, record.end)).toBe(record.text)
+}
+
+describe("splitSentences", () => {
+	test("#given a Korean paragraph with da/yo/nida endings #when split #then sids and offsets match each sentence", () => {
+		// given
+		const text = "매출은 100억 원입니다. 비용도 늘었어요. 이익은 줄었다.다만 회복이 기대된다."
+		// when
+		const records = splitSentences(text) as Sentence[]
+		// then
+		expect(records.map((r) => r.sid)).toEqual(["s1", "s2", "s3", "s4"])
+		expect(records.map((r) => r.text)).toEqual([
+			"매출은 100억 원입니다.",
+			"비용도 늘었어요.",
+			"이익은 줄었다.",
+			"다만 회복이 기대된다.",
+		])
+		expect(at(records, 1).start).toBe(text.indexOf("비용도"))
+		expectSlices(text, records)
+	})
+
+	test("#given an English paragraph with abbreviations and decimals #when split #then e.g. and 3.2 do not end a sentence", () => {
+		// given
+		const text = "Use units, e.g. 3.2 m per bar. The next one follows! Is it fine? Yes."
+		// when
+		const records = splitSentences(text) as Sentence[]
+		// then
+		expect(records.map((r) => r.sid)).toEqual(["s1", "s2", "s3", "s4"])
+		expect(records.map((r) => r.text)).toEqual([
+			"Use units, e.g. 3.2 m per bar.",
+			"The next one follows!",
+			"Is it fine?",
+			"Yes.",
+		])
+		expect(at(records, 3).start).toBe(text.indexOf("Yes."))
+		expect(at(records, 3).end).toBe(text.length)
+		expectSlices(text, records)
+	})
+
+	test("#given line breaks and blank lines #when split #then each non-empty line yields its own record", () => {
+		// given
+		const text = "매출은 100억 원이다. 다만 아직 확정되지 않았다.\n\n  Second line without stop\nThird?"
+		// when
+		const records = splitSentences(text) as Sentence[]
+		// then
+		expect(records.map((r) => r.text)).toEqual([
+			"매출은 100억 원이다.",
+			"다만 아직 확정되지 않았다.",
+			"Second line without stop",
+			"Third?",
+		])
+		expect(records.map((r) => r.sid)).toEqual(["s1", "s2", "s3", "s4"])
+		expectSlices(text, records)
+	})
+
+	test("#given Korean quoted speech closed right after a da ending #when split #then the quote stays inside one sentence", () => {
+		// given
+		const single = '그는 "매출이 늘었다."라고 말했다.'
+		const pair = '그는 "매출이 늘었다."라고 말했다. 다음 날 떨어졌다.'
+		const bracket = "그는 「좋아요.」라고 답했다."
+		// when
+		const singleRecords = splitSentences(single) as Sentence[]
+		const pairRecords = splitSentences(pair) as Sentence[]
+		const bracketRecords = splitSentences(bracket) as Sentence[]
+		// then
+		expect(singleRecords.map((r) => r.text)).toEqual([single])
+		expect(pairRecords.map((r) => r.text)).toEqual(['그는 "매출이 늘었다."라고 말했다.', "다음 날 떨어졌다."])
+		expect(pairRecords.map((r) => r.sid)).toEqual(["s1", "s2"])
+		expect(at(pairRecords, 0).start).toBe(0)
+		expect(at(pairRecords, 1).start).toBe(pair.indexOf("다음 날"))
+		expect(at(pairRecords, 1).end).toBe(pair.length)
+		expect(bracketRecords.map((r) => r.text)).toEqual([bracket])
+		expectSlices(pair, pairRecords)
+	})
+
+	test("#given the word no #when split #then it is an abbreviation only before a number", () => {
+		// given
+		const answer = "The answer was no. Then we left."
+		const numbered = "See No. 5 for details. Then stop."
+		// when
+		const answerRecords = splitSentences(answer) as Sentence[]
+		const numberedRecords = splitSentences(numbered) as Sentence[]
+		// then
+		expect(answerRecords.map((r) => r.text)).toEqual(["The answer was no.", "Then we left."])
+		expect(at(answerRecords, 1).start).toBe(answer.indexOf("Then"))
+		expect(numberedRecords.map((r) => r.text)).toEqual(["See No. 5 for details.", "Then stop."])
+		expectSlices(answer, answerRecords)
+		expectSlices(numbered, numberedRecords)
+	})
+
+	test("#given empty or whitespace-only text #when split #then no records are produced", () => {
+		// when / then
+		expect(splitSentences("")).toEqual([])
+		expect(splitSentences(" \n\t\n")).toEqual([])
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/source-commands.mjs

@@ -0,0 +1,140 @@
+// source-commands.mjs - the `source snapshot` and `claims index` subcommands of report-tools.
+// A source dir is immutable: the same id with identical text is a no-op, different text fails
+// (exit 1, snapshot_exists), because ledger rows pin the old hash. `--url` fetches with plain
+// fetch (30 s timeout, no browser) and records extractor tool:source-snapshot@1; `--html` and
+// `--text` import a browser-lane capture and record extractor model (lower trust), or the named
+// extractor for `--text --extractor NAME@VERSION`; `--command` runs an argv without a shell and
+// snapshots its stdout, with the argv, cwd, exit status, and output hashes in command.json.
+// node: builtins and sibling imports only.
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+import { CliError, parseArgs, sha256Of, writeJsonAtomic } from "./cli-support.mjs"
+import { parseFidelityBlock } from "./fidelity-brief.mjs"
+import { writeSnapshot } from "./source-snapshot.mjs"
+
+const FETCH_TIMEOUT_MS = 30_000
+const TOOL_EXTRACTOR = "tool:source-snapshot@1"
+const SNAPSHOT_USAGE =
+	"usage: source snapshot --id S<n> (--url <u> | --html <file> | --text <file> [--extractor NAME@VERSION] | --command '<argv json>' --cwd DIR) [--kind page|command|document] [--provenance primary|secondary] [--revision R] --session-dir D"
+
+function readInput(path) {
+	try {
+		return readFileSync(path, "utf8")
+	} catch (error) {
+		throw new CliError(`cannot read ${path}: ${error.code ?? error.message}`)
+	}
+}
+
+/** The session dir from --session-dir or SESSION_DIR; a usage error when neither is set. */
+export function sessionDirOf(flags) {
+	const dir = flags["session-dir"] ?? process.env.SESSION_DIR
+	if (!dir || dir === true) throw new CliError("--session-dir is required (or set SESSION_DIR)")
+	return resolve(dir)
+}
+
+/** The snapshot of one source: meta.json, text.txt, and source.html when the source was a page. */
+export function snapshotOf(sessionDir, id) {
+	const dir = join(sessionDir, "sources", String(id))
+	if (!existsSync(join(dir, "meta.json"))) throw new CliError(`source ${id} has no snapshot; run source snapshot --id ${id} first`)
+	const html = join(dir, "source.html")
+	return { meta: JSON.parse(readInput(join(dir, "meta.json"))), text: readInput(join(dir, "text.txt")), html: existsSync(html) ? readInput(html) : null }
+}
+
+/** Whether the brief's source floor lists this source as pointed at (`pointed only: a, b`). */
+export function pointedFlag(sessionDir, url) {
+	const brief = join(sessionDir, "brief.md")
+	const floor = existsSync(brief) ? (parseFidelityBlock(readInput(brief)).fields?.["source floor"] ?? "") : ""
+	const match = /^pointed only:\s*(.+)$/i.exec(floor.trim())
+	return match ? match[1].split(",").map((entry) => entry.trim()).includes(url) : false
+}
+
+async function fetchSource(url) {
+	if (!URL.canParse(url)) throw new CliError(`--url is not a URL: ${url}`)
+	let response
+	try {
+		response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+	} catch (error) {
+		throw new CliError(`fetch failed for ${url}: ${error.message}`)
+	}
+	if (!response.ok) {
+		await response.body?.cancel()
+		throw new CliError(`fetch failed: HTTP ${response.status} for ${url}`)
+	}
+	const type = response.headers.get("content-type") ?? ""
+	if (/pdf/i.test(type)) {
+		await response.body?.cancel()
+		throw new CliError(`pdf response: ${url}; extract its text and use --text <file> --extractor NAME@VERSION`)
+	}
+	const body = await response.text()
+	return /html|xml/i.test(type) || /^\s*</.test(body) ? { url, html: body } : { url, text: body }
+}
+
+function runCommand(argvJson, cwd) {
+	let argv
+	try {
+		argv = JSON.parse(argvJson)
+	} catch (error) {
+		throw new CliError(`--command must be a JSON array of strings: ${error.message}`)
+	}
+	if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string" && part.length > 0)) {
+		throw new CliError("--command must be a non-empty JSON array of non-empty strings")
+	}
+	if (!cwd || cwd === true) throw new CliError("--command needs --cwd DIR")
+	const proc = spawnSync(argv[0], argv.slice(1), { cwd: resolve(cwd), encoding: "utf8", shell: false, maxBuffer: 64 * 1024 * 1024 })
+	if (proc.error) throw new CliError(`--command could not start: ${proc.error.message}`)
+	const receipt = { argv, cwd: resolve(cwd), exit_status: proc.status, stdout_sha256: sha256Of(proc.stdout), stderr_sha256: sha256Of(proc.stderr) }
+	return { path: `command:${argv.join(" ")}`, text: proc.stdout, kind: "command", receipt }
+}
+
+async function acquire(flags) {
+	const given = ["url", "html", "text", "command"].filter((name) => flags[name] !== undefined)
+	if (given.length !== 1) throw new CliError(SNAPSHOT_USAGE)
+	if (flags.extractor !== undefined && flags.text === undefined) throw new CliError("--extractor goes with --text only")
+	if (flags.url !== undefined) return { ...(await fetchSource(flags.url)), extractor: TOOL_EXTRACTOR }
+	if (flags.html !== undefined) return { path: resolve(flags.html), html: readInput(flags.html), extractor: "model" }
+	if (flags.text !== undefined) return { path: resolve(flags.text), text: readInput(flags.text), extractor: flags.extractor === undefined ? "model" : `extractor:${flags.extractor}` }
+	return { ...runCommand(flags.command, flags.cwd), extractor: TOOL_EXTRACTOR }
+}
+
+export async function runSource(argv) {
+	const [sub, ...rest] = argv
+	if (sub !== "snapshot") throw new CliError(SNAPSHOT_USAGE)
+	const args = parseArgs(rest)
+	const id = args.required("id")
+	const sourcesDir = join(sessionDirOf(args.flags), "sources")
+	const { receipt, ...input } = await acquire(args.flags)
+	if (args.flags.kind !== undefined) input.kind = args.flags.kind
+	if (args.flags.provenance !== undefined) input.provenance = args.flags.provenance
+	if (args.flags.revision !== undefined) input.revision = args.flags.revision
+	let written
+	try {
+		written = writeSnapshot(sourcesDir, id, input)
+	} catch (error) {
+		if (String(error.message).startsWith("snapshot_exists")) {
+			return { json: { command: "source snapshot", status: "fail", exitCode: 1, error: "snapshot_exists", message: error.message }, summary: `source snapshot: ${error.message}`, exitCode: 1 }
+		}
+		if (error instanceof TypeError) throw new CliError(error.message)
+		throw error
+	}
+	if (receipt) writeFileSync(join(written.dir, "command.json"), `${JSON.stringify(receipt, null, 2)}\n`)
+	const meta = JSON.parse(readFileSync(join(written.dir, "meta.json"), "utf8"))
+	const data = { source_id: id, directory: written.dir, snapshot_sha256: written.sha256, extractor: meta.extractor, kind: meta.kind, provenance: meta.provenance }
+	return { json: { command: "source snapshot", status: "pass", exitCode: 0, data }, summary: `source snapshot: ${id} ${written.sha256.slice(0, 12)} (${meta.extractor})`, exitCode: 0 }
+}
+
+export function runClaims(argv) {
+	const [sub, ...rest] = argv
+	const args = parseArgs(rest)
+	const [graph] = args.positionals
+	if (sub !== "index" || !graph) throw new CliError("usage: claims index <claim-graph.md> --out claims.json")
+	const out = args.required("out")
+	const index = indexClaims(readInput(graph))
+	if (index.errors.length > 0) throw new CliError(`claims index ${graph}: ${index.errors.join("; ")}`)
+	writeJsonAtomic(out, { schemaVersion: 1, graph: resolve(graph), graph_sha256: sha256Of(readFileSync(graph)), ...index })
+	const verified = index.claims.filter((claim) => claim.in_verified).length
+	return { json: { command: "claims index", out: resolve(out), claims: index.claims.length, verified }, summary: `claims index: ${index.claims.length} claim(s), ${verified} verified`, exitCode: 0 }
+}

package/packages/shared-skills/skills/ulw-research/scripts/source-snapshot.mjs

@@ -0,0 +1,176 @@
+// source-snapshot.mjs - the per-source snapshot that fact locators read.
+//
+// snapshotFromHtml turns a page into text.txt form: one line per block (prose blocks via
+// proseText, one table cell per line; head, scripts, styles and code are dropped). writeSnapshot
+// writes <sourcesDir>/<S-id>/ with text.txt (pages joined by a form feed), source.html when html
+// was given, meta.json, sentences.jsonl (sid S<n>:s<k>) and acronyms.json. The sha256 covers
+// text.txt only. Nothing here touches the network: the caller supplies the html or text.
+// Plain Node ESM, node: builtins and sibling imports only.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { sha256Of } from "./cli-support.mjs"
+import { parseHtml, PROSE_TAGS, proseText } from "./html-lite.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+
+const SKIP = new Set(["head", "script", "style", "svg", "code", "pre", "kbd", "samp", "template", "noscript"])
+const INLINE = new Set([
+	"a", "abbr", "b", "bdi", "bdo", "cite", "data", "del", "dfn", "em", "font", "i", "ins", "label", "mark", "q", "s",
+	"small", "span", "strong", "sub", "sup", "time", "u", "var",
+])
+const SOURCE_ID = /^S[1-9]\d*$/
+const EXTRACTOR = /^(?:tool:source-snapshot@1|model|extractor:[\w.@+-]+)$/
+const KINDS = new Set(["page", "command", "document"])
+const PROVENANCE = new Set(["primary", "secondary", "unknown"])
+const ACRONYM_AFTER = /\(([A-Z]{2,6})\)/g
+const ACRONYM_BEFORE = /(?<![\p{L}\p{N}])([A-Z]{2,6})\s?\(([A-Z][^()\n]{2,79})\)/gu
+const NAME_WORD = /^[A-Z][\p{L}\p{N}-]*$/u
+const CONNECTOR = new Set(["of", "and", "for", "the", "in", "on", "to", "&"])
+
+/**
+ * Block lines of a page: { root, text, blocks: [{ node, start, end }] } where text joins the block
+ * texts with "\n" and text.slice(start, end) is one block. fact-locate reads cells through `node`.
+ */
+export function snapshotBlocks(html) {
+	const root = parseHtml(html)
+	const lines = []
+	let buffer = ""
+	const flush = (node) => {
+		const line = buffer.replace(/\s+/g, " ").trim()
+		buffer = ""
+		if (line) lines.push({ node, text: line })
+	}
+	const walk = (node) => {
+		for (const child of node.children) {
+			if (child.tag === "#text") buffer += child.text
+			else if (SKIP.has(child.tag)) continue
+			else if (child.tag === "br") flush(node)
+			else if (INLINE.has(child.tag)) walk(child)
+			else if (PROSE_TAGS.has(child.tag)) {
+				flush(node)
+				const line = proseText(child)
+				if (line) lines.push({ node: child, text: line })
+			} else {
+				flush(node)
+				walk(child)
+				flush(child)
+			}
+		}
+	}
+	walk(root)
+	flush(root)
+	const blocks = []
+	let at = 0
+	for (const line of lines) {
+		blocks.push({ node: line.node, start: at, end: at + line.text.length })
+		at += line.text.length + 1
+	}
+	return { root, text: lines.map((line) => line.text).join("\n"), blocks }
+}
+
+/** text.txt form of an html page. */
+export function snapshotFromHtml(html) {
+	return snapshotBlocks(html).text
+}
+
+/** Sentence index rows { sid: "S<n>:s<k>", start, end, text }; a form feed (page break) always ends a sentence. */
+export function indexSentences(text, sourceId) {
+	return splitSentences(text.replace(/\f/g, "\n")).map((row) => ({
+		sid: `${sourceId}:${row.sid}`,
+		start: row.start,
+		end: row.end,
+		text: text.slice(row.start, row.end),
+	}))
+}
+
+const sentenceIdAt = (sentences, offset) => sentences.find((row) => row.start <= offset && offset < row.end)?.sid ?? null
+
+/** "High Bandwidth Memory (HBM)": the capitalized words before the parenthesis, at most one per letter. */
+function nameBefore(text, at, letters) {
+	const prefix = text.slice(Math.max(0, at - 160), at)
+	if (!/\S[ \t]?$/.test(prefix)) return null
+	const words = [...prefix.matchAll(/\S+/g)]
+	const picked = []
+	let content = 0
+	for (let k = words.length - 1; k >= 0 && content < letters; k--) {
+		const word = words[k][0]
+		if (NAME_WORD.test(word)) content++
+		else if (!CONNECTOR.has(word) || picked.length === 0) break
+		picked.unshift(words[k])
+	}
+	while (picked.length > 0 && CONNECTOR.has(picked[0][0])) picked.shift()
+	if (picked.length === 0) return null
+	const start = at - prefix.length + picked[0].index
+	const end = at - prefix.length + picked[picked.length - 1].index + picked[picked.length - 1][0].length
+	return { start, expansion: text.slice(start, end) }
+}
+
+/** Every `Full Name (ACR)` and `ACR (Full Name)` in the text, ordered by position. */
+export function findAcronyms(text, sentences) {
+	const entries = []
+	for (const match of text.matchAll(ACRONYM_AFTER)) {
+		const name = nameBefore(text, match.index, match[1].length)
+		if (!name || name.expansion === match[1]) continue
+		entries.push({ acronym: match[1], expansion: name.expansion, span: [name.start, match.index + match[0].length] })
+	}
+	for (const match of text.matchAll(ACRONYM_BEFORE)) {
+		const expansion = match[2].trim()
+		if (!/\s/.test(expansion) || expansion === expansion.toUpperCase()) continue
+		entries.push({ acronym: match[1], expansion, span: [match.index, match.index + match[0].length] })
+	}
+	return entries
+		.sort((a, b) => a.span[0] - b.span[0])
+		.map((entry) => ({ acronym: entry.acronym, expansion: entry.expansion, sentence_id: sentenceIdAt(sentences, entry.span[0]), span: entry.span }))
+}
+
+function snapshotText(input) {
+	if (Array.isArray(input.pages)) return input.pages.join("\f")
+	if (typeof input.text === "string") return input.text
+	if (typeof input.html === "string") return snapshotFromHtml(input.html)
+	throw new TypeError("writeSnapshot needs text, pages, or html")
+}
+
+function checkInput(sourceId, input) {
+	if (!SOURCE_ID.test(String(sourceId))) throw new TypeError(`source id must be S<n>, got ${sourceId}`)
+	if (!EXTRACTOR.test(String(input.extractor))) throw new TypeError(`extractor must be tool:source-snapshot@1, model, or extractor:<name>, got ${input.extractor}`)
+	if (typeof (input.url ?? input.path) !== "string") throw new TypeError("writeSnapshot needs a url or a path")
+	if (input.kind !== undefined && !KINDS.has(input.kind)) throw new TypeError(`kind must be page, command, or document, got ${input.kind}`)
+	if (input.provenance !== undefined && !PROVENANCE.has(input.provenance)) throw new TypeError(`provenance must be primary, secondary, or unknown, got ${input.provenance}`)
+}
+
+/**
+ * Write <sourcesDir>/<sourceId>/ for one source; returns { dir, sha256 } with sha256 over text.txt.
+ * input: { url | path, text | pages | html, extractor, observed_at?, revision?, kind?, provenance? }.
+ * Re-writing the same text is a no-op change; a different text over an existing snapshot throws
+ * snapshot_exists, because ledger rows pin the old hash.
+ */
+export function writeSnapshot(sourcesDir, sourceId, input) {
+	checkInput(sourceId, input)
+	const text = snapshotText(input)
+	const sha256 = sha256Of(Buffer.from(text, "utf8"))
+	const dir = join(sourcesDir, sourceId)
+	const textPath = join(dir, "text.txt")
+	if (existsSync(textPath) && sha256Of(readFileSync(textPath)) !== sha256) {
+		throw new Error(`snapshot_exists: ${sourceId} already holds a different text.txt`)
+	}
+	mkdirSync(dir, { recursive: true })
+	writeFileSync(textPath, text)
+	if (typeof input.html === "string") writeFileSync(join(dir, "source.html"), input.html)
+	const meta = {
+		source_id: sourceId,
+		url: input.url ?? input.path,
+		observed_at: input.observed_at ?? new Date().toISOString(),
+		sha256,
+		extractor: input.extractor,
+		revision: input.revision ?? null,
+		kind: input.kind ?? (input.url !== undefined || typeof input.html === "string" ? "page" : "document"),
+		provenance: input.provenance ?? "unknown",
+	}
+	writeFileSync(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`)
+	const sentences = indexSentences(text, sourceId)
+	writeFileSync(join(dir, "sentences.jsonl"), sentences.map((row) => `${JSON.stringify(row)}\n`).join(""))
+	const acronyms = { schemaVersion: 1, source_id: sourceId, snapshot_sha256: sha256, entries: findAcronyms(text, sentences) }
+	writeFileSync(join(dir, "acronyms.json"), `${JSON.stringify(acronyms, null, 2)}\n`)
+	return { dir, sha256 }
+}

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

@@ -0,0 +1,113 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { createHash } from "node:crypto"
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { snapshotFromHtml, writeSnapshot } from "./source-snapshot.mjs"
+
+const FIXTURES = join(import.meta.dir, "tests", "fixtures", "fidelity", "sources")
+const S4_HTML = readFileSync(join(FIXTURES, "S4.html"), "utf8")
+const S9_TEXT = readFileSync(join(FIXTURES, "S9.txt"), "utf8")
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "ulw-snapshot-"))
+	onTestFinished(() => rmSync(dir, { recursive: true, force: true }))
+	return dir
+}
+
+type Sentence = { sid: string; start: number; end: number; text: string }
+
+function readSentences(dir: string): Sentence[] {
+	return readFileSync(join(dir, "sentences.jsonl"), "utf8")
+		.split("\n")
+		.filter((line) => line !== "")
+		.map((line) => JSON.parse(line))
+}
+
+describe("snapshotFromHtml", () => {
+	test("#given a page with prose, a table, a script and a comment #when snapshotted #then blocks are lines and each table cell is its own line", () => {
+		const lines = snapshotFromHtml(S4_HTML).split("\n")
+		expect(lines).toContain("Span length: 320 m")
+		expect(lines).toContain("After the delay, we estimate completion no earlier than 2027.")
+		const header = lines.indexOf("Metric")
+		expect(lines.slice(header, header + 4)).toEqual(["Metric", "Length", "Span", "320 m"])
+		const text = lines.join("\n")
+		expect(text).not.toContain("not prose")
+		expect(text).not.toContain("internal draft comment")
+		expect(text).not.toContain("p { margin")
+	})
+})
+
+describe("writeSnapshot", () => {
+	test("#given html #when written #then text.txt, source.html, meta.json, sentences.jsonl and acronyms.json exist and sha256 covers text.txt", () => {
+		const sources = tempDir()
+		const result = writeSnapshot(sources, "S4", { url: "https://example.test/bridge", html: S4_HTML, extractor: "tool:source-snapshot@1", observed_at: "2026-10-23T00:00:00Z" })
+		expect(result.dir).toBe(join(sources, "S4"))
+		for (const name of ["text.txt", "source.html", "meta.json", "sentences.jsonl", "acronyms.json"]) expect(existsSync(join(result.dir, name))).toBe(true)
+		const text = readFileSync(join(result.dir, "text.txt"))
+		expect(result.sha256).toBe(createHash("sha256").update(text).digest("hex"))
+		expect(readFileSync(join(result.dir, "source.html"), "utf8")).toBe(S4_HTML)
+		const meta = JSON.parse(readFileSync(join(result.dir, "meta.json"), "utf8"))
+		expect(meta).toEqual({
+			source_id: "S4",
+			url: "https://example.test/bridge",
+			observed_at: "2026-10-23T00:00:00Z",
+			sha256: result.sha256,
+			extractor: "tool:source-snapshot@1",
+			revision: null,
+			kind: "page",
+			provenance: "unknown",
+		})
+	})
+
+	test("#given a written snapshot #when sentences.jsonl is read #then every row slices text.txt and carries an S<n>:s<k> id", () => {
+		const sources = tempDir()
+		const { dir } = writeSnapshot(sources, "S4", { url: "https://example.test/bridge", html: S4_HTML, extractor: "tool:source-snapshot@1" })
+		const text = readFileSync(join(dir, "text.txt"), "utf8")
+		const sentences = readSentences(dir)
+		expect(sentences.length).toBeGreaterThanOrEqual(4)
+		sentences.forEach((row, index) => {
+			expect(row.sid).toBe(`S4:s${index + 1}`)
+			expect(text.slice(row.start, row.end)).toBe(row.text)
+		})
+	})
+
+	test("#given both acronym forms #when written #then acronyms.json lists each expansion with its sentence and span", () => {
+		const sources = tempDir()
+		const text = "The deck uses High Bandwidth Memory (HBM) sensors.\nA second note cites TSV (Through Silicon Via) bonding."
+		const { dir, sha256 } = writeSnapshot(sources, "S2", { path: "notes/memo.txt", text, extractor: "model" })
+		const acronyms = JSON.parse(readFileSync(join(dir, "acronyms.json"), "utf8"))
+		expect(acronyms.source_id).toBe("S2")
+		expect(acronyms.snapshot_sha256).toBe(sha256)
+		const entries = acronyms.entries.map((entry: { acronym: string; expansion: string; sentence_id: string; span: number[] }) => [entry.acronym, entry.expansion, entry.sentence_id, text.slice(entry.span[0], entry.span[1])])
+		expect(entries).toEqual([
+			["HBM", "High Bandwidth Memory", "S2:s1", "High Bandwidth Memory (HBM)"],
+			["TSV", "Through Silicon Via", "S2:s2", "TSV (Through Silicon Via)"],
+		])
+		expect(JSON.parse(readFileSync(join(dir, "meta.json"), "utf8")).kind).toBe("document")
+		expect(existsSync(join(dir, "source.html"))).toBe(false)
+	})
+
+	test("#given pages #when written #then pages are joined by a form feed and no sentence crosses a page", () => {
+		const sources = tempDir()
+		const { dir } = writeSnapshot(sources, "S7", { path: "report.pdf", pages: ["First page ends here", "second page starts here."], extractor: "extractor:pdftotext" })
+		expect(readFileSync(join(dir, "text.txt"), "utf8")).toBe("First page ends here\fsecond page starts here.")
+		expect(readSentences(dir).map((row) => row.text)).toEqual(["First page ends here", "second page starts here."])
+	})
+
+	test("#given Korean text #when written #then the sentence index covers it", () => {
+		const sources = tempDir()
+		const { dir } = writeSnapshot(sources, "S9", { path: "S9.txt", text: S9_TEXT, extractor: "tool:source-snapshot@1" })
+		expect(readSentences(dir).map((row) => row.sid)).toEqual(["S9:s1"])
+	})
+
+	test("#given an invalid extractor, source id, or a different text over an existing snapshot #when written #then it throws", () => {
+		const sources = tempDir()
+		expect(() => writeSnapshot(sources, "S1", { path: "a.txt", text: "x", extractor: "guess" })).toThrow()
+		expect(() => writeSnapshot(sources, "source1", { path: "a.txt", text: "x", extractor: "model" })).toThrow()
+		writeSnapshot(sources, "S1", { path: "a.txt", text: "first", extractor: "model" })
+		expect(() => writeSnapshot(sources, "S1", { path: "a.txt", text: "first", extractor: "model" })).not.toThrow()
+		expect(() => writeSnapshot(sources, "S1", { path: "a.txt", text: "second", extractor: "model" })).toThrow(/snapshot_exists/)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/fidelity/assets/share.csv

@@ -0,0 +1,3 @@
+fact_id,plot_value,unit
+F5,12,%
+F6,27,%

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/fidelity/claim-graph.md

@@ -0,0 +1,13 @@
+# Claim graph
+
+## verified-claims
+
+- C1: The bridge span is up to 320 m.
+
+## Claims
+
+| claim_id | statement | claim type | risk tier | status | final synthesis location |
+|---|---|---|---|---|---|
+| C1 | The bridge span is up to 320 m. | factual | high | supported | findings |
+| C2 | Revenue grew about 10 percent in 2025. | factual | normal | partial | findings |
+| C3 | The project finished ahead of schedule. | factual | high | refuted | gaps |

package/packages/shared-skills/skills/ulw-research/scripts/tests/fixtures/fidelity/gen-legacy-dev.mjs

@@ -0,0 +1,89 @@
+// gen-legacy-dev.mjs - regenerates ledger-legacy-dev.json with dev's own pre-registry writer, so the
+// dimension 31 tests load every value shape dev could write, not hand-picked rows.
+// Pinned dev commit: 99220c4e95f9ef3a667834486f2caa03873deeab (origin/dev when the fixture was generated).
+// Usage: node gen-legacy-dev.mjs [dev-sha]. Needs git and the commit in the local clone; node: builtins only.
+
+import { execFileSync } from "node:child_process"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const DEV_SHA = process.argv[2] ?? "99220c4e95f9ef3a667834486f2caa03873deeab"
+const SCRIPTS = "packages/shared-skills/skills/ulw-research/scripts"
+// fact-ledger.mjs and every module it imports at the pinned commit.
+const WRITER_FILES = ["fact-ledger.mjs", "fact-ledger-kinds.mjs", "fact-ledger-schema.mjs", "cli-support.mjs", "entry-guard.mjs"]
+const HERE = dirname(fileURLToPath(import.meta.url))
+const OUT = join(HERE, "ledger-legacy-dev.json")
+
+const at = { artifact: "sources/S1/text.txt", line: 2, char_start: 0, char_end: 30 }
+const sha = "a".repeat(64)
+const base = { extracted_by: "fact add --find", observed_at: "2026-10-20T08:00:00Z" }
+
+function measured(label, value, unit) {
+	const raw = `${value} ${unit}`
+	return { ...base, kind: "measured", label, value, unit, raw, quote: `The figure is ${raw}.`, value_span: [14, 14 + value.length], source_id: "S1", locator: at, snapshot_sha256: sha }
+}
+
+function assumed(label, value, unit, exact) {
+	return { ...base, kind: "assumed", label, value, unit, exact, raw: "", quote: "", extracted_by: "fact add --assumed", rationale: "planning assumption from the brief" }
+}
+
+function legacy(kind, label, fields) {
+	return { ...base, kind, label, raw: "", quote: "", extracted_by: "fact derive", ...fields }
+}
+
+// Every kind and every value shape dev's addRow accepts: alias units (English and Korean count and
+// currency words, written as escapes so this file stays ASCII), leading zeros, negative values,
+// assumed rows with unreduced or zero-padded exacts, and a legacy derived and converted row. The
+// last three are shapes dev accepted that the strict dimensions do not (empty metadata, an operation
+// on a source row, an extra key in exact): they must load and be refused only as operands.
+const SEEDS = [
+	measured("north-span", "12", "kilometers"),
+	measured("south-span", "8.5", "kilometers"),
+	measured("share-online", "41.2", "per cent"),
+	measured("share-gap", "1.5", "pp"),
+	measured("staff-count", "320", "\uBA85"),
+	measured("unit-price", "750", "\uCC9C\uC6D0"),
+	measured("padded-span", "007", "km"),
+	measured("net-change", "-2.5", "per cent"),
+	{ ...base, kind: "quote", label: "quote-claim", raw: "grew fast", quote: "The market grew fast.", value_span: [11, 20], source_id: "S1", locator: at, snapshot_sha256: sha },
+	assumed("growth-assumption", "3", "%", null),
+	assumed("whole-ratio", "1", "%", { num: "2", den: "2" }),
+	assumed("quarter-ratio", "2.5", "kilometers", { num: "10", den: "4" }),
+	assumed("padded-exact", "7", "km", { num: "007", den: "01" }),
+	assumed("negative-exact", "-2.5", "per cent", { num: "-10", den: "04" }),
+	legacy("derived", "total-span", { value: "20.5", unit: "kilometers", exact: { num: "82", den: "4" }, operation: "sum", operands: ["F1", "F2"], derived_from: ["F1", "F2"], formula: "F1 + F2" }),
+	legacy("converted", "span-metres", { value: "12000", unit: "m", exact: { num: "24000", den: "2" }, operation: "convert", operands: ["F1"], derived_from: ["F1"], formula: "F1 * 1000", factor: "1000" }),
+	{ ...measured("blank-entity", "5", "km"), entity: "" },
+	{ ...measured("tagged-sum", "6", "km"), operation: "sum" },
+	assumed("keyed-exact", "3", "km", { num: "3", den: "1", note: "from the brief" }),
+]
+
+/** JSON with every non-ASCII character as a \u escape, tab-indented like the other fixtures. */
+function asciiJson(value) {
+	return `${JSON.stringify(value, null, "\t").replace(/[\u0080-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`)}\n`
+}
+
+async function main() {
+	const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: HERE, encoding: "utf8" }).trim()
+	const work = mkdtempSync(join(tmpdir(), "gen-legacy-dev-"))
+	try {
+		mkdirSync(join(work, "scripts"))
+		for (const file of WRITER_FILES) {
+			const source = execFileSync("git", ["show", `${DEV_SHA}:${SCRIPTS}/${file}`], { cwd: root, encoding: "utf8" })
+			writeFileSync(join(work, "scripts", file), source)
+		}
+		const dev = await import(pathToFileURL(join(work, "scripts", "fact-ledger.mjs")).href)
+		const ledger = dev.emptyLedger()
+		for (const seed of SEEDS) dev.addRow(ledger, seed)
+		const errors = dev.validateLedger(ledger)
+		if (errors.length > 0) throw new Error(`dev's validateLedger rejected the generated ledger: ${errors.join("; ")}`)
+		writeFileSync(OUT, asciiJson(ledger))
+		process.stdout.write(`wrote ${OUT} (${ledger.rows.length} rows, dev ${DEV_SHA})\n`)
+	} finally {
+		rmSync(work, { recursive: true, force: true })
+	}
+}
+
+await main()