Eve library

OSHUN Shared-Service Proto Contracts

Spec

Revision 1

On this page

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