M0 typed primary-memory provider contract

Contract status: Accepted. M0 was accepted after independent architecture review and correction closure.

Implementation status: Not started. This document does not implement or authorize a primary-memory provider, provider substrate, persistence schema, migration, or rollout.

M0 specializes the D1 kernel invariants and provider control-plane contract for durable primary memory. D1 is Accepted and I0 is Accepted; this contract depends on those decisions and does not reopen either one. It defines the exclusive provider boundary behind Tyrum's current memory behavior while keeping identity, governance, canonical outcomes, and audit in the kernel.

Quick orientation

• Read this if: you are reviewing the typed provider boundary for durable agent memory, its source of truth, or a future memory-provider cutover.
• Skip this if: you need current tool or operator behavior; start with Memory.
• Go deeper: use D1 for common control-plane semantics, ARCH-29 for dependency order, and the memory consolidation page for current retention intent.

The diagram is target contract, not implemented runtime flow.

Decision summary

Tyrum will define one provider kind, tyrum.provider.primary-memory, at initial ProviderContractVersion 1.0.0. Its serving cardinality is exclusive: one tenant-agent memory scope has exactly one active provider binding and one authoritative canonical data set at a time.

The provider performs typed persistence, retrieval, deletion, retention, portability, and recovery operations. The kernel owns the scope and item identities, authorization, policy and approval, operation requests, sensitivity and provenance rules, budgets, binding epoch, canonical operation outcome, final prompt use, and audit. A provider result is evidence the kernel validates; it is not authority to expose a tool, use recall, approve a mutation, or create audit truth.

The first later implementation sequence remains:

1. represent the current built-in SQL-backed behavior through the M0 contract without copying its canonical data;
2. route current memory call sites through that built-in binding while preserving public behavior;
3. move canonical data only under a separately approved, fenced source-of-truth migration.

M0 defines that boundary. It is not evidence that any provider catalog, binding, adapter, or migration exists.

Current truth

The current implementation has no primary-memory provider control plane or binding record.

• Canonical memory records are tenant- and agent-partitioned SQL rows for fact, note, procedure, and episode items, with stable item IDs, sensitivity, provenance, tags, timestamps, and kind-specific content.
• Deletes remove an item and atomically create a minimal tombstone. Operator routes can list, get, search, delete, and list tombstones.
• memory.seed builds bounded attributed pre-turn recall; memory.search performs bounded in-turn recall; memory.write creates durable items. The mcp.memory.* forms remain compatibility aliases during their documented deprecation window.
• pre_turn_tools and MCP metadata control hydration and memory-role integration. They do not admit or select a primary-memory provider.
• Structured and keyword retrieval read canonical records. Semantic vectors are derived, omit sensitive records in the built-in path, may be rebuilt, and already degrade independently.
• A successful item insert is durable before subsequent consolidation or semantic-index refresh. A later consolidation or indexing failure can therefore occur after the item exists.
• Consolidation is budget-driven: it deduplicates facts, may summarize episodes, drops derived indexes, then evicts lower-utility items with tombstones. Temporary over-budget state is possible; inactivity TTL is not the forgetting rule.
• Gateway snapshot export/import includes memory items, provenance, tags, and tombstones. Import is operator-gated, transactional, and currently requires selected target tables to be empty.
• The built-in StateStore supports SQLite and Postgres. Canonical item changes use database transactions; no external-provider durability, recovery, or conformance path exists.

The target contract must preserve these truths during adoption and must not describe provider behavior as current implementation.

Goals

• define one narrow primary-memory contract, not a universal operational provider interface;
• make the tenant-agent source of truth exclusive, deterministic, operator-selected, and immutable for one binding epoch;
• preserve current memory tools, pre-turn hydration, administration, scopes, item kinds, provenance, tombstones, and useful degraded recall;
• state exact consistency, idempotency, ambiguity, deadline, cancellation, retention, recovery, and no-fallback rules;
• permit provider-native retrieval and indexing without making indexes, ranking, or provider storage authoritative policy;
• preserve current built-in behavior through the same admission, binding, health, and conformance path required of external implementations;
• define a portable, fenced migration path that cannot create split brain.

Non-goals

• no M1 built-in adapter, M2 call-site/data migration, provider implementation, or rollout;
• no provider schema, database table, migration, registry service, marketplace, dynamic hot reload, or distributed lifecycle;
• no universal Provider, read, write, or execute interface shared with other provider kinds;
• no new model-facing memory tool or provider-selection argument;
• no alternate turn executor, context assembler, authorization path, approval store, audit authority, or identity system;
• no conversation-, workspace-, turn-, query-, discovery-, health-, or model-selected primary-memory routing;
• no additive/fan-out recall across independent primary stores and no silent fallback store;
• no provider-authored retention policy, sensitivity decision, provenance authority, or prompt instruction;
• no public item-update operation: current stable model and operator surfaces do not expose one;
• no claim that MCP, a plugin, a remote service, an embedding model, or a database name is itself provider admission or conformance.

Scope, identity, cardinality, and selection

M0 defines ProviderKindId tyrum.provider.primary-memory, uses the remaining D1 identities unchanged, and adds memory-specific durable identities:

