Reference

Storage protocols¶

Required semantics¶

Required semantic	Why it matters
Compare-and-swap revision	Prevent stale writers from silently winning
Tenant-and-space-scoped reads	Keep stored revisions inside their isolation boundary
Immutable history	Reconstruct what was known at a prior time
Disposable indexes	Rebuild derived state from canonical artifacts

The included store defines reference semantics. Measure production database adapters for throughput and verify the same behavior.

Compare-and-swap examples

Current revision	Expected revision	Mutation result
None	None	Initial commit succeeds
`r1`	`r1`	Update to `r2` succeeds
`r2`	`r1`	`RevisionConflict`
Tenant A artifact	Tenant B scope	Hidden by scope filter

DocumentStore and ArtifactStore specify observable behavior. InMemoryDocumentStore and InMemoryArtifactStore implement the reference semantics. Store keys include tenant, space, and structural object identity. Artifact history supports point-in-time reads by recorded_at, independent of commit order.

How it works¶

Protocols specify behavior that callers can observe. Each implementation declares compare-and-swap, history, point-in-time reads, and scope isolation through StoreCapabilities. Cross-store operations use an application transaction or outbox boundary. Each database keeps its own commit semantics. Indexes remain disposable projections built from documents and artifacts.

Research basisInvariant confluence shows that safe coordination depends on application invariants. Mari specifies atomicity and replay through observable behavior. Isolation, time travel, and deletion each have explicit capability fields. The protocol split is a Mari library design.

Compare-and-swap revisions with explicit lineage¶

from mari_kit.platform import InMemoryArtifactStore, RevisionConflict
from mari_kit.testing import assert_artifact_store_conforms

store = InMemoryArtifactStore()
store.commit(first_revision, expected_revision=None)

try:
    store.commit(second_revision, expected_revision="stale-revision")
except RevisionConflict:
    refresh_and_retry()

current = store.get("fact:refund-window", scope=scope)
historical = store.at_time(
    "fact:refund-window",
    scope=scope,
    known_at=query_time,
)

# Run this same suite against a production adapter factory.
assert_artifact_store_conforms(InMemoryArtifactStore)

InMemoryArtifactStore rejects duplicate artifact revisions and uses deterministic ordering. It provides point-in-time reads, tenant-and-space isolation, and atomic revision checks. assert_document_store_conforms and assert_artifact_store_conforms exercise the public adapter contract.

For a retry after an uncertain commit, read the current revision and reconcile it with the attempted write before issuing another commit. Subsequent artifact revisions must explicitly supersede the current revision. Authorization and evidence validation remain application checks.

When persisting dependency receipts, commit the output and receipt atomically against the input snapshot. Remove a receipt when its reusable output is evicted. A receipt is a record of available completed work, so output availability is part of the storage contract.