lazycodex-ai 5.1.48 → 5.1.54

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

@@ -8,10 +8,12 @@
 // escaped HTML projection (same line numbers) and checked with its fill map, which is the only
 // record of where its values sit; LaTeX is verified through its Markdown source.
 //
-// The locked brief is re-judged here, not only at fill: the edition's fill map (--fill-map, else
-// `<report>.fill-map.json` when present) must carry the current brief's brief_sha256
-// (brief_changed), and policyErrors re-runs over every data-fact the edition carries, so an
-// edition that violates the current derived-numbers or source-floor rule fails here too.
+// The locked brief is re-judged here, not only at fill: every edition (HTML or Markdown) needs its
+// fill map (fillMapOf: --fill-map, else whichever of `<report>.fill-map.json` and the
+// `<report>.polished.fill-map.json` polish-apply writes records the edition's bytes), and that map
+// must carry the current brief's brief_sha256; no map, or another hash, is brief_changed. policyErrors
+// re-runs over every data-fact the edition carries, so an edition that violates the current
+// derived-numbers or source-floor rule fails here too.
 //
 // The delivery barrier that reads these records (and every other fidelity record) is
 // fidelity-records.mjs.
@@ -66,8 +68,8 @@ function entryHtml(text, entry, rows) {
 	if (entry.translates) return `<span data-translates="${escapeHtml(entry.translates)}">${projectMarkdownInline(body.replace(/^<!--[\s\S]*?-->\s*/u, ""))}</span>`
 	if (!row) return `<data data-fact="${escapeHtml(entry.fact_id)}">${escapeHtml(body)}</data>`
 	const quoted = row.kind === "quote" ? parseRenderedQuote(body) : null
-	if (quoted) return renderQuote(row, entry.selector ?? "full", quoted.text, "html")
-	return row.kind === "quote" ? null : renderValueHtml(row, body)
+	if (quoted) return renderQuote(row, entry.selector ?? "full", quoted.text, "html", entry.claimKind)
+	return row.kind === "quote" ? null : renderValueHtml(row, body, { mode: entry.mode, claimKind: entry.claimKind ?? null })
 }
 
 /** [from, to) of the filled text as HTML, each intact fill-map entry rebuilt as its fill element. */
@@ -149,6 +151,17 @@ const MARKDOWN_EXTENSION = /\.(md|markdown)$/iu
 /** The edition format: the explicit flag, else md for a .md or .markdown path (any case), else html. */
 export const editionFormatOf = (path, flag) => flag ?? (MARKDOWN_EXTENSION.test(path) ? "md" : "html")
 
+/**
+ * An edition's fill map path: --fill-map, else whichever of fact fill's `<report>.fill-map.json` and
+ * polish-apply's `<report>.polished.fill-map.json` records these bytes as its artifact_sha256, else the
+ * first of them that exists; null when neither exists.
+ */
+export function fillMapOf(report, text, flag) {
+	if (flag !== undefined) return flag
+	const found = [`${report}.fill-map.json`, `${report}.polished.fill-map.json`].filter((path) => existsSync(path))
+	return found.find((path) => readJsonFile(path).artifact_sha256 === sha256Of(text)) ?? found[0] ?? null
+}
+
 /** The report's format (from --format or its extension) and, for Markdown, its fill map entries. */
 export function readEdition(report, flags) {
 	const format = editionFormatOf(report, flags.format)
@@ -174,19 +187,23 @@ export function runFactVerify(args) {
 	const briefPath = flags.brief ?? join(sessionDir, "brief.md")
 	const ledger = readLedger(sessionDir)
 	const projected = edition.format === "md" ? markdownAsHtml(edition.text, edition.entries, ledger) : null
+	// The entries whose element is in the checked HTML: an HTML edition's own map, or the projection's intact entries.
+	const ownMap = flags["fill-map"] ?? `${report}.fill-map.json`
+	const fillEntries = projected ? edition.entries.filter((entry) => !projected.stale.includes(entry)) : existsSync(ownMap) ? readJsonFile(ownMap).entries : null
 	const result = checkFidelity(projected?.html ?? edition.text, {
 		ledger,
 		sourcesDir: resolve(flags.sources ?? join(sessionDir, "sources")),
 		claims: flags.claims !== undefined || existsSync(claimsPath) ? readJsonFile(claimsPath) : null,
 		fillMap: projected?.stale ?? edition.entries,
+		fillEntries,
 		brief: existsSync(briefPath) ? readText(briefPath) : "",
 		baseDir: dirname(resolve(report)),
 		recompute,
 	})
 	const checked = projected?.html ?? edition.text
 	const pointers = [...checked.matchAll(/\bdata-fact="([^"]+)"/gu)].map((match) => ({ token: match[0], start: match.index, parsed: { id: match[1] } }))
-	const mapPath = flags["fill-map"] ?? `${report}.fill-map.json`
-	const bound = existsSync(mapPath) ? briefBindingErrors(readJsonFile(mapPath), mapPath, parsed) : []
+	const mapPath = fillMapOf(report, edition.text, flags["fill-map"])
+	const bound = briefBindingErrors(mapPath === null ? null : readJsonFile(mapPath), mapPath ?? `${report}.fill-map.json`, parsed)
 	const defects = [...bound, ...policyErrors(checked, pointers, ledger, sessionDir, policy).errors, ...result.defects]
 	const counts = countDefects(defects)
 	const status = defects.some(blocksDelivery) ? "fail" : "pass"

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

@@ -10,11 +10,14 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join, resolve } from "node:path"
 
 import { CliError, parseArgs, sha256Of } from "./cli-support.mjs"
+import { DEFECT_CODES } from "./contracts.mjs"
+import { alteredIn } from "./conversion-probe.mjs"
 import { derive } from "./fact-derive.mjs"
 import { addRow, readLedger, retractRow, supersedeRow, writeLedger } from "./fact-ledger.mjs"
 import { locateFind, locateMatch, locatePageLine, locateTable } from "./fact-locate.mjs"
 import { QUALIFIER_FORMS } from "./fidelity-lexicon.mjs"
 import { exportRows } from "./fidelity-values.mjs"
+import { rawLocated } from "./raw-locator.mjs"
 import { pointedFlag, sessionDirOf, snapshotOf } from "./source-commands.mjs"
 
 const CONTEXT = 60
@@ -30,26 +33,30 @@ function readText(path) {
 	}
 }
 