Identity	Meaning
MemoryScopeId	Kernel-owned canonical durable memory resource for exactly one (TenantId, AgentId) tuple.
MemoryProfileRevisionId	Immutable operator-authored or compatibility-materialized selection revision for one memory scope.
MemoryBindingEpoch	Kernel-issued monotonic epoch that identifies one period with one active immutable provider binding.
MemoryScopeRecordId	Stable kernel recovery record allocated before provider-owned scope effects.
MemoryMutationId	Kernel-issued idempotency identity for exactly one write or delete request.
MemoryScopeRevision	Provider-issued, binding-epoch-local monotonic revision after a committed canonical mutation.
MemoryRetentionRunId	Kernel-issued idempotency identity for one resumable enforceRetention request.
MemoryExportId / MemoryImportId	Kernel-issued identities for one resumable full export or import under one migration authorization.

The serving selection key is exactly (TenantId, AgentId, ProviderKindId). Workspace, conversation, thread, turn, memory item, operation, retrieval query, provider discovery, and model input are not selection scopes. Tenant identity remains part of every access check even when an operator UI filters only by agent.

The provider kind's cardinality is exclusive: for each MemoryScopeId, the kernel records exactly one active ProviderBindingId, exact provider release, and MemoryBindingEpoch. Ordered-many, additive, fan-out, capability-routed, and model-routed composition do not apply. Historical or non-serving migration bindings may exist as evidence, but they cannot answer serving reads or accept serving mutations.

Selection comes only from one operator-authored memory profile resolved for the tenant-agent key. During compatibility adoption, the kernel may deterministically materialize one immutable built-in profile from the existing agent-owned server_settings.memory configuration. An explicit profile and a synthesized compatibility profile cannot both be active. Zero active revisions, multiple active revisions, duplicate revision identities with different content, or conflicting candidates fail closed; there is no precedence rule among conflicts.

The resolved profile pins the exact D1 implementation/version/ProviderReleaseId, provider configuration and conformance evidence, trust and deployment mode, authenticated peer where applicable, provider-native data-namespace reference, portability capability, durability posture, and declared operation maxima. Kernel-owned exposure, recall budgets, allowed sensitivities, retention policy, and final prompt rules are carried by separate immutable policy revisions and do not let a provider select itself.

The model cannot select or influence provider identity, implementation version, release, configuration, deployment mode, data location, binding epoch, fallback, migration candidate, or durability posture. None may appear in model-supplied tool arguments. M0 v1 has no fallback list. An unavailable exact binding fails closed rather than selecting the built-in or another installed implementation.

One binding epoch is immutable. Discovery, registration order, a newer release, configuration changes, health, provider self-priority, or an agent-config edit cannot rewrite it. A change that alters storage identity or cannot recover the existing namespace requires the migration/cutover procedure. A compatible release, configuration, trust, or deployment-posture change that preserves the exact admitted persistence-equivalence identity may instead use the same-namespace epoch-rollover procedure in the lifecycle section; it never rewrites the active epoch in place.

Setting current memory exposure to disabled may omit memory.seed, memory.search, memory.write, and pre-turn hydration. It does not erase an existing corpus, change its binding, or make authorized operator deletion and export silently unavailable.

Public compatibility boundary

The existing model-facing capability family remains:

• memory.seed — bounded attributed recall for pre_turn_tools pre-turn hydration;
• memory.search — bounded in-turn recall with kind/tag/limit filters;
• memory.write — create one fact, note, procedure, or episode with current kind-specific fields.

The mcp.memory.seed, mcp.memory.search, and mcp.memory.write spellings remain compatibility aliases only for the existing rollout window. Canonical policy, approval, provenance, and used-tool identity remains memory.*. MCP may transport an admitted provider operation, but MCP metadata, server discovery, and pre_turn_tools order are context integration—not provider admission, provider selection, or a second source of truth.

Current argument meaning, item kinds, public/private model-write sensitivity, provenance linkage, bounded result behavior, and pre-turn injection remain compatible unless separately changed. The kernel continues to format prompt-ready recall and places it in untrusted data boundaries; the provider never writes directly into the prompt.

The current tenant-authorized operator administration remains supportable: list items, get an item, search items, delete one item with a reason, and list tombstones, including current filters and cursor pagination. Existing gateway snapshot export/import remains supportable through a built-in adapter over the portable transfer operations. HTTP route shapes and snapshot wire format are not themselves the provider protocol.

No new model-facing tool is added. read, scan, query, retention, export, import, mutation inspection, binding, and migration are internal typed operations or kernel workflows. Provider identity and degraded-state diagnostics may be exposed only through safe operator status and audit surfaces.

Tool exposure, policy matching, approval reuse, mutation access mode, tenant/agent authorization, and the native turn state machine remain kernel-owned. A provider outage cannot cause another provider's tool to appear, and a provider cannot ask the model to choose a backend or supply credentials.

Canonical memory data

The kernel defines and validates the canonical logical record vocabulary passed across the provider boundary:

• item identity, MemoryScopeId, tenant and agent references;
• item kind fact, note, procedure, or episode and the current kind-specific fields;
• sensitivity public, private, or sensitive subject to caller-specific policy;
• normalized tags, canonical timestamps, confidence where admitted, and version metadata;
• provenance source kind and bounded channel/thread/conversation/message/tool-call references;
• tombstone item identity, deletion time, deleting authority class, reason, and retention class;
• kernel policy, approval, correlation, and audit linkage references that carry no authority for the provider.

