Files
ai-engineering/docs/storage-migration.md
T

73 lines
3.4 KiB
Markdown

# SQLite migration and recovery
Installation and migration are separate operations. Building/installing a CLI does
not convert a project. Keep the installed version used by ongoing projects until
choosing to activate a compatible release. This implementation was tested on
fixtures only; its canonical workspace and consumers were not migrated.
## Preview and apply
Use a CLI that advertises protocol contract 4. In the chosen legacy project:
```sh
aie project compatibility --format json
aie project validate --format json
aie storage migrate --format json
```
Preview reads supported canonical records, histories, evidence and bootstrap. It
returns validity, Work count and a fingerprint. It writes no lock, backup or database.
Repair invalid input first. Preserve original scope/authority; do not reopen completed
Works to normalize them. This route does not accept unknown future schemas.
After reviewing the preview:
```sh
aie storage migrate --apply --expect <fingerprint> --format json
```
Application takes the publication lock, verifies the current fingerprint, makes a
safety copy under `.ai-engineering/.local/sqlite-migration/<operation>/original`,
and imports into a separate staging database. It compares typed values/revisions,
references, approvals, reserved IDs, hashes and completion provenance. Original
file bytes remain external for historical chain verification; they are not BLOBs
or file-shaped TEXT in SQLite.
Only after validation does activation publish the protected contract, database and
storage selection. A visible `works/SQLITE-STORAGE` marker also stops legacy readers
that had already passed an old contract check. Existing Work documents stay
byte-identical as retained non-authoritative originals; future writes use SQLite.
No tracked file is automatically untracked or removed, and existing Git ignore policy
is preserved. New projects use `init` with state ignored by default.
Success reports APPLIED and the safety-copy path. Staging is removed. Repeating the
same application is idempotent. Keep the safety originals: historical revision hashes
may depend on them. They are not a general backup/export feature.
## Interrupted operation
Ordinary CLI access reports the pending migration rather than reading mixed storage.
Inspect its public preview/report, then choose:
```sh
aie storage migrate --recover --expect <operation-fingerprint>
# Or explicitly return to the recoverable legacy source:
aie storage migrate --rollback --expect <operation-fingerprint>
```
Recovery verifies source/safety/prepared data and resumes without duplicate records.
If a legacy writer changed input before activation, recovery refuses stale data;
rollback preserves those legacy edits, then a new preview captures them.
Rollback restores only bootstrap files changed by this operation and removes its
unchanged published database/guard. It retains the safety copy. Unrelated bootstrap
edits require deliberate review. Once SQLite has received new engineering writes,
rollback refuses to discard that memory; keep SQLite and inspect the diagnostic.
Never delete the database or journal to force a fresh-looking project.
A migration does not retroactively discard legacy evidence, add approvals or claim
new quality gates passed. New temporary inputs and gate results follow the current
[retention contract](protocol.md#temporary-inputs-and-outputs). Work/DEC sharing,
import/export, distributed reconciliation and backup as a product feature remain
outside this version.