Docs navigation

Docs Core

Architecture

How NoKV routes Agent workspaces through a fenced metadata control plane and stores immutable artifact bodies in S3-compatible storage.

NoKV is an Agent-native distributed workspace and artifact store. It exposes a path-shaped Workbench contract while keeping namespace authority, routing, artifact-byte durability, and Agent runtime policy in distinct layers.

The native full nokv CLI is the primary integration surface. The Python SDK serves embedded callers, the Rust SDK is the lower-level native boundary, and the exact 18-tool stdio MCP endpoint is an optional sidecar. These adapters share one transport-free Workbench facade and one storage architecture.

FUSE, POSIX emulation, CSI, and transparent fsspec access are not architecture layers.

System Shape

Downstream Agent skills -> native full nokv CLI
Embedded callers        -> direct Python SDK
MCP hosts               -> optional 18-tool stdio sidecar
                                  |
                                  v
                     Workbench facade / Rust SDK
                                  |
                                  v
             Root router -> fenced logical-shard owner
                                  |
                  +---------------+---------------+
                  |                               |
                  v                               v
       NoKV metadata semantics          immutable-object data path
                  |                      local soft cache + S3
                  v
              TxnStore
                  |
                  v
       HoltStore local adapter

Small control and namespace records go through the shard owner. Artifact blocks are streamed through the object boundary after the client receives a revision, upload, or read plan. The metadata path and object path therefore have separate authorities and failure modes.

Package Direction

Application surfaces
  nokv          native full CLI and optional MCP sidecar wiring
  nokv-python   direct Python SDK and materialize/collect adapters
  nokv-agent    transport-free Workbench facade and result shaping
  nokv-client   root-routed Rust SDK and immutable-object data path

Control and metadata
  nokv-types       storage-neutral workspace domain types
  nokv-protocol    versioned lifecycle and metadata RPC DTOs
  nokv-control     root placement, owner leases, and epoch fencing
  nokv-server      logical-shard owner and RPC composition
  nokv-meta        workspace commands, indexes, lifecycle, and GC
  nokv-meta-store  ordered transaction-store contract
  nokv-meta-holt   serving local Holt adapter

Artifact bodies
  nokv-object    S3-compatible provider I/O and local soft cache

Types and protocol remain storage-neutral. Metadata owns durable workspace semantics and logical keyspaces. Control owns placement and fencing, not path semantics. The object layer owns provider I/O, not reachability. Holt remains behind the TxnStore contract.

Identity and Namespace

RootPlacement(root_id)                    control-plane placement truth
RootFence(root_id)                        installed shard-local fence

WorkspaceCurrent(root_id, workbench_id)
  -> incarnation, revision, lifecycle

WorkspaceIncarnationClaim(root_id, incarnation)
  -> stable workbench_id; permanent and never reused

PathCurrent(root_id, incarnation, normalized_relative_path)
  -> generation, immutable revision, body and manifest digests,
     size, dependency bounds, content type, typed projection

RootId is the storage and routing identity. A Workbench presentation root shapes paths returned to an Agent, but never enters canonical metadata keys or grants storage authority.

PathCurrent is the only namespace truth. Paths are exact, case-sensitive UTF-8 and directories are implicit prefixes. Workbench names are separated from path keys by a never-reused incarnation, preventing staged or retired rows from appearing under a later Workbench claim.

See Metadata Schema for the detailed key and state contracts.

Publish Path

NoKV publish path: callers use the native CLI, direct SDKs, or optional MCP sidecar to reach a fenced logical-shard owner for metadata. The client uploads artifact bytes directly to S3-compatible storage before one metadata command publishes the generation through TxnStore and the HoltStore adapter. Agent-facing caller CLI / SDKs / optional MCP Shard owner root + epoch fenced MetadataCommand TxnStore / HoltStore S3-compatible artifacts
Publish path — the client uploads immutable artifact bytes directly to object storage, then one owner-fenced metadata command publishes the new Workbench generation.

