Compatibility data contracts

agentic-proteins preserves historical names for runtime request, execution, state, and API contracts. It does not maintain an independent schema model. Objects imported through the bridge are the canonical runtime objects, so validation and serialization behavior come from bijux-proteomics-runtime.

Contract mapping

Legacy path	Canonical owner	Contract family
agentic_proteins.execution.schemas	bijux_proteomics_runtime.execution.schemas	execution traces and workflow execution payloads
agentic_proteins.state.schemas	bijux_proteomics_runtime.state.schemas	artifact metadata, confidence items, and state snapshots
agentic_proteins.execution.run_config	bijux_proteomics_runtime.runs.run_config	run configuration and execution-mode choices
agentic_proteins.execution.evaluation.schemas	bijux_proteomics_runtime.execution.evaluation.schemas	evaluation observations and results
agentic_proteins.tools.schemas	bijux_proteomics_runtime.execution.tools.schemas	tool requests, responses, and failure data
agentic_proteins.interfaces.http.v1.schema	bijux_proteomics_runtime.api.v1.schema	HTTP request and response models

flowchart LR
    caller["legacy caller"]
    bridge["agentic_proteins.*\nimport compatibility"]
    canonical["bijux_proteomics_runtime.*\nvalidation and serialization"]
    document["runtime-owned payload"]
    caller --> bridge --> canonical --> document

Because forwarding modules re-export canonical definitions, an instance does not acquire a separate compatibility type identity. This is important for Pydantic validation, equality, exception handling, and serialized documents.

HTTP schema parity

The tracked compatibility API contract lives under apis/agentic-proteins/v1/; the canonical contract lives under apis/bijux-proteomics-runtime/v1/. Each contains a pinned OpenAPI document, a reviewable YAML schema, and a schema hash. Compatibility changes must be checked against both roots so an apparently harmless runtime evolution does not break legacy clients silently.

Schema parity does not mean permanent equality. A canonical API can add new behavior that is not promised through the bridge. Any intentional divergence requires an explicit compatibility decision and migration route.

Canonical schema change	Bridge decision	Consumer evidence
additive optional field	expose only if legacy validation and clients remain compatible	OpenAPI diff, request/response parity, legacy client tests
changed default or enum	treat as behavioral compatibility risk	old and new serialization cases, caller impact, migration guidance
renamed or removed field	preserve with declared adaptation or refuse	mapping and loss statement, deprecation evidence, replacement route
new canonical-only endpoint	leave outside the bridge unless explicitly promised	canonical documentation and no implied legacy route
error-schema change	preserve status and machine-readable failure contract	status-code, body-schema, and exception parity

Version-Skew Contract

The bridge and canonical runtime are released separately, so import success alone cannot establish a compatible pair. A governed deployment must record both package versions, the imported canonical target, the API or schema digest where applicable, and the parity checks used for that pair.

flowchart LR
    bridge["agentic-proteins version"]
    runtime["runtime version"]
    contract["declared preserved surface"]
    parity["pair-specific parity evidence"]
    usable{"compatible pair?"}
    bridge --> usable
    runtime --> usable
    contract --> parity --> usable
    usable -->|yes| consumer["supported migration window"]
    usable -->|no| refusal["visible incompatibility"]

Persisted payloads remain runtime-owned. The compatibility package version can help reproduce an import path, but it must never replace the canonical schema version, runtime version, or artifact fingerprint in a durable record.

Stability boundary

• Public bridge imports must resolve to a declared canonical target.
• Field validation, defaults, enum values, and JSON behavior are owned by the canonical module.
• Private names forwarded for historical reasons are migration liabilities, not newly supported API.
• Dead namespace modules do not define data contracts and must not gain them.
• New consumers should import canonical types directly.

Use the canonical migration guide to resolve a specific module and the runtime CLI reference for the maintained operator surface.