lazycodex-ai 5.1.44 → 5.1.46

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-derive.mjs

@@ -0,0 +1,66 @@
+// Public append boundary: dispatch through the operation table, verify transitive trust, append only on success.
+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 { refusal } from "./unit-errors.mjs"
+import { object, sameDeclared } from "./unit-metadata.mjs"
+import { display, renderValue, resultPrecision, toText } from "./unit-precision.mjs"
+import { expectedUnit, renderPrecision, ruleOf, unitMismatch } from "./unit-rules.mjs"
+export { recompute, display }
+
+/** Arithmetic and generated fields are chosen exclusively by the registry. */
+export function compute(op, rows, unit, ast, context, formula = null) {
+	const rule = ruleOf(op)
+	const out = rule.calculate(rows, context, ast, formula)
+	const mode = renderPrecision(op, unit, ast)
+	const precision = resultPrecision(rows, ast ? leaves(ast).literals : [], out.exact, mode)
+	const value = renderValue(out.exact, precision, mode)
+	const render = rule.render(display(value, unit), rows)
+	return { exact: toText(out.exact), value, render, raw: render, formula: out.formula, factor: out.factor, precision, compatibility: rule.compatibility, ...rule.metadataResult(rows) }
+}
+
+function declaredUnit(spec, rule) {
+	const own = Object.hasOwn(spec, "unit")
+	if ((!own && !rule.defaultUnit) || (own && spec.unit === undefined)) refuse("declare the result unit: pass unit (null for a dimensionless result)", undefined, "missing_unit", "an explicit unit or null")
+	const declared = own ? spec.unit : rule.defaultUnit(spec)
+	if (inputScale(declared)) refuse(`${declared} needs rescaling: declare %p and scale the value`)
+	return canonicalUnit(declared)
+}
+
+export function derive(ledger, spec) {
+	try {
+		if (!object(spec)) refuse("spec must be an object")
+		const errors = validateLedger(ledger)
+		if (errors.length) refuse(errors.join("; "), undefined, "ledger_schema", "a ledger conforming to KIND_RULES and canonical storage")
+		const rule = ruleOf(spec.op)
+		const allowed = ["op", "unit", "rationale", "label", "now", "context", ...rule.inputFields]
+		if (Object.keys(spec).some((key) => !allowed.includes(key))) refuse("spec carries fields outside its operation", undefined, "spec_fields", allowed)
+		const ast = rule.expression ? parseExpr(spec.formula) : null
+		const ids = rule.operandIds(spec, ast)
+		if (!Array.isArray(ids) || !ids.every((id) => typeof id === "string")) refuse(`${spec.op} needs its operand fact ids`, undefined, "operands", "an array of existing fact ids")
+		const verified = verifyGraph(ledger, ids, true)
+		if (!verified.ok) return { error: "incompatible_operands", ...verified }
+		const byId = new Map(ledger.rows.map((r) => [r.fact_id, r]))
+		const rows = ids.map((id) => readRow(byId.get(id)))
+		const context = rule.context(spec)
+		if (Object.hasOwn(spec, "context") && !sameDeclared(spec.context, context)) refuse("supplied context differs from the operation's input fields", undefined, "context", context ?? "explicit null")
+		const shape = rule.shape({ operation: spec.op, operands: ids, formula: spec.formula, context })
+		if (shape) refuse(shape, undefined, "context_or_formula", "the operation's declared context and matching formula operand set")
+		const expected = expectedUnit(spec.op, rows, { ast, context: { ...context, rationale: spec.rationale ?? null } })
+		const declared = declaredUnit(spec, rule)
+		if (declared !== expected) refuse(unitMismatch(spec.op, rows, declared, expected), undefined, "result_unit", { unit: expected })
+		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(),
+			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) {
+		return { error: "incompatible_operands", ...refusal(error) }
+	}
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-expr.mjs

@@ -0,0 +1,108 @@
+// fact-expr.mjs - the expression language of `fact derive --op expr` (references/unit-rules.md, expr row).
+// Leaves are fact ids and decimal literals; nodes are + - * / and pct(x), the explicit dimensionless-to-% node.
+// evaluate() is exact rational arithmetic. Under * and / a child whose inferred unit is % or %p enters as its
+// fraction (20% as 0.2): that unit comes from the registry's inference over the operand rows, never from the row's
+// own declared unit.
+
+import { add, div, fromDecimal, mul, sub } from "./rational.mjs"
+import { isPercentish, refuse } from "./unit-algebra.mjs"
+
+const TOKEN = /\s*(?:(F\d+)|(\d+(?:\.\d+)?)|(pct)\b|([-+*/()]))/y
+const HUNDRED = fromDecimal("100")
+
+function tokenize(formula) {
+	const text = String(formula ?? "")
+	const tokens = []
+	TOKEN.lastIndex = 0
+	while (/\S/.test(text.slice(TOKEN.lastIndex))) {
+		const at = TOKEN.lastIndex
+		const match = TOKEN.exec(text)
+		if (!match) refuse(`unsupported expression text at ${at}: "${text.slice(at).trim().slice(0, 16)}"`)
+		tokens.push(match[1] ? { id: match[1] } : match[2] ? { literal: match[2] } : match[3] ? { fn: "pct" } : { op: match[4] })
+	}
+	if (tokens.length === 0) refuse("expr needs an expression")
+	return tokens
+}
+
+/** Shunting-yard parser: parentheses and AST depth do not consume the JS call stack. */
+export function parseExpr(formula) {
+	if (typeof formula !== "string") refuse("expr needs an expression")
+	const tokens = tokenize(formula)
+	const values = []
+	const ops = []
+	const precedence = (op) => op === "*" || op === "/" ? 2 : 1
+	const reduce = () => {
+		const op = ops.pop()
+		if (op === "pct") values.push({ fn: op, arg: values.pop() })
+		else { const right = values.pop(); values.push({ op, left: values.pop(), right }) }
+	}
+	let need = true
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i]
+		if (need) {
+			if (token.id || token.literal) { values.push(token); need = false }
+			else if (token.fn) {
+				if (tokens[i + 1]?.op !== "(") refuse("pct needs a parenthesized argument")
+				ops.push("pct")
+			} else if (token.op === "(") ops.push("(")
+			else refuse(`unexpected "${token.op}" in the expression`)
+		} else if (token.op === ")") {
+			while (ops.length && ops.at(-1) !== "(") reduce()
+			if (ops.pop() !== "(") refuse("unexpected closing parenthesis")
+			if (ops.at(-1) === "pct") reduce()
+		} else if (["+", "-", "*", "/"].includes(token.op)) {
+			while (ops.length && ops.at(-1) !== "(" && precedence(ops.at(-1)) >= precedence(token.op)) reduce()
+			ops.push(token.op)
+			need = true
+		} else refuse("unexpected text after the expression")
+	}
+	if (need) refuse("the expression ends early")
+	if (ops.includes("(")) refuse("the expression is missing a closing parenthesis")
+	while (ops.length) reduce()
+	return values[0]
+}
+
+const childrenOf = (node) => (node.op ? [node.left, node.right] : node.fn ? [node.arg] : [])
+
+export function leaves(node, found = { ids: [], literals: [] }) {
+	const ids = new Set(found.ids)
+	const stack = [node]
+	while (stack.length) {
+		const current = stack.pop()
+		if (current.id) ids.add(current.id)
+		if (current.literal) found.literals.push(current.literal)
+		stack.push(...childrenOf(current).reverse())
+	}
+	found.ids = [...ids]
+	return found
+}
+
+export function postorder(node) {
+	const stack = [node]
+	const order = []
+	while (stack.length) { const current = stack.pop(); order.push(current); stack.push(...childrenOf(current)) }
+	return order.reverse()
+}
+
+/** Exact value of the tree; `units` maps each node to its inferred canonical unit (inferExpr in unit-rules.mjs). */
+export function evaluate(node, values, units) {
+	const results = new Map()
+	for (const current of postorder(node)) {
+		let value
+		if (current.id) value = values.get(current.id)
+		else if (current.literal) value = fromDecimal(current.literal)
+		else if (current.fn === "pct") value = mul(results.get(current.arg), HUNDRED)
+		else {
+			const operand = (child) => {
+				const v = results.get(child)
+				return (current.op === "*" || current.op === "/") && isPercentish(units.get(child)) ? div(v, HUNDRED) : v
+			}
+			const left = operand(current.left)
+			const right = operand(current.right)
+			if (current.op === "/" && right.num === 0n) refuse("the expression divides by zero", undefined, "divides_by_zero", "a nonzero denominator")
+			value = { "+": add, "-": sub, "*": mul, "/": div }[current.op](left, right)
+		}
+		results.set(current, value)
+	}
+	return results.get(node)
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-fill.mjs

@@ -0,0 +1,194 @@
+// fact-fill.mjs - the fill step: substitute every fact pointer in a report source from the
+// ledger, all or nothing. Fatal errors (pointer_label_mismatch, unresolved_placeholder,
+// quote_anchor_unresolved, unit_duplicated) return out null; warnings (particle_unverified,
+// fallback_without_entity) never block. A twice-failed sentence can be replaced by an attributed
+// block quote of its source row (replaceFailed). No IO, but not pure: unless options.view is set,
+// it records each replaced sentence in options.replaceFailed through markReplaced. node: builtins only.
+
+import { finalReading, rewriteParticle } from "./particles-ko.mjs"
+import { failureCount, markReplaced, sentenceKey } from "./fidelity-state.mjs"
+import { findPlaceholders, lead, qualifiedText, renderBlockquote, renderQuote, renderValueHtml, subSpan, valueParts } from "./placeholder.mjs"
+import { splitSentences } from "./sentence-split.mjs"
+
+const FORMATS = Object.freeze(["html", "md"])
+const TRANSLATION = Object.freeze({
+	html: /^\s*<span data-translates="(Q\d+)">[\s\S]*?<\/span>/u,
+	md: /^\s*<!-- translates: (Q\d+) -->[^\n]*/u,
+})
+const HEADING = Object.freeze({ html: /<h[1-6]\b([^>]*)>([\s\S]*?)<\/h[1-6]>/giu, md: /^#{1,6}[ \t]+(.+)$/gmu })
+
+const lineOf = (text, at) => text.slice(0, at).split("\n").length
+
+function resolveValue(row, parsed, format) {
+	const { valueText, unitText } = valueParts(row)
+	const text = { full: row.raw, value: valueText, unit: unitText, q: qualifiedText(row) }[parsed.mode]
+	if (text === null) return { code: "quote_anchor_unresolved", message: `${row.fact_id} has qualifier ${row.qualifier}, but its quote holds no qualifier beside "${row.raw}"` }
+	return { row, parsed, visible: text, rendered: format === "html" ? renderValueHtml(row, text) : text }
+}
+
+function resolveQuote(row, parsed, format) {
+	const whole = { text: row.quote, start: 0, end: row.quote.length }
+	const selection = parsed.mode === "lead" ? lead(row.quote, parsed.lead) : parsed.mode === "span" ? subSpan(row.quote, parsed.from, parsed.to) : whole
+	if (selection === null) {
+		return { code: "quote_anchor_unresolved", message: `from "${parsed.from}" and to "${parsed.to}" must each occur exactly once in ${row.fact_id}'s quote, in that order` }
+	}
+	const rendered = renderQuote(row, parsed.selector, selection.text, format)
+	return { row, parsed, visible: `[${row.source_id}]`, rendered, selector: parsed.selector, quote_span: [selection.start, selection.end] }
+}
+
+function resolve(found, rows, format) {
+	const { parsed } = found
+	if (parsed.error) return { code: "unresolved_placeholder", message: parsed.error }
+	const row = rows.get(parsed.id)
+	if (row === undefined) return { code: "unresolved_placeholder", message: `${parsed.id} is not in the fact ledger` }
+	if (row.status !== "active") return { code: "unresolved_placeholder", message: `${parsed.id} is ${row.status}; cite its replacement` }
+	if (row.label !== parsed.label) return { code: "pointer_label_mismatch", message: `${parsed.id} has label "${row.label}", not "${parsed.label}"` }
+	return parsed.kind === "Q" ? resolveQuote(row, parsed, format) : resolveValue(row, parsed, format)
+}
+
+/** A unit typed right after a pointer that already renders it: never absorbed, always an error. */
+function unitDuplicated(text, item) {
+	if (item.parsed.kind !== "F" || (item.parsed.mode !== "full" && item.parsed.mode !== "q")) return false
+	const suffix = item.row.raw.replace(/^[\s\S]*\d/u, "").trim()
+	const units = [item.row.unit, valueParts(item.row).unitText, suffix].filter((unit) => typeof unit === "string" && unit !== "")
+	const following = text.slice(item.end).replace(/^[ \t]+/u, "")
+	return units.some((unit) => following.startsWith(unit) && !/[A-Za-z0-9]/u.test(following[unit.length] ?? ""))
+}
+
+/*
+ * Sentence-key rules (fidelity-state.mjs sentenceKey(slug, ids)); any other producer of keys must match:
+ * - slug source: an HTML heading's id attribute wins over its text; md headings use their text.
+ * - slugify: strip tags, lowercase, turn each run of non-letters/digits (\p{L}\p{N}) into "-",
+ *   trim leading and trailing "-".
+ * - a sentence takes the nearest heading that starts strictly before the sentence's start offset;
+ *   a sentence before the first heading gets slug "".
+ * - fact ids cited in the sentence are de-duplicated before sentenceKey sorts them.
+ */
+function slugify(text) {
+	return text
+		.replace(/<[^>]*>/gu, "")
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}]+/gu, "-")
+		.replace(/^-+|-+$/gu, "")
+}
+
+function headings(text, format) {
+	return [...text.matchAll(HEADING[format])].map((match) => {
+		const id = format === "html" ? /\bid="([^"]*)"/u.exec(match[1])?.[1] : undefined
+		return { at: match.index, slug: slugify(id ?? match[match.length - 1]) }
+	})
+}
+
+/** Sentence offsets over the source with pointers, comments and (html) tags blanked to equal length. */
+function sentencesOf(text, found, format) {
+	let masked = text
+	for (const item of found) masked = masked.slice(0, item.start) + "x".repeat(item.end - item.start) + masked.slice(item.end)
+	const blank = (part) => part.replace(/[^\n]/gu, " ")
+	masked = masked.replace(/<!--[\s\S]*?-->/gu, blank)
+	if (format === "html") masked = masked.replace(/<[^>]*>/gu, blank)
+	return splitSentences(masked)
+}
+
+function replacements(text, found, items, options, warnings) {
+	const { format, replaceFailed: state } = options
+	const marks = headings(text, format)
+	const out = []
+	for (const sentence of sentencesOf(text, found, format)) {
+		const inside = items.filter((item) => item.start >= sentence.start && item.end <= sentence.end)
+		if (inside.length === 0) continue
+		const slug = marks.filter((mark) => mark.at < sentence.start).at(-1)?.slug ?? ""
+		const key = sentenceKey(slug, [...new Set(inside.map((item) => item.row.fact_id))])
+		if (failureCount(state, key) < 2) continue
+		const rows = inside.map((item) => item.row)
+		const source = rows.find((row) => row.kind === "quote") ?? rows.find((row) => row.source_id !== null && row.quote !== "")
+		if (source === undefined) continue
+		let rendered = options.fallback === "omit" ? "" : renderBlockquote(source, key, format)
+		if (rendered !== "" && format === "md") {
+			if (sentence.start > 0 && text[sentence.start - 1] !== "\n") rendered = `\n\n${rendered}`
+			if (sentence.end < text.length && text[sentence.end] !== "\n") rendered = `${rendered}\n\n`
+		}
+		if (rendered !== "" && source.entity === null) {
+			warnings.push({ code: "fallback_without_entity", token: key, line: lineOf(text, sentence.start), message: `${source.fact_id} has no entity; the block quote cites [${source.source_id}] alone` })
+		}
+		out.push({ start: sentence.start, end: sentence.end, key, source, rendered })
+	}
+	return out
+}
+
+/** The text after a pointer: rewrite a following Korean particle, and map a translation span. */
+function afterPlaceholder(segment, item, context) {
+	const { format, text, warnings, fillMap } = context
+	const probeEnd = format === "html" && segment.includes("<") ? segment.indexOf("<") : segment.length
+	const result = rewriteParticle(segment.slice(0, probeEnd), finalReading(item.visible, null))
+	let next = segment
+	if (result.applied) next = result.text + segment.slice(probeEnd)
+	else if (result.candidate) {
+		warnings.push({ code: "particle_unverified", token: item.token, line: lineOf(text, item.start), message: `the particle after ${item.token} was not rewritten; check it by eye` })
+	}
+	const translation = item.parsed.kind === "Q" ? TRANSLATION[format].exec(next) : null
+	if (translation !== null && translation[1] === item.row.fact_id) {
+		const span = translation[0].trimStart()
+		const start = context.out.length + translation[0].length - span.length
+		fillMap.push({ token: span, fact_id: translation[1], translates: translation[1], start, end: start + span.length, rendered: span })
+	}
+	return next
+}
+
+function assemble(text, parts, context) {
+	let cursor = 0
+	let previous = null
+	const flush = (until) => {
+		const segment = text.slice(cursor, until)
+		context.out += previous?.parsed ? afterPlaceholder(segment, previous, context) : segment
+	}
+	for (const part of parts) {
+		flush(part.start)
+		const start = context.out.length
+		if (part.parsed) {
+			const extra = part.selector === undefined ? {} : { selector: part.selector, quote_span: part.quote_span }
+			context.fillMap.push({ token: part.token, fact_id: part.row.fact_id, start, end: start + part.rendered.length, rendered: part.rendered, ...extra })
+		} else if (part.rendered !== "") {
+			context.fillMap.push({ token: null, fact_id: part.source.fact_id, replaced: part.key, start, end: start + part.rendered.length, rendered: part.rendered })
+		}
+		context.out += part.rendered
+		cursor = part.end
+		previous = part
+	}
+	flush(text.length)
+	return context.out
+}
+
+/**
+ * @param {string} sourceText the report source with {{F..}} / {{Q..}} pointers
+ * @param {{ rows: object[] }} ledger
+ * @param {{ format?: "html"|"md", replaceFailed?: object, fallback?: "quote"|"omit", view?: boolean }} [options]
+ * @returns {{ out: string|null, fillMap: object[], errors: object[], warnings: object[] }}
+ */
+export function fill(sourceText, ledger, options = {}) {
+	const format = options.format ?? "html"
+	if (!FORMATS.includes(format)) throw new TypeError(`format must be one of ${FORMATS.join(", ")}`)
+	const rows = new Map(ledger.rows.map((row) => [row.fact_id, row]))
+	const found = findPlaceholders(sourceText)
+	const errors = []
+	const warnings = []
+	const items = []
+	for (const pointer of found) {
+		const resolved = resolve(pointer, rows, format)
+		const line = lineOf(sourceText, pointer.start)
+		if (resolved.code) errors.push({ code: resolved.code, token: pointer.token, line, message: resolved.message })
+		else {
+			const item = { ...pointer, ...resolved }
+			if (unitDuplicated(sourceText, item)) {
+				errors.push({ code: "unit_duplicated", token: pointer.token, line, message: `${pointer.token} already renders its unit; use {{${item.row.fact_id}:${item.row.label}:value}}` })
+			} else items.push(item)
+		}
+	}
+	if (errors.length > 0) return { out: null, fillMap: [], errors, warnings }
+	const replaced = options.replaceFailed ? replacements(sourceText, found, items, { ...options, format }, warnings) : []
+	const kept = items.filter((item) => !replaced.some((block) => item.start >= block.start && item.end <= block.end))
+	const parts = [...kept, ...replaced].sort((a, b) => a.start - b.start)
+	const context = { format, text: sourceText, warnings, fillMap: [], out: "" }
+	const out = assemble(sourceText, parts, context)
+	if (!options.view) for (const block of replaced) markReplaced(options.replaceFailed, block.key)
+	return { out, fillMap: context.fillMap, errors, warnings }
+}

