Module manifest 

Canonical manifest/object encodings and fsck rules for the immutable CAS.

Additive. Nothing in the existing object or wire paths reads or writes any of this yet. It is the upstream format definition the data-model reshape will build on (weft epic #1052, Phase 1: “Design canonical manifest/object encodings and fsck rules upstream in Heddle because object and wire formats belong there”). Cutover is a later phase, deliberately.

What is here

• node — the canonical manifest node: a 32-way HAMT keyed by (object kind, object hash), addressed by BLAKE3 of its canonical bytes. One logical node has exactly one byte string, so identical membership always yields an identical root.
• build — deterministic construction and expansion. Replacing one object rewrites only the old and new routes; every other subtree keeps its hash.
• binding — the (spool, facet, owner) -> content root binding, with owner identity deliberately outside the shared root.
• extent — the canonical pack-range claim: per-record BLAKE3 digests in offset-canonical order, covering a range gap-free.
• fsck — the integrity rules, each with a name.

The immutable/mutable line

A manifest node carries object kind, object hash, decoded size, trie structure, and subtree summaries — nothing else. Pack id, storage key, offset, encoded length, ETag, audience, and current head are mutable control-plane facts. They live in extent, resolved after authorization, so a repack changes a read envelope and never a manifest hash.

Compatibility

The node layout, the WPMF magic, the weft-plan-manifest-key-v1 routing domain, and the offset-canonical extent ordering are byte-identical to the already-merged downstream consumer (weft PR #1069 and its follow-up fix #1070, weft/docs/PLAN_MANIFEST_FORMAT.md). This module is the normative upstream definition of bytes that already exist downstream, not a second competing format — see the crate-level note in node on why the magic was kept rather than renamed.

Facet identity follows the ratified weft #358 decision: four uniform facets per spool, no content-bearing discriminant.

Modules

binding

Canonical manifest bindings — what ties a content root to an identity.

build

Deterministic construction and expansion of a canonical manifest trie.

extent

Canonical pack-extent claims — the physical half of the reshape’s read path.

fsck

fsck rules for a manifest/object graph.

node

Canonical manifest-node encoding — WPMF v1.

Structs

BuiltManifest

The output of a build: a root address plus every node byte string it reaches, deduplicated by address.

FsckFinding

One violation: the rule, where it was found, and a human-readable detail.

FsckOptions

What fsck should check beyond node structure.

FsckReport

Every finding from one fsck run.

ManifestBinding

An immutable (spool, facet, owner) -> content_root binding.

ManifestBranch

ManifestChild

A branch’s reference to one child subtree, with the summary that lets a planner size a subtree without descending into it.

ManifestFacetParseError

ManifestKey

The trie key: (kind, object_hash). Ordering is the canonical plan order — kind first, then the 32 hash bytes lexicographically.

ManifestLeaf

ManifestObject

One immutable content object named by a manifest leaf.

ManifestRoute

The fixed 256-bit route derived from a ManifestKey, read as successive 5-bit groups, most-significant bit first.

PackRangeAudit

What to check a pack claim against, beyond its own structure.

PackRangeClaim

One coalesced physical range read, plus the partition of authorized records it covers.

PackRecord

One object’s physical slice of a pack.

Enums

FsckRule

The named integrity rules fsck enforces.

ManifestBindingDecodeError

ManifestBuildError

ManifestDecodeError

Rejected while decoding node bytes. Each variant is a distinct corruption class and maps to a named fsck rule via ManifestDecodeError::fsck_rule.

ManifestExpandError

ManifestFacet

The four uniform spool facets from weft #358, plus an open named tail.

ManifestNode

ManifestNodeError

Rejected while constructing a node in memory.

ManifestObjectKind

The object types a manifest leaf may name.

ManifestOwnerKind

What a content root is bound to.

PackClaimDecodeError

Constants

MANIFEST_BINDING_MAGIC

Magic prefix on every canonical binding.

MANIFEST_BINDING_VERSION

The only binding format version this binary reads or writes.

MANIFEST_BRANCH_WIDTH

Branch fan-out — one bitmap slot per possible 5-bit route group.

MANIFEST_FORMAT_VERSION

The only manifest format version this binary reads or writes.

MANIFEST_LEAF_MAX_ENTRIES

Entries a leaf may hold before it must split into a branch, unless the route is already exhausted.

MANIFEST_NODE_MAGIC

Magic prefix on every canonical manifest node.

MANIFEST_ROUTE_BITS

Routing bits consumed per trie level (32-way branching).

MANIFEST_ROUTE_DOMAIN

Domain separator for the trie route. Hashed with the plan key to derive the 256 routing bits.

MANIFEST_ROUTE_LEVELS

Levels available before the fixed 256-bit route is exhausted (ceil(256 / 5)). A leaf at this depth may exceed MANIFEST_LEAF_MAX_ENTRIES because no routing bits remain to split it.

PACK_CLAIM_MAGIC

Magic prefix on every canonical pack-range claim.

PACK_CLAIM_VERSION

The only claim format version this binary reads or writes.

Traits

ManifestNodeSource

Read access to canonical manifest node bytes, keyed by node address.

ManifestNodeStore

Optional whole-store enumeration, used only to report nodes that are present but unreachable from a root.

ManifestObjectIndex

The set of content objects a manifest may legally name, with their decoded sizes.

Functions

build_manifest

Build the canonical manifest for objects.

expand_manifest

Expand a manifest root into its object set, in canonical plan-key order.

fsck_manifest

Check a manifest graph rooted at root for structure and digests only.

fsck_manifest_store

Check every root in roots against a whole node store, additionally reporting nodes no root reaches.

fsck_manifest_with

Check a manifest graph rooted at root, with optional object and reachability checks.

fsck_pack_range

Check that a coalesced pack range is offset-canonical, gap-free, and — when the caller supplies them — digest-correct and manifest-covered.