Product Design

NoKV is a distributed workspace and artifact store for multi-agent infrastructure. It gives datasets, scripts, logs, outputs, checkpoints, reports, and provenance stable path-shaped addresses while keeping immutable artifact bytes in S3-compatible object storage.

NoKV is not an AI training filesystem. Its product boundary is a metadata control plane for durable Agent workspaces: namespace truth, versioned publication, discovery, recovery points, lineage, retention, and safe object lifetime.

Supported Interfaces

The supported front doors, in delivery order, are:

1. the native full nokv CLI, including all 18 Workbench operations;
2. the direct Python SDK for embedded programmatic callers;
3. the Rust SDK for lower-level native integrations; and
4. the optional stdio MCP sidecar for hosts that require MCP discovery and JSON-RPC transport.

Downstream Agent systems normally provide skills that invoke the CLI. The Python SDK is the in-process alternative. The MCP sidecar delegates to the same transport-free Workbench facade; it is not a required deployment component, a canonical API, or a separate state machine.

Programs that require local files use explicit materialize/collect adapters. Those disposable sandbox paths are not NoKV namespace identities.

Deliberate Non-goals

NoKV is not:

• a FUSE mount, POSIX filesystem, CSI volume, or transparent fsspec backend;
• a general NAS replacement or raw S3 key browser;
• a semantic-memory database or Agent orchestrator;
• a runtime trace database; or
• a globally deduplicated content-addressed store.

It intentionally does not model inode/dentry, uid/gid/mode, hardlinks, symlinks, xattrs, locks, special nodes, arbitrary directory rename, empty directory identity, or random in-place writes.

Product Boundary

NoKV owns
  persisted RootId placement and owner fencing
  Workbench incarnation visibility
  normalized full-path namespace truth
  atomic publication and deterministic replay
  typed indexes and change events
  snapshots, commits, restore, references, retention, and GC

Object providers own
  physical artifact-byte durability and replication
  availability, access policy, and provider lifecycle behavior

Agent runtimes own
  planning, execution, semantic retrieval, and runtime policy

Object stores already provide durable byte storage. NoKV supplies the workspace metadata those stores do not: stable path identities, atomic generation changes, version-consistent discovery, reusable commits, leased recovery points, and reference-fenced reclamation.

System Shape

The metadata and object paths are separate. Small control and namespace records go through the fenced logical-shard owner. Clients stream immutable blocks through the object boundary after receiving an upload or read plan.

Core Data Model

Agent root
  RootId -> one persisted logical-shard placement

Workbench name
  -> one visible WorkspaceIncarnationId

Artifact path
  (RootId, WorkspaceIncarnationId, normalized relative path)
  -> PathCurrent

PathCurrent
  -> complete immutable metadata projection
  -> immutable ArtifactRevisionId

ArtifactRevisionId
  -> compact manifest
  -> immutable S3-compatible object blocks

PathCurrent is the only namespace truth. Directories are implicit prefixes, not stored inode/dentry objects. A never-reused Workbench incarnation prevents failed restore rows or retired workspace state from becoming visible under a later Workbench claim.

The path value projects the revision and manifest digests, size, content type, dependency bounds, and typed index fields needed by stat and list. An exact read is one ordered point lookup; a direct-child list is one component-safe delimiter scan.

Transaction Store Role

MetaShard owns workspace semantics. TxnStore supplies ordered reads and checked atomic writes. Holt is the current serving local adapter, not the product API.

NoKV metadata layer
  path and Workbench semantics
  command validation and idempotency
  visibility and secondary indexes
  snapshot, commit, restore, reference, and GC lifecycle
  root and owner fencing

TxnStore
  point reads and prefix/delimiter scans
  checked atomic multi-keyspace writes

HoltStore
  physical keyspace mapping
  synchronous local WAL
  checkpoints, views, and reopen recovery

Holt’s physical tree layout does not leak into metadata records, protocols, SDKs, Workbench tools, or object-provider contracts.

Immutable Bodies and Publication

The object layout is revision-owned:

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

Object bytes upload first. One owner-fenced metadata command then publishes the immutable revision, manifest, path generation, workspace revision, indexes, event, reference changes, and deterministic replay result.

Readers therefore observe the previous complete revision or the new complete revision, never a partial body. A response lost after commit can be replayed with the same request id. Failed or abandoned uploads remain invisible and are tracked by durable recovery state.

Whole-artifact replacement is the generic write primitive. Logs use immutable append segments plus a conditional stream-head advance. Range reads and multipart uploads remain first-class SDK operations.

Discovery and Provenance

Typed secondary indexes are updated atomically with the path entry. They support dataset and run lookup, parameter and metric filtering, lineage, commit discovery, search, aggregation, catalog, and Workbench finding.

Indexes are derived and repairable. Query results recheck the visible Workbench incarnation at the same read version; PathCurrent remains namespace truth.

NoKV is not the authority for high-volume runtime events. Traces may live in JSONL, SQLite, or a telemetry service. NoKV stores the durable artifacts and evidence an Agent needs to find, cite, snapshot, restore, and retain.

Recovery Products

Mechanism	Purpose	Retention
Leased snapshot	Short-term frozen MVCC recovery point	Read-version history hold until retire or reap
Durable commit	Immutable reusable dataset, run, or workspace tree	Exact artifact revision references
Durable tag	Mutable human name for a commit	CAS-protected pointer

Restore creates a new Workbench. It stages path metadata and exact revision references under a fresh incarnation, verifies the member closure, and makes the destination visible with one final marker transition. Normal reads do not pay for a lazy overlay chain.

Safe Object Lifetime

Every visible path and durable commit owns an exact strong reference to its artifact revision. Adding or removing a reference atomically changes the revision’s count and epoch. GC can claim only the current zero-reference epoch, and new references require the revision to remain available.

Snapshots and in-progress scans protect older metadata with leased history holds. Ambiguous provider deletions are quarantined instead of guessed. These guarantees remain root- and shard-local.

Distribution and Qualification

The control plane persists RootId -> LogicalShardId before the first write. One epoch-fenced active owner serves each logical shard. Placement is never recomputed from a filename, path prefix, or the current shard count, so owner movement does not change logical identity or object keys.

One root is not split across logical shards. Workbenches, queries, commits, snapshots, restores, references, and object GC remain local to that root’s shard. NoKV does not provide cross-shard transactions.

The current local profile acknowledges metadata writes after the owning shard’s Holt WAL boundary. Remote checkpoint/log recovery, shared metadata durability, multi-machine failover, production metadata HA, tenant identity and RBAC, and complete provider fault-injection qualification are not yet qualified. Source presence alone is not evidence for any of those properties.

The detailed behavior and current evidence live in the Architecture, Agent Interface, and Benchmarks and Evidence. The separate 2026 interface comparison is archived benchmark evidence, not a release-qualification result.