diff --git a/projects/Magic/docs/MAGE_GEAR.md b/projects/Magic/docs/MAGE_GEAR.md index 4c1e5b2..11b6e00 100644 --- a/projects/Magic/docs/MAGE_GEAR.md +++ b/projects/Magic/docs/MAGE_GEAR.md @@ -49,6 +49,132 @@ cannot hit the old orbs, and the station's part choices and any pending over-tie confirmation are cleared, so it must choose and confirm again. A player without an active character is told so and cannot start a run. +Deposited weapons belong to the full account and character that prepared or +rested them. Abort and material-refund actions require the station's current +owning character or `magic.admin`. Charging and empty-hand ejection remain public to active living +characters. An ownerless legacy station retains public charging and ejection; +its active run records the initiating character. Abort returns require the +station's full character owner, including when staff act. Ownerless or unresolved +property stays on the station for review. + +Menus, over-tier confirmations and runs capture their initiating session. A late +callback checks the occupancy ID, original item and full owner before writing. +Ending an outgoing session can finish its already-paid run, including after the +session becomes noncurrent, without changing a replacement station or a newer +session's menu. + +## Property storage and inheritance + +`data/gear-stations.yml` remains authoritative. Original row keys, root metadata, +unknown fields, explicit nulls, unloaded worlds and unsupported item records +survive saves and restarts. Character-owned rows add an `occupancy-id`, explicit +`ownership` envelope and `effect-state`; new or updated weapons use exact Paper +`item-bytes`. The original legacy item map and account attribution remain raw. +Unresolved ownership or unreadable data is held for review. +A row with an unparseable location retains its raw data without blocking deposits +at unrelated valid coordinates. Known held coordinates remain reserved; duplicate +occupancy IDs or valid occupied coordinates still hold the inventory. + +Legacy account owners migrate only after the reviewed heir directory is ready, +using its exact account-matching character reference. Plans fix that recipient; +a changed heir mapping never redirects a retry. Missing or malformed owners are +kept separately from legitimately ownerless stations. TLibs 2.6.0 supplies the +character ownership and estate APIs. On an older API, character gear actions and +migration remain unavailable until the supported APIs are installed. +Participant startup failures with present APIs log the underlying cause at +`SEVERE`, separately from the missing-API warning. + +Estate participant `magic-gear` transfers deposited gear and queued returns. +It waits for every orb run touching the testator's gear, including public runs +started by someone else. It checks the current estate decision before each +publication and records exact death, source, recipient, revision and decision. +Newer decisions move only untouched property; a partial older publication is +blocked for recovery. Immutable source archives and independent receipts retain +cumulative moved IDs through waiting or frozen decisions. Restoring a completed +source, losing receipt IDs or altering a captured envelope blocks further moves. +Every completed revision, including zero-item outcomes, also has independent +full-decision evidence and its remaining source IDs. The same revision cannot +absorb newly discovered property; a newer estate decision is required. Globally +duplicate return operation IDs are held, including delivered or interrupted +evidence. An exact pair belonging to one unfinished fixed publication can resume +only that captured plan. +Inheritance does not apply acquisition limits. + +Magic profiles, focus, resonance and progression never participate in this +transfer. Crafting costs, bypass permissions and other account policies retain +their existing behavior. + +## Interrupted effects and queued refunds + +Deposits, charges and releases persist intent before changing inventory or +spawning world output. Abort refunds are queued under +`data/gear-returns//.json`. Rested weapons return +as the original item; fresh crafts refund their recorded materials. Delivery +always targets the station's owning character, even after a staff abort. Immediate +delivery uses only that recipient's captured session; staff aborts for another +character queue the property for its owner. Delivery uses empty storage slots, +retains any remainder and retries for the owning +character when its next valid session starts. A full inventory does not discard +the queued remainder or hand it to an incoming character. + +A fresh craft with a missing, malformed or overflowing recorded material payment +cannot automatically refund today's recipe. Its weapon and raw record stay on +the station for staff review; it can still be charged and publicly ejected after +attunement. An explicit empty cost map remains a known material bypass. After +release is acknowledged, its empty abort return is recorded as delivered without +granting items. Older empty pending returns are acknowledged through the owning +character's checked delivery path; held returns remain held. + +An interrupted deposit, charge, world release or inventory delivery is held with +its evidence for staff review. Restart does not blindly repeat or discard it. +Runtime scans and the offline return inventory preserve regular `magic-*.tmp` +staging files without treating them as committed records. The recovery backup +retains their bytes. Temporary-looking directories or symlinks and malformed +committed records still hold operations for review. +Paper inventory/player saves, world item storage and Magic files are separate +durability domains: this is not an arbitrary-crash exactly-once guarantee. +Public ejection and missing-furniture cleanup still drop the weapon into the +world; a crash between that effect and its acknowledgment requires staff to +compare the held record, player/world data and recovery evidence. + +## Offline ownership recovery + +Stop Paper before using +[`tools/gear-ownership.py`](https://github.com/TF-Minecraft/Magic/blob/main/tools/gear-ownership.py). +Python 3 and PyYAML are required for this offline tool; plugin dependencies are +unchanged. Preview legacy migration or estate journals: + +```sh +python3 tools/gear-ownership.py --data /path/to/plugins/Magic/data --kind migration +python3 tools/gear-ownership.py --data /path/to/plugins/Magic/data --kind estates +``` + +Apply only one previewed run/death UUID, with a new backup directory outside +Magic's data folder: + +```sh +python3 tools/gear-ownership.py --data /path/to/plugins/Magic/data --kind estates \ + --journal --apply --backup /path/to/new-gear-recovery +``` + +The tool preflights the whole selected journal, full references, captured +decisions, raw payload semantics, original archives, receipts and current rows. +It rejects conflicting, progressed or ambiguous effects before restoring +ownership. It saves and verifies gear-only recovery bytes first, preserves +unrelated station rows and archives rolled-back journals and receipts. Untouched +planned records are no-ops. Restore errors require preserving the backup and +keeping Paper stopped for manual recovery. The tool never replays physical +effects or changes profiles/focus. + +Never start an older Magic JAR against data this version has used. Older JARs +ignore `effect-state`, character ownership and `data/gear-returns/`. A released +migrated station still retains its legacy `item` map, so it reappears and can be +ejected again, or drops the weapon again when its furniture is gone. Inherited +stations revert to the original account's abort/refund authority, and queued +refunds stop being delivered. Roll back only by restoring the complete offline +pre-upgrade checkpoint, including Magic data, worlds and player data. A JAR-only +or plugin-folder-only rollback is not supported. + ## Staff weapon commands `/magic weapon give [part...]` diff --git a/projects/Magic/docs/SYSTEM.md b/projects/Magic/docs/SYSTEM.md index eaa6211..154c23a 100644 --- a/projects/Magic/docs/SYSTEM.md +++ b/projects/Magic/docs/SYSTEM.md @@ -126,7 +126,7 @@ or alias. Sacrifice lore keeps the victim's character name from the moment of th ## Dependencies -- **TLibs** (required, 2.3.0 or newer) - shared identity/session API, item refs, formatHex, inventory scanning +- **TLibs** (required; 2.3.0 or newer to load, 2.6.0 for character-owned mage gear and estates) - shared identity/session API, item refs, formatHex, inventory scanning - **ItemsAdder** (required) - `ia.` icons in gui.yml / elements - **RPCharacters** (required, 2.16.0 or newer) - identity provider, character Focus pool, character head, injury and permadeath APIs - **InteractibleFurniture** (required) - pedestals