[cscheid]

Fixes #846. Braid strand bd-7gqr148v. Plan: claude-notes/plans/2026-10-15-lmd-ast-desugar-contract.md.

The problem

A .list-table or .definition-list div that an {lmd} cell built from nodes reached the writer as a div of nested bullet lists, because the reader's div desugar only ever ran over blocks the qmd reader produced. The fragment workaround failed from the other side: {=: ::: {.list-table} … :=} parses to a Table, and the lmd emitter had no Table arm.

The contract

The reader's postprocess mixes concrete-syntax clean-up with three structural rewrites that an author can also produce by constructing nodes: list-table div → Table, definition-list div → DefinitionList, single-image paragraph with alt text → Figure (pandoc's implicit_figures; applied at any depth, as pandoc 3.11 and the reader both do). This PR names that set as a contract: every block list that enters the pipeline other than through the reader is rewritten by it, exactly once. It is owed to lmd cell results, lmd fragments, pandoc.read(…, "json"), pampa's --from json, and document import. It is not owed to what user Lua filters return (pandoc and Quarto 1 parity). Written up in dev-docs/syntax-notes.md § Structural desugaring contract.

Changes, one commit per phase

1. Fixture desugar.qmd pinning the gap, snapshotted through the native HTML pipeline (--to markdown runs Quarto 1's own list-table filter and hides the bug).

2. pampa: new pandoc::desugar module (desugar_blocks / desugar_inlines / desugar_document) replacing transform_divs; the reader shares the per-node helpers so the two cannot drift; the Lua pandoc.read(…, "json") arm applies the set like the CLI and import paths.

3. lmd cells: execute_lmd_cells runs the set per cell over what the cell returned (block and inline cells, so a Note's blocks are covered). A Q-2-35 from a malformed cell-built list-table is relocated onto the cell's code with an info line:

   Warning: [Q-2-35] Invalid List-Table Structure
       ╭─[ desugar.qmd:94:1 ]
       │
    94 │ return pandoc.Div({ pandoc.Para({ pandoc.Str("not a list") }) }, pandoc.Attr("", {"list-table"}))
       │ ────────────────────────────────────────────────┬────────────────────────────────────────────────
       │                                                 ╰────────────────────────────────────────────────── list-table div's last block must be a bullet list (the rows)
   ────╯
   ℹ The node was built by this lmd cell.
   ℹ Check the list-table documentation for the correct structure?
   

4. Emitter: Block::Table is printed as pandoc.Table(caption, colspecs, head, bodies, foot, attr) in both modes, so pipe tables and list-tables work inside fragments. The tests and the errors.qmd fixture that used a pipe table as their unsupported example use a footnote definition instead.

5. Docs: the contract in dev-docs/syntax-notes.md; a section in the Lua filters guide; a note on the Q-2-35 page.

Tests

Eight unit tests for pandoc::desugar, six for the execute stage, three for the emitter, JSON and pandoc.read round-trips, and the desugar fixture (13 sections: literal controls, node-built shapes, fragment tables, invalid list-table, pandoc.read markdown and json, a list-table inside an inline cell's Note, a block cell nested in a fragment). Full cargo xtask verify green locally.

🤖 Generated with Claude Code

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.