Skip to content

v3.2.0 — duck_blocks 1.3: the body predicate

Choose a tag to compare

@teaguesterling teaguesterling released this 13 Sep 04:51
079123d

duck_blocks spec 1.3, additive on 1.2 (#32).

The body predicate. The document's body, what a text renderer, indexer or embedder should see, is now defined once:

body(kind, element_type) := kind IN ('block', 'inline') AND element_type <> 'metadata'

It is not a kind filter. The verbatim metadata blob (frontmatter, tailmatter, a .yaml read whole) is kind='block' because it has a source position, and it is no more body than the kind='value' tree. Two conformant producers diverged on exactly that element: duckeye's text renderer printed a markdown file's frontmatter above its first heading while the same metadata from a .docx stayed out, and duck_blocks_to_text had the same leak (duckeye and markdown sessions, 2026-09-11).

Carried three ways so they cannot disagree:

  • Header: constexpr bool IsBody(kind, element_type), beside ImplicitParentOf; vendored copies get the rule with the constants.
  • SQL: duck_block_is_body(kind, element_type) -> BOOLEAN, NULL in, NULL out.
  • duck_blocks_to_text / duck_blocks_to_match_text no longer render the blob. This changes their output for a document carrying frontmatter or tailmatter: a fix to the reference tool, recorded in the header's history. raw is body and merely has no text rendering.

Design record: docs/superpowers/specs/2026-09-12-body-predicate-design.md.

Verified: v1.5.5 matrix green; DuckDB-main canary green on all 21 legs, dispatched against the branch before merge. Suite 1273 assertions. Tagged at 079123d.

Consumers: re-vendor the header against this commit and stamp "Vendored at upstream commit: 079123d (SPEC_VERSION 1.3)". A hand-written body filter becomes duck_block_is_body. Nothing else moves; 1.2 consumers are one minor behind, not broken.