architecture: Define bundle, logical-contract, and persisted-payload compatibility

Summary

Define and enforce compatibility guarantees for the compiled agent bundle and every persisted contract that participates in its logical identity or runtime interpretation.

The original investigation focused on graphs and result payloads. The compiler-first architecture expands the scope to the complete bundle while keeping logical contracts and physical formats independently versioned.

Compatibility model

Version independently:

1. bundle manifest/physical packaging — directory, deterministic ZIP and future OCI mapping;
2. logical capability contracts — normalized capability, schema, resource and phase-policy semantics;
3. derived artifact formats — graph, vectors, indexes and caches;
4. runtime exchange contracts — route decision, hydrated capability, execution request/result and context pack;
5. reports — source coverage, containment, evaluation, provenance, reproducibility and trust summary.

A loader may recognize a physical container without understanding the logical contract. In that case it may inspect metadata, but it must not route, hydrate or silently reinterpret the bundle.

Required behavior

• every persisted component carries or references a versioned contract;
• manifest references component role, media type, size, digest and contract version;
• unknown future logical versions fail explicitly for semantic use;
• unknown additive fields are tolerated only where the contract permits;
• logical migrations are explicit, versioned and produce a new artifact identity;
• lossy migrations emit a structured loss report and are blocked by default;
• physical repackaging that preserves components does not change logical identity;
• platform-derived binary indexes are separate from canonical logical representation;
• a compatible index may be rebuilt into an external content-addressed cache without mutating the bundle.

Reproducibility profiles

Distinguish:

• semantic equivalence across the declared supported platform matrix;
• byte identity within a declared reproducible profile (Python/ABI/platform/native components).

The manifest states what was actually proven.

Inventory

Include at minimum:

• bundle manifest and lock;
• normalized capabilities and schemas;
• resource descriptors/content;
• graph/index/vector inputs and outputs;
• route decisions and explanations;
• context/handoff packs and build reports;
• normalized execution results;
• evaluation datasets/results;
• enrichment patches and acceptance state;
• trust/restriction registries and summaries.

Acceptance criteria

• committed compatibility inventory and policy;
• compatibility fixtures from at least one older release where applicable;
• loader tests for old, current, unknown-future and malformed contracts;
• independent logical/physical version tests;
• explicit migrator interface and loss-report schema;
• stale catalog/source/builder mismatches fail or degrade according to pinned policy;
• directory and deterministic ZIP forms share logical identity;
• documentation in stability and compiler artifact references this policy.

Non-goals

• indefinite compatibility for experimental contracts;
• silent best-effort reinterpretation;
• embedding operational deployment approval in artifact compatibility;
• requiring byte-identical derived binaries across unrelated platforms.

No files or entry points are named. Start by mapping the compatibility model and inventory into the committed policy, then define the loader, migrator, and loss-report test scope; done means the acceptance criteria are covered, including logical/physical identity and old, current, future, and malformed contract cases.