# OSHUN Cross-Domain Contract Versioning

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:

- `OshunContractVersionDescriptor`
- `OshunVersionedContractEnvelope`
- 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.adapter`
- `oshun.domain.arete.adapter`
- `oshun.domain.veritas.adapter`
- `oshun.domain.nyx.adapter`
- `oshun.domain.nisaba.adapter`
- `oshun.evidence.sophia.adapter`
- `oshun.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.proto`
- `libs/proto/src/shared/memory.proto`
- `libs/proto/src/shared/persona_policy.proto`
- `libs/proto/src/shared/generation_control.proto`

## Rollout Rules

1. Additive, backward-compatible changes stay on the same major version.
2. Any consumer-visible breaking change requires a major version bump.
3. The contract descriptor must move `minimumCompatibleVersion` only when
   mixed-version support for older consumers is intentionally dropped.
4. Deprecated contract versions must remain explicitly discoverable during the
   rollout window.
5. Cross-process or persisted handoffs should use versioned envelopes whenever
   the receiving side may not be deployed in lockstep with the producer.
6. 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.
