73 lines
3.4 KiB
Markdown
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.
|