# Versioning And Compatibility

Supply-Y versions four things independently so that a documentation update does not force a network migration.

| Version | Example | Changes when |
| --- | --- | --- |
| Protocol version | `supply-y/1.0` | Object semantics or lifecycle compatibility changes |
| Schema version | `1.0.0` | A specific JSON Schema contract changes |
| Skill version | `0.1.0` | Scenario rules, field meaning or local checks change |
| API version | `/v1` | Hosted control-plane HTTP compatibility changes |

## Current release status

| Surface | Status | Evidence |
| --- | --- | --- |
| Core object semantics | Stable Protocol 1.0 | Six documented object types with one common envelope |
| JSON Schemas | Executable 1.0 contract | Six object contracts plus shared Draft 2020-12 definitions |
| Examples | Validated locally | Seven valid and seventeen invalid fixtures |
| Protocol release package | Stable 1.0 publication | 21 / 21 Manifest and Agent Bundle checks pin 15 release artifacts and 55 embedded implementation artifacts without repository access |
| Thread context | Executable reference preview | 15 / 15 basis, chain, Response and customer-local evidence-reference cases pass |
| Agent API contract | Stable 1.0 reference contract | 21 / 21 documented operations match OpenAPI; 29 request and response examples pass schema validation; hosted service availability is separate |
| TypeScript SDK | Publish-ready reference preview | 15 / 15 integration checks pass; 24 fixtures, 14 publisher lifecycle and 18 Skill update decisions, signed release verification, non-exporting KMS adapters and all 21 API methods covered; registry publication pending |
| Signed Skills | Executable preview | Core and Material Risk artifacts pass 21 / 21 schema, dependency, digest, signature and tamper checks; production signing trust pending |
| Skill publisher trust | Executable lifecycle preview | Public key records and 14 / 14 preview, active, retiring, revoked and historical-proof decisions pass; protected production signing key pending |
| Skill updates | Executable decision preview | 18 / 18 contract, selection, trust, compatibility, migration, revocation and approval outcomes pass; production release registry pending |
| Agent discovery | Executable preview | One v0.3.0 `/.well-known/supply-y` manifest passes 14 / 14 release-pin, contract, canonical-link, install-contract and false-claim checks |
| Agent install manifest | Executable preview | Strict v0.7.0 manifest passes 17 / 17 public Bundle, restricted SDK fallback, evidence, connection, Policy Receipt and trust checks |
| Customer Connection Profile | Executable customer-local preview | v0.1.0 profile passes 18 / 18 release-pin, secret-reference, identity, Skill, key separation, environment, transport, policy and notification checks; only its digest enters the compatibility report |
| Agent installation result | Executable preview | Compatibility Report v0.4.0 and decision profile pass 13 / 13 checks across TypeScript and language-neutral paths; all nine required capabilities are explicit |
| Policy Receipt | Stable 1.0 signed-claim contract | 17 / 17 eligibility decisions and 24 contract checks pass; independent business-fact proof remains a certification and audit concern |
| Native cryptographic profile | Cross-language executable preview | 9 / 9 checks pass in JOSE, WebCrypto and Python; key lifecycle passes 24 / 24 in Node |
| Events and webhooks | Two-stack executable preview | 24 / 24 signature, retry, replay, ordering and acknowledgement checks pass |
| Native transport | Architecture defined | Production API not generally available |
| Catena-X transport | Two-process reference path passes | One EDC asset, zero Native copies; partner connector test pending |
| Agent conformance | Executable reference preview | 14 / 14 behavior and 26 / 26 interoperability checks pass; independent implementation and hosted-sandbox evidence pending |

Protocol 1.0 fixes the interoperable wire contract. It does not claim that every reference implementation, hosted service, trust root or certification program is already production-ready. This table is intentionally candid so implementers can distinguish a stable specification from implementation availability.

## Immutable release package

The canonical Protocol 1.0 release is published at [`/protocol/1.0/manifest.json`](/protocol/1.0/manifest.json). Its strict Manifest lists 15 artifacts, including 12 normative contracts and one 55-entry Agent Bundle, with immutable URLs, exact byte counts and RFC 9530 SHA-256 digests. Discovery pins the Manifest digest; the customer-local Connection Profile records that same binding. Unversioned discovery may point to a later release, but `/protocol/1.0/` resources do not change after publication.

## Protocol 1.0 migration

- `supply-y/1.0` replaces the preview identifier `supply-y/0.1`.
- Core object examples use schema version `1.0.0` and Policy Receipts use receipt version `1.0.0`.
- Protocol identifiers and schema versions are signed or authenticated fields. An implementation must regenerate signatures, ciphertext authenticated data, receipts and dependent digests after migration.
- A Protocol 1.0 receiver must reject `supply-y/0.1`; it must not rewrite an old Package in place or infer compatibility from similar fields.
- Skill, SDK, discovery, installation and customer-profile versions remain independent. Their 0.x version does not downgrade the Protocol 1.0 wire contract, and Protocol 1.0 does not upgrade their production-readiness status.

## Compatibility rules

- A receiver must reject an unknown major protocol version before decryption or processing.
- A receiver may accept a newer minor schema only when the Skill manifest declares backward compatibility.
- Additive optional fields are backward compatible when unknown fields can be safely ignored.
- Removing a field, changing meaning, tightening a previously valid constraint or changing lifecycle semantics is breaking.
- Every Package records protocol, schema and Skill versions.
- Transport mode does not change object semantics.
- A thread keeps one protocol major version and one transport mode for its lifetime.

## Skill update policy

Each current Skill release is signed and includes its coordinate, release channel, protocol range, schema references, artifact URL, canonical digest, publication time, update policy and publisher key ID. The update policy classifies the release as `initial`, `additive`, `security` or `breaking`; names its exact predecessor and minimum supported version; and states whether automatic download is allowed. The artifact separately declares dependencies, capabilities, workflow, disclosure rules, failure behavior and safety invariants.

An Agent enumerates candidate releases from `GET /v1/skills`, compares semantic versions and then verifies release status, publisher trust, signature, digest, protocol range, dependencies, predecessor and capability changes in that order. A compatible additive or security release may be downloaded automatically when its signed policy permits it. Capability expansion requires manual review; a breaking or skipped update requires a migration path; a revoked installed release is disabled and alerts the operator.

No release activates itself. The OpenAPI contract permits only `operator_approval_required`, so signature validity proves publisher intent but never customer consent. The deterministic algorithm and 18 positive and negative outcomes live in `conformance/skill-update.cases.json`; TypeScript SDK preview.5 exposes raw verification as `verifySkillRelease`, publisher lifecycle decisions as `evaluateSkillPublisherTrust` and update selection as `evaluateSkillUpdate`.

## Deprecation policy

A production release should provide:

1. a published end-of-support date;
2. at least one supported migration path;
3. compatibility warnings before rejection begins;
4. conformance fixtures for both old and new behavior;
5. a changelog that separates security fixes, additive changes and breaking changes.

Security-critical revocations may shorten the normal window, but the reason and required customer action must be explicit.

## Conformance levels

| Level | Required capability |
| --- | --- |
| Schema | Parse and produce the required objects and reject invalid fixtures |
| Secure Package | Encrypt, sign, verify, decrypt and rotate keys correctly |
| Exchange | Implement idempotency, receipts, retries and thread state |
| Safe Agent | Treat incoming reasoning as untrusted and isolate it from tools and prompts |
| Certified | Pass the published suite and provide time-limited implementation evidence |

Conformance is implementation-specific. A valid Package does not certify the Agent that produced it.