lazycodex-ai 5.1.45 → 5.1.46

package/packages/shared-skills/skills/ulw-research/scripts/gates-fidelity.mjs

@@ -0,0 +1,113 @@
+// gates-fidelity.mjs - the deterministic fidelity gate over a filled HTML report.
+//
+// checkFidelity refuses to judge a report whose brief has no locked `## Fidelity` block (one
+// fidelity_interview_incomplete defect). Otherwise it builds the static-gate document context
+// once and runs the value, binding, and lexicon checks over it, returning defects in the shape
+// `check` emits plus integrity, sorted blocker, major, minor, then line, selector, code. It never
+// calls a model or reads the network; the meaning verifier consumes its pairs separately.
+// Plain Node ESM, sibling imports only.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { DEFECT_CODES } from "./contracts.mjs"
+import { bindingChecks, proseSentences } from "./fidelity-binding.mjs"
+import { isLocked, parseFidelityBlock } from "./fidelity-brief.mjs"
+import { lexiconChecks } from "./fidelity-lexicon.mjs"
+import { valueChecks } from "./fidelity-values.mjs"
+import { buildContext } from "./gates-static.mjs"
+import { parseHtml } from "./html-lite.mjs"
+
+/** Every code this gate can raise. */
+export const FIDELITY_GATE_CODES = Object.freeze([
+	"fidelity_interview_incomplete", "unresolved_placeholder", "value_mismatch", "unit_mismatch", "quote_not_verbatim",
+	"quote_unbound", "claim_status_invalid", "snapshot_hash_mismatch", "chart_value_untraceable", "untraceable_number",
+	"unsupported_verification", "conflicting_readings", "hedge_dropped", "direction_flipped", "causality_added",
+	"qualifier_dropped", "unbound_sentence", "snapshot_mismatch", "join_integrity_fail", "quote_stale_version",
+	"quote_fuzzy_match", "name_outside_quote", "scope_widened_warn", "claim_kind_mismatch", "verification_claim_unmarked",
+])
+const RANK = { blocker: 0, major: 1, minor: 2 }
+
+/** The gate and delivery barrier share registry policy; caller severities cannot demote it. */
+export function blocksDelivery(defect) {
+	if (!Object.hasOwn(DEFECT_CODES, defect?.code)) return true
+	const entry = DEFECT_CODES[defect.code]
+	return entry.integrity || entry.severity !== "minor"
+}
+
+export function deliveryBlockReason(defect) {
+	return Object.hasOwn(DEFECT_CODES, defect?.code) ? `fidelity_unresolved: ${defect.code}` : `unknown defect code ${defect?.code}`
+}
+
+function withIntegrity(defect) {
+	const { code, severity, selector, line, message, hint } = defect
+	return { code, severity, integrity: DEFECT_CODES[code].integrity, selector, line, message, hint }
+}
+
+function compareDefects(a, b) {
+	const text = (x, y) => (x < y ? -1 : x > y ? 1 : 0)
+	return RANK[a.severity] - RANK[b.severity] || (a.line ?? 0) - (b.line ?? 0) || text(a.selector ?? "", b.selector ?? "") || text(a.code, b.code)
+}
+
+function readAcronyms(sourcesDir, sourceId, cache) {
+	if (!sourcesDir || !sourceId) return {}
+	if (!cache.has(sourceId)) {
+		const path = join(sourcesDir, sourceId, "acronyms.json")
+		cache.set(sourceId, existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {})
+	}
+	return cache.get(sourceId)
+}
+
+/** One (row quote, report sentence) pair per fact cited in a prose sentence outside sources and toc. */
+export function fidelityPairs(ctx, ledger, sourcesDir) {
+	const rows = new Map((ledger?.rows ?? []).map((row) => [row.fact_id, row]))
+	const cache = new Map()
+	const pairs = []
+	for (const block of proseSentences(ctx)) {
+		if (block.kind === "sources" || block.kind === "toc") continue
+		block.sentences.forEach((sentence, index) => {
+			for (const fact of sentence.facts) {
+				const row = rows.get(fact.id)
+				if (!row?.quote) continue
+				pairs.push({
+					pair_id: `${fact.id}@${block.owner.line}:${index + 1}`,
+					fact_id: fact.id,
+					quote: row.quote,
+					sentence: sentence.text,
+					span: [fact.start - sentence.start, fact.end - sentence.start],
+					qualifier: row.kind === "quote" ? null : row.qualifier,
+					acronyms: readAcronyms(sourcesDir, row.source_id, cache),
+					node: block.owner,
+				})
+			}
+		})
+	}
+	return pairs
+}
+
+function incomplete(parsed) {
+	const reasons = !parsed?.present ? "no ## Fidelity block" : [...(parsed.errors ?? []), ...parsed.missing.map((f) => `missing: ${f}`), ...parsed.pending.map((f) => `pending: ${f}`)].join("; ")
+	const entry = DEFECT_CODES.fidelity_interview_incomplete
+	return { code: "fidelity_interview_incomplete", severity: entry.severity, integrity: entry.integrity, selector: null, line: null, message: `fidelity interview incomplete (${reasons})`, hint: entry.hint }
+}
+
+/**
+ * @param {string} html the filled report
+ * @param {{ ledger: { rows: object[] }, sourcesDir?: string | null, claims?: object | null, fillMap?: object[] | null,
+ *   brief: string | object, baseDir?: string, recompute?: (ledger: object, row: object) => { ok: boolean } }} options
+ *   `brief` is the brief.md text or parseFidelityBlock output; `baseDir` resolves data-chart-source paths.
+ * @returns {{ defects: object[], gatesRun: string[] }}
+ */
+export function checkFidelity(html, { ledger, sourcesDir = null, claims = null, fillMap = null, brief, baseDir, recompute } = {}) {
+	const parsed = brief && typeof brief === "object" ? brief : parseFidelityBlock(String(brief ?? ""))
+	if (!isLocked(parsed)) return { defects: [incomplete(parsed)], gatesRun: ["fidelity_interview_incomplete"] }
+	const ctx = buildContext(parseHtml(html), { baseDir })
+	const defects = [
+		...valueChecks(ctx, ledger, fillMap, sourcesDir, { recompute, asOf: parsed.fields["as of"] }),
+		...bindingChecks(ctx, claims, ledger),
+	]
+	const pairs = fidelityPairs(ctx, ledger, sourcesDir)
+	const byId = new Map(pairs.map((pair) => [pair.pair_id, pair]))
+	for (const finding of lexiconChecks(pairs).findings) defects.push(ctx.defect(finding.code, byId.get(finding.pair_id).node, `${finding.pair_id}: ${finding.message}`))
+	return { defects: defects.map(withIntegrity).sort(compareDefects), gatesRun: [...FIDELITY_GATE_CODES] }
+}

