From c412b41f79c6617158c513a5a206b42aca483ece Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Wed, 14 Oct 2026 09:31:30 +0000 Subject: [PATCH 1/2] docs: explain attested empty legacy gear import --- projects/Magic/docs/MAGE_GEAR.md | 36 ++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/projects/Magic/docs/MAGE_GEAR.md b/projects/Magic/docs/MAGE_GEAR.md index 11b6e00..e2907fb 100644 --- a/projects/Magic/docs/MAGE_GEAR.md +++ b/projects/Magic/docs/MAGE_GEAR.md @@ -175,6 +175,42 @@ 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. +### Exact empty legacy save before upgrading + +Magic 0.5.2 can save an empty station file as zero bytes. Import that specific +legacy representation only with Paper stopped, the deployment lock held, a +complete checkpoint, and retained logs/ledger proving that character-ownership +Magic has never run against this data. Run the reviewed tool pinned by commit +and file SHA-256. The producer JAR must be the allowlisted 0.5.2 release. + +```sh +python3 tools/gear-ownership.py --legacy-empty-import \ + --data /path/to/plugins/Magic/data --legacy-jar /path/to/magic-0.5.2.jar +``` + +Preview writes nothing and returns `ELIGIBLE_REQUIRES_LINEAGE_ATTESTATION` with +the baseline digest and file metadata. Put that exact digest and the fresh +checkpoint/lineage evidence in an attestation file, then apply: + +```sh +python3 tools/gear-ownership.py --legacy-empty-import \ + --data /path/to/plugins/Magic/data --legacy-jar /path/to/magic-0.5.2.jar \ + --apply --expect-baseline --attest /path/to/lineage.txt \ + --backup /path/to/new-external-recovery +``` + +Apply retains the zero source, attestation, tool hash and plan/result in the new +verified backup, then publishes exactly `stations: {}` followed by a newline +with the original mode. It refuses other content, links, history, sibling or +staging evidence and changed metadata; it is not a generic blank-file repair. +It cannot combine with `--kind` or `--journal`. Exact canonical replay returns +`ALREADY_CANONICAL` without another backup. On `REFUSED` or +`PUBLISHED_UNCONFIRMED`, keep Paper stopped and preserve the evidence; preview +again before deciding what to do. A retained staging file needs staff review. +An old 0.5.2 run before the first 0.6.0 Start rewrites the empty file to zero, +requiring a fresh checkpoint and preview. After any 0.6.0 Start, the complete +checkpoint rollback rule above still applies. + ## Staff weapon commands `/magic weapon give [part...]` From 9f8661419c4ec77e5399d7e1efa3e620b26ae79a Mon Sep 17 00:00:00 2001 From: Ryan Barlow <7389646+ryanbarlow97@users.noreply.github.com> Date: Wed, 14 Oct 2026 10:18:45 +0000 Subject: [PATCH 2/2] docs: clarify empty gear import evidence --- projects/Magic/docs/MAGE_GEAR.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/projects/Magic/docs/MAGE_GEAR.md b/projects/Magic/docs/MAGE_GEAR.md index e2907fb..34b7fbb 100644 --- a/projects/Magic/docs/MAGE_GEAR.md +++ b/projects/Magic/docs/MAGE_GEAR.md @@ -190,7 +190,8 @@ python3 tools/gear-ownership.py --legacy-empty-import \ Preview writes nothing and returns `ELIGIBLE_REQUIRES_LINEAGE_ATTESTATION` with the baseline digest and file metadata. Put that exact digest and the fresh -checkpoint/lineage evidence in an attestation file, then apply: +checkpoint/lineage evidence in an attestation file, then apply using the same +`--data` path through the same mount: ```sh python3 tools/gear-ownership.py --legacy-empty-import \ @@ -199,10 +200,12 @@ python3 tools/gear-ownership.py --legacy-empty-import \ --backup /path/to/new-external-recovery ``` -Apply retains the zero source, attestation, tool hash and plan/result in the new -verified backup, then publishes exactly `stations: {}` followed by a newline -with the original mode. It refuses other content, links, history, sibling or -staging evidence and changed metadata; it is not a generic blank-file repair. +Apply first retains the zero source, attestation and plan (including the tool +hash) in the new verified backup. It then publishes exactly `stations: {}` +followed by a newline with the original mode, owner and group. Only after +publication verifies does it write the successful result. It refuses other +content, links, history, sibling or staging evidence and changed metadata; it +is not a generic blank-file repair. It cannot combine with `--kind` or `--journal`. Exact canonical replay returns `ALREADY_CANONICAL` without another backup. On `REFUSED` or `PUBLISHED_UNCONFIRMED`, keep Paper stopped and preserve the evidence; preview