The gameplay bridge

Vixen.Live.Gameplay is the only assembly that references both halves of the engine's server story: the gameplay libraries of doc 28 and the persistence and cluster of doc 27. It exists because the layer rules make it the only place that can — Live/ may reference Gameplay/, nothing in Gameplay/ may reference Live/, so the join has nowhere else to live.

It is five things:

There are three, and the engine had joined the first two:

• Vixen.Net.Sessions.PlayerId — a uint the session assigns.
• Vixen.Live.PlayerKey — two Guids the database is keyed by. RealmPlayer already joined these.
• Vixen.Gameplay.PlayerId — a ulong every rule in doc 28 passes around, and the one every durable write starts from.

GameplayIdentityMap is that join, and it is a widening rather than a hash: a gameplay id is its session id in a wider integer, populated as a table at admission. Hashing a 256-bit PlayerKey into 64 bits collides, and two players who collided would write each other's inventory.

⚠ A gameplay PlayerId is realm-scoped and must never reach the database. Doc 28 calls one "stable for as long as a party invite or a mute list has to be", and those are not the same length: a party lasts a session, a mute list outlives every realm the player will ever be on. A saved row carrying a raw gameplay id means somebody else on the next realm.

The three bridges have one shape, and ADR-016 is why: "Orleans is asked, not awaited." Every interface here is synchronous, because a purchase, a zone-in and a guild-chat line all ask it mid-frame, and the thing that owns the true answer is a round trip. So each bridge answers from an in-memory view and posts the change to an outbox the realm drains off the frame path.

⚠ A drained write is not a removed write. Drain() returns what is waiting and leaves it there; Settle is what takes it out. In flight is not done, and losing a ledger intent is losing an item.

That one sentence decides the storage of everything a character owns, and it decides it from a property of the data rather than from taste. An asset can be duplicated, so every movement of one is a journal row with an idempotency key. A counter cannot — writing level 42 twice leaves you at 42 — so a counter is written on a cadence, and a crash loses at most one interval.

⚠ That loss is the correct trade and not a compromise: making a counter durable per kill puts a database round trip on the combat path. It is also why ProfilePityStore can be synchronous where LedgerBridge could not.

Each one is arranged around a different way of being wrong, and they are worth reading as three answers to the same question — what does a partial view get wrong, and how loud is it?

• LedgerBridge — the balance that disagrees. The projection is authoritative for the frame and the database is the audit trail, which is not optimism: the lease already says exactly one realm writes. So Insufficient coming back from the database is a defect and not a refusal — the projection checked first, and disagreement means the single-writer property broke. It is counted in Divergences, raised, and kept as evidence. And Supersede() is not an undo: ADR-021 buffers and re-flushes, so every waiting write is restamped when the lease returns.

• LockoutBridge — the absence that reads as permission. An unknown balance reads as zero and refuses a purchase, which is annoying and safe. An unknown lockout reads as null, and ILockoutStore.Find defines null as "not locked" — so a player whose lockouts were never loaded is admitted to a raid they are already saved to, and the run they get is one the fleet cannot take back. That is doc 28's "a lockout one shard knew about is a lockout a player evades by zoning" reopened from inside. The interface cannot say "I do not know", so IsWarm is what admission checks and a cold Find increments ColdReads and raises Cold.

• SocialBridge — the roster that is only partly here. A 500-member guild has maybe thirty members online, and a member who is not connected to this realm has no gameplay id at all, so they cannot be seated. That is the same partial view the other two keep — but it makes one thing lethal: a partial roster must never be written back as the whole truth, or the write deletes everybody who was offline.

SocialBridge.SaveGuild is implemented, counted in StateWrites, and writes nothing. Two things are missing from a state-shaped save of a guild and neither can be recovered afterwards:

1. The roster is partial, so writing it down deletes the absent.
2. A diff of two rosters cannot say who did it — and every IGuildGrain method needs an actor, because every guild rule is about authority.

Invite, Kick, Promote and Rename are the same operations with the actor kept, and each queues a GuildEdit. A member this realm cannot name is in neither side of any operation, so they are never touched — which is exactly the property that makes a partial roster safe.

A graph is state-shaped and safely so, and the difference is worth naming: it has one owner and every change in it is theirs, so handing over the whole thing throws nothing away. Only the nameable part is diffed; a tie to somebody this realm cannot name is carried through untouched.

