corpus/README.md

@@ -1,6 +1,6 @@
 # The corpus
 
-One directory per contract kind:
+One directory per contract kind, each landing with its milestone:
 
 - `round-trip/` — `<name>.json` + `<name>.md`: the markdown `adfToMarkdown` must emit for that
   document, byte for byte, and that `markdownToAdf` must read back to it (AGENTS.md §2). Grouped
@@ -10,8 +10,8 @@ One directory per contract kind:
 - `errors/` — `<name>.md`: markdown input that must not convert. A `<name>.error` beside it
   pins which error.
 - `unspellable/` — `<name>.json`: ADF `adfToMarkdown` must refuse, the `ConvertErrorCode` in the
-  `<name>.error` beside it. A maintainer decision (`todo.md`) moves a document from here to
+  `<name>.error` beside it. Two populations live here: refusals that stay contract, and documents
-  `round-trip/`.
+  a maintainer decision (`todo.md`) moves to `round-trip/`.
 - `real-payloads/` — `<name>.json`: sanitized live ADF, round-tripped ADF→markdown→ADF. No
   expected markdown.
 

corpus/round-trip/block-nodes/container-crossing.json

@@ -0,0 +1,77 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "panelType": "info"
+      },
+      "content": [
+        {
+          "content": [
+            {
+              "content": [
+                {
+                  "attrs": {
+                    "panelType": "warning"
+                  },
+                  "content": [
+                    {
+                      "content": [
+                        {
+                          "text": "Check the torque before signing off.",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "panel"
+                }
+              ],
+              "type": "listItem"
+            },
+            {
+              "content": [
+                {
+                  "content": [
+                    {
+                      "text": "Plain item.",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "listItem"
+            }
+          ],
+          "type": "bulletList"
+        },
+        {
+          "content": [
+            {
+              "attrs": {
+                "title": "Full build log"
+              },
+              "content": [
+                {
+                  "content": [
+                    {
+                      "text": "The build ran for 11 minutes.",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "expand"
+            }
+          ],
+          "type": "blockquote"
+        }
+      ],
+      "type": "panel"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/block-nodes/container-crossing.md

@@ -0,0 +1,10 @@
+::::panel info
+- :::panel warning
+  Check the torque before signing off.
+  :::
+- Plain item.
+
+> :::expand {title="Full build log"}
+> The build ran for 11 minutes.
+> :::
+::::

src/adf-document.ts

@@ -2,6 +2,8 @@ import { isJsonValue, type JsonValue } from './json-value.ts'
 
 export type AdfAttributes = { [key: string]: JsonValue }
 
+export type AttributeKind = 'boolean' | 'json' | 'number' | 'string'
+
 export type AdfMark = {
   attrs?: AdfAttributes
   type: string

src/adf-to-markdown.ts

@@ -2,21 +2,21 @@ import type { AdfDocument, AdfNode } from './adf-document.ts'
 import type { BlockDirective } from './block-directives.ts'
 import type { JsonValue } from './json-value.ts'
 import { blockDirective, spellDirectiveHeader } from './block-directives.ts'
-import { emitImageLine, emitInlineLine } from './markdown-inline.ts'
+import { emitImage } from './markdown-image.ts'
-import { emitPipeTable } from './markdown-tables.ts'
+import { emitInlineLine } from './markdown-inline.ts'
+import { emitPipeTable } from './markdown-pipe-table.ts'
 import { failure, success, type ConvertErrorPath, type Result } from './result.ts'
 import { holdsNullCharacter, isThematicBreak } from './commonmark-grammar.ts'
 import { isAdfDocument } from './adf-document.ts'
 import { largestNesting } from './nesting.ts'
 import { longestBacktickRun } from './backtick-runs.ts'
-import { serializeCanonicalJson } from './canonical-json.ts'
 
 type BlockContainer = 'directive' | 'document' | 'list-item'
+type BlockSpelling = 'commonmark' | 'directive'
 type EmittedBody = { fenceColons: number; text: string }
-type EmittedBlock = EmittedBody & { node: AdfNode; path: ConvertErrorPath }
+type EmittedBlock = EmittedBody & { spelling: BlockSpelling }
+type PlacedBlock = EmittedBlock & { node: AdfNode; path: ConvertErrorPath }
 
-const centeredMediaSingle = '{"layout":"center"}'
-const imageAttributes = ['alt', 'type', 'url']
 const largestListMarker = 999999999
 const listTypes = ['bulletList', 'orderedList']
 
@@ -30,7 +30,7 @@ export function adfToMarkdown(document: AdfDocument): Result<string> {
 
 function emitBlocks(nodes: readonly AdfNode[], container: BlockContainer, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
   if (depth > largestNesting) return failure('unsupported-node-shape', `the document nests deeper than the ${largestNesting} levels the emitter carries`, path)
-  const blocks: EmittedBlock[] = []
+  const blocks: PlacedBlock[] = []
   for (const [index, node] of nodes.entries()) {
     const nodePath = [...path, 'content', index]
     const block = emitBlock(node, nodePath, depth)
@@ -52,7 +52,7 @@ function emitBlocks(nodes: readonly AdfNode[], container: BlockContainer, path:
   return success({ fenceColons, text })
 }
 
-function separationBetween(previous: EmittedBlock, next: EmittedBlock, container: BlockContainer): Result<string> {
+function separationBetween(previous: PlacedBlock, next: PlacedBlock, container: BlockContainer): Result<string> {
   if (listTypes.includes(next.node.type) && previous.node.type === next.node.type) {
     return failure('unspellable-adjacent-lists', `two adjacent ${next.node.type} nodes read back as one list`, next.path)
   }
@@ -63,8 +63,8 @@ function separationBetween(previous: EmittedBlock, next: EmittedBlock, container
     return success('\n')
   }
   if (container !== 'directive') return success('\n\n')
-  if (previous.fenceColons === 0 && next.fenceColons === 0) return success('\n\n')
+  if (previous.spelling === 'commonmark' && next.spelling === 'commonmark') return success('\n\n')
-  if (previous.fenceColons > 0 && next.fenceColons > 0) return success('\n')
+  if (previous.spelling === 'directive' && next.spelling === 'directive') return success('\n')
   return failure(
     'unspelled-block-separation',
     `the canonical form leaves the separation between a ${previous.node.type} and a ${next.node.type} in a container body unspelled`,
@@ -77,13 +77,13 @@ function interruptsParagraph(node: AdfNode): boolean {
   return ((node.content ?? [])[0]?.content ?? []).length > 0
 }
 
-function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
+function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  if (node.type === 'blockquote') return plainBlock(emitBlockquote(node, path, depth))
+  if (node.type === 'blockquote') return commonMarkContainer(emitBlockquote(node, path, depth))
-  if (node.type === 'bulletList' || node.type === 'orderedList') return plainBlock(emitList(node, path, depth))
+  if (node.type === 'bulletList' || node.type === 'orderedList') return commonMarkContainer(emitList(node, path, depth))
-  if (node.type === 'codeBlock') return plainBlock(emitCodeBlock(node, path))
+  if (node.type === 'codeBlock') return commonMarkLine(emitCodeBlock(node, path))
-  if (node.type === 'heading') return plainBlock(emitHeading(node, path))
+  if (node.type === 'heading') return commonMarkLine(emitHeading(node, path))
   if (node.type === 'paragraph') return emitParagraph(node, path)
-  if (node.type === 'rule') return plainBlock(emitRule(node, path))
+  if (node.type === 'rule') return commonMarkLine(emitRule(node, path))
   const directive = blockDirective(node.type)
   if (directive !== undefined) {
     if (node.type === 'mediaSingle') return emitMediaSingle(node, directive, path, depth)
@@ -96,71 +96,62 @@ function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result
   return failure('unsupported-node-type', `the canonical form spells no block node of type ${node.type}`, path)
 }
 
-function plainBlock(text: Result<string>): Result<EmittedBody> {
+function commonMarkLine(text: Result<string>): Result<EmittedBlock> {
   if (!text.ok) return text
-  return success({ fenceColons: 0, text: text.value })
+  return success({ fenceColons: 0, spelling: 'commonmark', text: text.value })
 }
 
-function emitDirectiveBlock(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
+function commonMarkContainer(body: Result<EmittedBody>): Result<EmittedBlock> {
+  if (!body.ok) return body
+  return success({ ...body.value, spelling: 'commonmark' })
+}
+
+function emitDirectiveBlock(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
   if (node.text !== undefined) return failure('unsupported-node-shape', `a ${node.type} carries no text`, path)
   const header = spellDirectiveHeader(node, directive, path)
   if (!header.ok) return header
   const content = node.content ?? []
   if (directive.body === 'none') {
     if (content.length > 0) return failure('unsupported-node-shape', `a ${node.type} holds no content`, path)
-    return success({ fenceColons: 2, text: `::${header.value}` })
+    return success({ fenceColons: 2, spelling: 'directive', text: `::${header.value}` })
   }
   const body = directive.body === 'inline' ? emitInlineBody(content, path) : emitBlocks(content, 'directive', path, depth + 1)
   if (!body.ok) return body
   const fenceColons = Math.max(3, body.value.fenceColons + 1)
   const fence = ':'.repeat(fenceColons)
   const lines = body.value.text === '' ? '' : `${body.value.text}\n`
-  return success({ fenceColons, text: `${fence}${header.value}\n${lines}${fence}` })
+  return success({ fenceColons, spelling: 'directive', text: `${fence}${header.value}\n${lines}${fence}` })
 }
 
 function emitInlineBody(content: readonly AdfNode[], path: ConvertErrorPath): Result<EmittedBody> {
   if (content.length === 0) return success({ fenceColons: 0, text: '' })
-  return plainBlock(emitInlineLine(content, 'paragraph', path))
+  const line = emitInlineLine(content, 'paragraph', path)
+  if (!line.ok) return line
+  return success({ fenceColons: 0, text: line.value })
 }
 
-function emitMediaSingle(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
+function emitMediaSingle(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  const image = imageShape(node)
+  const image = emitImage(node, path)
   if (image === undefined) return emitDirectiveBlock(node, directive, path, depth)
-  const mediaPath = [...path, 'content', 0]
+  return commonMarkLine(image)
-  if (image.alt === '') return failure('ambiguous-empty-media-alt', 'an empty media alt and an absent one share one image spelling', mediaPath)
-  return plainBlock(emitImageLine(image.alt, image.url, mediaPath))
 }
 
-function imageShape(node: AdfNode): { alt: string | undefined; url: string } | undefined {
+function emitTable(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  const content = node.content ?? []
-  const media = content[0]
-  if (serializeCanonicalJson(node.attrs ?? {}, 'compact') !== centeredMediaSingle || (node.marks ?? []).length > 0) return undefined
-  if (media === undefined || content.length !== 1 || media.type !== 'media' || (media.marks ?? []).length > 0 || (media.content ?? []).length > 0) return undefined
-  const attrs = media.attrs ?? {}
-  const alt = attrs['alt']
-  const url = attrs['url']
-  if (Object.keys(attrs).some((key) => !imageAttributes.includes(key)) || attrs['type'] !== 'external') return undefined
-  if (typeof url !== 'string' || (alt !== undefined && typeof alt !== 'string')) return undefined
-  return { alt, url }
-}
-
-function emitTable(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
   const pipe = emitPipeTable(node, path)
   if (pipe === undefined) return emitDirectiveBlock(node, directive, path, depth)
-  return plainBlock(pipe)
+  return commonMarkLine(pipe)
 }
 
-function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result<string> {
+function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
   const validation = validateBlockNode(node, [], path)
   if (!validation.ok) return validation
   const inner = emitBlocks(node.content ?? [], 'document', path, depth + 1)
   if (!inner.ok) return inner
-  return success(
+  const text = inner.value.text
-    inner.value.text
     .split('\n')
     .map((line) => (line === '' ? '>' : `> ${line}`))
-      .join('\n'),
+    .join('\n')
-  )
+  return success({ fenceColons: inner.value.fenceColons, text })
 }
 
 function emitCodeBlock(node: AdfNode, path: ConvertErrorPath): Result<string> {
@@ -211,54 +202,63 @@ function emitHeading(node: AdfNode, path: ConvertErrorPath): Result<string> {
   return success(`${hashes} ${line.value}`)
 }
 
-function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<string> {
+function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
   const ordered = node.type === 'orderedList'
   const validation = validateBlockNode(node, ordered ? ['order'] : [], path)
   if (!validation.ok) return validation
   const items = node.content ?? []
-  if (items.length === 0) return failure('unsupported-node-shape', `a ${node.type} holds at least one listItem`, path)
+  const start = listStart(node, items.length, path)
-  const start = ordered ? node.attrs?.['order'] : 0
+  if (!start.ok) return start
-  if (ordered && (start === undefined || start === 1)) {
-    return failure('ambiguous-ordered-list-start', 'an orderedList starting at 1 and one with no order share one markdown spelling', path)
-  }
-  if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || start > largestListMarker) {
-    return failure('unsupported-node-shape', `no list marker spells the order ${JSON.stringify(start ?? null)}`, path)
-  }
-  if (start + items.length - 1 > largestListMarker) {
-    return failure('unspellable-list-marker', `no list marker spells the ${items.length} items a list starting at ${start} needs`, path)
-  }
   const lines: string[] = []
+  let fenceColons = 0
   for (const [offset, item] of items.entries()) {
     const itemPath = [...path, 'content', offset]
     if (item.type !== 'listItem') return failure('unsupported-node-shape', `a ${node.type} holds listItem nodes only`, itemPath)
-    const emitted = emitListItem(item, ordered ? `${start + offset}. ` : '- ', itemPath, depth)
+    const emitted = emitListItem(item, ordered ? `${start.value + offset}. ` : '- ', itemPath, depth)
     if (!emitted.ok) return emitted
-    lines.push(emitted.value)
+    fenceColons = Math.max(fenceColons, emitted.value.fenceColons)
+    lines.push(emitted.value.text)
   }
-  return success(lines.join('\n'))
+  return success({ fenceColons, text: lines.join('\n') })
 }
 
-function emitListItem(item: AdfNode, marker: string, path: ConvertErrorPath, depth: number): Result<string> {
+function listStart(node: AdfNode, items: number, path: ConvertErrorPath): Result<number> {
+  if (items === 0) return failure('unsupported-node-shape', `a ${node.type} holds at least one listItem`, path)
+  if (node.type !== 'orderedList') return success(0)
+  const start = node.attrs?.['order']
+  if (start === undefined || start === 1) {
+    return failure('ambiguous-ordered-list-start', 'an orderedList starting at 1 and one with no order share one markdown spelling', path)
+  }
+  if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || start > largestListMarker) {
+    return failure('unsupported-node-shape', `no list marker spells the order ${JSON.stringify(start)}`, path)
+  }
+  if (start + items - 1 > largestListMarker) {
+    return failure('unspellable-list-marker', `no list marker spells the ${items} items a list starting at ${start} needs`, path)
+  }
+  return success(start)
+}
+
+function emitListItem(item: AdfNode, marker: string, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
   const validation = validateBlockNode(item, [], path)
   if (!validation.ok) return validation
   const inner = emitBlocks(item.content ?? [], 'list-item', path, depth + 1)
   if (!inner.ok) return inner
-  if (inner.value.text === '') return success(marker.trimEnd())
+  if (inner.value.text === '') return success({ fenceColons: 0, text: marker.trimEnd() })
   const indent = ' '.repeat(marker.length)
   const lines = inner.value.text.split('\n').map((line, index) => (index === 0 ? `${marker}${line}` : line === '' ? '' : `${indent}${line}`))
   const first = lines[0] ?? ''
   if (isThematicBreak(first)) {
     return failure('unspellable-line-start', `block parsing would claim the emitted line ${JSON.stringify(first)}`, path)
   }
-  return success(lines.join('\n'))
+  return success({ fenceColons: inner.value.fenceColons, text: lines.join('\n') })
 }
 
-function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result<EmittedBody> {
+function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> {
   const validation = validateBlockNode(node, [], path)
   if (!validation.ok) return validation
   const content = node.content ?? []
-  if (content.length === 0) return success({ fenceColons: 2, text: '::paragraph' })
+  if (content.length === 0) return success({ fenceColons: 2, spelling: 'directive', text: '::paragraph' })
-  return plainBlock(emitInlineLine(content, 'paragraph', path))
+  return commonMarkLine(emitInlineLine(content, 'paragraph', path))
 }
 
 function emitRule(node: AdfNode, path: ConvertErrorPath): Result<string> {

src/block-directives.ts

@@ -1,5 +1,4 @@
-import type { AdfMark, AdfNode } from './adf-document.ts'
+import type { AdfMark, AdfNode, AttributeKind } from './adf-document.ts'
-import type { AttributeKind } from './directive-attributes.ts'
 import type { JsonValue } from './json-value.ts'
 import { failure, success, type ConvertErrorPath, type Result } from './result.ts'
 import { isBareToken, spellAttributeValue, spellAttributes, spellJsonAttribute } from './directive-attributes.ts'

src/corpus.test.ts

@@ -72,6 +72,50 @@ for (const directory of emittingDirectories) {
   }
 }
 
+// The rule spec/flavour.md states as "a container's fence is longer than every directive fence line
+// in its body", checked against the emitted bytes: a hand-written fixture cannot be its own witness.
+function fenceNestingFault(markdown: string): string | undefined {
+  const open: number[] = []
+  let codeFence: string | undefined
+  for (const line of markdown.split('\n')) {
+    const content = line.replace(/^ {0,3}(?:(?:> ?|[-*+] |\d{1,9}[.)] ) {0,3})*/, '')
+    const backticks = /^(`{3,}|~{3,})/.exec(content)?.[1]
+    if (codeFence !== undefined) {
+      if (backticks !== undefined && backticks[0] === codeFence[0] && backticks.length >= codeFence.length) codeFence = undefined
+      continue
+    }
+    if (backticks !== undefined) {
+      codeFence = backticks
+      continue
+    }
+    const colons = /^(:{2,})(.*)$/.exec(content)
+    if (colons === null) continue
+    const run = colons[1]?.length ?? 0
+    const enclosing = open[open.length - 1]
+    if (colons[2] === '') {
+      open.pop()
+      continue
+    }
+    if (enclosing !== undefined && run >= enclosing) return `${JSON.stringify(line)} sits in a container fenced with ${enclosing} colons`
+    if (run > 2) open.push(run)
+  }
+  return undefined
+}
+
+test('the fence nesting check catches a fence a container cannot hold', () => {
+  assert.equal(fenceNestingFault(':::panel info\n- :::panel warning\n  B\n  :::\n:::'), '"- :::panel warning" sits in a container fenced with 3 colons')
+  assert.equal(fenceNestingFault('::::panel info\n- :::panel warning\n  B\n  :::\n::::'), undefined)
+  assert.equal(fenceNestingFault(':::tableCell\n```text\n:::::::panel warning\n:::\n```\n:::'), undefined)
+})
+
+for (const directory of emittingDirectories) {
+  for (const name of fixtureNames(directory, '.md')) {
+    test(`${directory}/${name} fences every container longer than its body`, () => {
+      assert.equal(fenceNestingFault(readFileSync(join(roundTripRoot, directory, `${name}.md`), 'utf8')), undefined)
+    })
+  }
+}
+
 test('unspellable pairs every .json with an .error', () => {
   assert.deepEqual(names(unspellableRoot, '.json'), names(unspellableRoot, '.error'))
 })

src/directive-attributes.ts

@@ -1,8 +1,7 @@
+import type { AttributeKind } from './adf-document.ts'
 import type { JsonValue } from './json-value.ts'
 import { serializeCanonicalJson } from './canonical-json.ts'
 
-export type AttributeKind = 'boolean' | 'json' | 'number' | 'string'
-
 const bareToken = /^[A-Za-z0-9_-]+$/
 
 export function isBareToken(text: string): boolean {

src/markdown-image.ts

@@ -0,0 +1,28 @@
+import type { AdfNode } from './adf-document.ts'
+import { emitImageLine } from './markdown-inline.ts'
+import { failure, type ConvertErrorPath, type Result } from './result.ts'
+import { serializeCanonicalJson } from './canonical-json.ts'
+
+const centeredMediaSingle = '{"layout":"center"}'
+const imageAttributes = ['alt', 'type', 'url']
+
+export function emitImage(node: AdfNode, path: ConvertErrorPath): Result<string> | undefined {
+  const image = imageShape(node)
+  if (image === undefined) return undefined
+  const mediaPath = [...path, 'content', 0]
+  if (image.alt === '') return failure('ambiguous-empty-media-alt', 'an empty media alt and an absent one share one image spelling', mediaPath)
+  return emitImageLine(image.alt, image.url, mediaPath)
+}
+
+function imageShape(node: AdfNode): { alt: string | undefined; url: string } | undefined {
+  const content = node.content ?? []
+  const media = content[0]
+  if (serializeCanonicalJson(node.attrs ?? {}, 'compact') !== centeredMediaSingle || (node.marks ?? []).length > 0) return undefined
+  if (media === undefined || content.length !== 1 || media.type !== 'media' || (media.marks ?? []).length > 0 || (media.content ?? []).length > 0) return undefined
+  const attrs = media.attrs ?? {}
+  const alt = attrs['alt']
+  const url = attrs['url']
+  if (Object.keys(attrs).some((key) => !imageAttributes.includes(key)) || attrs['type'] !== 'external') return undefined
+  if (typeof url !== 'string' || (alt !== undefined && typeof alt !== 'string')) return undefined
+  return { alt, url }
+}

todo.md

@@ -100,11 +100,16 @@ detail is settled at its own milestone.
       assumes — CommonMark flanking, as for `*` — which `spec/flavour.md` does not yet pin.
       `src/` gets its hierarchy at the same split — `adf/`,
       `markdown/`, `html/`, the grammar module shared inside `markdown/` — while the rename is
-      still mechanical.
+      still mechanical. `block-directives.ts` is the one file that does not move whole: the node
+      table is ADF knowledge milestones 6-7 need too and belongs in `adf/`, `spellDirectiveHeader`
+      in `markdown/`. The table is a second copy of `spec/flavour.md`'s prose with no drift guard,
+      and a mistyped attribute name degrades into a false refusal no test catches.
 - [ ] **4 — Round-trip property tests** over the corpus, both ways — the thing that proves 2 and
       3. Editor-normal (§2) gets its implementation here — `toEditorNormal(doc)` and the equality
       the round-trip asserts, which over normalized input is the canonical serializer's compact
-      spelling — rather than staying spelled inline as `?? []` at every reader.
+      spelling — rather than staying spelled inline as `?? []` at every reader. The reading half is
+      `nodeContent`/`nodeAttrs`/`nodeMarks` over the ~28 sites spelling it inline today, which also
+      lifts the branch floor §10 keeps below 100 for exactly those halves.
       Generators emit editor-normal ADF (§2). Real sanitized ADF from live Atlassian APIs lands
       here too (§10), in `corpus/real-payloads/`: an ADF→markdown→ADF check with no expected
       markdown, the payloads supplied by the maintainer.