Eve library

OSHUN V1 When To Call Which Subsystem Guide

Spec

Revision 1

On this page

Status: Active

Date: March 23, 2026

Owners: OSHUN Product, OSHUN Engineering, OSHUN Platform, OSHUN Safety

Related:

  • docs/releases/v1/reports/subsystem-ownership-matrix.md
  • docs/releases/v1/specs/program-charter.md
  • docs/releases/v1/specs/web-app-admin-v1-prd.md
  • docs/releases/v1/specs/todos.md

1. Purpose and Authority#

This guide operationalizes the OSHUN V1 ownership matrix.

Use it when the question is not "who owns this capability?" but "which subsystem should this feature, flow, or incident invoke right now?"

This guide is authoritative for day-to-day routing decisions as long as it remains consistent with:

  • docs/releases/v1/reports/subsystem-ownership-matrix.md
  • docs/releases/v1/specs/program-charter.md
  • docs/releases/v1/specs/web-app-admin-v1-prd.md

If a scenario seems to require multiple subsystems, compose them through the shell, BFF, and explicit adapters. Do not collapse ownership to make the flow feel simpler.

2. Fast Routing Table#

If the need is... Call... Why
route composition, shared UX, continuity UI, admin/operator surfaces OSHUN Shell the shell owns composition, routing, adapters, and shared presentation
identity, entitlements, shared search infra, notifications infra, audit, observability, privacy, experimentation Shared Platform Services these are shared infrastructure concerns, not peer customer domains
centering, rituals, transitions, sleep, presence Tara Tara owns the contemplative customer-facing experience
habits, goals, reflection, daily structure Arete Arete owns disciplined embodiment experiences
grounded claims, briefings, evidence inspection Veritas + Sophia Veritas owns the experience; Sophia owns grounding and citations
passages, study, compare, annotation, scholarship Nisaba + Sophia Nisaba owns the study experience; Sophia owns grounding support
sky awareness, celestial events, cosmological orientation Nyx Nyx owns wonder and astronomy experiences
durable assistant identity, memory, conversation history, memory consent Iris Iris owns assistant continuity and memory state
live text/voice/avatar runtime, conferencing, turn-taking Psyche Psyche owns real-time multimodal orchestration
contemplative tone, teacher logic, persona safety Lilith Lilith owns contemplative persona policy and safeguards
retrieval, citations, evidence packs, notebooks, research evaluation Sophia Sophia is the grounding and research-integrity substrate
model/workflow selection, generation policy, provenance, release gates Isis Isis is the generation control plane

3. Decision Flow#

  1. Is the problem about product composition, routing, shared UI presentation, or admin/operator surface behavior? Call OSHUN Shell first.
  2. Is the problem about a shared infrastructure concern such as identity, entitlements, search infra, notifications infra, audit, privacy, or observability? Call Shared Platform Services first.
  3. Is the user-facing value primarily one of the five customer domains? Call the corresponding domain owner first: Tara, Arete, Veritas, Nyx, or Nisaba.
  4. Does the flow need durable assistant memory, consent-aware recall, or persistent conversation continuity? Add Iris.
  5. Does the flow need live text/voice/avatar orchestration, conferencing, or low-latency embodiment? Add Psyche.
  6. Does the flow need contemplative tone, teacher behavior, or domain-specific spiritual safety policy? Add Lilith.
  7. Does the flow need evidence, citations, retrieval, source-aware synthesis, notebooks, or research evaluation? Add Sophia.
  8. Does the flow need model selection, workflow selection, generation policy, provenance, staging/promotion, or release-gated media execution? Add Isis.
  9. If more than one step above applies, compose the responsible subsystems through explicit adapters and keep ownership split intact.

4. Common Scenarios#

Scenario Call... Do Not Call First... Reason
text assistant turn with continuity but no live voice and no evidence need OSHUN Shell + Iris Psyche, Sophia, Isis this is a memory-backed assistant flow, not a real-time or grounded-generation flow
live voiced Tara guide or avatar-led contemplative session OSHUN Shell + Iris + Psyche + Lilith Sophia unless grounded evidence is required the flow needs memory, embodiment, and contemplative policy
evidence-backed claim explanation in Veritas OSHUN Shell + Veritas + Sophia Lilith or Isis as primary owners Veritas owns the experience, Sophia owns grounding
Nisaba study/compare/annotation flow OSHUN Shell + Nisaba + Sophia Veritas as primary owner unless the goal is claim briefing the study surface is Nisaba, but grounding still belongs to Sophia
cross-domain search result rendering OSHUN Shell + Shared Platform Services + Sophia where grounding is required treating each domain as an independent search owner search infra is shared; grounded evidence remains Sophia-owned
notification preferences and delivery controls OSHUN Shell + Shared Platform Services domain surfaces owning the global preference model notification infra is shared, while the shell owns the surfaced UX
memory review, delete, export, or consent change OSHUN Shell + Iris Psyche this is durable memory and consent state, not live runtime
model-backed image/audio/video/avatar generation OSHUN Shell or domain surface + Isis direct provider runtime Isis owns workflow, model, provenance, and release governance
imported Civitai model or workflow intake Isis ad hoc direct provider usage Civitai assets must normalize into Isis-owned records

5. Anti-Patterns#

  • Do not call Sophia for every assistant turn just because the response feels "smart." Call Sophia only when grounding, citations, retrieval, or source-aware synthesis are actually required.
  • Do not use Psyche as a durable memory or consent store.
  • Do not use Lilith as the shell router or generic orchestration layer.
  • Do not let domains or shell code bypass Isis and talk directly to generation providers as the runtime of record.
  • Do not move domain business logic into the shell for convenience.
  • Do not treat Shared Platform Services as a customer-facing peer domain.

6. Escalation Rule#

If this guide still leaves a call-routing decision ambiguous:

  1. use docs/releases/v1/reports/subsystem-ownership-matrix.md to identify the system-of-record owner
  2. use the charter and PRD to confirm the intended dependency edge
  3. update this guide, the matrix, and the governing docs together before implementation proceeds