heddle_object_model/object/manifest/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2//! Canonical manifest/object encodings and fsck rules for the immutable CAS.
3//!
4//! **Additive.** Nothing in the existing object or wire paths reads or writes
5//! any of this yet. It is the upstream format definition the data-model
6//! reshape will build on (weft epic #1052, Phase 1: *"Design canonical
7//! manifest/object encodings and fsck rules upstream in Heddle because object
8//! and wire formats belong there"*). Cutover is a later phase, deliberately.
9//!
10//! # What is here
11//!
12//! * [`node`] — the canonical manifest node: a 32-way HAMT keyed by
13//!   `(object kind, object hash)`, addressed by `BLAKE3` of its canonical
14//!   bytes. One logical node has exactly one byte string, so identical
15//!   membership always yields an identical root.
16//! * [`build`] — deterministic construction and expansion. Replacing one object
17//!   rewrites only the old and new routes; every other subtree keeps its hash.
18//! * [`binding`] — the `(spool, facet, owner) -> content root` binding, with
19//!   owner identity deliberately outside the shared root.
20//! * [`extent`] — the canonical pack-range claim: per-record `BLAKE3` digests
21//!   in offset-canonical order, covering a range gap-free.
22//! * [`fsck`] — the integrity rules, each with a name.
23//!
24//! # The immutable/mutable line
25//!
26//! A manifest node carries object kind, object hash, decoded size, trie
27//! structure, and subtree summaries — nothing else. Pack id, storage key,
28//! offset, encoded length, ETag, audience, and current head are **mutable**
29//! control-plane facts. They live in [`extent`], resolved after authorization,
30//! so a repack changes a read envelope and never a manifest hash.
31//!
32//! # Compatibility
33//!
34//! The node layout, the `WPMF` magic, the `weft-plan-manifest-key-v1` routing
35//! domain, and the offset-canonical extent ordering are byte-identical to the
36//! already-merged downstream consumer (weft PR #1069 and its follow-up fix
37//! #1070, `weft/docs/PLAN_MANIFEST_FORMAT.md`). This module is the normative
38//! upstream *definition* of bytes that already exist downstream, not a second
39//! competing format — see the crate-level note in [`node`] on why the magic
40//! was kept rather than renamed.
41//!
42//! Facet identity follows the ratified weft #358 decision: four uniform facets
43//! per spool, no content-bearing discriminant.
44
45pub mod binding;
46pub mod build;
47pub mod extent;
48pub mod fsck;
49pub mod node;
50
51pub use binding::{
52    MANIFEST_BINDING_MAGIC, MANIFEST_BINDING_VERSION, ManifestBinding, ManifestBindingDecodeError,
53    ManifestFacet, ManifestFacetParseError, ManifestOwnerKind,
54};
55pub use build::{
56    BuiltManifest, ManifestBuildError, ManifestExpandError, ManifestNodeSource, ManifestNodeStore,
57    build_manifest, expand_manifest,
58};
59pub use extent::{
60    PACK_CLAIM_MAGIC, PACK_CLAIM_VERSION, PackClaimDecodeError, PackRangeClaim, PackRecord,
61};
62pub use fsck::{
63    FsckFinding, FsckOptions, FsckReport, FsckRule, ManifestObjectIndex, PackRangeAudit,
64    fsck_manifest, fsck_manifest_store, fsck_manifest_with, fsck_pack_range,
65};
66pub use node::{
67    MANIFEST_BRANCH_WIDTH, MANIFEST_FORMAT_VERSION, MANIFEST_LEAF_MAX_ENTRIES, MANIFEST_NODE_MAGIC,
68    MANIFEST_ROUTE_BITS, MANIFEST_ROUTE_DOMAIN, MANIFEST_ROUTE_LEVELS, ManifestBranch,
69    ManifestChild, ManifestDecodeError, ManifestKey, ManifestLeaf, ManifestNode, ManifestNodeError,
70    ManifestObject, ManifestObjectKind, ManifestRoute,
71};
heddle_object_model/object/manifest/mod.rs

heddle_object_model/object/manifest/
mod.rs
