Eve library

OSHUN Cross-Domain Contract Versioning

Spec

Revision 1

On this page

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.