The kernel allocates canonical item and mutation identities and validates all records before dispatch and again on return. A provider may use internal row keys, object locators, vector IDs, or index metadata, but those are provider-native and never replace canonical IDs. Provider-native ranking scores and cursors are bounded evidence, not stable cross-provider identities.

Provider-generated consolidated records use a kernel-authorized item identity, allowed transformation class, sensitivity floor, and provenance template that references replaced items. The provider cannot silently rewrite an item, change sensitivity, fabricate user provenance, or remove a canonical record outside an accepted typed mutation.

Kernel-owned responsibilities

Tyrum owns and enforces:

• tenant, agent, MemoryScopeId, item, mutation, retention, migration, binding-epoch, actor, conversation, and tool-call identity;
• authentication, authorization, policy, approval, mutation-access mode, quotas, and tool exposure before provider dispatch;
• D1 registration, compatibility, trust, conformance, deterministic selection, active-epoch cardinality, and immutable binding;
• canonical tool exposure, recall and prompt budgets, provenance requirements, sensitivity decisions, secret exclusion, and content limits;
• allowed sensitivities, source attribution, provider-result validation, redaction, and final prompt/context use;
• retention-policy revisions, permitted consolidation transformations, tombstone/audit retention, erasure authorization, and migration authorization;
• absolute operation and settlement deadlines, cancellation intent, retry/reconciliation decisions, and shutdown sequencing;
• canonical operation states and outcomes, including committed, not_committed, unknown, partial retention/import progress, and unavailable recall;
• canonical audit events, safe operator status, unavailable reasons, migration gates, and rollback authority.

Provider reports cannot directly expose a tool, authorize a caller, approve a write/delete/import, lower sensitivity, change provenance, mark a kernel operation successful, replace a binding, use recall in a prompt, or create canonical audit state.

Provider-owned responsibilities

An admitted primary-memory implementation owns only the persistence, retrieval, derived-index, retention, and recovery mechanism inside its typed boundary:

• map the exact bound MemoryScopeId to one provider-owned durable namespace and recover that mapping under the pinned release/configuration;
• persist canonical items, tombstones, mutation outcomes, scope revisions, and retention/import checkpoints with the contracted consistency and durability;
• perform bounded exact reads, deterministic scans, and provider-native structured/keyword/semantic retrieval over only the bound scope;
• maintain, invalidate, rebuild, and report derived indexes without making them canonical data;
• apply accepted writes and deletes idempotently and report commit certainty truthfully;
• execute only kernel-authorized retention transformations, return their full mutation evidence, and resume partial runs safely;
• produce and consume portable canonical export/import streams for backup compatibility and fenced migration;
• back up, restore, compact, and recover provider-native persistence within its declared durability and data-residency posture;
• enforce request authentication, correlation, replay protection, deadlines, cancellation, message/resource bounds, and least-privilege secret projection for admitted deployment modes;
• emit bounded, redacted diagnostics and operation-specific health/capability evidence.

The provider cannot authorize memory access, evaluate policy or approvals, choose a retention rule, infer another agent scope, serve a different binding, create a canonical audit event, silently retain undeclared canonical copies, or treat an index/cache as a fallback source of truth.

Typed domain operations

M0 defines the following complete v1 operation family. These are not methods on a universal provider interface and are never model-facing tools.

Operation	Effect	Contract
read	Read-only	Read exact item or tombstone identities at or after a requested scope revision; distinguish found, tombstoned, and absent from unavailable.
scan	Read-only	Return a deterministic bounded page of canonical items or tombstones from one consistent snapshot for operator list and migration verification.
query	Read-only, possibly degraded	Return bounded attributed candidates for memory.seed, memory.search, and operator search with per-mode completeness/freshness evidence.
write	State-changing, idempotent	Create exactly one kernel-issued canonical item and commit its mutation outcome atomically; it does not imply retention completed.
delete	State-changing, idempotent	Atomically make one exact item non-readable and create or return its canonical tombstone.
enforceRetention	State-changing, resumable	Apply one kernel-issued retention-policy revision through journaled permitted transformations and return complete or explicit partial progress.
exportScope	Read-only, resumable	Export one consistent full snapshot of canonical items and tombstones for current snapshot support, backup, or fenced migration.
importScope	State-changing, resumable, non-serving only	Import one validated portable stream into an empty non-serving staging namespace and report a destination digest and revision.
inspectMutation	Read-only reconciliation	Return the persisted outcome/checkpoint for one exact operation-specific idempotency identity after an ambiguous reply or restart.

read and scan justify current operator get/list/tombstone behavior. query is the single provider retrieval seam behind seed and search; the kernel still applies sensitivity, budgets, attribution, redaction, and final formatting. write and delete preserve current create/delete behavior. enforceRetention represents current budget enforcement without turning policy over to the provider. exportScope and importScope are required because current snapshots carry canonical memory and because an exclusive source-of-truth move cannot be safe without portable transfer. inspectMutation is required to resolve ambiguous state-changing outcomes without issuing a second effect.

