Metadata Schema

NoKV’s durable metadata contract is path-native. PathCurrent is namespace truth; there is no canonical inode, dentry, parent-pointer, directory-record, or fallback path-index layer.

Schema Gate

Every logical-shard store has one authoritative marker:

System("schema")
  value_format_version = 1
  schema_id = "nokv_workspace"
  format_version = 10

Startup is fail-closed. Empty stores receive the exact supported marker and keyspace catalog. Non-empty stores open only when their marker, value format, and adapter catalog match format 10. Format 9 and older stores are rejected without writes; a marker-only upgrade cannot install the authoritative index families introduced by format 10.

Durable Identities

RootId                   16 bytes, globally unique
LogicalShardId           16 bytes, globally unique
WorkspaceIncarnationId   16 bytes, never reused
ArtifactRevisionId       16 bytes, unique within one RootId
SnapshotId                8 bytes, unsigned big-endian within one RootId
OperationId              16 bytes, unique within one RootId
CommitId                 32 bytes, root-global SHA-256 identity

RootId is the storage and routing identity. The control plane persists its logical-shard placement before the first write; paths never choose shards. Workbench names are presentation identities and map to never-reused workspace incarnations.

Paths are relative, case-sensitive UTF-8. The shared normalizer rejects empty, . and .. components, slash or backslash inside a component, and NUL; it applies no lossy cleanup, case folding, or Unicode normalization.

Workspace And Path Truth

WorkspaceCurrent
  key: RootId | workbench_id
  val: WorkspaceIncarnationId, workspace_revision,
       Staging | Visible | Retired, owning operation,
       created_version, modified_version

PathCurrent
  key: RootId | WorkspaceIncarnationId | normalized_relative_path
  val: path generation, ArtifactRevisionId, logical size,
       body and manifest digests, dependency bounds,
       content type, producer, manifest id, typed index projection

WorkspaceCurrent.state == Visible is the publication marker. Staging rows are absent from point, list, search, aggregate, catalog, snapshot, and watch results. A cold exact artifact lookup reads one visible WorkspaceCurrent and one PathCurrent; the path row already contains the immutable projection needed to return metadata, so reads do not fan out to ArtifactRevision.

Directories are implicit prefixes. Empty directory identity, stable inode numbers, POSIX timestamps, and hardlink semantics are not part of this schema.

Revisions, Manifests, And References

ArtifactRevision
  key: RootId | ArtifactRevisionId
  val: size, digests, block and dependency bounds,
       Available | Deleting | Deleted | Quarantined,
       reference epoch and strong-reference count

ArtifactManifest
  key: RootId | ArtifactRevisionId | object_index
  val: physical owner revision and object index, object key,
       logical/object ranges, digest, optional append segment

RevisionRef
  key: RootId | reference kind | owner id | ArtifactRevisionId

Each successful body publication creates a never-reused immutable revision. Current paths, durable commits, and reused-block dependencies own exact strong references. Adding or removing a reference updates its row, count, and epoch in the same metadata command. GC can claim only the current zero-reference epoch while the revision is Available; a claimed revision rejects new references.

See Object Layout for the provider-neutral block identity and deletion state machine.

Command And Replay Boundary

All durable mutations pass through one bounded MetadataCommand containing the root fence, predicates, mutations, typed event, history projection, and deterministic replay result. The active shard owner validates placement and owner epoch in the same physical transaction.

An exact request-id retry returns its stored result before evaluating a newer fence. Reusing a request id with different inputs fails. A failed predicate applies no mutation. These rules keep namespace publication, revision references, indexes, events, history, and recovery evidence on one write path.

Snapshots, durable commits, tags, and restore deliberately have different retention semantics. See Checkpoints, Commits, and Restore.