# OSHUN Shared-Service Proto Contracts

Status: Active  
Owner: OSHUN Architecture  
Last Updated: 2026-03-23  
Related: `docs/releases/v1/specs/todos.md`,
`docs/releases/v1/specs/cross-domain-contract-versioning.md`,
`docs/reference/api-contracts.md`

## Purpose

This document records the language-neutral shared-service contracts published
for OSHUN substrate capabilities that must survive cross-service and
mixed-language integration without relying on TypeScript-only interfaces.

These contracts intentionally sit at the OSHUN product boundary, not at the raw
domain-internal API boundary.

## Published Proto Contracts

The following shared substrate services are now published under
`libs/proto/src/shared/`:

- `shared/evidence.proto` Purpose: grounded answers, evidence packs, notebook
  saves, claim checks, and trace exports for Sophia-backed evidence flows used
  by assistant, Nisaba, Veritas, Studio, and Admin.
- `shared/memory.proto` Purpose: assistant profile, continuity, consent
  summaries, review/search, write planning, deletion, and export for Iris-backed
  memory flows.
- `shared/persona_policy.proto` Purpose: persona-policy packs, tone guidance,
  safety assessment, topic-scope checks, prompt overlays, and full Lilith policy
  evaluation results.
- `shared/generation_control.proto` Purpose: workflow and model catalogs,
  provider routing, controlled generation planning/dispatch, provenance bundles,
  release-readiness, and retention policy summaries for Isis-backed media
  operations.
- `shared/common.proto` Purpose: normalized shared-service enums plus contract
  version descriptor messages used by versioned shared substrates.

## Selection Rationale

These services were chosen because they have one or more of the following:

- cross-domain reuse across assistant, shell, admin, studio, or support flows
- durable payloads that may be persisted, exported, reviewed, or replayed
- a realistic chance of mixed-language consumers needing a stable schema
- rollout-sensitive contracts where compatibility must be explicit

## Deliberate Non-Scope

`@oshun/embodiment-psyche` remains TypeScript-first for now.

Reason:

- the current session-orchestration surface is strongly transport-shaped and
  realtime-oriented
- the durable cross-service handoff boundary is less mature than evidence,
  memory, policy, and generation control
- publishing a language-neutral schema there now would imply a stability level
  the repo does not yet enforce

When Psyche realtime session payloads become durable or multi-language
integration targets, a dedicated proto contract should be added rather than
stretching the current shared service set.

## Publication Standard

For every shared proto contract in this set:

- `@oshun/proto` loader paths and service metadata must register it
- repository tests must assert discoverability and loadability
- contract docs must point to the canonical proto path
- codegen and drift checks must treat these files as release-gated
- BFF-to-domain and domain-to-substrate contract promotion must pass the
  executable gate in `@oshun/platform-foundations`: no observed schema drift, no
  backward-incompatible field changes, every declared consumer covered by a
  compatibility test, and an explicit rollback target recorded for the promoted
  contract
