Expand description
L1 unified content-addressed store (CAS) substrate — #812 (epic #809, W1).
One content-addressed store under everything. Every artifact is addressed by a
self-describing multihash (hyprstream_rpc::cid), and every ingest is
partitioned into a dedup domain keyed (compartment, algorithm, digest_length, trust_boundary) so content is only ever deduplicated against
other content in the same domain.
§What this layer is
CasSubstrate absorbs cas_serve::CasStore (the write/reconstruct core
left behind the retired cas-serve binary) behind a domain-partitioned,
multihash-addressed facade. The registry putBlob/getBlob paths and the XET
get_xorb route reach the store through the substrate now, never a bare
CasStore::from_env().
- Chunking is unchanged: gearhash CDC via
cas_serve::chunker, byte-for-byte identical to xet-core (see that crate’schunker.rsgolden test). - Default algorithm is BLAKE3-256, aligning with the existing merklehash/xet substrate.
- On-disk layout for the default domain
(None, Blake3, Local)is identical to the legacyCasStoreroot, so existing stores and callers keep working byte-for-byte. Non-default domains get their own sub-root.
§Dedup domains (DedupDomain)
Content in different domains is never deduplicated together, because each domain is a distinct storage sub-root:
- compartment — tenant / need-to-know isolation, keyed off the existing MAC
Compartmentvocabulary (READ-only here — the substrate never authors or enforces MAC policy). - algorithm — SHA-1 content is never deduplicated against SHA-256; the pair would lean on the weaker collision resistance.
- digest_length — length is part of multihash/CID identity, so it is part of
the dedup key: BLAKE3 is an XOF and
BLAKE3-512(x)[0:32] == BLAKE3-256(x), so the two widths must not share a storage root (#812/#881 joint decision). Ingest is BLAKE3-256 today; a 512-bit width lands as its own root in #881. - trust_boundary — node-local content is never deduplicated against shared-remote content (an existence/content oracle across the boundary, U5).
§MAC boundary
A BlobManifest is a sealed, labeled object: its required
security_label is part of the bytes hashed into its CID. Staging may be
unlabeled, but it cannot seal until a label has been supplied.
Structs§
- Allow
AllCas Authorizer - Explicit allow authorizer for tests and trusted local single-tenant wiring.
- Blob
Manifest - The L1 manifest describing one stored blob.
- Bootstrap
CasAuthorizer - Enforcing authorizer for the live
GET /get_xorb/{hash}/surface (#1094): an explicit bootstrap grant list, default-deny, one audit event per decision. - CasMount
- CAS as a namespace mount.
- CasMount
Authz Request - Authorization request made before a CAS operation.
- CasMount
Grant - One explicit authorization grant — the unit of policy the
BootstrapCasAuthorizerevaluates (#1094). - CasSubstrate
- The L1 unified content-addressed store.
- Dedup
Domain - A dedup domain: content is only ever deduplicated against other content in the same domain. Keyed by:
- Deny
AllCas Authorizer - Fail-closed authorizer used by
CasMount::new. - Invalid
Dedup Domain - Error returned by
DedupDomain::newwhen the(algorithm, digest_length)pair is not a well-formed multihash pair (e.g. sha1/32, blake3/48). - Staging
Config - Quota + lattice configuration for write-then-seal staging (#814).
Enums§
- CasError
- Errors from the L1 CAS substrate.
- CasGrant
Subject - Who a
CasMountGrantapplies to — the subject breadth axis the #1094 ratchet narrows. - CasMount
Object Kind - Object class addressed through
CasMount. - Trust
Boundary - The storage layer / trust boundary a blob lives in.
Constants§
- AUTHENTICATED_
XORB_ READ - The day-one bootstrap grant: “any authenticated subject may read xorb
X” (#1094). Covers
open+readonCasMountObjectKind::Xorbonly —stat,obj/*reads, and everystage/*operation stay denied. - DEFAULT_
STAGING_ SLOT_ QUOTA - Default per-slot staging cap (256 MiB). Staging buffers are in-memory today; a spill-to-disk backing for truly huge ingests follows with the durable resource saga (#1064).
- DEFAULT_
STAGING_ SUBJECT_ QUOTA - Default per-Subject aggregate cap across all open staging slots (1 GiB).
- FILE_
RECONSTRUCTION_ CODEC - Multicodec for a sealed labeled blob manifest.
Traits§
- CasMount
Authorizer - Per-op authorization hook for
CasMount.
Functions§
- cid_
from_ merkle - Encode a legacy XET merkle hex digest as a canonical CIDv1 for the given algorithm, using the reconstruction-shard codec.
- merkle_
from_ address - Resolve a legacy caller-supplied reconstruction address to the hex digest the
underlying
cas_serve::CasStorekeys on.