There is no v1 update operation. Current stable model tools and operator routes do not expose update, and retention can create a replacement plus tombstone under one journaled run. Adding direct update requires a later contract change defining optimistic concurrency, provenance replacement, index invalidation, and public compatibility.

Every request carries the exact binding/epoch, scope and operation identity, canonical actor/correlation references, absolute deadline, cancellation reference, bounded limits, and applicable policy/approval revisions. A state-changing request carries exactly one top-level operation-specific idempotency identity plus a canonical request digest: MemoryMutationId for write or delete, MemoryRetentionRunId for enforceRetention, and MemoryImportId for importScope. The identity is scoped to the exact binding, epoch, scope, operation, and digest; one request never aliases another operation's identity. inspectMutation accepts the corresponding typed identity and returns only that operation's outcome or checkpoint. Out-of-process requests use the confidential authenticated protocol admitted under D1.

Source of truth and consistency

For one active binding epoch, the bound provider's canonical namespace is the sole source of truth for memory items, tombstones, accepted mutation outcomes, and MemoryScopeRevision. The kernel remains source of truth for the active binding, identity and authorization, policy/approval decisions, canonical operation outcomes, migration state, and audit. This assignment makes provider persistence authoritative content storage; it does not delegate canonical semantics or governance.

A kernel cache, prompt digest, search result, embedding/vector store, export artifact, migration staging copy, provider log, or snapshot package is not a serving source of truth. A derived index is rebuildable from canonical items and tombstones. Losing an index may degrade a query mode but cannot lose, resurrect, or mutate canonical memory.

Within one memory scope and binding epoch:

• canonical mutations are serialized by the provider into a monotonically advancing MemoryScopeRevision;
• one item write, its durable MemoryMutationId outcome, and revision advance commit atomically;
• one delete, its tombstone, mutation outcome, and revision advance commit atomically;
• exact read and scan are linearizable with committed writes/deletes and provide read-after-write consistency when given the returned minimum revision;
• a query may use a lagging derived mode only when it reports that mode's indexed-through revision and partial status; every returned item is revalidated against canonical state before return;
• an item tombstoned at or before the served revision must not be returned by read, scan, or query, even if a stale index still references it;
• pagination binds one snapshot revision and deterministic ordering; an expired cursor is an explicit error, never a restart at an arbitrary current page;
• no cross-scope transaction or ordering is promised.

A provider cannot acknowledge a committed mutation before the canonical record, mutation outcome, and revision are durable to its declared posture. It cannot return not_found when the exact binding is unavailable. Availability errors and absence are distinct.

Dual write is forbidden. The kernel must not write the same serving mutation to two primary providers, merge two canonical stores, or accept first-success/last-success semantics. Shadow exports or non-serving comparisons may exist during an authorized migration, but they cannot answer tools, operator reads, hydration, or policy decisions.

Invocation, deadlines, and ambiguous outcomes

All requests carry an absolute deadline and cancellation reference chosen by the kernel under the caller, turn, operator, shutdown, and provider-declared maxima. State-changing operations also carry a later absolute settlement deadline that reserves bounded time for commit-status persistence and reconciliation. The provider cannot extend either timestamp.

Each state-changing request uses exactly one top-level operation-specific idempotency identity as defined in the operation contract; it never combines or aliases top-level identities across operations.

For write and delete, the provider must durably accept (ProviderBindingId, MemoryBindingEpoch, MemoryMutationId, request digest) before the first canonical effect. enforceRetention durably accepts its MemoryRetentionRunId and digest; importScope durably accepts its MemoryImportId and digest. Their internal item steps may record child mutation evidence, but those child records cannot be replayed or inspected as a second top-level request identity. Replaying the same operation-specific identity and digest returns the existing outcome or resumes from the existing checkpoint. Reusing an identity with a different digest or under another operation is a provider protocol violation.

A single-record mutation has exactly one provider evidence state:

• committed — the canonical effect, outcome, and returned MemoryScopeRevision are durable;
• not_committed — the provider proves no canonical effect occurred and the identity is terminal;
• unknown — settlement ended without authoritative proof either way.

A timeout, transport loss, provider crash, or cancellation race after possible acceptance is unknown, not failure and not permission to issue another mutation identity. The kernel invokes inspectMutation to resolve the unknown canonical operation outcome under a new bounded reconciliation deadline using the same identity. An exact replay may also return the existing outcome, but it may not repeat the effect. If certainty remains unavailable, the scope is write-unavailable and operator recovery is required; reads may continue only when their own capability remains trustworthy.

Cancellation prevents work not yet accepted and asks the provider to stop safe remaining work. Cancellation cannot undo or uncommit a canonical mutation that already committed. The provider reports whether cancellation arrived before acceptance, during a resumable run, or after commit. Partial enforceRetention and importScope return their durable checkpoint and completed revision range; they never present partial completion as full success.

At the operation deadline, the kernel stops ordinary waiting. At the settlement deadline, it stops waiting for mutation certainty, records unresolved truth, and does not rebind or use another provider. Later reconciliation is a separately bounded, authorized operation under the same exact binding. Retry/backoff remains kernel-owned, and no retry or error permits fallback.

Failure and degraded behavior

