feat(portable): read-only export of offline characters from a realm (Phase 2)

Reads one offline character out of a realm's characters database through the
existing Db abstraction: fixed SQL with the local guid as the only (numeric)
input, one consistent READ ONLY snapshot per character, hex-encoded text.
Maps the approved minimal v1 scope to the portable model; refuses online,
deleted, bot, active challenge/game mode/Manastorm and unknown-table cases.
Adds the 163-table registry, the settings policy, "Make Portable" in one store
transaction, and item mapping lifecycle with content identity (schema 2) so a
recycled local item guid never inherits an old portable item.

Recorded answers of a real MySQL drive the unit tests; live tests re-verify
them, read-only enforcement and snapshot consistency on a disposable server.
No realm database is written and nothing changes for existing installs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
ДмитрийandClaude Sonnet 5.5 committed 2026-10-06 08:11:54 +05:00
1 parent adefa84885
commit c590b82d27
34 files changed
+5236 -110

No files matched your search

+96
View File
@@ -0,0 +1,96 @@
# Portable export from a realm (Phase 2)
Code: `crates/coa-core/src/portable/realm/`. Scope decisions: `PORTABLE_CHARACTERS_AUDIT.md` sections 15-16.
Phase 2 is **read-only**. It reads one **offline** character out of a realm's characters database into a
`PortableCharacter` and (for "Make Portable") registers it in the local store. It never writes to a realm.
## What it does
| Function | Meaning |
|---|---|
| `inspect_characters(db)` | "Inspect realm characters": every character of a non-bot account with the reasons it cannot be exported yet |
| `export_character(db, guid, character_id, prior_items)` | "Export snapshot": the portable model + item observations + warnings |
| `make_portable(db, store, profile, server_id, guid)` | "Make Portable": export, then register in the local store in one transaction (revision 1, bound to the realm, items mapped) |
No Tauri command or UI exists yet (Phase 9).
## How the realm is read
* Through the Manager's existing `Db` abstraction (the bundled `mysql` client, or the same client inside a Docker
database container). No driver, no new connection type, no published port. The Wildcard realm profile is routed by
`Db` exactly like everything else, and **the database decides the ruleset**, not the caller.
* **Fixed SQL, typed input.** Every statement is a literal in `script.rs`. The only input is the character's local
guid as a `u32` formatted as a number. Table and column names of *unknown* tables come from `information_schema`,
are checked as plain identifiers and appear only in `SELECT COUNT(*)`.
* **One consistent read-only snapshot.** All statements for a character run in one `mysql` session inside
`SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ; START TRANSACTION WITH CONSISTENT SNAPSHOT, READ ONLY;`.
Verified against a real server: a write inside the script fails, and a concurrent write by someone else in the
middle of the script is not seen.
* **Hex-encoded text.** Names, item texts, settings and macro blobs are returned as `x<hex>`, so tabs, newlines, quotes
and backslashes cannot confuse the parser.
* Writing into a realm (Phase 3) must use prepared statements or the realm's own in-core import; this read path is not
a basis for it.
## Who may be exported (`Blocker`)
| Blocker | Rule |
|---|---|
| `Online` | `characters.online <> 0` (also after a crash, when the flag is stale: stop the realm or log in/out) |
| `Deleted` | `deleteDate` is set |
| `BotAccount` | account `COABOT*` or `COAMANAGER` |
| `ActiveChallenge` | a row in `coa_character_challenge` |
| `ActiveGameMode` | `coa_character_gamemode.gameMode <> 0` |
| `ActiveCustomTrial` | a row in `coa_custom_trial_active` |
| `PendingManastormCaches` | a row in `ascension_manastorm_cache` (it names item guids that would be orphaned) |
| `UnclassifiedState(table)` | a table this Manager does not know has a per-character column with rows for this character |
Finished challenges, game mode 0 and condition flags are history, not active state, and do not block (decision D6:
*active* state blocks). A realm that lacks a core table (`SchemaMismatch`) cannot be exported from.
## What is exported (v1)
17 tables: `characters`, `character_inventory`, `item_instance`, `character_gifts`, `character_spell`,
`character_talent`, `character_skills`, `character_glyphs`, `character_reputation`, `character_queststatus`,
`character_queststatus_rewarded` (`active = 1`, as the realm loads it), `character_action`, `character_pet`, `pet_spell`,
`character_pet_declinedname`, `character_settings` (by policy), `character_account_data` (macros, type 5).
**Not exported by decision** (deferred): collections, the personal Ascension bank, equipment sets, per-character wardrobe
(`character_appearance*`), `mod_craftsmans_codex`. Auras, cooldowns, mail, guild, social, achievements, daily/weekly
quests, position and homebind are never part of v1.
Left out *with a warning* (the realm would delete them on load anyway): inventory rows without an `item_instance`,
items in a bag that is not on the character, items in buyback slots.
### `character_settings` policy (`policy.rs`, version 1)
* **Carry**: known CoA gameplay state (`core.ascension_*`, `core.spell_charge.*`, `core.destiny_weaver`, ...), and
`core.wildcard*` on a Wildcard realm.
* **Drop**: `coa.bot*`, `coa.gameplay_test`, `coa.highrisk`.
* **Quarantine**: everything else is kept in the snapshot as the opaque extension `coa:unlisted-settings` (never
destroyed, never applied at a realm).
### Table registry (`registry.rs`)
All 163 tables of the characters schema are classified (`Portable`, `Deferred`, `Collection`, `AccountLocal`,
`CharacterLocal`, `Blocking`, `Realm`). A test fails if the real schema has a table the registry does not know, and at
export time an unknown table that holds this character's rows blocks the export. A silent half-export is not possible.
## Item identity
Realms recycle local item guids. `ItemObservation.identity` hashes what cannot change during an item's life (entry,
random property, crafter). A re-export keeps an item's portable id only if the identity behind the local guid is
unchanged; a recycled guid produces a new portable item. The store side is in `PORTABLE_FORMAT.md` (item mapping
lifecycle).
## Tests
* `realm/tests.rs`: on **recorded answers of a real MySQL** (`testdata/golden/`), no database needed: naked level 1,
geared level 80 (bags, enchants, gems, random suffix, crafted-by, texts, charges, gift, currency tokens), quests,
reputation, action bars, 300 spells + talents + glyphs + skills + CoA settings + binary macros, hunter and summon
pets with declined names, every blocker, item id stability and recycling, Wildcard ruleset, CRLF, 400 damaged
answers (no panics), registration in the store (one transaction, refused twice, rolled back on failure).
* `realm/live.rs` (`#[ignore]`): the same answers re-recorded/verified against a **real disposable MySQL**, plus the
read-only and snapshot-consistency proofs, the 21 genuine template characters of the schema fixture, and the proof that
`make_portable` changes nothing in the realm. Instructions are at the top of the file.
* `tools/gen_portable_fixture.py` writes `testdata/realm-fixture.sql` (deterministic).
+22 -3
View File
@@ -76,7 +76,7 @@ Account-wide sets of numeric ids (`coa:wardrobe`, `coa:vanity`, ...), stored per
## Store (`%LOCALAPPDATA%\CoAServerManager\portable\portable.db`)
SQLite, WAL, `synchronous=FULL`, `foreign_keys=ON`, `application_id = 0x434F4150`, forward-only migrations tracked in
`PRAGMA user_version`. A database from a newer Manager, or a foreign SQLite file, is refused and left untouched.
`PRAGMA user_version` (currently 2). A database from a newer Manager, or a foreign SQLite file, is refused and left untouched.
| Table | Purpose |
|---|---|
@@ -84,8 +84,27 @@ SQLite, WAL, `synchronous=FULL`, `foreign_keys=ON`, `application_id = 0x434F4150
| `character` | summary row + canonical revision |
| `snapshot` | `(character_id, revision)` -> compressed canonical payload + hash |
| `character_server_mapping` | `(character_id, server_id)` -> local guid; `UNIQUE(server_id, local_guid)` |
| `item_mapping` | `(character_id, server_id, portable_item_id)` -> local item guid; `UNIQUE(character_id, server_id, local_item_guid)` |
| `item_mapping` | one row per mapping with a lifecycle (schema 2, see below) |
| `collection` | per profile and kind: revision, hash, encoded set |
| `setting` | `history_keep` |
The store never reads or writes a realm database and never leaves the machine.
## Item mapping lifecycle (schema 2)
A realm's item guid counter restarts at `MAX(guid)+1`, so a freed guid can be given to a different item. A bare
`guid -> portable item` mapping would attach the new item to the old portable id. Every mapping therefore records what
the item *was* (`entry`, `identity`) and has a state:
* `active`: at most one per portable item and at most one per local item guid
(`UNIQUE(character_id, server_id, local_item_guid)` and `UNIQUE(.., portable_item_id)`, both for active rows);
* `retired` (kept for the record) with a reason: `guid_reused`, `moved`, `absent`, `character_rebound`.
`Store::reconcile_item_mappings` takes the complete observation of a character on a realm and confirms, adds or retires
mappings; `Store::resolve_item_ids` answers `Known`, `Reused` (recycled guid) or `Unmapped` for a local guid and its
current identity. Schema-1 rows are migrated with an empty identity, which matches nothing: they are re-verified, never
trusted. Rebinding a portable character to another local guid retires its item mappings.
The identity covers what cannot change during an item's life (entry, random property, crafter); two different items that
share all of these are interchangeable for mapping purposes.
The store never reads or writes a realm database and never leaves the machine. (Phase 2's realm reader lives in
`portable/realm/` and is documented in `PORTABLE_EXPORT.md`; it only reads.)