Durable state and the ledger

IPersistence is four things behind one connection: Accounts, Players, Guilds and Ledger.

The first three are ordinary rows. The last is a journal: append-only, double-entry, and the only place a quantity of anything ever changes. A character's gold is not a column — it is the sum of the rows that moved it, and live_balance is a projection of those rows kept in the same transaction so that reading it is a lookup.

Two implementations. MemoryPersistence is what the tests run against; SqlPersistence is what ships.

An MMO's unrecoverable failure is item duplication, and every game that got it wrong got it wrong the same way: state serialised into a message, a packet lost, a retry, two copies. Three mechanisms here make that unrepresentable rather than unlikely.

The fence. PlayerRecord.LeaseEpoch is the epoch of the last write the row accepted, and it only ever rises. A realm that lost its lease mid-combat keeps simulating and keeps flushing; every one of those late writes comes back Superseded, and nothing anywhere had to notice in time. This is ADR-021's lease reaching the database — the grain decides who holds it, the fence enforces it.

The idempotency key. (player, kind, operationId) is a primary key, and it is *derived from the operation* rather than generated per attempt. A key minted fresh on the retry is a different key, so the retry is a second trade — which is the bug. Derived from the auction's id, the mail's id, the quest's id, both attempts compute the same value and the second one loses the insert.

Double entry. Every intent's deltas sum to zero, per asset, always. There are no faucets outside the ledger: a drop is a transfer out of world/loot and a sale is a transfer into world/vendor, so the invariant is total and ReconcileAsync can check the whole database against itself.

An intent applies whole or not at all, which is why a trade is one of them and not two:

⚠ Applied and Replayed are both success, and the caller must not distinguish them. The whole point of the idempotency key is that the caller cannot tell whether its first attempt reached the database and does not have to:

The shipped store takes a DbDataSource rather than a driver, so the deployment brings Npgsql and configures pooling, TLS and tracing where it already configures them:

A loot drop is a transfer, not a creation.

The support tool's question. "What happened to my sword?" is a query, and it is the reason the asset is an addressable address rather than a number the database minted:

The conservation oracle, as an operation. Empty is the healthy answer, and a nightly job that runs this is worth more than the test that also does:

⚠ That is the whole reason IGuildRepository is a repository rather than grain storage. § Persistence's own rule is that gameplay data kept in Orleans's serializer *"cannot be queried by anything else — including the support tool, the economy dashboard and the analytics job"*, and *"which guilds is this account in"* is a query. So GuildRow carries ImmutableArray<GuildMemberRow> and the members are a table.

⚠ The fence is a revision, not a lease epoch, and the difference is IGuildGrain's. A character is fenced by ADR-021 because two realms can each believe they hold it; a guild has no lease at all, because its single writer is the grain's own turn. What the revision guards against is a stale writer after a reactivation — optimistic concurrency rather than a lease. It travels on the row and the comparison is in the same statement as the write, because reading it first would be the same check with the race in the middle.

⚠ ForAccountAsync is keyed by the account and not by the character, because the question a player asks is "what am I in" and the roster stores a PlayerKey whose account half is exactly that.

⚠ Two of its methods are explicit interface implementations in both MemoryPersistence and SqlPersistence, and it is not a style choice: ReadAsync(Guid) and ForAccountAsync(Guid) collide with the account and player repositories' methods, differing only in return type.

⚠ A GuildRow hand-writes its equality, and so does GuildMemberRow's container. A record's generated equality compares an ImmutableArray by reference, so a row read back never equals the one written — the trap doc 27 § Slice two already recorded for RealmEndpoint, hit again.

Anything that is a quantity of an asset does not belong in PlayerRecord.Profile. Inventory and currency are balances, balances are a projection of the journal, and a gold count in the profile blob as well would be two numbers meaning one thing. The rule that decides: if the support tool would ever be asked where did this come from, it is a ledger asset. If the answer is only ever *the player chose it* — appearance, keybinds, quest flags, the position they logged out at — it is profile.

Credentials do not go here at all. AccountRecord has a handle and no password: what an engine can honestly own is the mapping from whatever your authority calls this person to the account the world knows. Everything upstream of that — OIDC, Steam, EOS, your own account service — is the deployment's, and the seam is IAccountAuthority.

A counterparty whose lease this realm does not hold does not go in an intent. The fence checks the acting character, so a face-to-face trade — both characters on one realm — may name both, and anything else moves through world/escrow: value out under the sender's lease and their key, value in under the recipient's. That is what makes mail and auctions safe across realms without a distributed transaction.

• Placing players — the lease this fence is the database half of.
• Transfer tickets — the other half of ADR-021's atomic moment.
• docs/plan/27 § Persistence — the three rules, and the failure mode behind each.