Skip to main content

Module cas

Module cas 

Source
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’s chunker.rs golden 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 legacy CasStore root, 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 Compartment vocabulary (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§

AllowAllCasAuthorizer
Explicit allow authorizer for tests and trusted local single-tenant wiring.
BlobManifest
The L1 manifest describing one stored blob.
BootstrapCasAuthorizer
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.
CasMountAuthzRequest
Authorization request made before a CAS operation.
CasMountGrant
One explicit authorization grant — the unit of policy the BootstrapCasAuthorizer evaluates (#1094).
CasSubstrate
The L1 unified content-addressed store.
DedupDomain
A dedup domain: content is only ever deduplicated against other content in the same domain. Keyed by:
DenyAllCasAuthorizer
Fail-closed authorizer used by CasMount::new.
InvalidDedupDomain
Error returned by DedupDomain::new when the (algorithm, digest_length) pair is not a well-formed multihash pair (e.g. sha1/32, blake3/48).
StagingConfig
Quota + lattice configuration for write-then-seal staging (#814).

Enums§

CasError
Errors from the L1 CAS substrate.
CasGrantSubject
Who a CasMountGrant applies to — the subject breadth axis the #1094 ratchet narrows.
CasMountObjectKind
Object class addressed through CasMount.
TrustBoundary
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 + read on CasMountObjectKind::Xorb only — stat, obj/* reads, and every stage/* 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§

CasMountAuthorizer
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::CasStore keys on.