feat: add protocol compatibility diagnostics and historical readers
This commit is contained in:
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user