Event sequence mutation registry
The mutation registry records an immutable mutation request, its active lifecycle, and a terminal receipt inside an event store namespace. It is a storage foundation for kernel contributors, not an application-facing mutation API.
Normal revision, redaction, and backfill execution paths do not yet use this registry. Registering or transitioning a mutation does not modify events, dispatch repairs, wait for observers, or fence existing mutation paths. Runtime integration remains part of issue 3920; these foundations do not complete that issue.
Existing public observer, barrier, protobuf, and WaitForCompletion APIs are unchanged. This registry introduces no public snapshots, cuts, or applied-through positions.
Access and operations
Section titled “Access and operations”Resolve IEventStoreNamespaceStorage.EventSequenceMutations to obtain IEventSequenceMutationRegistry. The interface is in Cratis.Chronicle.Storage.EventSequences.Mutations. Providers that do not implement it return explicit Unsupported outcomes through the default implementation.
| Operation | Inputs | Behavior |
|---|---|---|
Begin |
Request, proposed target, optional cancellation token | Reserves a free head and positive ordinal, resumes an identical request, or reports its archived receipt. |
Transition |
Target identity, predecessor state token, transition, optional cancellation token | Applies a legal state-machine transition using a complete compare-and-swap binding. |
Archive |
Target identity, terminal predecessor token, optional cancellation token | Persists a payload-free receipt and releases only the matching terminal head. |
BeginTracking |
Target identity, expected coverage, optional cancellation token | Changes Untracked coverage to Unsealed; repeating the operation reports AlreadyTracking. |
The proposed range is frozen only by a winning registration. Resuming an existing request ignores a newly proposed range. Reusing a registered ID with a different request returns DefinitionConflict rather than changing the original definition. A different mutation on an occupied target returns MutationAlreadyInProgress.
A losing claim can return Contended; retry the same immutable request. Invalid inputs, state conflicts, unsupported providers, and corrupt state are explicit outcomes, not successful no-ops. Cancellation and transport/storage exceptions can leave the durable outcome unknown: reconcile by retrying the same operation, not by inventing a new ID.
Identities and state tokens
Section titled “Identities and state tokens”EventSequenceMutationIdentity preserves the exact display string and a strict UTF-8 key. It does not trim, case-fold, or normalize identifiers. NUL, malformed UTF-16, and identifiers exceeding 200 UTF-16 code units or 600 UTF-8 bytes are rejected.
EventSequenceMutationDigestCalculator.CalculateId derives a deterministic ID from the target, origin sequence, origin position, and mutation kind. Definition digests bind the namespace, immutable request, and frozen target. Terminal receipt digests cover the terminal history and definition digest. These hashes establish consistency; they are not authentication credentials.
A state token binds the event store, namespace, target key, mutation ID, ordinal, definition digest, state version, phase, blocked-from phase, and repair state. Versions start at one for each mutation. Therefore a version alone is never a sufficient storage fence: providers also compare the mutation identity, ordinal, and definition binding atomically.
Ordinals increase across head reuse. Claims compare the previously observed ordinal; a delayed claim cannot reuse an ordinal consumed by an intervening mutation. Ordinal exhaustion fails closed with Corrupt, and state-version exhaustion returns validation failure. Neither counter wraps.
Lifecycle
Section titled “Lifecycle”Blocking records the source phase, so resuming cannot skip verification. A committed mutation requiring repair proceeds through Pending and Dispatching, then Accepted or Unknown. A mutation without repair uses NotRequired. Only these terminal repair outcomes can be archived. Transitioning these records does not itself perform the work their phase names describe.
An exact transition retry against the immediate successor returns AlreadyApplied and the same state. Older tokens cannot advance active state, including after a block/resume cycle. After archival, a correctly bound earlier token can receive AlreadyArchived with the receipt; this reports terminal lineage, not proof that an arbitrary requested transition ran.
Archive recovery
Section titled “Archive recovery”The receipt insert and the head release are one provider transaction, so a crash leaves either the exact terminal head with no receipt, or the receipt with the head released. See Receipts. The transaction does not span the entire mutation operation.
| Retry situation | Result |
|---|---|
| Receipt absent, exact eligible terminal head present | Insert the receipt, release the head, return Archived. |
| Crash before the archive transaction commits | Nothing was written. The terminal head remains and an exact archive retry returns Archived. |
| A concurrent exact archive wins the race | The duplicate receipt insert is detected, the transaction rolls back, and the retry returns the stored receipt as AlreadyArchived. |
| Head already released | The exact archive token returns the same AlreadyArchived receipt. |
| Head reused, including the same state version on another mutation | Return the original receipt without releasing or modifying the later mutation. |
| Provider object recreated | Persistent providers recover from stored history, with the same retry semantics. |
| Preterminal, future, or differently bound archive token | Return StateConflict; do not release any head. |
History does not retain the command payload. Retries validate stored receipt fields and the token’s definition binding; they never depend on stale head payload columns. Begin can additionally recompute the definition digest from the caller’s request and the original frozen range. In-memory archival also removes the payload-bearing registration.
There is no background recovery worker. After an interrupted archive, the owner retries the original request or the exact terminal archive token.
Receipts
Section titled “Receipts”Archiving writes one payload-free receipt per mutation: mutation ID, ordinal, kind, target range, terminal phase, repair state, the terminal witness (definition digest, final state version, receipt digest and digest version), and the archive time in UTC milliseconds. It holds no command payload, reason, event content, origin or event-source ID.
Digests are computed behind one internal seam, and the digest version is stored with the definition and the receipt. Every recomputation uses the stored version, so a digest is always checked with the algorithm that produced it. A version that is no longer supported fails closed as corrupt.
| Version | Construction | Use |
|---|---|---|
| 1 | Domain-separated SHA-256 over the canonical frames | Read only, for receipts and heads written before version 2 |
| 2 | HMAC-SHA256 over the same frames, keyed per event store | Written |
The version 2 key is derived with HKDF-SHA256 (label cratis.chronicle.mutation-receipt-digest.v2) from one secret per event store. The configured encryption key store holds the secret as an internal secret, in a storage location separate from subject keys, so the compliance surface cannot reach it. The secret is created on first use with an atomic create-if-absent operation, so concurrent silos adopt the same secret. The derived key is cached in memory per event store. If the key cannot be read or created, every registry operation returns Corrupt before it touches any state; it never falls back to version 1.
The keyed digest stops anyone who can read receipts, but not the key store, from confirming a guessed definition. It does not survive crypto-shredding: key holders and authorized retry callers can still confirm a guess. See decision 0026 for the construction, the residual exposure and the relationship to decision 0007.
An exact retry returns the stored receipt as AlreadyArchived, including after the head is reused. A different definition digest is DefinitionConflict and a non-matching head is StateConflict. Receipts are kept for the life of the event sequence, with no expiry.
The archive is atomic: a MongoDB session transaction (a replica set is required), an EF execution strategy with a database transaction for SQL, and one lock in memory. The append path never reads or writes receipts.
Provider storage
Section titled “Provider storage”| Provider | Representation and concurrency |
|---|---|
| In-memory | Namespace-owned shared state, serialized by a lock. New wrappers over the same state preserve retries; process loss discards everything. |
| MongoDB | One head document per sequence and payload-free history by mutation ID, with a unique sequence/ordinal history index. Document compare-and-swap operations fence claims, transitions, and release. |
| SQL: SQLite, PostgreSQL, SQL Server | Namespace head/history tables, unique history mutation IDs, and conditional updates. Each operation opens a fresh context. SQL Server uses binary UTF-8 sequence keys to avoid case-folding and trailing-space equality. |
SQL namespace migrations create the registry tables. Dynamic event-sequence table migration also upgrades existing Tags-era tables with Revisions and LastMutationOrdinal, preserving existing rows. Legacy events have mutation ordinal zero; the non-sparse mutation-ordinal/sequence-number index includes them. MongoDB retains the same legacy ordinal default. The fields are persistence foundations, not evidence that current mutation paths stamp ordinals.
Provider verification
Section titled “Provider verification”Shared provider conformance exercises registration conflicts, scope/binding rejection, legal transitions, exact retries, stale tokens, concurrent begin, identity distinctions, and archive retries after recreation and head reuse. Controlled SQL and MongoDB interleavings exercise delayed claims and cross-mutation ABA without sleeps. Archive specs cover a crash before commit, a racing duplicate archive, and a head that changes before release. The seven archive-retry facts run on InMemory, MongoDB (replica set), SQLite, PostgreSQL and SQL Server; the last two run in CI only.
The SQL conformance spec defaults to SQLite. To run it against a disposable PostgreSQL or SQL Server instance, set CHRONICLE_REGISTRY_SQL_PROVIDER to PostgreSQL or SqlServer and CHRONICLE_REGISTRY_SQL_CONNECTION to an administrative test connection string. It creates and removes uniquely named test databases and exercises the registry migration. SQL Server requires -p:InvariantGlobalization=false for SqlClient. Never point these specs at a production server.
MongoDB registry specs use a single-node replica set container fixture because archiving needs transactions. CHRONICLE_SPECS_MONGODB_IMAGE optionally selects a compatible local container image; the default remains mongo. Provider-specific infrastructure results must be reported separately: SQLite success alone does not verify PostgreSQL or SQL Server.
See the kernel contribution overview for the surrounding kernel architecture.