Skip to content

v3.3.0 — duck_blocks 1.4: body is a subtree property

Choose a tag to compare

@teaguesterling teaguesterling released this 15 Sep 00:03
95a84e6

duck_blocks spec 1.4, additive on 1.3 (#35).

Body is a subtree property. 1.3 defined body per row, and a per-row predicate cannot see an ancestor: Pandoc-derived readers (docx, odt, org, epub, rtf, tex) emit metadata as a kind='value' container whose text lives in kind='inline' children, so duck_block_is_body said the container was not body and then said "Test Author" under it was. duck_blocks_to_text was clean because it walks the tree; every row filter leaked (panduck's #54 fixture, 2026-09-14). The definition is now:

a row is body  iff  kind IN ('block', 'inline') AND element_type <> 'metadata'
                    AND no ancestor by level is a value or metadata row
  • duck_blocks_body(blocks) -> LIST(duck_block), new: a value or metadata row roots a subtree; it and every following row at a greater level are dropped; the subtree ends at the first row at or above the root's level. Childless value rows and lone frontmatter blobs are dropped whole. A projection: element_order is kept. A scalar over the list, not a table macro (re-scanning a table function through CTE references returned zero rows on DuckDB 2.0, measured by panduck).
  • duck_block_is_body unchanged in its answers, documented as the necessary per-row half.
  • duck_blocks_to_text / to_match_text now level-scope the metadata blob as they do value trees, so to_text(blocks) = to_text(duck_blocks_body(blocks)) holds for a metadata block with descendants too.
  • Validation rule L6: a value tree's descendants sit strictly deeper than their root; an inline that closes a value subtree at exactly the root's level fails with field = 'list'. What validation cannot see is stated: an unindented MetaBlocks child is a block at the root's level.
  • PREDICATE_REVISION = "1.3" in the header: consumer drift checks compare constants by value and cannot see a predicate body; this constant changes when a predicate's answers do (rules in the header comment).
  • check_consumer_alignment reads sitting_duck's (main, SPEC_VERSION x.y) stamp form and reports an unreadable version claim instead of skipping it.

Consumers: re-vendor the header against this tag's commit (a copy on 1.3 reports PREDICATE_REVISION missing until it does). A consumer with native body filters keeps its own walk and adds a gated parity test against duck_blocks_body where both are installed; calling duck_blocks_body from a macro that must work without duck_block_utils would add a runtime dependency.

Verified: v1.5.5 matrix and the v2.0-cyanoptera line green on the PR; suite 1327 assertions / 18 cases; spec alignment OK. Tagged at 95a84e6.