package/packages/shared-skills/skills/ulw-research/scripts/gates-fidelity.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { indexClaims } from "./claims-index.mjs"
+import { DEFECT_CODES, FIDELITY_CODES } from "./contracts.mjs"
+import { checkFidelity } from "./gates-fidelity.mjs"
+
+type Defect = { code: string; severity: string; integrity: boolean; selector: string | null; line: number | null; message: string; hint: string }
+type Result = { defects: Defect[]; gatesRun: string[] }
+
+const FIXTURES = join(import.meta.dir, "tests", "fixtures")
+const FIX = join(FIXTURES, "fidelity")
+const read = (path: string) => readFileSync(path, "utf8")
+const OPTIONS = {
+	ledger: JSON.parse(read(join(FIX, "ledger-verify.json"))),
+	sourcesDir: join(FIX, "sources"),
+	claims: indexClaims(read(join(FIX, "claim-graph.md"))),
+	fillMap: null,
+	brief: read(join(FIXTURES, "fidelity-brief-locked.md")),
+	baseDir: FIX,
+}
+
+function run(html: string, extra: Record<string, unknown> = {}): Result {
+	return checkFidelity(html, { ...OPTIONS, ...extra }) as Result
+}
+
+const codes = (result: Result) => result.defects.map((defect) => defect.code)
+
+describe("checkFidelity", () => {
+	test("#given the filled good report with a locked brief #when checked #then zero defects", () => {
+		expect(run(read(join(FIX, "report-good.html"))).defects).toEqual([])
+	})
+
+	test("#given the bad report #when checked #then the exact defect multiset, blockers first", () => {
+		const result = run(read(join(FIX, "report-bad.html")))
+		expect(codes(result)).toEqual([
+			"unit_mismatch",
+			"value_mismatch",
+			"quote_not_verbatim",
+			"unresolved_placeholder",
+			"claim_status_invalid",
+			"untraceable_number",
+			"unbound_sentence",
+		])
+	})
+
+	test("#given any defect #when emitted #then it has the check shape with severity and integrity from the contract", () => {
+		for (const defect of run(read(join(FIX, "report-bad.html"))).defects) {
+			expect(Object.keys(defect).sort()).toEqual(["code", "hint", "integrity", "line", "message", "selector", "severity"])
+			expect(defect.severity).toBe(DEFECT_CODES[defect.code as keyof typeof DEFECT_CODES].severity)
+			expect(defect.integrity).toBe(DEFECT_CODES[defect.code as keyof typeof DEFECT_CODES].integrity)
+		}
+	})
+
+	test("#given an unlocked brief #when checked #then only fidelity_interview_incomplete", () => {
+		const result = run(read(join(FIX, "report-bad.html")), { brief: read(join(FIXTURES, "fidelity-brief-pending.md")) })
+		expect(codes(result)).toEqual(["fidelity_interview_incomplete"])
+		expect(result.defects[0]?.integrity).toBe(true)
+	})
+
+	test("#given a row qualifier dropped in the report #when checked #then qualifier_dropped, and the :q rendering is clean", () => {
+		const dropped = '<h2>Findings</h2><p>The span is <data class="fact" data-fact="F1" data-unit="m">320 m</data> long [S4].</p>'
+		expect(codes(run(dropped))).toEqual(["qualifier_dropped"])
+		expect(run(dropped.replace(">320 m<", ">up to 320 m<")).defects).toEqual([])
+	})
+
+	test("#given the gate #when it runs #then every code it reports is a fidelity code", () => {
+		const { gatesRun } = run(read(join(FIX, "report-good.html")))
+		expect(gatesRun.length).toBeGreaterThan(0)
+		expect(gatesRun.every((code) => FIDELITY_CODES.includes(code))).toBe(true)
+	})
+})

