feat: adopt local SQLite engineering memory and quality gates
This commit is contained in:
+25
-13
@@ -1,7 +1,7 @@
|
||||
# Compatibility and protocol evolution
|
||||
|
||||
A project's historical records do not have to be rewritten whenever AIE evolves.
|
||||
Completed Works retain their original files, approvals, evidence and completion
|
||||
Completed Works retain useful memory, approvals, validated evidence results and completion
|
||||
provenance. Continued readability is a reader responsibility, not a reason to reopen
|
||||
delivered work or to add current refinement content to old Works.
|
||||
|
||||
@@ -32,13 +32,24 @@ No repository commands, adapters, locks or writes occur during compatibility rea
|
||||
| `UNSUPPORTED` | A declared version has no supported reader | 4 |
|
||||
| `INVALID` | Malformed metadata, unknown fields, missing records or invalid typed content | 4 |
|
||||
|
||||
The report is an inspection, not a conversion plan. No required migrations are
|
||||
registered, so `migrationRequired` is false, including for unsupported versions:
|
||||
The report is an inspection, not a conversion plan. Legacy reading does not require conversion, so `migrationRequired` is false, including for unsupported versions:
|
||||
an unknown version is not evidence that an older CLI can convert it. Unsupported
|
||||
records require a CLI with the appropriate reader; invalid data needs deliberate
|
||||
repair. Basic command/path errors retain the usual exit codes.
|
||||
|
||||
## Three independent version dimensions
|
||||
Contract 4 adds `sqlite-storage`, `local-memory`, `quality-gates`,
|
||||
`temporary-artifacts` and the explicit storage migration route. New projects select
|
||||
SQLite and ignore state by default. Legacy projects can remain readable on their
|
||||
original backend. SQLite requires contract 4; a database without the matching
|
||||
bootstrap is refused rather than treated as empty memory.
|
||||
|
||||
The SQLite report inspects typed records/revisions in the database. Bootstrap,
|
||||
database schema and original legacy document versions remain separate dimensions.
|
||||
Project validation checks foreign keys, revision chains and evidence/retirement facts.
|
||||
A retired attachment is valid historical evidence only with its persisted validation;
|
||||
new checks still require available inputs.
|
||||
|
||||
## Independent version dimensions
|
||||
|
||||
`protocol.json.schemaVersion` describes the manifest's structure. Its new optional
|
||||
`protocolVersion` identifies the engineering contract. The initial explicit contract
|
||||
@@ -49,7 +60,7 @@ operations and onboarding from overwriting a newer contract. Compatibility inspe
|
||||
remains available to explain the mismatch.
|
||||
|
||||
Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts
|
||||
1, 2 and 3, and existing contract-1 projects remain legacy compatible without any
|
||||
1, 2, 3 and 4, and existing contract-1 projects remain legacy compatible without any
|
||||
Work migration. An import-enabled manifest requires contract 2 and the
|
||||
`discussion-import` capability. This makes old contract-1 CLIs refuse the new
|
||||
manifest before onboarding could overwrite its feature declaration. `onboard`
|
||||
@@ -70,7 +81,8 @@ The format catalog is deliberately small:
|
||||
| Canonical record schema (including configuration and Work) | 1 | 1 |
|
||||
| Narrative document | 2 | 1, 2 |
|
||||
| Metadata-only document (Work) | 1 | 1 |
|
||||
| Work sequence | 2 | 1, 2 |
|
||||
| Work sequence (legacy files) | 2 | 1, 2 |
|
||||
| SQLite schema/application | 1 / AIE1 | 1 / AIE1 |
|
||||
|
||||
`schemaVersion` and `documentVersion` describe different layers of one file. A
|
||||
discussion may have record schema 1 in document version 2. An omitted document
|
||||
@@ -84,7 +96,7 @@ record has been converted. The scanner reads actual versions in current records
|
||||
history; mixed supported versions are normal. Capabilities are discovery labels,
|
||||
not independent migration versions or evidence that a feature has been configured.
|
||||
|
||||
## Updating instructions and future migrations
|
||||
## Updating instructions and storage
|
||||
|
||||
`aie onboard` is idempotent and backs up changed entry files. It refreshes the README,
|
||||
agent instructions and manifest, preserving project rules outside the managed block.
|
||||
@@ -99,12 +111,12 @@ reader/adaptation path and retained fixtures. Unknown schemas and fields must no
|
||||
be silently ignored to simulate compatibility. Increasing a writer version must not
|
||||
remove an existing reader or alter the meaning of historical approval/provenance.
|
||||
|
||||
A future required conversion must declare its source and target versions and expose
|
||||
a public command that previews exact scope before applying changes, backs up original
|
||||
bytes, resumes safely and is idempotent. The report may only claim a required migration
|
||||
when a known route actually exists. Completed historical Works must retain a read path;
|
||||
they must not be selected for blanket normalization. There is no placeholder migration
|
||||
command and no automatic project-wide rewrite in this release.
|
||||
The public SQLite route is `storage migrate` (read-only preview), then
|
||||
`--apply --expect HASH`. `--recover` and `--rollback` require the operation's same
|
||||
fingerprint. It is optional for supported legacy reading and never runs implicitly.
|
||||
Read [the migration procedure](storage-migration.md) before conversion. Unknown
|
||||
schemas still need an appropriate reader; this route converts supported legacy
|
||||
records, not arbitrary unsupported versions.
|
||||
|
||||
## Historical regression fixture
|
||||
|
||||
|
||||
Reference in New Issue
Block a user