Module store 

The storage contract (PRD §5.3): the key-level NamespaceStore, the content-addressed BlobStore, and the key layouts, value codecs and typed readers every backend shares. Nothing here needs SQL: a single-writer key-value store implements the whole contract.

Layers over the contract that work on any backend: the global ContentIndex, the portable logical export and import, and the optional StoreMaintenance and StateCommitment hooks.

The contract types are also re-exported at the crate root; keys, codec and read stay namespaced.

Modules

codec

Value codecs. Structured values are serde_json behind a leading version byte (CODEC_V1); refs are the raw 32-byte id and integers are raw big-endian. Decoding an unknown version, a wrong length or a value that fails validation is StoreError::Corrupt.

index

Repository-scoped, write-once object index rows. A row becomes visible only when its pack’s repository membership row exists. Production writers are installed by WP-4.7 and WP-4.8.

inspection_flags

Repository flags and their monotonic version share the canonical zero-id object-index partition.

inspection_holds

Repository-wide inspection holds; kind-14 work writes content rows after advance commit.

inspection_mode

One-way deployment inspection marker, checked before other startup writes.

keys

Key layouts: the registry of every row and index the server stores (reconciliation R-17). Indexes are layouts, not queries.

outbox

Pure reservation and outbox fragments. One guarded o row arbitrates Ticketed or Pending -> terminal; delivery removes that row only after acknowledgement.

publication

RefShard authority for paired publication and retained inspection obligations.

read

Typed readers over any NamespaceStore: the store::keys layouts and store::codec values in one place, so no backend reimplements them.

restore

Restore portable partition exports into a quiesced, fresh store.

tickets

Pure ticket/counter and ref-shard membership fragments. Callers supply time and read snapshots, compose these fragments with their ref/replay writes, and apply the complete batch in one partition.

view

Request-local read view. Every batched read remains one underlying store call.

watermark

Coordinator relay watermark and shard enumeration. The value is a lower bound on the commit time of every undelivered relay row. Consumers compare it against T + MAX_APPLY_WINDOW + margin. A new shard’s first report may be stale-low, so the namespace result can decrease without recovery; recovery can reset maxima too.

Structs

Batch

One atomic, declarative write: preconditions, then puts and deletes in order (a later write to the same key wins). A batch with no writes only checks.

BlobKey

A blob’s content hash and storage namespace. Pack RPCs construct only Pack keys, so an upload marker cannot be fetched as a pack.

BlobMeta

A blob’s metadata.

BlockEntry

A blocklist entry (PRD §6.7 takedown).

ByteRange

An inclusive byte range, as in HTTP Range.

ContentIndex

The ContentIndex layer over a store’s content shards. The store must accept every key class and atomic multi-key batches; otherwise every mutation fails with StoreError::Unsupported.

Cursor

An opaque scan cursor. Callers only pass back one that a NamespaceStore::scan returned for the same range.

ExportHeader

What an export was taken from.

ExportPage

One page of export_page.

ExportReader

Reads an export’s records from its bytes; see encode_export_record.

ExportRecord

One exported row.

ExportStream

The record stream of export_partition.

GcPlan

A GC delete plan from ContentIndex::collectable: one batch in the object’s shard, guarded on the state row it checked, that prunes the expired holds and sets deleting. Apply it with ContentIndex::commit_collect.

Holder

A repository that holds an object.

HolderOutcome

The result of ContentIndex::add_holder.

HolderPage

One page of ContentIndex::holders.

HolderRecord

A holder row’s value (R-131).

Importer

Restores exported records into a store, in batches within MAX_BATCH_OPS and MAX_BATCH_BYTES (so they fit Durable Object limits), one partition per batch; one write per batch on a store without atomic_multi_key. A partition’s records must be contiguous, as an export writes them.

Key

A key. Keys order by raw bytes; store::keys owns every layout.

ObjectState

An object’s state row. Absent means never indexed: no holders, no holds, last change at 0, not deleting.

PartRef

A stored part reference recovered from a server-authenticated receipt.

PartitionStats

Storage used by one partition.

PendingHolderV1

Identity of a pending extraction holder intent, stored under gp.

RangeScan

One ordered range in a batched scan. Its cursor belongs to this exact range, just as for NamespaceStore::scan.

ScanPage

One page of a NamespaceStore::scan.

StoreCapabilities

What a store supports. The pipeline plans around it. Start from StoreCapabilities::full or StoreCapabilities::refs_only and set fields: the struct is #[non_exhaustive], so later fields default safely.

UnsupportedPartSink

The sink type for backends whose multipart support arrives later.

Value

An opaque value. A backend never interprets it.

Enums

BatchOutcome

The result of NamespaceStore::apply.

BlobBody

A blob’s bytes, whole or streamed.

BlobNamespace

The physical namespace of a content-addressed blob.

CommitOutcome

How a PackSink::commit ended.

HoldOutcome

The result of ContentIndex::add_hold.

ImportMode

