Build specification
State and Persistence#
Four layers#
| Layer | Examples | Store | Merge rule |
|---|---|---|---|
| Canonical world | family Actor goals/location, Project state, accepted Contributions, Portal topology | AGE graph + object registry | versioned Commands only |
| Player-specific | Orientation, quest progress, relationships, grants, interpretations, discovered mystery | graph + protected relational records | Source/authorized Action; directional ownership |
| Instance | shard occupancy, current Pitch evidence, encounter composition, temporary puzzle placements | relational/ephemeral service with checkpoints | instance authority; promote durable consequence by Command |
| Ephemeral visual | camera, hover, particles, animation phase, audio mix | client memory | never authoritative |
Immutable Records/events preserve consequential transitions. pgvector stores permission-scoped semantic candidates, not authority. A double-entry ledger owns balances.
Persistence targets#
Critical Commands acknowledge after local transaction p95 <400 ms. Reconnect uses event cursor plus aggregate versions. Instance checkpoint every 15 seconds and on scene exit/confirmation. Pitch drafts save after each answer under selected retention. Portal moves, accepted Contributions, funding decisions, Ally permissions, and completion survive service restart and client reinstall when identity recovery succeeds.
Conflict and offline#
Offline-safe actions queue only when declared; financial, governance, membership, and permission changes require online reauthorization. Conflicts return current versions and a fresh preview. No last-write-wins for authority or relationships.