Status: Active
Owner: OSHUN Architecture
Last Updated: 2026-03-22
Related: docs/releases/v1/specs/program-charter.md,
docs/releases/v1/specs/todos.md
Purpose#
This document defines the runtime versioning rules for key OSHUN cross-domain contracts so shell, evidence, and generation-control adapters can survive mixed-version rollouts without silent breakage.
Shared Primitive#
@oshun/types now owns the canonical cross-domain versioning primitive:
OshunContractVersionDescriptorOshunVersionedContractEnvelope- semantic-version parsing and comparison helpers
- compatibility resolution helpers for rollout checks
Every key adapter contract publishes one explicit descriptor with:
- a stable contract id
- the current contract version
- the minimum backward-compatible version
- supported and deprecated version markers
- compatibility mode and notes
Transported payloads can be wrapped in OshunVersionedContractEnvelope<T> so
consumers can inspect compatibility before deserializing business data.
Current Versioned Contracts#
The following adapter families now publish canonical contract descriptors and
versioned envelope helpers at version 1.0.0:
oshun.domain.tara.adapteroshun.domain.arete.adapteroshun.domain.veritas.adapteroshun.domain.nyx.adapteroshun.domain.nisaba.adapteroshun.evidence.sophia.adapteroshun.generation.isis.adapter
Language-neutral shared-service proto contracts are also published for the durable substrate boundaries that need cross-language interoperability:
libs/proto/src/shared/evidence.protolibs/proto/src/shared/memory.protolibs/proto/src/shared/persona_policy.protolibs/proto/src/shared/generation_control.proto
Rollout Rules#
- Additive, backward-compatible changes stay on the same major version.
- Any consumer-visible breaking change requires a major version bump.
- The contract descriptor must move
minimumCompatibleVersiononly when mixed-version support for older consumers is intentionally dropped. - Deprecated contract versions must remain explicitly discoverable during the rollout window.
- Cross-process or persisted handoffs should use versioned envelopes whenever the receiving side may not be deployed in lockstep with the producer.
- Breaking changes require migration notes and test coverage for the new compatibility boundary.
Verification Standard#
Changes to these adapter contracts must update:
- contract-focused unit tests
- library typecheck coverage
- any relevant mixed-version or rollout validation suites
No contract change should be treated as complete unless the descriptor, versioned envelope path, and compatibility behavior are all verified together.