package/packages/omo-codex/plugin/skills/ulw-research/scripts/fact-ledger-kinds.mjs

@@ -0,0 +1,250 @@
+// fact-ledger-kinds.mjs - the per-kind column rules of the fact ledger as one table, KIND_RULES.
+// validateLedger checks every per-kind column through kindRuleErrors, the writers read their
+// per-kind choices (id prefix, measured exact) from it, and the per-kind table in
+// references/fact-ledger-grammar.md is rendered from it (`node fact-ledger-kinds.mjs --render-grammar`).
+// Also the value primitives the schema shares. Pure functions with no IO; node: builtins only.
+
+import { isCliEntry } from "./entry-guard.mjs"
+import { canonicalUnit, inputScale, RuleError } from "./unit-algebra.mjs"
+import { metadataErrors } from "./unit-metadata.mjs"
+import { mul } from "./rational.mjs"
+import { placesOf, roundPlaces, toBig } from "./unit-precision.mjs"
+import { OPERATION_RULES } from "./unit-rules.mjs"
+
+export const DECIMAL = /^-?\d+(?:\.\d+)?$/
+const INTEGER = /^-?\d+$/
+const SHA256 = /^[0-9a-f]{64}$/
+const SOURCE_ID = /^S\d+$/
+
+export const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+export const isString = (value) => typeof value === "string"
+export const isNonEmpty = (value) => typeof value === "string" && value.length > 0
+export const isCount = (value) => Number.isInteger(value) && value >= 0
+const isDecimal = (value) => isString(value) && DECIMAL.test(value)
+export function isRational(exact) {
+	if (!isObject(exact) || Object.keys(exact).sort().join(",") !== "den,num" || !isString(exact.num) || !isString(exact.den) || !INTEGER.test(exact.num) || !/^[1-9]\d*$/.test(exact.den)) return false
+	let a = BigInt(exact.num)
+	let b = BigInt(exact.den)
+	if (String(a) !== exact.num) return false
+	if (a < 0n) a = -a
+	while (b !== 0n) [a, b] = [b, a % b]
+	return a === 1n
+}
+
+/** The exact rational of a decimal string, reduced. */
+export function exactFromDecimal(value) {
+	const [whole, fraction = ""] = value.replace(/^-/, "").split(".")
+	let num = BigInt(whole + fraction)
+	let den = 10n ** BigInt(fraction.length)
+	let a = num
+	let b = den
+	while (b !== 0n) [a, b] = [b, a % b]
+	if (a > 1n) [num, den] = [num / a, den / a]
+	return { num: `${value.startsWith("-") && num !== 0n ? "-" : ""}${num}`, den: `${den}` }
+}
+
+/** @returns {string[]} what is wrong with a locator object, each message prefixed with `at`. */
+export function locatorErrors(locator, at) {
+	const errors = []
+	if (!isObject(locator)) return errors
+	if (!isNonEmpty(locator.artifact)) errors.push(`${at}.artifact must be a non-empty string`)
+	if (!(isCount(locator.char_start) && isCount(locator.char_end) && locator.char_start <= locator.char_end)) errors.push(`${at}.char_start/char_end must be integers with start <= end`)
+	for (const key of ["page", "line"]) {
+		if (locator[key] !== undefined && !(Number.isInteger(locator[key]) && locator[key] >= 1)) errors.push(`${at}.${key} must be an integer >= 1`)
+	}
+	for (const key of ["table", "row_label", "col_label"]) {
+		if (locator[key] !== undefined && !isString(locator[key])) errors.push(`${at}.${key} must be a string`)
+	}
+	return errors
+}
+
+const isLocator = (value) => isObject(value) && locatorErrors(value, "").length === 0
+const orNull = (test) => (value, row) => value === null || test(value, row)
+const locatorDetail = (value, at) => locatorErrors(value, at)
+
+/**
+ * Every rule a KIND_RULES cell may name: `cell` is its text in the grammar table, `says` ends the
+ * error message, `test(value, row)` decides it, and `prefix` (id rules only) is what nextId uses.
+ */
+export const RULES = Object.freeze({
+	f_id: { cell: "`F<n>`", says: "F<n>", prefix: "F", test: (v) => isString(v) && /^F\d+$/.test(v) },
+	q_id: { cell: "`Q<n>`", says: "Q<n>", prefix: "Q", test: (v) => isString(v) && /^Q\d+$/.test(v) },
+	decimal: { cell: "decimal", says: "a decimal string", test: isDecimal },
+	null: { cell: "null", says: "null", test: (v) => v === null },
+	source: { cell: "`S<n>`", says: "S<n>", test: (v) => isString(v) && SOURCE_ID.test(v) },
+	source_or_null: { cell: "`S<n>` or null", says: "S<n> or null", test: orNull((v) => isString(v) && SOURCE_ID.test(v)) },
+	locator: { cell: "object", says: "a locator object", test: isLocator, detail: locatorDetail },
+	locator_or_null: { cell: "object or null", says: "a locator object or null", test: orNull(isLocator), detail: locatorDetail },
+	sha256: { cell: "sha256", says: "a sha256 hex digest", test: (v) => isString(v) && SHA256.test(v) },
+	sha256_or_null: { cell: "sha256 or null", says: "a sha256 hex digest or null", test: orNull((v) => isString(v) && SHA256.test(v)) },
+	string_or_null: { cell: "string or null", says: "null or a string", test: orNull(isString) },
+	non_empty: { cell: "non-empty", says: "a non-empty string (required for this kind)", test: isNonEmpty },
+	from_value: {
+		cell: "from `value`",
+		says: "the reduced exact rational of value",
+		test: (v, row) => isRational(v) && (!isDecimal(row.value) || (v.num === exactFromDecimal(row.value).num && v.den === exactFromDecimal(row.value).den)),
+	},
+	rational_or_null: { cell: "rational or null", says: "null or { num: integer string, den: positive integer string }", test: orNull(isRational) },
+	by_derive: { cell: "reduced rational", says: "a reduced { num: integer string, den: positive integer string }", test: isRational },
+	context_by_derive: { cell: "written by derive (object or null)", says: "null or an object", test: orNull(isObject) },
+	derived_operation: { cell: "sum/diff/growth/share/ratio/expr", says: "a derived operation", test: (v) => Object.hasOwn(OPERATION_RULES, v) && OPERATION_RULES[v].kind === "derived" },
+	convert_operation: { cell: "`convert`", says: "convert", test: (v) => Object.hasOwn(OPERATION_RULES, v) && OPERATION_RULES[v].kind === "converted" },
+	precision: { cell: "`{ places, sigfigs }`", says: "nonnegative places and positive sigfigs", test: (v) => isObject(v) && Object.keys(v).sort().join(",") === "places,sigfigs" && Number.isSafeInteger(v.places) && v.places >= 0 && Number.isSafeInteger(v.sigfigs) && v.sigfigs >= 1 },
+	compatibility: { cell: "checked or unchecked (expr)", says: "the operation's compatibility", test: (v, r) => Object.hasOwn(OPERATION_RULES, r.operation) && v === OPERATION_RULES[r.operation].compatibility },
+})
+
+/** The grammar's per-kind columns, in table order; `exact` follows `value` because it reads it. */
+export const KIND_COLUMNS = Object.freeze(["fact_id", "value", "source_id", "locator", "snapshot_sha256", "rationale", "exact", "context", "operation", "precision", "compatibility"])
+
+const sourced = { source_id: "source", locator: "locator", snapshot_sha256: "sha256" }
+const unsourced = { source_id: "source_or_null", locator: "locator_or_null", snapshot_sha256: "sha256_or_null" }
+const row = (cells) => Object.freeze(Object.fromEntries(KIND_COLUMNS.map((column) => [column, cells[column] ?? (["precision", "compatibility"].includes(column) && cells.operation !== "null" ? column : "null")])))
+
+export const KIND_RULES = Object.freeze({
+	measured: row({ fact_id: "f_id", value: "decimal", ...sourced, rationale: "string_or_null", exact: "from_value", context: "null", operation: "null" }),
+	quote: row({ fact_id: "q_id", value: "null", ...sourced, rationale: "string_or_null", exact: "null", context: "null", operation: "null" }),
+	derived: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive", context: "context_by_derive", operation: "derived_operation" }),
+	assumed: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "non_empty", exact: "rational_or_null", context: "null", operation: "null" }),
+	converted: row({ fact_id: "f_id", value: "decimal", ...unsourced, rationale: "string_or_null", exact: "by_derive", context: "context_by_derive", operation: "convert_operation" }),
+})
+
+/** The id prefix nextId assigns for a kind; an unknown kind gets F and fails validation later. */
+export function idPrefix(kind) {
+	return RULES[KIND_RULES[kind]?.fact_id ?? "f_id"].prefix
+}
+
+/** Whether addRow computes the row's exact from its decimal value. */
+export function exactComesFromValue(kind) {
+	return KIND_RULES[kind]?.exact === "from_value"
+}
+
+/** Columns added after schema version 1 shipped; a ledger written before them still loads (dimension 31). */
+export const LATER_COLUMNS = Object.freeze(["context", "precision", "compatibility"])
+const DERIVED_KINDS = Object.freeze(["derived", "converted"])
+const PRE_REGISTRY_COLUMNS = KIND_COLUMNS.slice(0, KIND_COLUMNS.indexOf("exact") + 1)
+
+/** A derived or converted row written before the later columns existed: loadable, never an operand. */
+export const isLegacyDerived = (row) => isObject(row) && DERIVED_KINDS.includes(row.kind) && LATER_COLUMNS.every((column) => !Object.hasOwn(row, column))
+/** A derived or converted row carrying this version's columns: the only rows checked strictly at read time. */
+export const isCurrentDerived = (row) => isObject(row) && DERIVED_KINDS.includes(row.kind) && !isLegacyDerived(row)
+
+/** An exact carrying keys beyond num and den: never normalized, never silently stripped, flagged on use. */
+export const hasUnknownExactKeys = (exact) => isObject(exact) && isString(exact.num) && isString(exact.den) && Object.keys(exact).sort().join(",") !== "den,num"
+/** Any integer pair dev's writer accepted, reduced: sign on num, no leading zeros, gcd 1; anything else as given. */
+function readExact(exact) {
+	if (!isObject(exact) || hasUnknownExactKeys(exact) || !isString(exact.num) || !isString(exact.den) || !INTEGER.test(exact.num) || !/^\d+$/.test(exact.den) || /^0+$/.test(exact.den)) return exact
+	const { num, den } = mul({ num: BigInt(exact.num), den: BigInt(exact.den) }, 1n)
+	return { num: String(num), den: String(den) }
+}
+
+const readDecimal = (value) => (isDecimal(value) ? value.replace(/^(-?)0+(?=\d)/, "$1") : value)
+
+/** A source unit read through the alias table; unknown, scaled, or unparseable text stays as given. */
+export function sourceUnit(unit) {
+	try {
+		const canonical = canonicalUnit(unit)
+		return isString(canonical) && !inputScale(unit) ? canonical : unit
+	} catch (error) {
+		if (error instanceof RuleError) return unit
+		throw error
+	}
+}
+
+/**
+ * A row as every reader sees it (dimension 31 wins at read time): rows not written by derive in this
+ * version get reduced exacts and decimals; source rows also get canonical units and null later columns.
+ * Current derived rows stay as stored so tampering is still detected. Idempotent.
+ */
+export function readRow(row) {
+	if (!isObject(row) || !Object.hasOwn(KIND_RULES, row.kind) || isCurrentDerived(row)) return row
+	const read = { ...row, value: readDecimal(row.value), exact: exactComesFromValue(row.kind) ? row.exact : readExact(row.exact) }
+	if (DERIVED_KINDS.includes(row.kind)) return read
+	read.unit = sourceUnit(row.unit)
+	for (const column of LATER_COLUMNS) if (!Object.hasOwn(read, column)) read[column] = null
+	return read
+}
+
+const carriesDerivation = (row) => row.operation !== null || row.operands?.length || row.derived_from?.length || row.formula !== null || row.factor !== null
+
+/** Dimension 32: a stored exact must equal the row's own value at the value's decimal places. */
+function valueExactDisagreement(row) {
+	const exact = readExact(row.exact)
+	const value = readDecimal(row.value)
+	if (!isRational(exact) || !isDecimal(value) || roundPlaces(toBig(exact), placesOf(value)) === value) return null
+	return `value ${value} disagrees with exact ${exact.num}/${exact.den} at ${placesOf(value)} decimal places`
+}
+function unitFlaw(unit) {
+	try {
+		return isString(unit) && (canonicalUnit(unit) !== unit || inputScale(unit)) ? `unit ${unit} has no canonical stored text` : null
+	} catch (error) {
+		if (error instanceof RuleError) return `unit ${unit}: ${error.message}`
+		throw error
+	}
+}
+
+/**
+ * What a loadable source row (read through readRow) still breaks under the strict dimensions: dev's
+ * writer accepted it, so it loads, but derive and recompute refuse it as an operand with this shape.
+ * addRow refuses a new row that has any. Empty for derived and converted rows.
+ */
+export function readFlaws(row) {
+	if (!isObject(row) || DERIVED_KINDS.includes(row.kind)) return []
+	const flaws = []
+	if (carriesDerivation(row)) flaws.push({ shape: "dimension 1", detail: "a source row carries an operation or derivation fields", expected: "null operation and empty derivation fields on measured, quote, and assumed rows" })
+	const unit = unitFlaw(row.unit)
+	if (unit) flaws.push({ shape: "dimension 6", detail: unit, expected: "a registered or canonical unit without scale" })
+	for (const detail of metadataErrors(row)) flaws.push({ shape: "dimension 18", detail, expected: "present, type-valid metadata; explicit null when unknown" })
+	const unknownKeys = hasUnknownExactKeys(row.exact)
+	const disagreement = unknownKeys ? null : valueExactDisagreement(row)
+	if (unknownKeys) flaws.push({ shape: "dimension 7", detail: `exact has unknown keys: ${Object.keys(row.exact).filter((key) => key !== "num" && key !== "den").join(", ")}`, expected: "an exact with exactly num and den (the stored row is kept as written)" })
+	if (disagreement) flaws.push({ shape: "dimension 32", detail: disagreement, expected: "an exact equal to value at the value's decimal places" })
+	return flaws
+}
+
+/** @returns {string[]} every per-kind column error of one row; empty for an unknown kind. */
+export function kindRuleErrors(candidate, at) {
+	const rules = KIND_RULES[candidate.kind]
+	if (rules === undefined) return []
+	const errors = []
+	const legacy = isLegacyDerived(candidate)
+	const columns = legacy ? PRE_REGISTRY_COLUMNS : isCurrentDerived(candidate) ? KIND_COLUMNS : KIND_COLUMNS.filter((column) => column !== "operation")
+	for (const column of columns) {
+		const value = candidate[column] === undefined && LATER_COLUMNS.includes(column) ? null : candidate[column]
+		const rule = RULES[legacy && column === "exact" ? "rational_or_null" : rules[column]]
+		// An exact with unknown keys loads as written (never stripped); readFlaws refuses it at use and at write.
+		if (column === "exact" && hasUnknownExactKeys(value) && !isCurrentDerived(candidate)) continue
+		if (rule.test(value, candidate)) continue
+		errors.push(`${at}.${column} must be ${rule.says} for a ${candidate.kind} row`)
+		if (rule.detail) errors.push(...rule.detail(value, `${at}.${column}`))
+	}
+	return errors
+}
+
+/** At-rest rules of current derived rows; source rows answer to readFlaws at use and at write instead. */
+export function storedErrors(row) {
+	if (!isCurrentDerived(row)) return []
+	const errors = metadataErrors(row)
+	try {
+		if (canonicalUnit(row.unit) !== row.unit || inputScale(row.unit)) errors.push("unit must be canonical stored text")
+	} catch (error) { errors.push(error.message) }
+	return errors
+}
+
+export const KIND_TABLE_BEGIN = "<!-- kind-rules:begin (rendered from KIND_RULES; do not edit by hand) -->"
+export const KIND_TABLE_END = "<!-- kind-rules:end -->"
+
+/** The grammar's per-kind Markdown table, one line per column, ending in a newline. */
+export function renderKindTable() {
+	const kinds = Object.keys(KIND_RULES)
+	const lines = [`| field | ${kinds.join(" | ")} |`, `|${"---|".repeat(kinds.length + 1)}`]
+	for (const column of KIND_COLUMNS) lines.push(`| \`${column}\` | ${kinds.map((kind) => RULES[KIND_RULES[kind][column]].cell).join(" | ")} |`)
+	return `${lines.join("\n")}\n`
+}
+
+if (isCliEntry(import.meta.url)) {
+	if (process.argv[2] === "--render-grammar" && process.argv.length === 3) process.stdout.write(renderKindTable())
+	else {
+		process.stderr.write("usage: node fact-ledger-kinds.mjs --render-grammar\n")
+		process.exitCode = 2
+	}
+}