package/packages/shared-skills/skills/ulw-research/scripts/gates-static.mjs

@@ -18,14 +18,19 @@ import { PROSE_TAGS, proseText, selectorPath } from "./html-lite.mjs"
 const CITATION_MARKER = /\[S\d+\]|\[Source\s*\d+\]|\[\uCD9C\uCC98[^\]]*\]|\[\^\d+\]/i
 const ANCHOR_HREF = /^#(?:s|src|source|ref|fn)/i
 const ANCHOR_TEXT = /^\[(?:\uCD9C\uCC98|Source\s*\d+|S\d+)\]$/i
-/** Closing ("how this report was made") heading; Korean alternates cover the same register. */
-export const CLOSING_HEADING = /\b(?:method(?:ology)?|how)\b|\uB4B7\uBA74|\uBC29\uBC95|\uC5B4\uB5BB\uAC8C|\uB9CC\uB4E4\uC5B4/i
+/**
+ * Closing ("how this report was made") heading; Korean alternates cover the same register. A
+ * heading that is exactly "Closing" (or the Korean word for it) also counts; a heading that only
+ * starts with it ("Closing the gap") does not.
+ */
+export const CLOSING_HEADING = /\b(?:method(?:ology)?|how)\b|\uB4B7\uBA74|\uBC29\uBC95|\uC5B4\uB5BB\uAC8C|\uB9CC\uB4E4\uC5B4|^\s*(?:closing|\uB9C8\uBB34\uB9AC)\s*$/i
 export const SOURCES_HEADING = /references|sources|bibliography|\uCD9C\uCC98|\uCC38\uACE0\s*(?:\uBB38\uD5CC|\uC790\uB8CC)/i