-function nowIso(flags) {
-	const date = flags.now === undefined ? new Date() : new Date(flags.now)
+/** A caller-supplied --now value as ISO; parsing only, never the clock. */
+function isoOf(text) {
+	const date = new Date(text)
 	if (Number.isNaN(date.getTime())) throw new CliError("--now requires an ISO timestamp")
 	return date.toISOString()
 }
 
+const nowIso = (flags) => (flags.now === undefined ? new Date().toISOString() : isoOf(flags.now))
+
 function failure(command, error, detail) {
 	const json = { command, status: "fail", exitCode: 1, error, ...detail }
 	return { json, summary: `${command}: ${error}${detail.message ? ` (${detail.message})` : ""}`, exitCode: 1 }
 }
 
-function locate(flags, snapshot, id, quote) {
+/** Every locator reads the view text (visible text nodes for a page), never raw markup. */
+function locate(flags, view, id, quote) {
 	const sourceId = id
-	if (quote) return locateMatch(snapshot.text, { match: flags.match, sourceId })
-	if (flags.find !== undefined) return locateFind(snapshot.text, { find: flags.find, unitExpected: flags["unit-expected"], sourceId })
+	if (quote) return locateMatch(view.text, { match: flags.match, sourceId })
+	if (flags.find !== undefined) return locateFind(view.text, { find: flags.find, unitExpected: flags["unit-expected"], sourceId })
 	if (flags.table !== undefined) {
-		if (snapshot.html === null) throw new CliError(`source ${id} has no source.html; --table needs a page snapshot`)
-		return locateTable(snapshot.html, { table: flags.table, row: flags.row, col: flags.col, sourceId })
+		if (view.root === null) throw new CliError(`source ${id} is not an HTML page snapshot; --table needs one`)
+		return locateTable(view, { table: flags.table, row: flags.row, col: flags.col, sourceId })
 	}
-	if (flags.page !== undefined) return locatePageLine(snapshot.text, { page: Number(flags.page), line: Number(flags.line), sourceId })
+	if (flags.page !== undefined) return locatePageLine(view.text, { page: Number(flags.page), line: Number(flags.line), sourceId })
 	throw new CliError("usage: fact add --source S<n> (--find TEXT | --table T --row R --col C | --page P --line L) --label LABEL")
 }
 
@@ -76,11 +83,17 @@ function runAdd(args, quote) {
 	const id = args.required("source")
 	if (quote) args.required("match")
 	const sessionDir = sessionDirOf(flags)
-	const snapshot = snapshotOf(sessionDir, id)
-	const found = locate(flags, snapshot, id, quote)
+	const { meta, view, sha256, drift } = snapshotOf(sessionDir, id)
+	const converted = view.mode === "converted"
+	if (drift.length > 0) return failure(command, "snapshot_hash_mismatch", { message: `${id}: ${drift.join("; ")}` })
+	if (view.mode === "legacy") return failure(command, "snapshot_not_raw", { message: `${id} is a legacy text.txt snapshot without raw.bin; snapshot the source again under a new id` })
+	if (converted && !quote) return failure(command, "snapshot_not_raw", { message: `${id} is converted-only (no raw bytes); measured rows need source snapshot --raw <original> --text <extraction>` })
+	const located = locate(flags, view, id, quote)
+	const found = rawLocated(view, located)
 	if (found.error === "unit_expected_mismatch") return failure(command, "unit_mismatch", { message: `expected ${found.expected}, found ${found.found}`, candidates: found.candidates })
 	if (found.error) return failure(command, found.error, { message: `no single match in ${id}`, candidates: found.candidates })
-	const { meta } = snapshot
+	const altered = alteredIn(join(sessionDir, "sources", id), [found.raw, found.quote])
+	if (altered.length > 0) return failure(command, "conversion_altered_number", { message: `${id}'s conversion altered ${[...new Set(altered)].join(", ")} (sources/${id}/conversion.json); the converted text cannot back this number, even where the source also shows it unaltered: write a verified text of the source and run \`source snapshot --id ${id} --text <verified.txt> --replace\`, then add the fact again`, tokens: altered, hint: DEFECT_CODES.conversion_altered_number.hint })
 	const host = URL.canParse(meta.url) ? new URL(meta.url).hostname : null
 	const labelSource = flags.find ?? flags.match ?? (flags.table !== undefined ? `${flags.row}_${flags.col}` : `p${flags.page}_l${flags.line}`)
 	const ledger = readLedger(sessionDir)
@@ -89,9 +102,10 @@ function runAdd(args, quote) {
 		...(quote ? {} : { value: found.value, unit: found.unit, value_span: found.value_span, qualifier: QUALIFIER_OF.get(found.qualifier) ?? null }),
 		raw: found.raw,
 		quote: found.quote,
+		context: found.context,
 		source_id: id,
 		locator: { ...found.locator, source_kind: meta.kind, url: meta.url, host, pointed: pointedFlag(sessionDir, meta.url) },
-		snapshot_sha256: meta.sha256,
+		snapshot_sha256: sha256,
 		sentence_id: found.sentence_id ?? null,
 		extracted_by: meta.extractor,
 		observed_at: nowIso(flags),
@@ -104,11 +118,14 @@ function runAdd(args, quote) {
 		fuzzy: found.fuzzy === true,
 	})
 	writeLedger(sessionDir, ledger)
-	const context = contextOf(snapshot.text, row)
-	const json = { command, status: "pass", exitCode: 0, defects: [], data: { row, context } }
+	const context = contextOf(view.text, located)
+	const { severity, integrity } = DEFECT_CODES.quote_converted_only
+	const defects = converted ? [{ code: "quote_converted_only", severity, integrity, message: `${id} is converted-only; the quote is not bound to the original fetched bytes` }] : []
+	const json = { command, status: "pass", exitCode: 0, defects, data: { row, context } }
 	if (flags.json) return { json, exitCode: 0 }
 	const shown = quote ? row.quote : `${row.raw} (value ${row.value}${row.unit ? `, unit ${row.unit}` : ""})`
-	return { text: `${row.fact_id} ${row.label}: ${shown} [${id} ${row.sentence_id ?? "-"}]\n  ...${context.before}[${context.match}]${context.after}...`, exitCode: 0 }
+	const warnings = defects.map((defect) => `\n  warning ${defect.code}: ${defect.message}`).join("")
+	return { text: `${row.fact_id} ${row.label}: ${shown} [${id} ${row.sentence_id ?? "-"}]\n  ...${context.before}[${context.match}]${context.after}...${warnings}`, exitCode: 0 }
 }
 
 function runRetract(args) {
@@ -157,11 +174,13 @@ function runExport(args) {
 function runDerive(args) {
 	const { flags } = args
 	const op = args.required("op")
+	// Time is the caller's: without --now the CLI refuses with the library's missing_now code (exit 2) and never reads the clock.
+	if (flags.now === undefined) throw new CliError("missing_now: fact derive needs --now <ISO timestamp> (the row's observed_at); no row written")
 	const sessionDir = sessionDirOf(flags)
 	const ledger = readLedger(sessionDir)
 	// The registry refuses any field outside the operation's inputFields, so only the given flags go in; --unit null declares a dimensionless result.
 	const picked = ["to", "from", "num", "den", "part", "whole", "reference", "rationale", "label"].filter((key) => flags[key] !== undefined)
-	const spec = { op, now: nowIso(flags), ...Object.fromEntries(picked.map((key) => [key, flags[key]])) }
+	const spec = { op, now: isoOf(flags.now), ...Object.fromEntries(picked.map((key) => [key, flags[key]])) }
 	if (op === "expr") spec.formula = args.positionals[0]
 	else if (args.positionals.length > 0) spec.operands = args.positionals
 	if (flags.disjoint === true) spec.disjoint = true

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

@@ -0,0 +1,149 @@
+import { describe, expect, onTestFinished, test } from "bun:test"
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { recompute } from "./fact-derive.mjs"
+import { derive } from "./tests/derive-clock"
+import { addRow, emptyLedger, readLedger, writeLedger } from "./fact-ledger.mjs"
+import { HASH, EOK_WON, Row, Ledger, measured, ledgerOf, fixture, rowOf } from "./tests/fact-derive-support"
+
+
+
+describe("unit rules: the design review's counterexamples", () => {
+	const book = () =>
+		ledgerOf([
+			measured("F1", "20", "%"),
+			measured("F2", "10", "%"),
+			measured("F3", "5", "pp"),
+			measured("F4", "25", "C", { valid_at: "2025", entity: "x" }),
+			measured("F5", "30", "C", { valid_at: "2026", entity: "x" }),
+			measured("F6", "200", "person"),
+			measured("F7", "100", "person"),
+			measured("F8", "100", "USD"),
+			measured("F9", "20", "USD/person"),
+			measured("F10", "0", "m"),
+		])
+
+	test("a sum of % operands without one shared reference is refused", () => {
+		const ledger = book()
+		const base = { op: "sum", operands: ["F1", "F2"], unit: "%", disjoint: true, rationale: "disjoint shares" }
+		expect(derive(ledger, base).error).toBe("incompatible_operands")
+		expect(derive(ledger, { ...base, reference: { F1: "voters", F2: "residents" } }).error).toBe("incompatible_operands")
+		expect(rowOf(derive(ledger, { ...base, reference: { F1: "voters", F2: "voters" } }))).toMatchObject({ value: "30", unit: "%" })
+	})
+
+	test("20% - 5pp is 15%", () => {
+		const row = rowOf(derive(book(), { op: "diff", operands: ["F1", "F3"], unit: "%" }))
+		expect(row).toMatchObject({ value: "15", unit: "%", render: "15%" })
+	})
+
+	test("growth on a Celsius scale is refused", () => {
+		const result = derive(book(), { op: "growth", from: "F4", to: "F5", unit: "%" })
+		expect(result.error).toBe("incompatible_operands")
+		expect(result.detail).toContain("affine")
+	})
+
+	test("temperatures are not summed or differenced as absolute values; ratio refuses them; convert C to F is allowed", () => {
+		const ledger = book()
+		const refused = [
+			{ op: "sum", operands: ["F4", "F5"], unit: "C" },
+			{ op: "diff", operands: ["F5", "F4"], unit: "C" },
+			{ op: "expr", formula: "F4 + F5", unit: "C" },
+			{ op: "expr", formula: "F5 - F4", unit: "C" },
+			{ op: "ratio", num: "F5", den: "F4", unit: null },
+		]
+		for (const spec of refused) {
+			const result = derive(ledger, spec)
+			expect({ spec, error: result.error, detail: result.detail }).toEqual({ spec, error: "incompatible_operands", detail: expect.stringContaining("affine") })
+		}
+		const converted = rowOf(derive(ledger, { op: "convert", operands: ["F4"], to: "F" }))
+		expect(converted).toMatchObject({ value: "77", unit: "F" })
+		expect(recompute(ledger, converted).ok).toBe(true)
+	})
+
+	test("a convert row relabeled to an alias in both unit and context.target is detected", () => {
+		const ledger = book()
+		const row = rowOf(derive(ledger, { op: "convert", operands: ["F10"], to: "km" }))
+		const relabeled = recompute(ledger, { ...row, unit: "kilometre", raw: "0 kilometre (0 m)", render: "0 kilometre (0 m)", context: { target: "kilometre" } })
+		expect(relabeled.ok).toBe(false)
+		expect(relabeled.detail).toContain('context.target "kilometre" is not canonical')
+	})
+
+	test("a share of 200 out of 100 is refused", () => {
+		expect(derive(book(), { op: "share", part: "F6", whole: "F7", unit: "%" }).error).toBe("incompatible_operands")
+	})
+
+	test("100 USD / (20 USD/person) is 5 person", () => {
+		const ledger = book()
+		const row = rowOf(derive(ledger, { op: "ratio", num: "F8", den: "F9", unit: "person" }))
+		expect(row).toMatchObject({ value: "5", unit: "person", exact: { num: "5", den: "1" } })
+		expect(recompute(ledger, row).ok).toBe(true)
+	})
+
+	test("convert 0 m to km relabeled cm is detected though the value is unchanged", () => {
+		const ledger = book()
+		const row = rowOf(derive(ledger, { op: "convert", operands: ["F10"], to: "km" }))
+		expect(recompute(ledger, row).ok).toBe(true)
+		const relabeled = recompute(ledger, { ...row, unit: "cm", raw: "0 cm (0 m)", render: "0 cm (0 m)" })
+		expect(relabeled.ok).toBe(false)
+		expect(relabeled.detail).toContain("km")
+	})
+
+	test("expr % + %p is %, in either order; a ratio over unequal % and %p is refused", () => {
+		const ledger = book()
+		for (const formula of ["F1 + F3", "F3 + F1"]) {
+			const row = rowOf(derive(ledger, { op: "expr", formula, unit: "%" }))
+			expect(row).toMatchObject({ value: "25", unit: "%" })
+			expect(recompute(ledger, row).ok).toBe(true)
+		}
+		const ratio = derive(ledger, { op: "ratio", num: "F1", den: "F3", unit: null })
+		expect(ratio.error).toBe("incompatible_operands")
+		expect(ratio.detail).toContain("needs equal units")
+	})
+
+	test("a stored context on an operation that has none is malformed", () => {
+		const ledger = book()
+		const diff = rowOf(derive(ledger, { op: "diff", operands: ["F1", "F2"], unit: "%p" }))
+		const expr = rowOf(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%p" }))
+		for (const [row, context] of [[diff, "x"], [expr, { target: "km" }]] as const) {
+			const result = recompute(ledger, { ...row, context })
+			expect(result.ok).toBe(false)
+			expect(result.detail).toContain("rows carry no context")
+		}
+	})
+
+	test("expr 20% - 10% is %p, never %", () => {
+		const ledger = book()
+		expect(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%" }).error).toBe("incompatible_operands")
+		const row = rowOf(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%p" }))
+		expect(row).toMatchObject({ value: "10", unit: "%p" })
+		expect(recompute(ledger, row).ok).toBe(true)
+	})
+})
+
+describe("render precision of expr results (invariant 5)", () => {
+	const book = () => ledgerOf([measured("F1", "20.25", "%"), measured("F2", "15.5", "%"), measured("F3", "1000", "m"), measured("F4", "3", "m"), measured("F5", "12.34", "m")])
+
+	test("an expr difference giving %p renders by decimal places, as diff does", () => {
+		const ledger = book()
+		const viaDiff = rowOf(derive(ledger, { op: "diff", operands: ["F1", "F2"], unit: "%p" }))
+		const viaExpr = rowOf(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%p" }))
+		expect(viaDiff).toMatchObject({ value: "4.8", render: "4.8 %p" })
+		expect(viaExpr).toMatchObject({ value: "4.8", render: "4.8 %p" })
+		expect(recompute(ledger, viaExpr).ok).toBe(true)
+	})
+
+	test("an expr with a - root renders 1000 m - 3 m as 997 m", () => {
+		const ledger = book()
+		const row = rowOf(derive(ledger, { op: "expr", formula: "F3 - F4", unit: "m" }))
+		expect(row).toMatchObject({ value: "997", render: "997 m", exact: { num: "997", den: "1" } })
+		expect(recompute(ledger, row).ok).toBe(true)
+	})
+
+	test("an expr with a * root keeps significant figures", () => {
+		const ledger = book()
+		const row = rowOf(derive(ledger, { op: "expr", formula: "F5 * 1.5", unit: "m" }))
+		expect(row).toMatchObject({ value: "19", render: "19 m" })
+		expect(recompute(ledger, row).ok).toBe(true)
+	})
+})

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

@@ -3,7 +3,7 @@ import { leaves, parseExpr } from "./fact-expr.mjs"
 import { readRow } from "./fact-ledger-kinds.mjs"
 import { addRow, nextId, validateLedger } from "./fact-ledger.mjs"
 import { recompute, verifyGraph } from "./fact-recompute.mjs"
-import { canonicalUnit, inputScale, refuse } from "./unit-algebra.mjs"
+import { canonicalUnit, inputScale, refuse, RuleError } from "./unit-algebra.mjs"
 import { refusal } from "./unit-errors.mjs"
 import { object, sameDeclared } from "./unit-metadata.mjs"
 import { display, renderValue, resultPrecision, toText } from "./unit-precision.mjs"
@@ -29,7 +29,11 @@ function declaredUnit(spec, rule) {
 	return canonicalUnit(declared)
 }
 
+/** Refused before any work, under its own code: time is the caller's (spec.now), never the clock. */
+const MISSING_NOW = Object.freeze({ error: "missing_now", shape: "missing_now", expected: "an ISO timestamp in spec.now", detail: "derive needs a caller-supplied now timestamp" })
+
 export function derive(ledger, spec) {
+	if (object(spec) && typeof spec.now !== "string") return { ...MISSING_NOW }
 	try {
 		if (!object(spec)) refuse("spec must be an object")
 		const errors = validateLedger(ledger)
@@ -54,13 +58,14 @@ export function derive(ledger, spec) {
 		const result = compute(spec.op, rows, expected, ast, context, spec.formula)
 		const row = addRow(ledger, {
 			kind: rule.kind, unit: expected, quote: "", extracted_by: "fact-derive",
-			observed_at: spec.now ?? new Date().toISOString(),
+			observed_at: spec.now,
 			label: spec.label ?? `${spec.op}-${nextId(ledger, rule.kind).toLowerCase()}`,
 			...result, operation: spec.op, operands: ids, derived_from: ids,
 			rationale: spec.rationale ?? null, context,
 		})
 		return { row, compatibility: rule.compatibility }
 	} catch (error) {
+		if (!(error instanceof RuleError)) throw error
 		return { error: "incompatible_operands", ...refusal(error) }
 	}
 }

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

@@ -2,58 +2,12 @@ import { describe, expect, onTestFinished, test } from "bun:test"
 import { mkdtempSync, rmSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
-
-import { derive, recompute } from "./fact-derive.mjs"
+import { recompute } from "./fact-derive.mjs"
+import { derive } from "./tests/derive-clock"
 import { addRow, emptyLedger, readLedger, writeLedger } from "./fact-ledger.mjs"
+import { HASH, EOK_WON, Row, Ledger, measured, ledgerOf, fixture, rowOf } from "./tests/fact-derive-support"
 
-const HASH = "a".repeat(64)
-const EOK_WON = "\uC5B5\uC6D0"
-
-type Row = Record<string, unknown>
-type Ledger = { schemaVersion: number; rows: Row[]; events: unknown[] }
-
-function measured(factId: string, value: string, unit: string, extra: Row = {}): Row {
-	return {
-		fact_id: factId,
-		kind: "measured",
-		value,
-		unit,
-		raw: `${value} ${unit}`,
-		quote: `The figure is ${value} ${unit}.`,
-		source_id: "S1",
-		locator: { artifact: "sources/S1/text.txt", char_start: 0, char_end: 20 },
-		snapshot_sha256: HASH,
-		extracted_by: "fact add --find",
-		observed_at: "2026-10-23T08:00:00Z",
-		label: factId.toLowerCase(),
-		...extra,
-	}
-}
-
-function ledgerOf(rows: Row[]): Ledger {
-	const ledger = emptyLedger() as Ledger
-	for (const row of rows) addRow(ledger, row)
-	return ledger
-}
 
-function fixture(): Ledger {
-	return ledgerOf([
-		measured("F5", "100", EOK_WON, { population: "all" }),
-		measured("F6", "200", EOK_WON, { population: "all" }),
-		measured("F7", "200", EOK_WON, { population: "subset" }),
-		measured("F8", "15", "%"),
-		measured("F9", "20", "%"),
-		measured("F12", "320", "m"),
-		measured("F19", "100", "case", { valid_at: "2025-Q3", entity: "acme" }),
-		measured("F20", "112", "case", { valid_at: "2026-Q3", entity: "acme" }),
-		measured("F30", "3.2", "m"),
-	])
-}
-
-function rowOf(result: { row?: Row; error?: string; detail?: string }): Row {
-	if (!result.row) throw new Error(`expected a row, got ${result.error}: ${result.detail}`)
-	return result.row
-}
 
 describe("derive: checked operations", () => {
 	test("sum of compatible rows stores the exact sum and appends a derived row", () => {
@@ -99,7 +53,7 @@ describe("derive: checked operations", () => {
 
 	test("an unknown or missing operand is refused", () => {
 		const ledger = fixture()
-		expect(derive(ledger, { op: "sum", operands: ["F5", "F99"], unit: EOK_WON }).error).toBeDefined()
+		expect(derive(ledger, { op: "sum", operands: ["F5", "F99"], unit: EOK_WON }).error).toBe("incompatible_operands")
 		expect(ledger.rows).toHaveLength(9)
 	})
 })
@@ -158,8 +112,8 @@ describe("derive: expr and exact chaining", () => {
 	// unit-rules.md: expr units are inferred with no rationale escape, and an omitted unit is an error, not null.
 	test("expr needs a declared unit that follows from its operands", () => {
 		const ledger = fixture()
-		expect(derive(ledger, { op: "expr", formula: "F12 / F30", rationale: "span over sample length" }).error).toBeDefined()
-		expect(derive(ledger, { op: "expr", formula: "F12 / F30", unit: "m" }).error).toBeDefined()
+		expect(derive(ledger, { op: "expr", formula: "F12 / F30", rationale: "span over sample length" }).error).toBe("incompatible_operands")
+		expect(derive(ledger, { op: "expr", formula: "F12 / F30", unit: "m" }).error).toBe("incompatible_operands")
 		const result = derive(ledger, { op: "expr", formula: "F12 / F30", unit: null })
 		expect(result.compatibility).toBe("unchecked")
 		expect(rowOf(result)).toMatchObject({ value: "100", formula: "F12 / F30", operands: ["F12", "F30"] })
@@ -168,7 +122,7 @@ describe("derive: expr and exact chaining", () => {
 	test("expr refuses unsupported tokens and absent ids", () => {
 		const ledger = fixture()
 		for (const formula of ["F12 ** 2", "Math.max(F12)", "F12 / F404", "F12 / 0", "(F12"]) {
-			expect(derive(ledger, { op: "expr", formula, unit: null }).error).toBeDefined()
+			expect(derive(ledger, { op: "expr", formula, unit: null }).error).toBe("incompatible_operands")
 		}
 		expect(ledger.rows).toHaveLength(9)
 	})
@@ -234,142 +188,3 @@ describe("recompute", () => {
 		expect(result.detail).toContain("F2")
 	})
 })
-
-describe("unit rules: the design review's counterexamples", () => {
-	const book = () =>
-		ledgerOf([
-			measured("F1", "20", "%"),
-			measured("F2", "10", "%"),
-			measured("F3", "5", "pp"),
-			measured("F4", "25", "C", { valid_at: "2025", entity: "x" }),
-			measured("F5", "30", "C", { valid_at: "2026", entity: "x" }),
-			measured("F6", "200", "person"),
-			measured("F7", "100", "person"),
-			measured("F8", "100", "USD"),
-			measured("F9", "20", "USD/person"),
-			measured("F10", "0", "m"),
-		])
-
-	test("a sum of % operands without one shared reference is refused", () => {
-		const ledger = book()
-		const base = { op: "sum", operands: ["F1", "F2"], unit: "%", disjoint: true, rationale: "disjoint shares" }
-		expect(derive(ledger, base).error).toBe("incompatible_operands")
-		expect(derive(ledger, { ...base, reference: { F1: "voters", F2: "residents" } }).error).toBe("incompatible_operands")
-		expect(rowOf(derive(ledger, { ...base, reference: { F1: "voters", F2: "voters" } }))).toMatchObject({ value: "30", unit: "%" })
-	})
-
-	test("20% - 5pp is 15%", () => {
-		const row = rowOf(derive(book(), { op: "diff", operands: ["F1", "F3"], unit: "%" }))
-		expect(row).toMatchObject({ value: "15", unit: "%", render: "15%" })
-	})
-
-	test("growth on a Celsius scale is refused", () => {
-		const result = derive(book(), { op: "growth", from: "F4", to: "F5", unit: "%" })
-		expect(result.error).toBe("incompatible_operands")
-		expect(result.detail).toContain("affine")
-	})
-
-	test("temperatures are not summed or differenced as absolute values; ratio refuses them; convert C to F is allowed", () => {
-		const ledger = book()
-		const refused = [
-			{ op: "sum", operands: ["F4", "F5"], unit: "C" },
-			{ op: "diff", operands: ["F5", "F4"], unit: "C" },
-			{ op: "expr", formula: "F4 + F5", unit: "C" },
-			{ op: "expr", formula: "F5 - F4", unit: "C" },
-			{ op: "ratio", num: "F5", den: "F4", unit: null },
-		]
-		for (const spec of refused) {
-			const result = derive(ledger, spec)
-			expect({ spec, error: result.error, detail: result.detail }).toEqual({ spec, error: "incompatible_operands", detail: expect.stringContaining("affine") })
-		}
-		const converted = rowOf(derive(ledger, { op: "convert", operands: ["F4"], to: "F" }))
-		expect(converted).toMatchObject({ value: "77", unit: "F" })
-		expect(recompute(ledger, converted).ok).toBe(true)
-	})
-
-	test("a convert row relabeled to an alias in both unit and context.target is detected", () => {
-		const ledger = book()
-		const row = rowOf(derive(ledger, { op: "convert", operands: ["F10"], to: "km" }))
-		const relabeled = recompute(ledger, { ...row, unit: "kilometre", raw: "0 kilometre (0 m)", render: "0 kilometre (0 m)", context: { target: "kilometre" } })
-		expect(relabeled.ok).toBe(false)
-		expect(relabeled.detail).toContain('context.target "kilometre" is not canonical')
-	})
-
-	test("a share of 200 out of 100 is refused", () => {
-		expect(derive(book(), { op: "share", part: "F6", whole: "F7", unit: "%" }).error).toBe("incompatible_operands")
-	})
-
-	test("100 USD / (20 USD/person) is 5 person", () => {
-		const ledger = book()
-		const row = rowOf(derive(ledger, { op: "ratio", num: "F8", den: "F9", unit: "person" }))
-		expect(row).toMatchObject({ value: "5", unit: "person", exact: { num: "5", den: "1" } })
-		expect(recompute(ledger, row).ok).toBe(true)
-	})
-
-	test("convert 0 m to km relabeled cm is detected though the value is unchanged", () => {
-		const ledger = book()
-		const row = rowOf(derive(ledger, { op: "convert", operands: ["F10"], to: "km" }))
-		expect(recompute(ledger, row).ok).toBe(true)
-		const relabeled = recompute(ledger, { ...row, unit: "cm", raw: "0 cm (0 m)", render: "0 cm (0 m)" })
-		expect(relabeled.ok).toBe(false)
-		expect(relabeled.detail).toContain("km")
-	})
-
-	test("expr % + %p is %, in either order; a ratio over unequal % and %p is refused", () => {
-		const ledger = book()
-		for (const formula of ["F1 + F3", "F3 + F1"]) {
-			const row = rowOf(derive(ledger, { op: "expr", formula, unit: "%" }))
-			expect(row).toMatchObject({ value: "25", unit: "%" })
-			expect(recompute(ledger, row).ok).toBe(true)
-		}
-		const ratio = derive(ledger, { op: "ratio", num: "F1", den: "F3", unit: null })
-		expect(ratio.error).toBe("incompatible_operands")
-		expect(ratio.detail).toContain("needs equal units")
-	})
-
-	test("a stored context on an operation that has none is malformed", () => {
-		const ledger = book()
-		const diff = rowOf(derive(ledger, { op: "diff", operands: ["F1", "F2"], unit: "%p" }))
-		const expr = rowOf(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%p" }))
-		for (const [row, context] of [[diff, "x"], [expr, { target: "km" }]] as const) {
-			const result = recompute(ledger, { ...row, context })
-			expect(result.ok).toBe(false)
-			expect(result.detail).toContain("rows carry no context")
-		}
-	})
-
-	test("expr 20% - 10% is %p, never %", () => {
-		const ledger = book()
-		expect(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%" }).error).toBe("incompatible_operands")
-		const row = rowOf(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%p" }))
-		expect(row).toMatchObject({ value: "10", unit: "%p" })
-		expect(recompute(ledger, row).ok).toBe(true)
-	})
-})
-
-describe("render precision of expr results (invariant 5)", () => {
-	const book = () => ledgerOf([measured("F1", "20.25", "%"), measured("F2", "15.5", "%"), measured("F3", "1000", "m"), measured("F4", "3", "m"), measured("F5", "12.34", "m")])
-
-	test("an expr difference giving %p renders by decimal places, as diff does", () => {
-		const ledger = book()
-		const viaDiff = rowOf(derive(ledger, { op: "diff", operands: ["F1", "F2"], unit: "%p" }))
-		const viaExpr = rowOf(derive(ledger, { op: "expr", formula: "F1 - F2", unit: "%p" }))
-		expect(viaDiff).toMatchObject({ value: "4.8", render: "4.8 %p" })
-		expect(viaExpr).toMatchObject({ value: "4.8", render: "4.8 %p" })
-		expect(recompute(ledger, viaExpr).ok).toBe(true)
-	})
-
-	test("an expr with a - root renders 1000 m - 3 m as 997 m", () => {
-		const ledger = book()
-		const row = rowOf(derive(ledger, { op: "expr", formula: "F3 - F4", unit: "m" }))
-		expect(row).toMatchObject({ value: "997", render: "997 m", exact: { num: "997", den: "1" } })
-		expect(recompute(ledger, row).ok).toBe(true)
-	})
-
-	test("an expr with a * root keeps significant figures", () => {
-		const ledger = book()
-		const row = rowOf(derive(ledger, { op: "expr", formula: "F5 * 1.5", unit: "m" }))
-		expect(row).toMatchObject({ value: "19", render: "19 m" })
-		expect(recompute(ledger, row).ok).toBe(true)
-	})
-})