# 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 --format json ``` Application takes the publication lock, verifies the current fingerprint, makes a safety copy under `.ai-engineering/.local/sqlite-migration//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 # Or explicitly return to the recoverable legacy source: aie storage migrate --rollback --expect ``` 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.