feat: adopt local SQLite engineering memory and quality gates
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user