Read behavior distinguishes content absence from service degradation:

• exact read, scan, operator delete, tombstone inspection, export, and migration verification return their typed result or an explicit unavailable/error result; they never translate provider failure into empty/not-found;
• query returns overall complete, partial, or unavailable status plus structured, keyword, and semantic mode freshness/completeness;
• semantic retrieval is derived and may be partial while canonical structured/keyword retrieval remains available; a stale or failed semantic mode does not authorize another provider;
• pre-turn memory.seed may degrade to explicitly attributed empty recall when no admitted query mode can return before its deadline. The context report and canonical audit/status record provider unavailability so "no memories" is not confused with "no service";
• in-turn memory.search may return bounded partial hits only with safe degraded attribution. It must not claim a complete empty search after provider failure.

A write reports success only after commit is confirmed. unknown, timeout, post-acceptance transport failure, retention failure, and semantic-index failure must not be rendered as an unqualified successful or failed write. Because item commit and retention are separate, a confirmed write may succeed while the scope becomes temporary over-budget/degraded and a retention run is pending. Conversely, a failed index refresh cannot retract an already committed item.

Deletion becomes logically effective at its committed tombstone revision. Failure to purge a derived copy or expired backup is separately visible and does not resurrect the item. If the provider cannot prove logical deletion, the kernel reports unknown/unavailable rather than success.

There is no silent fallback, dual read, or opportunistic rebinding. The built-in implementation is not a fallback for an unavailable external binding. Existing operations use only the pinned binding; new scope creation fails closed when the selected implementation is ineligible.

Retention, deletion, privacy, and redaction

Retention policy is kernel-owned and budget-driven, not inactivity TTL-driven. A MemoryPolicyRevision supplies item/character/token limits, per-kind budgets, permitted transformation classes, deletion authority, tombstone retention class, and hard work bounds. The provider may optimize mechanics but cannot invent a TTL, change policy order, or retain a record merely because its native store prefers another rule.

The initial compatible transformation order remains least destructive first: deduplicate/merge authorized facts, summarize/compress authorized episode groups, drop derived indexes, then evict lower-utility canonical items. A summary receives a new kernel-authorized ID and bounded system provenance referencing its inputs. Every removed item receives a tombstone. Provider-native compaction that changes only physical representation is allowed; semantic consolidation is allowed only inside enforceRetention.

A retention run is journaled and resumable. Each canonical step commits atomically with its mutation evidence and scope revision. A partial retention result carries a durable checkpoint, completed item/tombstone IDs, revision range, remaining policy work, and safe reason. Replaying the same MemoryRetentionRunId and digest resumes; a new run cannot overlap the same scope unless the kernel has terminally fenced the old one. Failure leaves temporary over-budget state explicit and never rolls back already committed safe deletions by recreating items.

delete creates or returns the canonical tombstone atomically with making the item non-readable. The provider then performs a bounded purge of derived indexes, caches, replicas, queues, and materialized snippets and reports each residual class. Tombstone retention and authorization to purge tombstones are kernel-owned. Tombstones may be compacted only after audit, migration, backup, and deletion-proof obligations have expired; removing one must never permit item resurrection from an index, replica, import, or backup.

Secrets must not be persisted into memory. Before dispatch, the kernel applies secret exclusion and content limits and supplies only the allowed sensitivity and provenance. The provider performs defense-in-depth rejection/redaction required by its conformance posture, but that does not replace kernel enforcement. Unknown suspicious content is not silently reclassified by the provider.

Sensitivity, provenance, tool exposure, recall use, and redaction decisions remain kernel-owned. By default-compatible behavior, sensitive content is excluded from semantic embedding and model recall unless a later explicit policy and provider capability admits the exact processing path. Remote or local-service admission declares data classes, residency, encryption, subprocessors, backup handling, and deletion bounds; protocol authentication alone is not permission to disclose private memory.

Canonical content, search queries, snippets, provenance metadata, export bytes, and secret-like values are confidential payloads. Provider logs, metrics, health, status, canonical audit payloads, and native error messages omit memory content and queries; they use bounded counts, sizes, reason codes, and opaque identities. Data returned across the trust boundary is validated and re-redacted by the kernel before operator or model use.

Binding, lifecycle, health, and recovery

The D1 immutable binding is durable for one MemoryBindingEpoch. It persists the exact provider kind/contract/release/configuration/conformance identities, trust/deployment mode and peer, MemoryProfileRevisionId, canonical MemoryScopeId, namespace configuration reference, durability/portability requirements, and D1's Recovery field as the stable kernel MemoryScopeRecordId.

The binding does not contain a mutable provider health report, current scope revision, provider-native index cursor, activation attempt, or runtime namespace locator that did not exist at selection. The append-only scope record receives the verified provider namespace locator, accepted revisions, mutation/reconciliation evidence, retention checkpoints, export/import evidence, backup/recovery observations, and terminal cutover state after those facts exist. Adding evidence does not rewrite the binding.

A provider activation may fail or restart. Exact recovery creates a new ProviderActivationId under the same ProviderBindingId and must use the same release, configuration, trust/deployment posture, authenticated peer, binding epoch, and scope record. Recovery does not rerun current selection, adopt a newer release, infer a namespace by label, replay a mutation under a new identity, or rebuild canonical items from a derived index.

