Define milestone one lifecycle ownership and migration contracts

This commit is contained in:
dingo
2026-09-08 11:44:54 -04:00
parent 4751359b6c
commit 0e1782c873
3 changed files with 303 additions and 0 deletions
+3
View File
@@ -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,
+295
View File
@@ -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.
+5
View File
@@ -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.