# warm-format
```
warm-format verify <store-or-data-dir> [--passphrase-env VAR] [--deep] [--json]
warm-format plan <store> warm-format upgrade <src> <dst> [--dry-run]
warm-format versions warm-format dump <store> [--frame N]
```
`verify` never modifies the store. `--deep` opens a private copy with the engine and compares
the loaded documents, vector count and relations with an independent replay of the journal.
Without a passphrase an encrypted store is checked for framing and CRC32 only
(`payloadsAuthenticated: false`).
## Exit codes
| 0 | ok | all checks passed (info findings allowed) |
| 10 | recoverable | opens after the engine repairs it: torn tail, bad cache, partial audit entry |
| 20 | corrupt | committed data or structure is damaged |
| 30 | unsupported | newer format, unknown encoder, or a store this build never opened (no `store.json`) |
| 64 / 74 | | usage / unreadable path |
## Finding codes
Info: `no-checksum-sidecar`, `legacy-zero-terminator`, `pre-manifest-store`, `orphan-generation`,
`text-segment-cache`, `index-cache-fresh`, `index-cache-stale`, `payloads-not-authenticated`,
`unrecognized-file`, `salt-unused`, `tenant-name`.
Warning: `torn-tail`, `segment-size`, `segment-size-unaligned` (final segment), `index-cache-invalid`,
`audit-torn-tail`, `audit-unknown-op`, `shard-meta-invalid`.
Error: `frame-corrupt`, `manifest-checksum`, `manifest-invalid`, `schema-invalid`, `segment-gap`,
`segment-size`, `payload-structure`, `payload-unrecognized`, `auth-failed`, `salt-invalid`,
`pointer-invalid`, `missing-file`, `key-invalid`, `deep-open`, `not-a-store`.
Unsupported: `storage-format-newer`, `storage-format-unknown`, `schema-newer`, `schema-version`,
`transaction-newer`, `transaction-older`, `unknown-magic`, `unknown-encoder`, `unknown-metric`,
`pre-schema-store`.
## Upgrade
`upgrade` writes a new store; the source is locked and never modified. Registered steps:
| `arena-1-to-4`, `arena-2-to-4`, `arena-3-to-4` | re-append every committed frame payload (opaque, encrypted frames unchanged) into a new format-4 arena; `seq` is renumbered |
| `text-segment-1-to-2` | drops `documents.text` (rebuilt on open) |
| `index-caches` | drops `indices.json` and NSG/IVF files (bound to the old journal length) |
The result is verified, its frame list (length and CRC32) must equal the source's, and it is
published with one rename. A store with no `store.json`, or a damaged or newer store, is refused
(use `warm-admin reencode`, restore a snapshot, or the newer release). A store already at format 4
needs nothing. Adding a format version means adding a registry entry in `src/core/format/upgrade.rs`
and a golden store.