# Portable character format (Phase 1)

What is stored locally and how it is serialised. Code: `crates/coa-core/src/portable/`. Reasoning:
`PORTABLE_CHARACTERS_AUDIT.md`.

**Status:** format version 1 is *provisional* until the Phase 3 gate (Realm A -> Manager -> Realm B) passes. Until then
a change of shape may be made without a migration because nothing outside development machines holds version 1 data.
After that gate every change bumps the version.

## Versions (`versions.rs`)

| Constant | Value | Meaning |
|---|---|---|
| `PORTABLE_CHARACTER_FORMAT_VERSION` | 1 | the serialised `PortableCharacter` |
| `PORTABLE_COLLECTION_FORMAT_VERSION` | 1 | the encoded id set of a collection |
| `EXTENSION_FORMAT_VERSION` | 1 | the extension container |
| `SNAPSHOT_FORMAT_VERSION` | 1 | the stored snapshot envelope (compressed canonical JSON) |
| `REGISTRY_PROTOCOL_VERSION` | 1 | reserved for Phase 10 |
| `RELAY_PROTOCOL_VERSION` | 1 | reserved for Phase 13 |

A reader **refuses** data whose version is newer than it knows (checked before the shape is parsed), and reads older
versions through a migration.

## Identity

* `CharacterId`, `ProfileId`, `PortableItemId`, `PortablePetId` are **UUIDv7**, generated locally. Only version-7 ids
  are accepted from text or JSON; a v4 or nil UUID is rejected as foreign.
* Local AzerothCore guids never appear in the model. They exist only in the mapping tables
  (`character_server_mapping`, `item_mapping`), per realm.
* Game content is addressed as `<namespace>:<kind>:<id>` (`ContentId`), e.g. `core:wotlk:item:19019`, `coa:class:12`,
  `mod:<module>:item:7`. The last two segments are kind and number; everything before is the namespace. Plain numbers
  elsewhere in the model (spells, quests, factions, skills) are interpreted in the character's `content_namespace`.

## Canonical form and hash

1. The model is **normalised**: every set is sorted and de-duplicated (spells, talents, skills, glyph sets, items by
   container/slot, quests, reputation, action buttons, pets and their spells, enchantments).
2. It is serialised as compact JSON with a fixed field order (`serde`), unknown fields refused on read.
3. `content_hash = SHA-256(canonical JSON)`. Equal characters have equal hashes; the hash does not depend on the
   compressor.
4. The stored payload is `zstd(canonical JSON)`.

## Limits (hostile input)

`model::limits` caps every list and string; the snapshot is capped at 16 MiB decompressed and 8 MiB compressed, and
decompression stops at the cap while reading (decompression bombs). Money is capped at the realm's own maximum
(2,147,483,646 copper). Items must form a valid container tree (containers directly on the character, no two items in
one place, no duplicate ids). Extension payloads must match their recorded hash.

## Revisions

* `character.revision` is the canonical revision; freshness is decided by this integer, never by a timestamp.
* `commit_snapshot(expected_revision, ...)` succeeds only if `expected_revision` equals the canonical revision
  (`StaleRevision` otherwise) and creates revision + 1, in one `BEGIN IMMEDIATE` transaction.
* `rollback_to` creates a **new** revision whose state equals an old one; revision numbers never decrease.
* The newest `history_keep` revisions are kept (default 20, 1..=1000, configurable). The current revision is never
  pruned.
* A character's `ruleset` (`coa` | `wildcard`) can never change.

## Extensions

`extensions` maps an extension namespace (`mod:<module>`) to `{module_version, format_version, content_hash, payload}`.
The payload is opaque bytes: it is stored and returned unchanged, whether or not this Manager understands it. A realm
that does not support an extension simply does not receive it; the canonical copy is kept.

## Collections

Account-wide sets of numeric ids (`coa:wardrobe`, `coa:vanity`, ...), stored per profile and kind:

* union only: `stored = stored U incoming`; nothing is ever removed because a realm did not return it;
* if the union equals what is stored, **no revision is created** and the hash is unchanged;
* encoding: `[format version][count][first id][gap]...`, unsigned LEB128 varints, strictly ascending ids, 1-2 bytes per
  id for realistic sets (50,000 scattered ids < 100 KB);
* `collection_hash = SHA-256("coa-collection-v1\0" + kind + "\0" + encoding)`.

## 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.

| Table | Purpose |
|---|---|
| `profile` | the owner |
| `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)` |
| `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.