feat: add protocol compatibility diagnostics and historical readers

This commit is contained in:
2026-11-16 10:13:05 +00:00
parent a8a8faf5d8
commit f10c237d44
48 changed files with 1382 additions and 13 deletions
+15
View File
@@ -216,6 +216,21 @@ receipts from their input key, allowing reuse after interrupted publication.
Reconciliation derives state from files; no mutable in-memory index is authoritative.
Details and explicit reopening/reauthorization rules are in [epics.md](epics.md).
## Compatibility inspection
The project module owns the protocol contract revision independently of the CLI
release and manifest schema. Filesystem owns the supported storage-format catalog;
existing typed readers continue interpreting older representations in memory.
Verification's compatibility service inspects actual metadata and typed content,
including record revisions and system completion receipts. The CLI exposes a full
read-only report through `project compatibility` and a summary in `status`.
This adds no automatic conversion or blanket normalization. Onboarding refreshes
entry instructions with backups and refuses to overwrite an unsupported contract.
Frozen prior-release fixtures protect historical approvals, completion provenance,
scope hashes and bytes. See [compatibility](compatibility.md) for the public contract
and requirements before a future incompatible writer or migration is introduced.
## Earlier framework review and migration
Both implementations were inspected read-only:
+102
View File
@@ -0,0 +1,102 @@
# 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
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.
- `currentProtocolVersion` and `readableProtocolVersions`: 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`, `migrationRequired` and 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. No required migrations are
registered, 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
`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.
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 | 2 | 1, 2 |
`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 future migrations
`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.
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.
## 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.
+12
View File
@@ -471,6 +471,18 @@ described in discussion/reference files, rather than copied into this workspace.
`artifacts/outputs` is versionable for deliberately retained outputs; use ignored `runs/`
for large temporary results. No command creates large output files by default.
## Compatibility and evolution
`project compatibility` inspects actual stored formats and revisions without writes.
`protocol.json.schemaVersion` versions the manifest, while optional `protocolVersion`
versions the engineering contract (absent means the supported legacy baseline 1).
The diagnostic exposes the supported read/write format catalog separately from the
executable release. Old compatible records remain valid and readable without
normalization, including COMPLETED Works. `onboard` updates only entry instructions
and the manifest; a newer unsupported contract is never silently overwritten.
See [compatibility and evolution](compatibility.md) for public states, update guidance
and requirements for future explicit conversions. No required migration exists today.
## Context and continuity
`work context --format markdown|json` loads only canonical project/Work files. It