Compatibility, Versioning, and Deprecation

Draft 0.1 — 2 August 2026
Version numbers communicate a compatibility promise, not quality, legal approval, security, or production readiness by themselves.

Objective

ANUKA will contain documents, schemas, APIs, events, SDKs, tools, skills, resident products, and hosted services that evolve at different speeds.

The system needs predictable change without freezing innovation or abandoning integrators.

The rule is:

No breaking change without a named boundary, migration path, support window, and accountable owner.

Versioned artifacts

The following are versioned independently:

Foundation documents;
Constitution;
protocol specifications;
JSON Schemas;
OpenAPI descriptions;
AsyncAPI descriptions;
CloudEvent types and payloads;
capability registry;
consent authorization types;
credential and attestation schemas;
SDKs;
CLI;
MCP servers and tool contracts;
skill packages;
hosted services;
resident-product integrations;
conformance profiles.

A single “ANUKA version” cannot accurately represent every artifact.

Semantic Versioning

Public software and machine contracts should use Semantic Versioning 2.0.0 unless a governing external standard requires another scheme.

MAJOR.MINOR.PATCH

MAJOR — incompatible public-contract change;
MINOR — backward-compatible capability addition;
PATCH — backward-compatible correction.

A released version is immutable. Fixes require a new version.

Document versions

Governance and policy documents use semantic versions plus status.

Examples:

Draft 0.3.0
Candidate 0.9.0
Ratified 1.0.0
Superseded 1.2.0

A document’s Git commit is evidence of content, but the declared version and status communicate its governance meaning.

Merge does not automatically mean ratification.

Stability states

Experimental

Early implementation exploration. Breaking changes may occur without a long support window.

Draft

Documented proposal open to substantive change.

Candidate

Feature-complete contract undergoing implementation and conformance validation.

Stable

Supported contract with compatibility and deprecation guarantees.

Deprecated

Still supported temporarily but should not be selected for new integrations.

Retired

No longer supported for normal operation.

Revoked

Unsafe or invalid artifact that must not be relied upon, subject to incident and legal requirements.

Compatibility dimensions

Compatibility is multidimensional.

Syntactic compatibility

Can the consumer parse and validate the message?

Semantic compatibility

Does the same field still mean the same thing?

Behavioral compatibility

Does the operation preserve side effects, ordering, retries, errors, and timing expectations?

Authorization compatibility

Are capabilities, consent, audiences, and policy semantics unchanged?

Privacy compatibility

Does the new version preserve data classification, collection, disclosure, and retention expectations?

Operational compatibility

Can the implementation coexist with current infrastructure and supported dependencies?

A syntactically compatible change can still be breaking in another dimension.

Public contract declaration

Every stable artifact must define its public contract.

For a library, this may be exported APIs.

For a service, it includes:

endpoints;
request and response schemas;
events;
errors;
consistency;
authorization;
rate and size limits;
side effects;
availability tier.

For a skill, it includes purpose, required tools, capabilities, inputs, outputs, approval behavior, and verification.

Breaking changes

Examples include:

removing or renaming a field;
changing a field’s meaning or unit;
requiring a previously optional field;
narrowing accepted input;
changing default privacy behavior;
broadening agent authority;
changing payment or ledger semantics;
changing retry safety;
changing event ordering guarantees;
altering approval requirements;
removing an error code relied upon by clients;
reducing support without notice.

Security fixes may intentionally break behavior and follow the emergency path.

Compatible changes

Usually include:

adding an optional field with safe default behavior;
adding a new endpoint;
adding a new event type;
adding an optional tool;
adding a compatible SDK helper;
clarifying documentation;
increasing limits without changing cost or security assumptions;
adding an enum value when unknown-value handling is already defined.

Adding an enum value is breaking when consumers are not required to tolerate unknown values.

API versioning

HTTP APIs use a major compatibility version in the base path or media type.

Clients must not be forced to update for compatible additions.

The API response may include:

API major version;
schema version;
request ID;
deprecation warning;
sunset date;
documentation reference.

Event versioning

Event type names include the major version.

Example:

network.anuka.contribution.accepted.v1

Compatible payload changes use a newer schema version under the same event major.

Publishers should support overlap when migrating to a new event major.

Consumers must declare supported event majors.

Schema versioning

Schema IDs are immutable and include the full version.

https://schemas.anuka.network/contribution/1.2.0/schema.json

The registry maintains:

compatibility relationships;
migrations;
deprecation;
affected API and event contracts;
example fixtures.

Capability versioning

Capability names remain stable when the action meaning remains stable.

A change in authority semantics may require a new capability.

Bad:

Keep payment.read but quietly include bank-account details.

Better:

retain payment.read_summary;
introduce payment.read_sensitive_details;
require new consent and review.

MCP version negotiation

MCP implementations pin supported protocol revisions and extensions.

Clients and servers must fail clearly when no compatible revision exists.

ANUKA tool contract versions remain separate from MCP protocol revision.

A server may support multiple MCP revisions during migration, but every request is interpreted under one explicit revision.

Skill compatibility

A skill declares:

compatible tool contract majors;
supported host capabilities;
required MCP extensions;
input and output schema versions;
minimum policy version;
risk tier.

A runtime must not execute a skill against an incompatible tool merely because the names are similar.

SDK compatibility

Official SDKs document:

supported API majors;
runtime support policy;
transitive dependency policy;
language-specific stability guarantees;
generated versus hand-written surfaces;
deprecation annotations.

The latest minor SDK release should continue to support the current stable API major.

Release channels

Recommended channels:

dev — continuously changing development artifacts;
canary — selected production-like validation;
beta — externally testable but not stable;
stable — supported production release;
lts — extended support where justified.

Pre-release labels do not weaken security, privacy, or legal obligations.

Feature flags

Feature flags may separate deployment from activation.

A flag must define:

owner;
purpose;
audience;
environments;
default;
expiry;
cleanup issue;
data impact;
rollback behavior.

Flags must not become permanent undocumented forks of behavior.

Compatibility matrix

The repository should publish a generated matrix covering:

API major ↔ SDK versions;
event majors ↔ consumer versions;
schema versions ↔ API and event versions;
MCP revisions ↔ server releases;
skill versions ↔ tool contracts;
resident-product adapter versions ↔ shared core;
supported runtime and browser versions.

Deprecation notice

A deprecation notice includes:

artifact and version;
reason;
replacement;
migration guide;
first warning date;
end of new adoption;
end of support;
retirement date;
security or legal urgency;
owner and contact.

Notices should be available in:

documentation;
changelog;
API headers or responses;
SDK warnings;
CLI output;
registry metadata;
direct communication for affected high-impact customers.

Support windows

Proposed defaults for stable protocol contracts:

at least 180 days between deprecation and normal retirement;
longer windows for widely adopted or high-impact contracts;
at least one supported migration path;
security support through the declared retirement date.

A protocol may adopt a longer external-standard minimum. MCP feature lifecycle requirements are evaluated separately and may require at least twelve months before removal.

Emergency retirement

A version may be retired early for:

exploitable security vulnerability;
active fraud or financial loss;
unlawful behavior;
privacy breach;
unsafe cryptography;
provider shutdown;
corrupted or misleading data semantics.

Emergency retirement requires:

incident record;
authority and scope;
immediate mitigation;
affected-user communication where safe;
migration or containment guidance;
retrospective review;
permanent governance decision if extended.

Migration artifacts

Every breaking migration should provide relevant artifacts:

change summary;
before and after examples;
schema transformation;
database migration guidance;
dual-read or dual-write plan;
SDK upgrade instructions;
event overlap period;
rollback or forward-recovery plan;
conformance tests;
data and privacy impact.

Expand and contract

Database and API migrations should prefer expand-and-contract:

add compatible new representation;
write or emit both where safe;
migrate consumers;
backfill and verify;
stop using old representation;
remove only after support window.

Dual writing requires reconciliation and must not silently diverge.

Data migrations

Data migrations record:

source and target schema;
transformation version;
affected records;
backups;
validation rules;
failure handling;
audit evidence;
privacy and retention impact;
operator.

A data migration does not erase the provenance of the original record.

Contract testing

CI should detect:

OpenAPI breaking changes;
JSON Schema incompatibility;
event contract breaks;
tool and skill incompatibility;
SDK compilation failures;
removed error codes;
changed authorization metadata;
changed privacy classification;
documentation links to retired versions.

Human review remains necessary for semantic and legal changes.

Consumer-driven validation

Important consumers may publish contract expectations.

Consumer tests must not veto legitimate protocol evolution indefinitely. They provide evidence for migration planning and support windows.

Unknown-version behavior

Clients encountering an unsupported major version must:

stop processing the affected contract;
preserve the raw message where policy permits;
emit a clear diagnostic;
avoid guessing field meaning;
expose upgrade guidance.

Compatible unknown optional fields may be ignored according to contract rules.

Historical reproducibility

The system must preserve enough information to interpret historical records:

schema version;
policy version;
tool and skill version;
model and host category where material;
transformation version;
event contract;
decision record.

The current implementation must not reinterpret old records under new semantics without an explicit migration.

Resident product adoption

A resident product declares supported protocol versions and adoption dates.

The network must not automatically upgrade a product’s contract without its operator’s explicit action unless an emergency safety rule applies.

Products may remain on an older supported version, but verification status can reflect outdated or risky versions.

Self-hosted implementations

Self-hosted operators receive the same compatibility documentation and conformance tests.

Hosted-service release dates and open-protocol release dates may differ, but the distinction must be visible.

Release records

A release record includes:

artifact name and version;
source commit;
build digest;
release channel;
schemas and contracts;
changelog;
security scan status;
provenance;
compatibility result;
approver;
release time;
rollback or replacement.

MVP policy

Before the first stable release:

all artifacts remain 0.x or explicitly Draft/Candidate;
public compatibility promises are limited and stated;
stable IDs and version fields are still required;
deprecation machinery is tested before it is needed;
no protocol is called stable without conformance evidence.

Acceptance criteria

every stable artifact declares a public contract;
status and version are separate;
compatibility includes semantics, authorization, privacy, and behavior;
breaking changes increment the correct major boundary;
event and schema versions are explicit;
compatibility matrices are generated;
deprecations have replacement and dates;
emergency retirement has incident governance;
migrations include validation and rollback or forward recovery;
historical records remain interpretable;
resident-product adoption is explicit;
conformance tests detect machine-visible breaks.

Sources

Verification record

Sources opened and checked: 2 August 2026
Default normal deprecation window: Proposed, not ratified
Stable protocol releases published: None
Compatibility tooling: To be selected