⚠ A block on somebody offline is the case to get right. The person blocked is usually not here, so the block lives in the durable set and in no graph — and SocialGraphs.IsSevered answers false, which means they can whisper, invite and trade the moment they log in. SocialBridge.Admitted is the sweep that seats them, and a realm that forgets to call it has a block that leaks.

PlayerRecord.Profile is opaque to the persistence layer on purpose — its schema is the game's. PlayerProfile gives that blob a shape without giving persistence one: a map of ProfileSectionId to bytes, written in id order.

⚠ The container knows nothing about types, and that is the whole point. Doc 27 § Upgrades fragments a population by version deliberately, so during a rollout an old realm and a new realm both write the same character. If the old one dropped the section the new one had added, a player who zoned the wrong way would lose it — silently, and only some of the time. A map of id to bytes cannot make that mistake, and the codecs that know types sit above it as IProfileSection.

Two further rules fall out: sections are written in id order, so two realms holding the same state produce the same bytes; and writing the same bytes back is not a change, or every checkpoint looks like one and the row is rewritten on a cadence for ever.

A realm builds one identity map and one of each bridge it needs, fills them at admission, answers from them during the frame, and drains them afterwards.

⚠ Warming with an empty list is meaningful. "Saved to nothing" and "nobody has asked" are the same absence in a cache and must not be the same fact — which is why LockoutBridge.Warmed takes an empty sequence and SocialBridge.Warmed takes a null row, and both mark the player warm.

Draining is the realm's own job, off the frame path, and settling is what removes a write:

⚠ A refusal does not roll the view back. Undoing a join two frames later is a player who was in the guild, saw the roster, said hello and was silently ejected — and the next Warmed corrects it from the authority anyway. What the realm owes is telling them, which is what Refused is for.

IProfileSection is the seam that keeps this assembly from being a bundle. Doc 28's whole shape is that every library is declinable, so a game that took quests and declined exploration should not carry an exploration codec. A section registers itself, and whatever is never registered is still preserved.

⚠ Two sections claiming one id are refused rather than last-wins. Section names are hashed, so a collision is possible; one section silently reading the other's bytes presents as a character whose quests are full of somebody else's fog.

Five are shipped: ProgressionSection, QuestSection, ExplorationSection, WardrobeSection and ProfilePityStore. Each one loads through a seating method on its gameplay object rather than through the rules that made the state, and every one of those seams was added for a failure the rules would otherwise cause on login:

Two rules about what a codec may write down are worth reading together, because they are the same rule:

⚠ Nothing build-scoped goes in the bytes. A GameplayTag is an index into a pre-order walk of the tag tree, so adding one tag renumbers every tag after it — WardrobeSection therefore writes slot names. A gameplay PlayerId is a session id widened, so ProfilePityStore writes only the loot table: a profile already names the character, and keeping the id would mean every lookup missing after a transfer with the rows still sitting in the profile. A DefId is safe in both places, because it is a hash of an address rather than a position in a table.

⚠ What this build does not understand is preserved, section by section and entry by entry. A profession or a talent tree with no definition here is carried through; a quest's history is kept for a quest this build has lost, because history is what QuestRepeat.Once reads and an id is all it needs. The one deliberate exception is an active quest with no template: it has no stages, no objectives and no tags, so there is nothing to hold — the bytes stay in the profile and it comes back on a build that knows it.

CheckpointPolicy decides when the counters are written down.

⚠ A failed write leaves it dirty and does not restart the clock. Clearing the flag loses the interval for good; restarting the clock means a store that is briefly unhappy is retried a whole cadence later, which turns a five-second outage into five minutes of lost progress.

⚠ Transfer and logout write only when there is something to write. "Always on transfer" reads as unconditional and should not be: a character nobody changed has the same bytes stored, and a round trip to write them is a round trip inside the overlap window a transfer spends loading a map.

A tick, in the order the pieces are meant to be used — ask, act, mark dirty, and let the drain happen somewhere else:

Reading a lockout for somebody who was never warmed is the mistake the type is built to make loud, so wire the counter to something that notices:

⚠ LedgerBridge.Divergences should be zero in normal running; a non-zero value means the single-writer property broke. SocialBridge.Divergences should not be zero — a cap measured against a partial roster is expected to be wrong sometimes, and the trade is deliberate. What that counter is for is noticing when the number stops looking like the online fraction of a roster.

• Durable state and the ledger — the journal, the repositories and the fence.
• Writing a realm — where the drain belongs in a tick.
• Economy — IEconomyLedger, from the other side.
• Social — ISocialStore, Guild.Seat and SocialGraph.Seat.
• Instances — ILockoutStore and what a lockout is.