From 0e1782c873d0258cfeb49c68b27393350b2f8eb2 Mon Sep 17 00:00:00 2001 From: dingo Date: Tue, 8 Sep 2026 11:35:08 -0400 Subject: [PATCH] Define milestone one lifecycle ownership and migration contracts --- docs/ARCHITECTURE.md | 3 + docs/LIFECYCLE-OWNERSHIP.md | 295 ++++++++++++++++++++++++++++++++++++ planning/SYSTEMS-ROADMAP.md | 5 + 3 files changed, 303 insertions(+) create mode 100644 docs/LIFECYCLE-OWNERSHIP.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 595097b..dccb96a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -38,6 +38,9 @@ key-owned hub housing, crafting rolls/provenance, and portal dungeon instances. These are design requirements, not implemented behavior. This document's terminal death and current-world boundaries describe the running implementation; see `planning/SYSTEMS-ROADMAP.md` for the future lifecycle rules and unresolved details. +The milestone 1 [lifecycle and ownership contract](LIFECYCLE-OWNERSHIP.md) maps the +current code to proposed states, transaction boundaries, and migration steps. +It is a specification for later milestones, not an applied schema change. One Go process owns one world, with a serial simulation protected by one lock. Clients submit bounded intents. The server determines speed, terrain height, diff --git a/docs/LIFECYCLE-OWNERSHIP.md b/docs/LIFECYCLE-OWNERSHIP.md new file mode 100644 index 0000000..46d084c --- /dev/null +++ b/docs/LIFECYCLE-OWNERSHIP.md @@ -0,0 +1,295 @@ +# Milestone 1: lifecycle and ownership contract + +Status: foundation specification delivered for review. No gameplay, database, or +protocol change is activated by this milestone. Confirmed product rules come from +[VISION](../planning/VISION.md) and the [roadmap](../planning/SYSTEMS-ROADMAP.md). +Record names and transaction boundaries below are the proposed implementation +contract. Open product decisions are explicitly listed at the end. + +## Existing code and migration constraints + +| Existing boundary | Evidence | Required future change | +| --- | --- | --- | +| Character states `alive`, `eligible`, `dead` | `server/internal/game/world.go`, `store/portal.go` | Separate life state from travel/victory eligibility | +| One living character per account | `one_living_character` partial unique index | Also reserve the account during transfer; serialize replacement against revival | +| Corpse ID is `corpse:` plus character ID | `game.World.kill` | Introduce a unique death ID for every death; repeated deaths cannot overwrite corpses | +| Looting deletes the corpse record | `game.World.lootCorpse` in `game/equipment.go` | Separate empty-corpse revival identity from its loot contents | +| Passage row is keyed by character ID | `store/store.go` | Preserve old claims; introduce unique operation IDs for repeated hub/world journeys | +| Owner token, revision, and DB-time lease fence saves | `store.Lease.SaveCommand` | Every new authoritative mutation retains ownership checks | +| Staging clones selected character fields | `store.stageTitleWorld` | Stage all affected corpses, items, houses, and character fields before new transactions | +| World version currently checks generator compatibility | `game.World.Restore` | Separate schema/payload versions from terrain generator version | +| XP is awarded by gameplay paths; skills use broad categories | `game/world.go`, `game/progression.go` | Gate every XP track by context; migrate profession splits explicitly | + +Do not turn historical deaths into resurrectable deaths merely by loading an old +save. Do not reopen claimed passages, reset daily usage, distribute generic skill +XP across every new profession, or reinterpret account titles as cosmetics. + +## Identity and ownership + +| Identity | Owns or references | Lifetime | +| --- | --- | --- | +| Account ID | Cosmetic entitlements; one current life/reservation; replacement generation | Across characters/worlds | +| Character ID | Stats, inventory, daily usage, current location; progression policy below | Preserved by revival and travel | +| Instance ID | One survival world, hub instance, house instance, or dungeon instance | Independent from the process hosting it | +| Death ID | Character, account generation, corpse instance/position, remaining items, eligibility | Unique per death, including repeated deaths of one character | +| Transfer ID | One journey, reason, payload, source/destination, result | Permanent idempotency/history reference | +| Item ID | One equipment/furniture/key instance, location, rolled stats, provenance, appearance | Never copied by movement/recovery | +| House ID | Stable contents, creator provenance, keys, deletion/recovery state | Independent from hub-instance selection | +| Cosmetic ID | Compatible appearance definition; account entitlement references | Ownership survives loss of objects displaying it | + +Each instance has one simulation owner. Chunks partition interest within an +instance; they are not ownership boundaries. Hub switching and dungeon/house +entry change the instance, so they use durable travel rather than a coordinate edit. + +An item has exactly one location: character inventory, corpse, ground loot, +container, placed object, or transfer escrow. House archival changes availability +of that same storage; it does not create a second item location. Quantity stacks +need provenance-aware grouping once crafting provenance lands. + +Recommended account reservation record: `account_id`, `current_character_id`, +`generation`, `revision`. A replacement increments generation. Resurrection checks +the generation recorded at death, so creating and then killing a replacement can +never make an older character eligible again. Cosmetic grants never depend on this +generation. Creator recovery retains account and original-character IDs so the +remaining recovery-identity decision does not require guessing later. + +## Life state transitions + +Keep life state (`alive`, `dead_recoverable`, `dead_final`) separate from presence +(`in_instance`, `in_transit`) and route eligibility. Victory is an entitlement/event, +not a second kind of life. A capped character remains alive but cannot play beyond +the existing daily budget. + +| Transition | Preconditions | Atomic result | +| --- | --- | --- | +| Alive -> recoverable death | New system enabled; valid death in an existing world | Record unique death/corpse, move remaining carried items once, stop character actions | +| Recoverable -> alive | Corpse exists; source world not destroyed; same account generation; item/spell valid at corpse | Consume cost once, transfer only remaining corpse contents, consume revival eligibility, restore same character | +| Recoverable -> final | Replacement creation or corpse's world destruction | Permanently invalidate revival; preserve death history | +| Final -> alive | Never through ordinary resurrection | Reject | +| Account -> replacement life | No alive/transferring life; explicit new-character request | Increment generation and finalize prior recoverable life in the same transaction | + +Ordinary healing cannot take any dead state to alive. No automatic respawn or +starting-kit replacement occurs on revival. An empty corpse remains targetable +while eligible. Lootees retain stolen gear/house keys; revival cannot reclaim it. +If the same character dies again, create a new death ID and do not reuse the old +corpse. Historical death events stay recorded even after successful resurrection. + +Revival, replacement, world destruction, corpse looting, and a second caster must +serialize on the same relevant account/death/instance records. Recheck range and +item/spell validity at resolution, not only at cast start. Partial loot leaves +exactly the unlooted contents available for revival. Preserving progress and daily +usage is mandatory; restored pool amounts and offline/capped interaction remain +product decisions. Dungeon closure needs its own corpse policy before rollout. + +## Travel and instance admission + +| Route | Authorization | Failure boundary | +| --- | --- | --- | +| Hub -> survival | Player chooses a not-full, not-destroyed destination | Recheck capacity/phase at acceptance; Harbinger arrival alone is not closure | +| Survival -> hub before victory | Valid escape item at activation | No ordinary free-return action; activation details remain open | +| Victorious survival -> hub | Player interacts with the victory portal | No automatic teleport or duplicate victory reward | +| Hub -> other hub | Player chooses an available instance | Preserve account/character/items and housing links | +| Hub <-> house | Valid entry key/invitation; exit route | No house copy on hub switch; permissions rechecked at entry | +| Portal <-> dungeon | Dungeon admission/exit policy | Population, reset, corpse, and destruction rules must be specified first | + +A recommended transfer protocol uses durable escrow, avoiding an unsafe assumption +that two independent world owners can mutate both live simulations in one call: + +1. **Prepare at source:** authenticate account; check route and source lease/revision; + stage item cost and final character payload; reserve the account; persist one + transfer record; make the source character non-interactive. Commit before replying. +2. **Accept at destination:** validate destination lease/revision, capacity and route; + consume the prepared transfer once; install the character and inventory; move + authoritative location; retain daily usage; commit before destination snapshots. +3. **Reconcile source:** old snapshots may retain historical data, but the registry + and transfer state fence it from interaction or saving over the destination. + +Transfer states: `prepared -> accepted` or `prepared -> returned`. Repeated request +IDs with the same payload return the recorded result; changed payloads conflict. +The account remains reserved in escrow, so disconnect/retry cannot create a new +life. Cost debit and escrow preparation commit together; any authorized return +restores that debit once, never through an untracked compensation item grant. + +Once departure commits, source-world destruction cannot also kill a character +already in transit. A source destruction that commits first rejects preparation. +An unavailable hub leaves a durable transfer awaiting a valid hub destination; +never send the player back into a destroyed world or copy them into two hubs. +Hub-to-survival acceptance checks destruction again; a failed destination may return +to its viable source hub under the same operation. Automatic cancellation into a +dying survival world is not an assumed fallback. Exact retry/routing UX belongs to +milestone 5; the owner/reservation rules are mandatory regardless of UX. + +World victory rewards and escape are separate facts: escaping does not implicitly +grant a boss kill, survival credit, housing eligibility, or a victory title. Those +product eligibility decisions remain open. Daily budget follows the character; +neither an escape item nor a hub switch supplies a fresh allowance. + +## House keys, three-second deletion, and recovery + +House states: `active -> pending_deletion -> archived_recoverable -> purged`. +Eligible recovery returns pending/archived state to the same active house. `purged` +has no recoverable contents. A record of the purge may remain for audit/history. + +| Operation | Required behavior | +| --- | --- | +| Transfer key | Move the unique key item; the holder has owner rights without changing creator provenance | +| Issue extra key | Check issuing permission; create distinct key ID referencing same house; never invalidate other keys | +| Destroy a non-last key | Destroy that item only; remaining holders retain ownership | +| Destroy last valid key | Mark pending and persist `delete_at = committed destruction time + 3 seconds` | +| Timer expires | Remove house/contents from active access; retain the same data for recovery | +| Eligible creator recovers | Issue key and reactivate the same retained contents once, before the recorded death world is destroyed | +| Recovery death world destroyed | End recovery right; purge archived data; do not delete an active house held by valid keys | + +Count all valid keys across inventories, corpses, containers, and locations. A key +on an inaccessible corpse is still valid until actually destroyed under an agreed +rule. Last-key count and destruction serialize with new-key creation and transfers. +Destroying one's carried key before death prevents that item appearing in loot; +an already-looted key cannot be remotely destroyed by its previous holder. + +The three-second deadline uses persisted authoritative time, not render time or a +restarted timer. Proposed safe recovery transaction: verify creator eligibility, +world lifetime, house revision and state; create the key; clear deletion deadline; +reactivate contents; commit all changes. Concurrent timer/recovery/purge operations +produce one result. Ordinary extra-key issuance versus recovery during the countdown +needs an explicit permission policy; it cannot bypass final purge eligibility. + +Archive the final committed contents at deletion, not an earlier backup that would +recreate withdrawn items. During archive no inventory access or placement is allowed. +Count-down occupant handling and eviction destination remain open. Recovery refers +to the creator's death world, not the construction world, hub, or thief's world. +If no valid death-world deadline is established, do not invent one or irreversibly +purge data; resolve that product case before enabling the relevant operation. + +## Account cosmetics and appearance transitions + +Store `(account_id, cosmetic_id)` entitlement independently from item/furniture +appearance. Dropping, trading, death, house archival/purge, and character replacement +cannot revoke it. The underlying object's stats, ID, and crafting provenance do +not change when its applied appearance is cleared. + +Operation semantics are explicit, not inferred from a generic inventory move: + +- `drop_loot`: remove applied cosmetic. +- `receive_other_player_item`: clear previous applied cosmetic; no entitlement grant. +- `place_furniture`: preserve applied cosmetic, including in someone else's house. +- `move_placed_object`: preserve it without inventory entry, even for an unentitled mover. +- `pick_up_furniture`: retain only if receiving account owns the cosmetic. +- `restore_house`/`switch_hub`: preserve placed appearance; neither operation is pickup. + +The furniture pickup exception takes precedence over generic other-player receipt. +Server validates application entitlement/compatibility. An object may retain its +placed appearance in a house whose occupants lack the entitlement; visibility is +not ownership. Do not clear it just because the decorator logs out or a key changes +hands. Cosmetics acquisition and corpse rendering are later design choices. + +## XP and discovery policy + +Instance kinds explicitly include `survival`, `hub`, `house`, and `dungeon`. Defaults +for legacy worlds are survival. Hub/house reject every XP award: character, +profession, weapon, spell, or future track. Unknown kinds reject XP until configured; +dungeons require an explicit policy rather than inheriting XP eligibility merely +because their entrance is in the hub. + +Every award carries server-owned activity context: event/operation ID, actor, +source instance and policy version, XP track, amount, and resolution context. +Recommended rule: both originating activity and recipient's resolution context +must permit XP. Deferring a hub activity until arrival in a survival world cannot +convert it to XP; receiving an old award while in a hub cannot grant XP there. +Do not bank suppressed XP for release on the next world transition. + +Hub crafting still runs recipe matching, validity feedback, ingredient consumption, +failure/refund and quality rolls, output creation, and recipe discovery recording. +Only XP is suppressed. Discovery and XP are separate mutations in the same craft +result. Retry returns the same result, not a fresh stat/failure roll. + +Character level/stats and daily usage already belong to the character. Cosmetics +are explicitly account-bound. Profession/weapon/spell/discovery ownership across +replacement lives awaits the milestone review; model their owner explicitly rather +than accidentally inheriting them through a copied character snapshot. Existing +account-title behavior remains unchanged pending its separate design confirmation. + +## Storage and execution contract + +Proposed durable records (names are not migrations yet): instance registry; account +life reservation; character lifecycle/location; death/corpse ledger; transfer +operations/escrow; house and key registry; cosmetic entitlements; operation results. +Use stable IDs, payload/schema versions, expected revisions, and explicit references. +Required uniqueness includes account reservation, one current location per item, +one active transfer per character, death identity, key identity, and account/cosmetic. + +The store coordinates transactions; game computes validated outcomes; transport +authenticates and forwards bounded intents. For multi-record transactions, adopt +one lock order across every participating writer: sorted instance ownership rows, +sorted account reservations, sorted character/death rows, transfers, houses, items/ +keys/containers, entitlement/award claims, and operation results. Recheck optimistic +read sets after locks; do not add a late lock that inverts the order. This requires +reviewing old save/claim paths together before mixed-version rollout. + +Owner leases and revisions fence gameplay writes. Timed housekeeping checks house +revision/deadline and recovery-world state in a durable transaction; it cannot +restore inventory into a running instance outside its owner. A shared advisory or +row-lock protocol must cover negative checks such as "no key/active life exists." +SQLite serialization and PostgreSQL row locking must have equivalent outcomes. + +Commit all logical effects before acknowledging success or publishing snapshots. +On ambiguous commit, reload/freeze as existing storage does; never retry a mutation +under a new operation ID to guess success. Persisted operations reconcile restarts. +No client can provide an authoritative account generation, cosmetic unlock, final +item roll, passage entitlement, or XP eligibility flag. + +## Migration and rollout plan + +1. Add versioned schema/payload readers and migration fixtures; preserve generator + version separately. New behavior stays disabled until compatible writers exist. +2. Backfill instance kind `survival`, current locations/reservations from authoritative + character records, and existing passage claims without resetting them. Conflicting + active lives or item ownership fail migration rather than silently selecting one. +3. Treat old `dead` as terminal. Retain old corpses as loot/history; only deaths + under the new lifecycle can create new resurrection eligibility. Old `eligible` + retains its existing unclaimed/claimed passage meaning until explicitly migrated. +4. Create entitlement/house registries empty where no source exists. Never infer + cosmetic ownership from visible meshes. Do not invent creator/death provenance. +5. Drain incompatible owners before enabling new writers; fence minimum supported + schema/owner version. Preserve original backup and compare authoritative counts, + IDs, balances, death states, daily usage, and passage claims before/after migration. +6. Enable each feature in its assigned milestone with lifecycle tests. After new + states exist, use a compatible forward fix; do not run old writers or restore an + old production snapshot that reverses deaths, transfers, costs, or key destruction. + +Milestone 1 executes none of these migrations. Existing production still requires +PostgreSQL/OIDC; development remains loopback-only. No capacity claim changes. + +## Review decisions and later gates + +| Decision | Needed before | Current boundary | +| --- | --- | --- | +| Profession/weapon/spell/discovery ownership on replacement | Progression schema activation (3/6/7) | Awaiting user selection; no implicit backfill | +| Creator recovery identity and death-world edge cases | Housing (8) | Store account + creator + death references; no guessed purge deadline | +| Hub daily-time accounting | Hub travel (5) | Preserve usage; zero XP does not mean unlimited daily play | +| Escape cost/activation, housing eligibility after escape, late admission | Hub travel (5) | Item-gated escape; no implicit victory reward | +| Resurrection consent/pools/item use, cap handling, dungeon corpse access | Resurrection (7), dungeons (10) | Corpse required, no replacement, world must exist | +| Guest/co-owner rights and countdown access | Housing (8) | Key holders remain owners; archive blocks access | + +These gates do not require implementing future menus or making numerical tuning +choices in milestone 1. The foundation review is about identity, state, ownership, +and commit boundaries. They must be resolved before the corresponding behavior ships. + +## Milestone handoff and verification + +Manual design checklist: + +- Review one death -> partial loot -> revival -> second death: unique corpses, + remaining items only, unchanged progression/daily usage. +- Review replacement and revival arriving together: one life wins permanently. +- Review escape -> source destruction -> destination restart: one reserved character, + one item cost, no source-world revival or duplicate import. +- Review last key -> three seconds -> archive -> creator recovery/death-world end: + same house/items restored once, or recovery permanently denied after the deadline. +- Review hub crafting and furniture pickup: discovery is separate from XP; appearance + is separate from account cosmetic ownership. + +Validation for this specification: compare every referenced current boundary with +the source; check Markdown/local links and diff whitespace. No Playwright run or +game build is necessary for documentation-only changes. Future executable changes +retain required type/build/Go checks and focused lifecycle tests. There is no new +playable feature to test in this milestone; continue only after the user's review. diff --git a/planning/SYSTEMS-ROADMAP.md b/planning/SYSTEMS-ROADMAP.md index 96f44fe..752c18d 100644 --- a/planning/SYSTEMS-ROADMAP.md +++ b/planning/SYSTEMS-ROADMAP.md @@ -508,6 +508,11 @@ are an in-game feature proposal; no external messages are sent by this plan. ## 10. Agreed milestone order and handoff +Milestone 1 specification: [Lifecycle and ownership contract](../docs/LIFECYCLE-OWNERSHIP.md). +The foundation document defines states, identities, transactions, migration +boundaries, and a review checklist. It is delivered for user review; it does not +activate future gameplay or change existing saves. Milestone 2 has not started. + This replaces the earlier proposed order. Each milestone produces a reviewable slice, followed by commit/push and a user testing handoff. These are dependency-based milestones, not time estimates or new tested-capacity claims.