Files
ai-engineering/docs/compatibility.md
T
Nilton Constantino 8e75bf7516
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/AI Engineering/pipeline/head There was a failure building this commit
build / jvm (push) Canceled after 0s
build / native (macos-15, macos-arm64) (push) Canceled after 0s
build / native (ubuntu-24.04, linux-x86_64) (push) Canceled after 0s
build / native (windows-2025, windows-x86_64) (push) Canceled after 0s
feat: import open Discussion Framework agendas into Works
Add deterministic preview and fingerprint-bound application for independent
DF sources under an AIE umbrella. Preserve complete agendas and original
evidence with source-scoped identities, validated receipts and safe retries.

Publish prepared Works atomically, require review for changed imports and
retain existing refinement without source edits or model calls.

Advertise protocol contract 2 while continuing to read contract-1 projects. Add JVM,
concurrency, recovery and native coverage; document usage and complete
WRK-0007 with verification evidence.
2026-11-16 14:53:05 +00:00

6.2 KiB

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.

Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts 1 and 2, 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.

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.