corpus/README.md

@@ -13,12 +13,12 @@ One directory per contract kind, each landing with its milestone:
 - `real-payloads/` — `<name>.json`: sanitized live ADF, round-tripped ADF→markdown→ADF. No
   expected markdown.
 - `commonmark-spec/` — the CommonMark suite run against `markdownToAdf` by three checks. `spec.json`
-  (0.31.2, vendored byte-exact) is the suite; `refusals.json` pins each refusing example to its
+  is the suite; `refusals.json` pins each refusing example to its error `code`; `exceptions.json`
-  error `code`; `exceptions.json` pins each known divergence by `check`, `example`, `kind` and the
+  pins each known divergence by `check`, `example`, `kind` and the exact `divergence`, with a
-  exact `divergence`, with a `reason`. `kind` is `mark-model` (the permanent count divergence from
+  `reason`. `kind` is `mark-model` (the permanent count divergence from ADF's mark-per-text-node
-  ADF's mark-per-text-node model), `unspellable` (parses but the flavour has no spelling) or
+  model), `unspellable` (parses but the flavour has no spelling) or `pending` (a parser gap a later
-  `pending` (a parser gap a later milestone may close).
+  milestone may close).
 
 JSON is editor-normal (AGENTS.md §2), two-space indent, keys sorted. `spec.json` is the vendored,
-upstream machine-readable suite (CommonMark 0.31.2, CC-BY-SA-4.0, © John MacFarlane) and is not
+upstream machine-readable suite, byte-exact (CommonMark 0.31.2, CC-BY-SA-4.0, © John MacFarlane),
-re-serialized by the corpus gate.
+and is not re-serialized by the corpus gate.

src/commonmark-spec.test.ts

@@ -10,8 +10,9 @@ import { adfToMarkdown } from './markdown/emit/adf-to-markdown.ts'
 import { markdownToAdf } from './markdown/parse/markdown-to-adf.ts'
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..', 'corpus', 'commonmark-spec')
+const checks = ['count', 'fixpoint', 'text'] as const
 
-type Check = 'count' | 'fixpoint' | 'text'
+type Check = (typeof checks)[number]
 type ExceptionKind = 'mark-model' | 'pending' | 'unspellable'
 
 type SpecExample = { example: number; html: string; markdown: string; section: string }
@@ -25,7 +26,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function isCheck(value: unknown): value is Check {
-  return value === 'count' || value === 'fixpoint' || value === 'text'
+  return checks.some((check) => check === value)
 }
 
 function isKind(value: unknown): value is ExceptionKind {
@@ -325,7 +326,7 @@ for (const example of spec) {
       fixpoint: fixpointRefused(example, parse.value),
       text: textMismatch(example, parse.value),
     }
-    for (const check of ['count', 'fixpoint', 'text'] as const) {
+    for (const check of checks) {
       const entry = exceptionIndex.get(`${example.example}:${check}`)
       const divergence = divergences[check]
       if (divergence === undefined) {

todo.md

@@ -53,7 +53,7 @@ The numbering is the order the work was planned in, not the order it ships.
   - [x] **3i — The inline nodes and the marks.**
   - [x] **3j — The carry and the combinations.**
   - [ ] **3k — The CommonMark spec suite (`0.2.0`).** Checked in at `corpus/commonmark-spec/`,
-        pinned to the version it ships — the one `html-blocks.ts` names for its start
+        pinned to the version it ships — the one `commonmark-grammar.ts` names for its start
         conditions — `corpus/README.md` gaining the kind.
         **Settled** (the maintainer, 2026-08-27): three checks an example must pass, the reference
         HTML each ships read as corpus data — which adds no format and no direction (§1). §2's