Versioning And Compatibility

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

This is the live compatibility page for current onboarding and implementation contracts. The exact document shipped with the immutable Protocol 1.0 release remains available at /protocol/1.0/documents/versioning.md; published release bytes are never rewritten to update this operational view.

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.5.0 /.well-known/supply-y manifest on supply-y.net passes 14 / 14 release-pin, versioned installer, conformance-profile, trust-boundary and false-claim checks
Agent Conformance Profile	Published 1.0 evidence contract	18 / 18 profile, input, executor, exact-result, cross-language and no-borrowed-evidence outcomes pass
Agent install manifest	Executable preview	Strict v0.9.0 manifest on supply-y.net passes 19 / 19 public Bundle, profile pin, 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.5.0 and decision profile pass 13 / 13 checks across TypeScript and SDK-free Java paths; all nine checks carry exact structured results
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	Cross-language reference path passes	Node.js sender to Python recipient; one EDC asset, zero Native copies; partner connector test pending
Agent conformance	Cross-language executable reference preview	14 / 14 behavior and 26 / 26 Node.js-to-Python interoperability checks pass; public hosted Sandbox available, independently maintained external Agent 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. 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.

Publication origin migration

https://supply-y.net is the canonical origin for the website, documentation and current Agent entry points. Discovery v0.5.0 and Agent installer v0.9.0 publish supply-y.net URLs and pin the same immutable Protocol 1.0 bytes by RFC 9530 digest.

Protocol 1.0 was originally published with https://supply-y.vercel.app artifact URLs. Those historical Manifest URLs, schema identifiers and bytes remain valid and are not rewritten. An implementation verifies the exact path and content digest when resolving the supply-y.net alias; a hostname change alone never implies a new Protocol release.

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.