A compatible same-namespace epoch rollover is distinct from data migration. The kernel fences and drains serving mutations, reconciles every accepted operation in the old epoch, and stops the old binding's serving access before the new binding may open the namespace. It then proves that the exact new release/configuration/peer has the same admitted persistence-equivalence identity and can recover the existing namespace and MemoryScopeRecordId. One kernel transaction closes the old epoch and activates the new epoch; concurrent serving access by both bindings is forbidden. Before the first new-epoch mutation commits, rollback may reactivate the old exact binding after the same drain and recovery proof. After a new-epoch mutation commits, rollback is another explicit epoch rollover and is allowed only when conformance evidence proves the old exact binding can recover every resulting revision; otherwise the scope remains on the new epoch for forward recovery or uses a separately authorized migration.

If the exact release, configuration, peer, namespace locator, mutation journal, or durability evidence cannot be restored, the kernel records primary-memory binding unavailable with no fallback. It does not attach the scope to the current preferred implementation. Provider-native backup restore is allowed only under the exact binding and must restore items, tombstones, mutation outcomes, revisions, and checkpoints consistently before serving.

Static and runtime capability are operation-specific: exact read, scan, query modes, write, delete, retention, export, import, mutation inspection, restart recovery, and backup/restore are independently declared and assessed. Degraded health is operation-specific: loss of semantic query may leave exact reads and writes available; uncertainty in canonical durability makes new writes/deletes/retention unavailable even if a cache can answer queries.

Health never changes a binding. Existing authorized operations use the pinned binding and return truthful unavailable/partial status. A provider cannot migrate a scope, select a replica as new primary, or change consistency because health fell. Internally replicated providers may fail over only within the release-bound namespace and persistence-equivalence evidence admitted for that same binding.

Gateway shutdown rejects new serving mutations and migration starts, drains or cancels reads and resumable work to their deadlines, persists unknown/checkpoint outcomes, stops per-binding/shared activations under D1 reference accounting, and records unresolved recovery or cleanup truthfully. A provider must not leave untracked subscriptions, queues, migration copies, or retention jobs outside the binding/scope record.

Migration, cutover, and rollback

M1 call-site adoption and a later source-of-truth move are different migrations.

For M1, the built-in adapter points at the same current SQL canonical source of truth. Existing canonical data remains readable throughout incremental call-site routing. Legacy and provider-routed call sites may temporarily share the same underlying transaction implementation, but they must not maintain separate copies or competing mutation journals. A call site is moved only when its compatibility tests prove equivalent behavior; no data export/import is required merely to add the adapter.

Any move to another namespace, provider configuration that changes storage identity, or provider release that cannot recover the old namespace uses one kernel-owned MemoryMigrationId and these ordered gates. M0 v1 deliberately accepts a bounded write-maintenance window; it has no evidenced downtime objective that justifies an online change stream.

1. Disposable preflight: admit and activate the exact destination release/configuration against a disposable non-serving namespace with the same persistence-equivalence identity as the intended destination. Prove import, scan, query, delete/tombstone, retention, export, recovery, privacy, cleanup, and capacity there. Dispose of that namespace through its authorized cleanup path; preflight items and tombstones never enter the migration destination.
2. Fresh destination: create and verify a distinct empty non-serving staging namespace for the final destination binding. No mutating preflight runs against it. Failure to prove it empty blocks import.
3. Fence and drain: install the source write fence, reject/queue new mutations under explicit caller behavior, and drain or reconcile every accepted source mutation. Reads may continue from the source until cutover.
4. Full export and import: exportScope takes one consistent full source snapshot at final source revision Rf; importScope writes only the fresh empty staging namespace. Resumable chunks remain bound to that one snapshot and destination identity.
5. Verification: compare canonical logical digest, item and tombstone count, sampled/full scan evidence as policy requires, latest deletion state, and export/import manifests. Derived indexes are rebuild evidence, not digest authority.
6. Atomic cutover: after all gates pass, one kernel transaction marks the old epoch non-serving and atomically activates the new active binding epoch with exactly one ProviderBindingId and MemoryBindingEpoch. Only then may new reads and mutations use the destination.
7. Post-cutover: release the write fence, monitor exact operation health, retain the old namespace read-only/non-serving for the authorized rollback window, and delete it only through separate retention/erasure authorization.

Dual write is forbidden during every stage. A shadow comparison cannot answer hydration, tools, operator reads, or canonical outcomes. Importing a tombstoned item without its tombstone, changing scope identity, using a different export snapshot during resume, or observing digest/count conflict blocks cutover.

Rollback before cutover discards or resumes only the non-serving staging copy. After cutover, direct pointer rollback is allowed only while the destination has accepted no serving writes and the old source still exactly represents Rf. Once any candidate serving write commits, rollback requires the same fenced full reverse migration, including export/import, tombstones, final verification, and a new binding epoch. It is never a silent rebind to the old or built-in provider.

A migration interruption recovers both source and destination through their exact recorded bindings and checkpoints. If either exact binding is unavailable, the kernel preserves the one known serving epoch, keeps the fence where required, and requests operator recovery; it never guesses which copy is newer.

