Define milestone one lifecycle ownership and migration contracts
This commit is contained in:
@@ -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,
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user