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

3.4 KiB

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:

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:

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:

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. Work/DEC sharing, import/export, distributed reconciliation and backup as a product feature remain outside this version.