From c8373706487a68e44d7de9c4d7a62bbbaf357907 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Wed, 14 Oct 2026 00:26:43 +0000 Subject: [PATCH 1/5] docs(magic): document character gear ownership and recovery --- projects/Magic/docs/MAGE_GEAR.md | 103 +++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/projects/Magic/docs/MAGE_GEAR.md b/projects/Magic/docs/MAGE_GEAR.md index 4c1e5b2..723bf56 100644 --- a/projects/Magic/docs/MAGE_GEAR.md +++ b/projects/Magic/docs/MAGE_GEAR.md @@ -49,6 +49,109 @@ 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 that character or +`magic.admin`. Charging and empty-hand ejection remain public to active living +characters. An ownerless legacy station retains its public behavior; an active +ownerless run records its initiating character for abort checks. A malformed or +unresolved owner never becomes the visiting character's property. + +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. + +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. + +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 +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. + +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. +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. Do not downgrade a progressed station to an +older JAR: the retained legacy item map may precede its newer authoritative item +bytes. + ## Staff weapon commands `/magic weapon give [part...]` From 809b6c654bf0c9fbaf531ce2fdcad3ed04f4153c Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Wed, 14 Oct 2026 00:53:35 +0000 Subject: [PATCH 2/5] docs: clarify character gear API requirements --- projects/Magic/docs/SYSTEM.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 35cb205ea2f145aa3e6d869f61377fe500b28507 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Wed, 14 Oct 2026 02:24:04 +0000 Subject: [PATCH 3/5] docs: clarify gear abort recipients and recovery holds --- projects/Magic/docs/MAGE_GEAR.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/projects/Magic/docs/MAGE_GEAR.md b/projects/Magic/docs/MAGE_GEAR.md index 723bf56..2946383 100644 --- a/projects/Magic/docs/MAGE_GEAR.md +++ b/projects/Magic/docs/MAGE_GEAR.md @@ -52,9 +52,10 @@ 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 that character or `magic.admin`. Charging and empty-hand ejection remain public to active living -characters. An ownerless legacy station retains its public behavior; an active -ownerless run records its initiating character for abort checks. A malformed or -unresolved owner never becomes the visiting character's property. +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. @@ -70,6 +71,9 @@ 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; @@ -77,6 +81,8 @@ 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 @@ -104,7 +110,10 @@ 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 -uses empty storage slots, retains any remainder and retries for the owning +always targets the deposited 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. @@ -115,6 +124,9 @@ attunement. An explicit empty cost map remains a known material bypass. 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 preserve regular `magic-*.tmp` staging files without treating them +as committed records. 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 From 0de2143e3980b41e540c2148abdcecbc94404ea1 Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Wed, 14 Oct 2026 02:27:25 +0000 Subject: [PATCH 4/5] docs: refer to the current station owner for returns --- projects/Magic/docs/MAGE_GEAR.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/Magic/docs/MAGE_GEAR.md b/projects/Magic/docs/MAGE_GEAR.md index 2946383..0fdc33a 100644 --- a/projects/Magic/docs/MAGE_GEAR.md +++ b/projects/Magic/docs/MAGE_GEAR.md @@ -110,7 +110,7 @@ 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 deposited character, even after a staff abort. Immediate +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 From 412a27e6128f3776d81c815f823dc8fdc0bd57fe Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Wed, 14 Oct 2026 03:12:22 +0000 Subject: [PATCH 5/5] docs: require complete Magic downgrade checkpoint --- projects/Magic/docs/MAGE_GEAR.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/projects/Magic/docs/MAGE_GEAR.md b/projects/Magic/docs/MAGE_GEAR.md index 0fdc33a..11b6e00 100644 --- a/projects/Magic/docs/MAGE_GEAR.md +++ b/projects/Magic/docs/MAGE_GEAR.md @@ -50,8 +50,8 @@ confirmation are cleared, so it must choose and confirm again. A player without 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 that character or -`magic.admin`. Charging and empty-hand ejection remain public to active living +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 @@ -120,12 +120,16 @@ 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. +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 preserve regular `magic-*.tmp` staging files without treating them -as committed records. Temporary-looking directories or symlinks and malformed +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. @@ -160,9 +164,16 @@ 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. Do not downgrade a progressed station to an -older JAR: the retained legacy item map may precede its newer authoritative item -bytes. +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