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.protoPurpose: 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.protoPurpose: assistant profile, continuity, consent summaries, review/search, write planning, deletion, and export for Iris-backed memory flows.shared/persona_policy.protoPurpose: persona-policy packs, tone guidance, safety assessment, topic-scope checks, prompt overlays, and full Lilith policy evaluation results.shared/generation_control.protoPurpose: 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.protoPurpose: 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/protoloader 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