Portable export and import semantics

exportScope emits provider-neutral logical records, not provider tables or index bytes. A stream manifest binds the source scope and binding epoch, export identity, exact full-snapshot revision, canonical contract/data version, record counts by class, deterministic logical digest, chunk digests/order, created time, and completion status. Records contain canonical items and tombstones; mutation journals are transferred only as bounded recovery metadata required to prevent duplicate replay.

An export is one consistent full scope snapshot. Export is resumable by an authenticated opaque chunk cursor bound to that exact snapshot; cursor expiry returns an explicit error. The provider cannot silently restart from a newer snapshot. Delta/change-stream export is not part of M0 v1 and requires a later measured availability requirement and contract revision.

importScope accepts only a kernel-validated stream into an empty, non-serving namespace. It validates scope, canonical versions, IDs, ordering, digests, bounds, duplicates, tombstone precedence, sensitivity/provenance shape, and resource limits before admitting chunks. The same MemoryImportId, chunk identity, and digest is idempotent; conflicting replay is a protocol violation. Partial import remains non-serving and resumes from its journaled checkpoint.

Import completion returns destination MemoryScopeRevision, item/tombstone counts, logical digest, and rebuild-required derived capabilities. Destination-native revisions need not equal source revisions; the manifest and digest establish equivalence. Provider-native indexes, caches, ranking scores, encryption keys, internal row IDs, and service credentials are not portable canonical data.

The kernel packages/unpackages these semantics into the current gateway snapshot format for the built-in adapter. Snapshot authorization, encryption at rest/in transit, artifact retention, and import enablement remain kernel/operator concerns. M0 does not select a new wire schema, authorize a snapshot-format change, or claim atomic restore across the gateway database and an external provider. Before an external provider can be activated where gateway snapshot support is required, M2 must separately define and verify whole-snapshot staging, activation, rollback, and cleanup across both ownership roots.

Error specialization

M0 specializes D1 errors with safe provider-kind reasons:

Code	Meaning
primary_memory_scope_unavailable	Exact scope binding/namespace cannot currently serve the requested operation.
primary_memory_query_partial	One or more admitted retrieval modes failed or were stale; returned candidates are explicitly partial.
primary_memory_mutation_rejected	Provider proves the exact mutation did not commit.
primary_memory_mutation_ambiguous	Mutation may have committed and exact reconciliation is not yet conclusive.
primary_memory_retention_incomplete	Retention stopped at a durable checkpoint and the scope may remain over budget.
primary_memory_delete_residual	Logical tombstone committed but one or more derived/backup purge obligations remain.
primary_memory_export_incomplete	Export did not produce a complete verified manifest and resumable state is recorded.
primary_memory_import_incomplete	Non-serving import stopped at a durable checkpoint.
primary_memory_migration_conflict	Revision, scope, count, digest, tombstone, or epoch evidence blocks cutover.
primary_memory_binding_unavailable	Exact release/configuration/peer/namespace/recovery identity cannot be restored.
primary_memory_protocol_violation	Provider violated scope, replay, digest, deadline, evidence, or confidential-protocol rules.

Each error includes phase, exact identities that exist, safe reason, retry/reconciliation classification, and bounded diagnostics. Provider-native messages never decide retryability, fallback, policy, approval reuse, or model-visible text.

Observability and canonical audit

The kernel emits canonical events for memory-profile resolution, binding epoch activation/rejection, operation admission, query complete/partial/unavailable status, mutation commit/rejection/ambiguity/reconciliation, tombstone creation, retention progress, export/import progress, cutover gates, rollback, recovery, protocol violation, and forced settlement.

Events contain safe IDs, revisions, counts, sizes, mode/capability states, reason codes, policy/approval references, deadlines, and correlations. They omit canonical memory content, search queries, snippets, values, bodies, raw provenance metadata, export bytes, credentials, secret references/values, and provider stack traces.

Provider telemetry may support health and debugging but is never canonical audit. A provider cannot declare an item written/deleted, a migration equivalent, or a retention obligation complete merely by logging it. The kernel validates typed evidence and records the canonical outcome.

M0 conformance contract

M0 adds one primary-memory suite to D1 common conformance. The same suite, activation gate, and outcome requirements apply to built-in and external implementations; delivery-specific fixtures may differ but semantic checks may not.

Every conformance record is bound to the exact ProviderReleaseId, provider contract version, implementation/configuration schema, admitted trust and deployment mode/protocol, persistence-equivalence identity/predicate digest, and suite version. For a replicated or managed service, the predicate binds observable API/service release identity, namespace semantics, consistency and transaction behavior, durability and failover guarantees, backup/restore class, residency/encryption posture, and deletion guarantees. Database/storage engine and version details are required only when the provider declares them or the operator controls them as part of the compatibility boundary. A provider name or service tier label is insufficient. Provider self-report is insufficient and cannot mint authoritative evidence.

The provider-kind suite proves at least:

