7.5 KiB
Compatibility and protocol evolution
A project's historical records do not have to be rewritten whenever AIE evolves. 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.
Public inspection
Run aie project compatibility --format json using the installed executable.
It reports:
cliVersion: the executable release, separately from data compatibility.currentProtocolVersionandreadableProtocolVersions: supported contract revisions.formats: supported read versions and the current write version for each format family.findings: observed versions, missing defaulted fields and diagnostics by file.state,readable,migrationRequiredand public guidance.
The scan covers configuration, discovery manifest, Work counter, all Works (including
archived and completed), canonical record documents, artifact manifests, AIE-generated
completion receipts and record revision files. It does not treat local backups,
ignored runs or ordinary artifact payloads as protocol records. It checks missing
references to current records. It does not
validate revision links, evidence integrity, semantic acceptance criteria or delivery
readiness; run project validate and work check for their respective contracts.
No repository commands, adapters, locks or writes occur during compatibility reads.
| State | Meaning | CLI exit |
|---|---|---|
CURRENT |
Observed representations match current supported formats | 0 |
LEGACY_COMPATIBLE |
Supported older representations or omitted defaulted Work fields | 0 |
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. 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.
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
revision is 1; absent protocolVersion means the pre-versioned baseline contract 1
and is reported as legacy compatible. The CLI release number is not a substitute
for either. Unsupported declared manifest/contract versions prevent ordinary CLI
operations and onboarding from overwriting a newer contract. Compatibility inspection
remains available to explain the mismatch.
Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts
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
refreshes the entry files with backups; completed Works and history are unchanged.
Contract 3 adds human Work guidance and optional Plan experiments; it advertises
work-guidance, human-decision-request and plan-experiments. New Works ask for
mode and require DEC approval by default. Existing Works without guidance retain
their historical semantics until explicit adoption. Guidance is omitted when absent
and empty experiment collections are omitted, preserving completion digests.
See Work conduct and OODA for the behavior and commands.
The format catalog is deliberately small:
| Format | Current writer | Supported readers |
|---|---|---|
| Manifest schema | 1 | 1 |
| Canonical record schema (including configuration and Work) | 1 | 1 |
| Narrative document | 2 | 1, 2 |
| Metadata-only document (Work) | 1 | 1 |
| 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
version means 1. Work operational/refinement/EPIC fields absent from earlier schema 1
records retain their documented empty/false defaults. Existing sequence readers
interpret legacy decimal reservations without changing identifier spelling; only an
explicit creation of a new Work advances and writes the sequence.
The installed manifest declares the expected contract, not a certificate that every record has been converted. The scanner reads actual versions in current records and 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 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.
It does not convert Works, decisions, history, evidence or the Work counter, and does
not manufacture topics, answers, decisions or approval. A historical Work remains
legacy compatible after onboarding, which is expected. Use only the installed CLI
and public documentation for consumer operations; report gaps rather than reading the
implementation to infer a procedure.
When introducing an incompatible format or contract, add an explicit supported reader/adaptation path and retained fixtures. Unknown schemas and fields must not be silently ignored to simulate compatibility. Increasing a writer version must not remove an existing reader or alter the meaning of historical approval/provenance.
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 before conversion. Unknown
schemas still need an appropriate reader; this route converts supported legacy
records, not arbitrary unsupported versions.
Historical regression fixture
CompatibilityTest loads a frozen project produced by the prior 0.1.0 native
executable, with a pre-versioned manifest, legacy sequence, omitted Work fields,
YAML-only discussion and decision revision, accepted decision, evidence and completed
Work. The tests compare all stored bytes before/after reads, and all Work files
before/after onboarding. They also check interpreted approval/completion provenance,
the original scope digest, mixed versions and unsupported/corrupt formats.