Repository navigation
v3.4.0 — duck_blocks 1.4: the explicit document root
duck_blocks spec 1.4, amended in place. SPEC_VERSION stays 1.4 and PREDICATE_REVISION stays 1.3: this release adds one constant and makes a previously-refused shape legal, so no consumer is forced to re-vendor.
The explicit document root
Level 0 is now the optional explicit document root: a kind='block', element_type='document' row standing for the document itself. Everything else still starts at 1, so every document valid before this release is valid after it.
- Several roots are permitted in one relation, legal wherever they appear. A file may hold more than one root document; a document has exactly one root; file-to-document is usually but not always 1:1.
- A root carries no content. It is structure. File-scoped facts — a filename, an ordinal, a byte offset distinguishing same-file documents — go in
attributes, and the validator rejects content on a root. - Still rejected at level 0: a
metadatablob, akind='value'row, any other block type, and every negative level. TYPE_DOCUMENTadded to the vocabulary header (97 constants).
The root exists because a consumer whose contract is "these rows are one tree" needs a single root to point at, and prepending one row is cheaper and safer than renumbering levels — shifting every level down by one makes every top-level block a root, which is a different document.
Fixes
- The Pandoc writers no longer fabricate prose for a root.
duck_blocks_to_pandoc_blocksandduck_blocks_to_pandoc_astshare one writer, whose terminal fallback turned any unmappedelement_typeinto a paragraph: an empty root became a blankPara(one per root, which real pandoc accepts and renders as a blank line), and a content-carrying root had its text emitted as document prose. Roots are now skipped. Found by panduck measuring the identical fallthrough in their own writer. - Several roots concatenate rather than refuse when converting to Pandoc JSON, which is a single document. The boundary is lost in the output format, not in the relation.
Consumer alignment checker
- Reads integer constants, not only strings — a stale struct offset was previously invisible.
- Enforces major equality plus a minor floor: an older same-major minor reads as BEHIND and passes, instead of forcing a fleet-wide re-vendor on every additive change.
- Compares provenance byte-exactly (both reads are raw bytes; universal newlines previously let a CRLF copy pass).
- Labels the checkout it actually measured, rather than a sibling directory.
Also
- Every scalar that can raise an execution error now has a test pinning its error class, so a lost
SetFallible()fails the DuckDB 2.0 leg instead of passing silently. - duck_block_utils functions are discoverable from
duckdb_functions()with descriptions and examples.
Verified
Format-check clean, build clean, full suite green (1356 assertions, 18 files) on the pinned DuckDB d8cdaa33 (v1.5.5), and CI green on the release commit.