A publication reserves an immutable revision and object plan. The client streams artifact blocks first. The shard owner verifies completion evidence, then one owner-fenced metadata command atomically publishes:

  • the revision and compact block manifest;
  • the new path generation and Workbench revision;
  • exact strong-reference changes;
  • typed secondary indexes and one change event;
  • any GC candidacy for a replaced revision; and
  • the deterministic request-replay result.

Failed uploads never become visible. Readers observe the previous complete revision or the new complete revision. A response lost after commit returns the same result when the exact request is replayed.

Generic random writes are absent. Whole-artifact replacement is conditional, and append publishes immutable segments before advancing a stream head with compare-and-swap.

Read and Discovery Paths

An exact read resolves the visible Workbench incarnation and performs one authoritative PathCurrent lookup at a fenced read version. It returns a generation and immutable block plan; the client then reads and verifies ranges through the object provider or local soft cache.

A direct-child list uses an ordered, component-safe delimiter scan rather than inode-to-dentry traversal. Search, aggregate, catalog, and find use derived typed indexes at one read version and recheck the visible Workbench incarnation. Indexes remain repairable; they never replace PathCurrent as namespace truth.

Opaque cursors bind their Workbench scope, selector, continuation fence, and last returned item. Snapshot continuations stay at one retained read version. Live continuations fail closed if the target Workbench incarnation or revision changes.

Workbench Lifecycle

The exact 18-tool Workbench surface is shared across the native CLI, direct SDKs, and optional MCP sidecar. Tool names define behavior, not a required transport.

NoKV exposes three distinct retention mechanisms:

  • Leased snapshots hold one MVCC read version for short-lived recovery.
  • Durable commits retain an immutable workspace tree and its exact artifact revisions without pinning the global history floor.
  • Durable tags are compare-and-swap protected names for commits.

Restore is same-root and same-shard. It stages a fresh Workbench incarnation, adds exact revision references, verifies the member closure, and makes the destination visible with one final marker transition. The source remains unchanged and no object bytes are copied.

Revision Ownership and GC

Artifact object identity is logical rather than tied to a physical process:

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

Every visible path and durable commit owns an exact RevisionRef. Revisions that reuse older blocks retain sealed dependency references to their owner revisions. Reference changes increment an epoch; a zero-reference GC candidate is valid only for that epoch.

GC claims only the current zero-count epoch and moves an available revision to deleting atomically. New references also require the revision to be available, which closes restore/commit/publication races with deletion. Ambiguous provider deletes are quarantined rather than guessed.

Sharding and Ownership

The control plane persists placement before a root’s first write:

RootId -> immutable LogicalShardId
LogicalShardId -> current physical owner, lease, epoch

The owner installs a matching shard-local root fence and checks its lease epoch at the metadata commit boundary. Placement is never inferred from a path or recomputed from the number of owners.

One root is not split across logical shards. Its Workbenches, queries, commits, snapshots, restores, references, and GC remain local. A logical shard may move to another physical owner under a new epoch without changing root, revision, or object identity. Cross-shard operations fail before partial work.

Durability and Qualification

In the default local profile, an acknowledged metadata write is synchronous at the owning shard’s Holt WAL boundary. The same command also records canonical, hash-chained replay material in that store. Unknown, mixed, or unverified successor stores fail closed rather than being admitted as an owner.

These are shard-local guarantees. NoKV does not provide cross-shard transactions. Snapshot protection is leased, and Workbench or root scoping is not an authentication or RBAC boundary.

Remote checkpoint/log recovery, shared metadata durability, multi-machine failover, production metadata HA, tenant identity and RBAC, and complete provider fault-injection qualification remain not qualified. The presence of source code, schemas, or isolated tests does not establish those properties.

Operational limits and evidence should be evaluated against the current Product Design, Benchmarks and Evidence, and the canonical repository revision used for a deployment. The separate 2026 interface comparison is archived benchmark evidence, not a release-qualification result.