How an Importer treats a partition that already holds rows.

KeyClasses

Which key classes (store::keys) a store accepts.

MembershipMode

How repo membership of a pack is decided (overview Q16).

Partition

A storage partition: one D34 shard. Everything that must commit atomically lives in one partition. The core computes the partition of every operation; a backend maps partitions to whatever it likes (a Durable Object each, rows keyed by partition in SQLite, a qmdb instance each).

Precondition

A condition a Batch checks before it writes: raw key/byte checks, not the ref CAS. A planner decides a ref write with crate::refs::evaluate_condition on the value it read, then guards that read here (Absent or Equals on the ref key) so the decision still holds at commit.

StoreError

Why a storage call failed. A failed precondition is not an error: it is crate::BatchOutcome::PreconditionFailed.

Write

A write in a Batch.

Constants

CONTENT_APPLY_WINDOW_MS

How long a hold or holder batch may take to reach the store, from the now_ms its plan was made at (NotAfter, SPEC-WRITE-GRANTS §5.5). The same bound as MAX_APPLY_WINDOW.

EXPORT_END

End marker: a record whose partition length is 0. A reader requires it, so a truncated export never imports as a shorter one.

EXPORT_FORMAT_V1

The export byte format this binary writes and reads.

EXPORT_MAGIC

First bytes of every export.

INDEX_FANOUT

Object-id prefix fan-out of the content shards (and repo index shards): a fixed deployment constant, never resharded (PRD §5.3, D34).

MAX_BATCH_BYTES

Most key and value bytes, summed over a Batch’s preconditions and writes.

MAX_BATCH_OPS

Most preconditions plus writes in one Batch.

MAX_BLOB_PIECE_BYTES

Largest piece of a streamed BlobBody, and the longest body a BlobStore::get may return as one buffer.

MAX_BLOCK_REASON_BYTES

Longest BlockEntry::reason, in bytes.

MAX_HOLD_TTL_MS

Longest hold, from now_ms to its expiry: 24 hours. A hold must outlive MAX_APPLY_WINDOW plus the relay-lag bound (00-plan P-21, P-23); the cap stops a caller from pinning an object indefinitely.

MAX_KEY_BYTES

Longest accepted key, in bytes.

MAX_SCAN_RANGES

Most ranges accepted by one NamespaceStore::scan_many call.

MAX_VALUE_BYTES

Longest accepted value, in bytes; below MAX_BATCH_BYTES.

REF_INDEX_FANOUT

Ref-name hash fan-out: a fixed deployment constant, never resharded (PRD §5.3, D34).

Traits

BlobStore

A content-addressed, immutable blob store. Writes are put-if-absent; rewriting a present key with identical bytes is AlreadyPresent.

MultipartBlobStore

A resumable blob store with opaque storage sessions and verified parts.

NamespaceStore

The metadata store: a partitioned, ordered key-value store. Any backend that can do an atomic conditional multi-key write per partition and an ordered range read can implement it: SQL is not required.

PackSink

An in-progress blob upload.

PartSink

A verified, staged part. commit makes only this part durable; the pack remains invisible until MultipartBlobStore::complete.

StateCommitment

A future verifiable state root over a partition (R-21). Optional and unimplemented in the epic; the pipeline never requires it.

StoreMaintenance

Backend-defined maintenance (R-19). Optional: the pipeline never calls it. SQLite implements it with versioned physical migrations and VACUUM INTO (M0-09); another backend may implement it however it likes, and every backend still has the portable export above.

Functions

content_shard

The content shard of object: its top 12 bits.

content_shards

Every content shard, by construction (the Partition enumeration rule 5).

encode_export_header

The export header bytes: EXPORT_MAGIC, EXPORT_FORMAT_V1, the layout version (be32) and the export time (be64).

encode_export_record

One record’s bytes: partition length (be16, never 0) and Partition::encode bytes, key length (be16) and key, value length (be32) and value. An export is the header, its records, then EXPORT_END.

export_header

The header of an export of p taken at now_ms.

export_page

Up to limit rows of p after after, in key order: one stateless step of an export (a Durable Object serves it per call).

export_partition

Portable logical backup of one partition: its header and a stream of every row in key order. The stream is not a snapshot: rows written while it runs may or may not appear, so export a quiesced partition.

import_stream

Import a record stream (such as an ExportStream) taken under header; the number of records imported. Records carry their partition, so one stream may restore several partitions.

is_reserved_pack_keyspace

Whether keyspace (a pack keyspace, possibly with a deployment prefix) would alias a sibling namespace directory: its last segment is objects, object-offsets or upload-markers, or its last two are object-offsets/v1 or upload-markers/v1. Segments compare case-insensitively and ignoring trailing dots and spaces, since a case-folding or Windows-style filesystem maps them onto the same directory. Backends refuse such a keyspace at construction and in BlobKey::relative_path.

Type Aliases

BoxError

A boxed backend error: Send + Sync on native targets only, because Workers errors are !Send.