Skip to content

v3.4.0 — duck_blocks 1.4: the explicit document root

Choose a tag to compare

@teaguesterling teaguesterling released this 22 Sep 00:20
· 85 commits to main since this release
39941a7

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 metadata blob, a kind='value' row, any other block type, and every negative level.
  • TYPE_DOCUMENT added 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_blocks and duck_blocks_to_pandoc_ast share one writer, whose terminal fallback turned any unmapped element_type into a paragraph: an empty root became a blank Para (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.