Skip to content

docs: explain attested empty legacy gear import #241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanbarlow97 merged 2 commits into from
Oct 14, 2026
Merged

docs: explain attested empty legacy gear import #241

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c412b41
docs: explain attested empty legacy gear import
ryanbarlow97 Oct 14, 2026
9f86614
docs: clarify empty gear import evidence
ryanbarlow97 Oct 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions projects/Magic/docs/MAGE_GEAR.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,45 @@ 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 using the same
`--data` path through the same mount:

```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 <baseline-HEX> --attest /path/to/lineage.txt \
--backup /path/to/new-external-recovery
```

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
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 <player> <staff|wand|sword> <element> <aura> <part> [part...]`
Expand Down