-const OTHER_KINDS = [
+/** Section kinds after sources and closing, in match order; HTML and Markdown share this table. */
+export const OTHER_KINDS = Object.freeze([
 	["toc", /\b(?:contents|toc)\b|\uBAA9\uCC28/i],
 	["appendix", /appendix|\uBD80\uB85D/i],
 	["glossary", /glossary|\uC6A9\uC5B4/i],
-]
+])
 const TEXT_SKIP = new Set(["code", "pre", "kbd", "samp", "script", "style", "svg", "template", "noscript"])
 const HEADING_TAG = /^h[1-6]$/
 /** The one sanctioned severity override: section-level lineage demotes unsourced_number. */
@@ -75,9 +80,25 @@ function findBody(doc) {
 	return doc
 }
 
-function sectionKind(text, closingTest) {
+/**
+ * Closing-heading test for both editions: CLOSING_HEADING plus the spec's optional pattern.
+ * @param {RegExp|string|null} [pattern]
+ * @returns {(text: string) => boolean}
+ */
+export function closingTest(pattern) {
+	const extra = pattern ? toRegExp(pattern) : null
+	return (text) => CLOSING_HEADING.test(text) || Boolean(extra?.test(text))
+}
+
+/**
+ * Section kind of an h2 heading text: sources, closing, toc, appendix, glossary, or null.
+ * @param {string} text
+ * @param {(text: string) => boolean} isClosing
+ * @returns {string|null}
+ */
+export function sectionKind(text, isClosing) {
 	if (SOURCES_HEADING.test(text)) return "sources"
-	if (closingTest(text)) return "closing"
+	if (isClosing(text)) return "closing"
 	return OTHER_KINDS.find(([, re]) => re.test(text))?.[0] ?? null
 }
 
@@ -111,7 +132,6 @@ function walkBody(ctx, node, state) {
 export function buildContext(doc, options) {
 	const lineageMode = options.lineageMode ?? "inline"
 	if (!LINEAGE_MODES.includes(lineageMode)) throw new TypeError(`lineageMode must be one of ${LINEAGE_MODES.join(", ")}`)
-	const closingPattern = options.closingPattern ? toRegExp(options.closingPattern) : null
 	const all = descendants(doc)
 	const styleBlocks = all.filter((node) => node.tag === "style").map((node) => ({ node, css: node.raw ?? "" }))
 	const styleAttrs = all.filter((node) => node.attrs.style).map((node) => ({ node, css: node.attrs.style }))
@@ -130,7 +150,7 @@ export function buildContext(doc, options) {
 		requireSections: (options.requireSections ?? []).map(toRegExp),
 		baseDir: options.baseDir ?? null,
 		fs: options.fs ?? nodeFs,
-		isClosing: (text) => CLOSING_HEADING.test(text) || Boolean(closingPattern?.test(text)),
+		isClosing: closingTest(options.closingPattern),
 		util: { classTokens, closest, descendants, hasCitation, citationMarker: CITATION_MARKER },
 		kindOf: (scope) => (scope.closingH3 ? "closing" : (scope.section?.kind ?? null)),
 		defect(code, node, message) {

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

@@ -54,8 +54,8 @@ function skipSpaces(source, at) {
 	return at
 }
 
-/** Read `<name attrs...>` starting just after `<`. */
-function readTag(source, start) {
+/** Read `<name attrs...>` starting just after `<`; the one attribute parser (any quoting). */
+export function readTag(source, start) {
 	const end = source.length
 	let at = start
 	while (at < end && !isSpace(source[at]) && source[at] !== ">" && source[at] !== "/") at++

package/packages/shared-skills/skills/ulw-research/scripts/html-markup.mjs

@@ -0,0 +1,182 @@
+// Byte-preserving HTML boundaries for polish. No CSS or visibility inference.
+import { readTag } from "./html-lite.mjs"
+
+const RAW = new Set(["script", "style"])
+const FROZEN = new Set([...RAW, "template"])
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"])
+const isLetter = (ch) => /[a-z]/i.test(ch ?? "")
+
+function scan(src, at, visit) {
+	while (at < src.length) {
+		const start = src.indexOf("<", at)
+		if (start === -1) return
+		const next = src[start + 1]
+		let kind
+		let end
+		let tag = null
+		if (src.startsWith("<!--", start)) {
+			// From start + 2 so the abrupt closes <!--> and <!---> end where the HTML tokenizer ends them.
+			kind = "skip"
+			const stop = src.indexOf("-->", start + 2)
+			end = stop === -1 ? src.length : stop + 3
+		} else if (next === "!" || next === "?" || (next === "/" && !isLetter(src[start + 2]))) {
+			// Declarations, <?...> and </ + non-letter (</> included) are bogus comments up to the next ">".
+			kind = "skip"
+			const stop = src.indexOf(">", start + 2)
+			end = stop === -1 ? src.length : stop + 1
+		} else if (isLetter(next) || (next === "/" && isLetter(src[start + 2]))) {
+			kind = next === "/" ? "close" : "open"
+			tag = readTag(src, start + (kind === "close" ? 2 : 1))
+			end = tag.end
+		} else {
+			at = start + 1
+			continue
+		}
+		const resume = visit(kind, start, end, tag)
+		if (resume === Infinity) return
+		at = resume ?? (kind === "open" && RAW.has(tag.name) ? closeOf(src, end, tag.name) : end)
+	}
+}
+
+// Script data with its escaped and double-escaped states: a </script> inside <!--<script>...-->
+// does not end the script. Returns the end of the closing tag, or the end of input.
+const SCRIPT_MARKS = { data: /<!--|<\/script(?=[\s/>])/gi, escaped: /-->|<\/?script(?=[\s/>])/gi, double: /-->|<\/script(?=[\s/>])/gi }
+function scriptEnd(src, from) {
+	let state = "data"
+	let at = from
+	for (;;) {
+		const marks = SCRIPT_MARKS[state]
+		marks.lastIndex = at
+		const match = marks.exec(src)
+		if (!match) return src.length
+		const token = match[0].toLowerCase()
+		if (token === "-->") [state, at] = ["data", match.index + 3]
+		else if (token === "<!--") [state, at] = ["escaped", match.index + 2]
+		else if (token === "<script") [state, at] = ["double", match.index + 7]
+		else if (state === "double") [state, at] = ["escaped", match.index + 8]
+		else return readTag(src, match.index + 2).end
+	}
+}
+
+function closeOf(src, from, name) {
+	if (name === "script") return scriptEnd(src, from)
+	if (RAW.has(name)) {
+		const close = new RegExp(`</${name}(?=[\\s/>])[^>]*>`, "gi")
+		close.lastIndex = from
+		const match = close.exec(src)
+		return match ? match.index + match[0].length : src.length
+	}
+	let depth = 0
+	let stop = src.length
+	scan(src, from, (kind, _start, end, tag) => {
+		if (tag?.name !== name) return undefined
+		if (kind === "open") depth++
+		else if (depth === 0) {
+			stop = end
+			return Infinity
+		} else depth--
+		return undefined
+	})
+	return stop
+}
+
+const endOf = (src, end, tag) => VOID.has(tag.name) ? end : closeOf(src, end, tag.name)
+
+/** Raw markup sequence, corresponding text slots, and markup with frozen elements omitted. */
+export function markupParts(html) {
+	const src = String(html)
+	const markup = []
+	const text = []
+	let source = ""
+	let kept = 0
+	scan(src, 0, (kind, start, end, tag) => {
+		const frozen = kind === "open" && FROZEN.has(tag.name)
+		const stop = frozen ? endOf(src, end, tag) : end
+		text.push(src.slice(kept, start))
+		markup.push(src.slice(start, stop))
+		source += src.slice(kept, start) + (frozen || kind === "skip" ? " " : src.slice(start, stop))
+		kept = stop
+		return stop
+	})
+	text.push(src.slice(kept))
+	source += src.slice(kept)
+	return { markup, text, source }
+}
+
+/** Whole elements accepted by the caller; nested matches stay within the outer match. */
+export function elementSpans(html, accept) {
+	const src = String(html)
+	const spans = []
+	scan(src, 0, (kind, start, end, tag) => {
+		if (kind !== "open" || !accept(tag.name, tag.attrs)) return undefined
+		const stop = endOf(src, end, tag)
+		spans.push({ start, end: stop, tag })
+		return stop
+	})
+	return spans
+}
+
+export function tagAttributes(html) {
+	const tags = []
+	scan(String(html), 0, (kind, _start, _end, tag) => {
+		if (kind === "open") tags.push({ name: tag.name, attrs: tag.attrs })
+		return undefined
+	})
+	return tags
+}
+
+/**
+ * Constructs this tokenizer does not model exactly; renderer output never contains them, so polish
+ * refuses a document holding any of them instead of trusting the markup comparison.
+ */
+export function ambiguousMarkup(html) {
+	const src = String(html)
+	const found = new Set()
+	if (/<\/(?![a-z])/i.test(src)) found.add("</ before a non-letter")
+	if (/<!\[CDATA\[/i.test(src)) found.add("<![CDATA[")
+	if (src.includes("<?")) found.add("<?")
+	if (src.includes("--!>")) found.add("--!>")
+	scan(src, 0, (kind, start, end, tag) => {
+		if (kind !== "skip" && src.slice(start + 1, end).includes("<")) found.add("< inside a tag or attribute value")
+		if (kind === "open" && RAW.has(tag.name) && src.slice(end, closeOf(src, end, tag.name)).includes("<!--")) found.add(`<!-- inside ${tag.name}`)
+		return undefined
+	})
+	return [...found]
+}
+
+/** One character reference token of a text node: & up to the first ; or non-name character. */
+export const CHARACTER_REFERENCE = /&[^;\s<&]*;?/g
+
+/**
+ * The skeleton of a document: every markup token (tags, comments, bogus comments and the frozen
+ * content of script/style/template) and every character reference of a text node, in document
+ * order, each with its byte offset. Polish may change text node characters only, and an edit can
+ * carry neither <, > nor & and may not touch a character reference, so an edited span holds no
+ * skeleton token: a polished document keeps this sequence byte-identical.
+ */
+export function skeletonTokens(html) {
+	const { markup, text } = markupParts(html)
+	const tokens = []
+	let at = 0
+	text.forEach((slot, index) => {
+		for (const match of slot.matchAll(CHARACTER_REFERENCE)) tokens.push({ kind: "reference", value: match[0], offset: at + match.index })
+		at += slot.length
+		if (index < markup.length) {
+			tokens.push({ kind: "markup", value: markup[index], offset: at })
+			at += markup[index].length
+		}
+	})
+	return tokens
+}
+
+const describeToken = (token) => (token ? `${token.kind} ${JSON.stringify(token.value)} at offset ${token.offset}` : "end of document")
+
+/** The first skeleton token two documents disagree on, as a message, or null when they agree. */
+export function skeletonChange(beforeHtml, afterHtml) {
+	const [before, after] = [skeletonTokens(beforeHtml), skeletonTokens(afterHtml)]
+	for (let index = 0; index < Math.max(before.length, after.length); index++) {
+		if (before[index]?.value === after[index]?.value) continue
+		return `skeleton changed at token ${index}: ${describeToken(before[index])} became ${describeToken(after[index])}`
+	}
+	return null
+}

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

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