• exclusive deterministic (TenantId, AgentId) selection, zero/multiple-candidate failure, immutable epochs, and no model/discovery/health fallback;
• tenant and agent isolation for every operation, cursor, cache, index, export, import, backup, and diagnostic path;
• canonical validation of all item kinds, sensitivity, provenance, tags, limits, unknown fields, and cross-scope IDs;
• single-item write/delete idempotency, conflicting replay rejection, committed/not-committed/unknown truth, ambiguous transport outcomes, inspectMutation, and provider/gateway restart;
• linearizable exact read/read-after-write, stable scan snapshots, tombstone precedence, stale-index non-resurrection, and absence versus unavailable distinction;
• structured/keyword/semantic query mode freshness, attributed partial and empty recall, filtering, bounds, cancellation, and deterministic kernel post-filtering;
• budget-driven retention order, summary provenance/sensitivity, partial retention checkpoint/resume, non-overlap, temporary over-budget truth, and no inactivity TTL;
• logical delete plus bounded derived-cache/index purge, backup residual reporting, tombstone retention, and import non-resurrection;
• consistent full export, interrupted resume, chunk replay/conflict, disposable preflight plus fresh empty-staging import, export/import round-trip digest equivalence, tombstones, and derived-index rebuild;
• write fencing, drain/reconciliation, full-snapshot digest/count conflict rejection, atomic epoch cutover, no dual write, and rollback boundary;
• same-namespace epoch rollover, exclusive serving access, recovery proof, and rollback before versus after the first new-epoch write;
• absolute deadlines, cancellation before/after acceptance, shutdown draining, exact-binding recovery, and no retry under a new mutation identity;
• secret exclusion, sensitive-content handling, confidential transport, logging/metrics/audit redaction, data residency, and bounded diagnostics;
• every out-of-process D1 requirement: authentication, channel protection, request identity/correlation, replay rejection, deadlines, cancellation, and message/resource bounds.

The built-in candidate must pass the suite against both supported StateStore modes where it claims compatibility. Its evidence must prove current SQL transactions, item/tombstone behavior, keyword retrieval, optional derived semantic degradation, post-write retention separation, current snapshots, and restart behavior. Built-in delivery provenance grants no waiver.

An external release must run the same behavioral suite against persistence-equivalent real infrastructure and its admitted protocol. A mock store, provider-authored health boolean, successful embedding query, generic database certification, or round-trip of only live items is insufficient.

Compatibility, adoption, and rollback constraints

The built-in implementation remains the default candidate until a separately reviewed implementation and rollout changes it. Current model-facing tools, compatibility aliases, pre-turn integration, operator APIs, and snapshot behavior remain stable. Provider identity does not enter model arguments or memory content.

M1 and M2 are not started. M1 may wrap current persistence only after S0, B0, and T0 exist and must use the same current source of truth. M2 may incrementally route call sites only after M1; any actual provider data move needs separate migration authorization and evidence under this contract.

M0 and C0 are Accepted (I0 and D1 are already Accepted). S0 is therefore dependency-eligible under ARCH-29, but it remains Planned and Not started. This contract supplies requirements for later shared-substrate analysis; it does not authorize S0 or dictate which concepts are common code.

Acceptance of M0 authorizes contract design only. It does not authorize a provider schema, migration, registry, marketplace, hot reload, adapter, implementation, configuration UI, database change, rollout, publication, commit, or external mutation.

Rollback of future adapter code may return to the legacy call path only while both paths address the same built-in source and preserve the same canonical mutation identity. Rollback of a source-of-truth cutover follows the reverse-migration rule and never means selecting the built-in by default.

Accepted decisions and adoption boundary

M0 acceptance records the following decisions. They are not choices left to implementation convention:

M1 and M2 implementation status is Not started; neither is authorized by M0 acceptance.

1. Portability is mandatory in v1 for consistent full exportScope and non-serving importScope: an exclusive cutover needs a provider-neutral fenced path. Online delta/change-stream portability is deliberately deferred until a measured downtime requirement justifies its journals and catch-up protocol. Current whole-gateway snapshot compatibility remains built-in-only until M2 separately accepts external-provider snapshot orchestration.
2. M0 does not expose direct item update: no stable model/operator update surface exists, and adding one now would require optimistic concurrency and provenance semantics without a current caller. Replacement remains write-plus-delete inside authorized retention/import workflows.
3. Selection does not vary below agent scope: current persistence and runtime behavior are tenant-agent scoped. Conversation/workspace/query routing would create multiple potential sources of truth and is not evidenced by current surfaces.
4. Retention is not guaranteed to commit in the write transaction: the item commit is independently conclusive, while retention is a resumable operation. A built-in implementation may optimize both under one database transaction only if the externally observable outcomes remain separable and conformance-proven.

The decision owner affirmed these four answers after independent review found no remaining High, Medium, or Low findings. Concrete TypeScript types, storage layout, profile persistence, portable byte encoding, timeout defaults, and rollout mechanics remain deliberately deferred; implementation must not choose semantics contrary to these accepted decisions.

No M1 or M2 work may begin from M0 acceptance alone. No schema, migration, registry, marketplace, hot reload, provider code, or data copy is authorized here. S0 remains Planned and requires its own separately accepted scope before work begins.

Related docs

• ARCH-29 policy-owning provider microkernel
• D1 kernel invariants and provider control-plane contract
• I0 typed isolation-provider contract
• Memory
• Memory consolidation and retention
• Context, Compaction, and Pruning
• Gateway plugins