Object Layout

NoKV keeps artifact bytes outside Holt. Metadata stores immutable revision and manifest records; an admitted S3-compatible provider stores the blocks.

Permanent Block Identity

nokv/artifacts/{logical_shard_id}/{root_id}/{artifact_revision_id}/blocks/{object_index}

The ids and object index use lowercase fixed-width hexadecimal. Process addresses, owner epochs, bucket endpoints, credentials, and Workbench names are absent. An object key is never reused for different bytes, and its logical identity survives movement between physical owners.

Revision And Manifest

Every successful body publication creates a never-reused ArtifactRevisionId. The revision records logical size, body and manifest digests, block count, bounded dependencies, content type, provenance, lifecycle state, and strong-reference state.

Each ordered ArtifactManifest row maps one logical range to a physical owner revision, physical object index, object key, object range, digest, and optional append segment. The manifest is immutable after publication. Range plans are derived from it and may be cached by revision identity.

Content digests establish identity and integrity. They do not claim provider-wide physical deduplication.

Publication

allocate operation and revision
  -> upload immutable blocks
  -> verify size, digest, and provider completion
  -> publish manifest, references, and PathCurrent in one fenced command
  -> acknowledge the deterministic result

Object upload alone never creates a namespace entry. If metadata publication fails, operation-owned staged objects remain available for explicit, recoverable cleanup. Exact request replay returns the same result and does not allocate another published revision.

A new revision may reuse blocks owned by older revisions. Before publication it seals one dependency reference for each distinct owner revision and verifies dependency count, depth, and digest. Those references prevent GC from deleting borrowed blocks while the child exists.

Reference Lifecycle And GC

Current paths and durable commit members own exact RevisionRef rows. Reference add/remove atomically changes the row, strong-reference count, reference epoch, and zero-reference candidate.

GC may claim a revision only when it is Available, its count is zero, its candidate epoch is current, retained history and operations permit deletion, and the current fenced shard owner performs the claim. Claimed revisions reject new references. Provider deletion advances through durable states; uncertain completion is quarantined and reconciled. Object listing is never reachability truth.

Provider Admission Boundary

A provider brand or static capability flag is not sufficient. Before business publication, write-conformance admission performs reserved, unreferenced test writes and verifies:

• fresh single-PUT create-if-absent;
• exact-byte replay and different-byte collision;
• whole-object and exact ranged readback;
• a concurrent different-byte create race with exactly one stored winner.

The receipt is bound to the exact provider handle and exercised single-PUT size profile. Admission v1 does not qualify multipart create, completion, or abort; those paths remain fail-closed. Credentials and endpoints are deployment configuration, never durable object identity.

See Metadata Schema for the authoritative metadata families and RustFS Backend for one local provider profile.