Module read 

Reads (spec/surface/README.md §2): ref resolution, whole-document reads, block hydration at a resolution, the outline wire format, and the two path-ordered list surfaces. Port of packages/core/src/core/read/*. Result keys follow the reference’s spelling (id, path, raw, the row rule of §1.2; renderedHashMatch, …) — the fixtures are generated from it.

Structs

BlockNode

A live block with its children (the containment forest).

DocInfo

A live document’s identity (findDoc).

DocListRow

One row of docs_list (path in the storage form; the wire roots it).

Enums

Resolution

The resolution ladder.

ResolvedRef

resolve_ref’s answer.

Constants

LIST_DEFAULT_LIMIT

docs_list / docs_tree default page size.

MANY_CAP

Max refs honored per docs_read_many / blocks_read_many call.

Functions

block_raw

A block’s raw bytes by hex hash ("" when unknown).

blocks_read

§2 blocks_read: one block subtree at a resolution; None when the block is not live in doc_id.

blocks_read_many

§2 blocks_read_many: { nodes, truncated, unresolved }.

docs_list

§2 docs_list: { items, truncated, cursor }.

docs_outline

§2 docs_outline: { text, truncated }.

docs_read

§2 docs_read: { id, path, rev, properties, raw } (+ ids, hashes, parents with ids) — the document’s row attributes under the surface’s names (§1.2, 3.0); None for a missing doc.

docs_read_at

§2 docs_read { at } / docs_read_at (4.7): the document AS OF a revision — spec/store §6.2 reconstruct, the path as of the revision in the reference form. No properties: the properties table is current-state only (spec/properties), and recomputing the bag from the reconstructed bytes is not a one-call affair of the format layer (the inline fields come out of the ingest’s node projection) — so the time-travel read carries the bytes and nothing it would have to guess at (through 4.6 docs_read_at returned the CURRENT bag flagged propertiesAreCurrent: true). None when rev is not a revision of the (live) document.

docs_read_many

§2 docs_read_many: { items, errors, truncated }.

docs_tree

§2 docs_tree: { prefix, depth, total, entries, truncated, cursor }. The tree is built over the storage form and rooted on the way out, so the prefix (/ for the root), the entries and the cursor all speak the reference form (§1 “Paths”).

find_doc_by_id

A live doc by id.

find_doc_by_path

A live doc by repo + path, in either form (spec/surface §1 “Paths”).

find_doc_by_ref

The id-or-path dispatch every doc-ref surface routes through: a d_ id is looked up by id only (never falling through to a path).

first_words

The first n whitespace-separated words, … when cut.

load_doc_blocks

A document’s live blocks as an ordered forest (ORDER BY parent_block, order_key; a row whose parent is not live is a root).

normalize_tree_prefix

Normalize a tree prefix to its storage form: no leading /, and either empty or ending in / (either path form is accepted).

resolve_ref

§2 resolve_ref: an n_ node id → its live block, else its doc; a b_ id → its live block; a d_ id → the live doc; anything else → the live doc at that path; None when nothing matches.

token_cost

ceil(JSON length / 4): the token estimate every budget uses.