Files
aeternalis/docs/LIFECYCLE-OWNERSHIP.md

25 KiB

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 and the roadmap. Record names and transaction boundaries below are the proposed implementation contract. Open product decisions are explicitly listed at the end.

Milestone 5 implementation status

Playable hub travel implements survival/hub kinds, character transfers (prepared -> accepted), in-transit account reservations, hub switching, escape stones and physical victory portals. Returning to a viable source hub is an acceptance of the same transfer. Later resurrection, housing, cosmetics and title-ledger migrations below remain planned. Current hub daily-time accounting is unchanged; XP is suppressed. See the milestone document for the applied schema, lock order, compatibility restrictions and manual checks.

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 Levels/stats, professions, weapon proficiency, spells/XP, abilities, discoveries, titles, inventory, daily usage, location Preserved by revival/travel; progression not inherited by replacement
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 permissions, three-second key destruction, and recovery

Implementation checkpoint: milestone 8b now implements these transactions and permission rules with floor-plan controls. Its provisional rules resolve the open interruption, eligibility, invitation, and occupant choices below for playtesting. Milestone 8c adds walkable interiors and visitor presence while preserving these ownership boundaries. The stored state name for archived_recoverable is archived.

Proposed house states: active -> archived_recoverable -> purged. Eligible recovery returns archived state to the same active house. purged has no recoverable contents. A record of the purge may remain for audit/history. Key destruction is a separate three-second action; no house-deletion countdown starts when that action begins. The key remains valid until completion.

Owners and co-owners configure a baseline for guests and per-person overrides:

Guest permission Action controlled
Move furniture Reposition furniture, including pushing/pulling without pickup
Open furniture Open furniture such as containers
Place furniture Place furniture in the house
Put items in furniture Deposit items into furniture
Pick up items in the house Pick up house items
Drop items in the house Drop carried items into the house

Proposed representation: baseline allow/deny values and per-person inherit/allow/deny overrides for each action. Resolve overrides per permission so unspecified actions follow the current baseline. Opening furniture does not implicitly grant deposit or pickup rights. Go must check the applicable permission on every operation, including after an owner/co-owner changes the settings. Guest overrides cannot strip owner rights from a holder of a valid key. Invitation and co-owner assignment policies remain separate from the six guest actions.

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
Start destroying a carried key Record the exact key, actor, and server-authoritative completion time three seconds later; key remains valid
Complete destruction Recheck that the living actor still holds that exact key, then destroy it and count remaining valid keys atomically
Completed destruction leaves other keys Remaining holders retain ownership; house stays active
Completed destruction removes last key Remove house/contents from active access; retain the same data for recovery, with no additional three-second house timer
Holder dies before completion Invalidate that pending action; the undestroyed key remains part of corpse loot
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 action uses authoritative time, never a client-reported elapsed duration. A changed holder or item location invalidates completion so a pending action cannot destroy a key after it has been dropped or looted. Movement, incoming damage, disconnect/restart cancellation, and manual cancellation policies remain open. A new key issued during the action counts when destruction completes. Proposed safe recovery transaction: verify creator eligibility, world lifetime, house revision and state; create the key; reactivate retained contents; commit all changes. Concurrent completion/recovery/purge operations produce one result and 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. Occupant handling upon house deletion 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.

Confirmed owner is character_id for character levels/XP, stats/allocations, profession levels/XP, weapon proficiency, learned spells/spell XP, abilities, and discovered recipes. Resurrection and every world/instance transfer preserve them. A replacement receives fresh initial character defaults, not a copied progression snapshot; only access to account cosmetics is inherited. Returning with a resurrected character is different from creating a replacement. Cosmetic appearance selections on the old character need not be copied merely because unlock access persists.

This also supersedes account title inheritance: permanent titles belong to the character, survive resurrection/travel, and remain in that character's death history. Separate future (character_id, title_id) active awards from immutable first-world/ first-ever claim reservations. New lives do not inherit title effects or release historical first claims. A new character may earn an ordinary personal title under its own requirements; it cannot claim a previously won first-ever title by replacing its owner. The existing account ledger is unchanged until explicitly migrated.

House access still comes from possessing keys or invitations, not copying a dead character's unlocks. The separately confirmed original-creator key recovery right remains in scope; its actor/identity rules must be specified independently rather than implemented as inheritance of progression, inventory, or keys.

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. For character-owned titles, retain immutable first-claim history and original grant provenance. Specify treatment of awards already copied to replacement lives by the old account ledger before migration; do not silently strip or duplicate existing awards. New progression/discovery records must key on character identity.
  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
Progression/discovery ownership Confirmed Character-owned; revival/travel preserve, replacement resets; only cosmetic access inherited
Existing inherited title migration Character title schema activation Character ownership confirmed; legacy copied-award treatment still needs a policy
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 actions Confirmed Owners/co-owners manage baseline and per-person permissions for the six listed actions; key holders remain owners
Key-action interruption and occupant handling upon deletion Housing (8) Three seconds destroys the key; archive blocks house access; no separate house timer

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: fresh profession/weapon/spell/stat/ability/recipe progression, no inherited titles or items, continued account cosmetic access. Historical title first claims remain reserved; creator house recovery is a separate explicit action.
  • 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 start key destruction -> three seconds -> completed last-key removal -> archive -> creator recovery/death-world end: same house/items restored once, or recovery permanently denied after the deadline.
  • Review death before key destruction completes: pending action cannot remove the undestroyed key from corpse loot. Extra-key issuance during the action prevents house deletion if another valid key remains.
  • Review each guest baseline and per-person override, subsequent permission changes, and the continued owner rights of every valid key holder.
  • 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.