# Oshun V1 Ownership Matrix

Source of truth: `libs/oshun/domain-registry/src/registry.ts`.

This matrix assigns the V1 feature surfaces to the subsystem that owns the
contract, persistence semantics, review gates, and release readiness for that
surface. The shell and BFF can orchestrate a workflow, but they do not become
the owner of the underlying domain object.

## Domain Surfaces

| Feature surface                                                                                                                                                                                                       | Owning subsystem                             | Primary code roots                                                           | When to call this subsystem                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tara rituals, ritual templates, ritual sessions, mood/theme/modality/lineage taxonomy, continuation state, ritual playback                                                                                            | Tara domain service                          | `libs/oshun/domain-tara/`, `apps/tara/`, `apps/oshun/bff/` Tara routes       | Call Tara when a workflow creates, resumes, schedules, edits, completes, exports, or reviews contemplative practice content or state.                   |
| Arete habits, goals, routines, check-ins, streak records, friction signals, interventions, weekly reviews, coaching summaries                                                                                         | Arete domain service                         | `libs/oshun/domain-arete/`, `apps/arete/`, `apps/oshun/bff/` Arete routes    | Call Arete when a workflow changes behavioral plans, accountability cadence, streak/recovery logic, coaching cards, or habit analytics.                 |
| Veritas stories, claims, sources, evidence packs, counterclaims, topic hubs, timelines, corrections, retraction cascades                                                                                              | Veritas domain service with Sophia grounding | `libs/oshun/domain-veritas/`, `apps/veritas/`, `libs/oshun/evidence-sophia/` | Call Veritas for news/story/claim objects and editorial state; call Sophia from Veritas for evidence retrieval, citation grounding, and source quality. |
| Nyx sky events, observation windows, quality bands, prediction sources, calendar entries                                                                                                                              | Nyx domain service                           | `libs/oshun/domain-nyx/`, `apps/nyx/`, `apps/oshun/bff/` Nyx routes          | Call Nyx for event taxonomy, visibility scoring, reminder timing, calendar sync records, or source-attributed astronomical predictions.                 |
| Nisaba passages, manuscripts, editions, translations, lexicon/morphology entries, annotations, concept graph links, notebooks, study plans, citations, scholar profiles                                               | Nisaba domain service                        | `libs/oshun/domain-nisaba/`, `libs/nisaba/`, `apps/oshun/bff/` Nisaba routes | Call Nisaba for textual study, scholarly provenance, passage comparison, annotation, citation, notebook, or study-plan ownership.                       |
| Metis source bundles, grounding packs, course builds, lesson assets, publication packages, tutor personas, tutor session memory, objective maps, assessment evidence, learning telemetry, academic integrity verdicts | Metis domain service                         | `libs/metis/`, `apps/metis/`, `libs/oshun/domain-metis/` when present        | Call Metis for learning product objects, course generation, tutoring, assessments, LMS/BYOM ingestion, mastery state, and academic integrity decisions. |

## Cross-Cutting Subsystems

| Feature surface                                                                                                                                      | Owning subsystem                  | Primary code roots                                                                  | When to call this subsystem                                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Domain metadata, route base, auth scopes, analytics ID, notification channel, assistant context key, BFF base path, deep-link prefix, admin taxonomy | Domain registry                   | `libs/oshun/domain-registry/`                                                       | Call the registry at every boundary that accepts or emits a domain ID, route, assistant handoff, notification target, BFF dispatch, or admin taxonomy label.                                      |
| Customer shell home, explore, activity, library, profile, search, command surface, current-domain persistence                                        | Oshun shell and navigation        | `apps/oshun/web/`, `apps/oshun/mobile/`, `libs/oshun/navigation/`, `libs/oshun/ui/` | Call the shell for navigation, layout, current-domain state, cross-domain presentation, and user-facing orchestration. Delegate domain object reads and writes back to the owning domain service. |
| Customer authentication, onboarding, session refresh, account recovery, personalization inputs                                                       | Oshun Auth                        | `libs/oshun/auth/`, shared auth services                                            | Call Auth before any user-specific domain state, entitlement-sensitive action, identity switch, re-auth, or account recovery flow.                                                                |
| Grounded retrieval, evidence ranking, citation trails, grounded answer envelope                                                                      | Sophia evidence service           | `libs/oshun/evidence-sophia/`, `libs/sophia/`, `apps/sophia/`                       | Call Sophia when a response, course, source inspection, assistant turn, or publication gate requires cited evidence, source ranking, or provenance.                                               |
| Memory scopes, continuity state, consent-aware memory write/read, recovery state                                                                     | Iris memory service               | `libs/oshun/memory-iris/`, `apps/iris/`                                             | Call Iris when a workflow reads or writes profile, session, notebook, tenant, or operator-copilot memory and whenever continuity crosses devices or domains.                                      |
| Real-time assistant runtime, streaming, voice/avatar turn state, interruption state, runtime recovery                                                | Psyche runtime service            | `libs/oshun/embodiment-psyche/`                                                     | Call Psyche for live session runtime state, streaming turn control, avatar/voice mode state, and recovery after runtime interruption.                                                             |
| Persona policy, tone rubric, safety policy, crisis handoff, allowed/refusal context                                                                  | Lilith persona policy             | `libs/oshun/persona-policy-lilith/`, `apps/lilith/`                                 | Call Lilith before assistant output, authored ritual publication, voice/avatar profile use, high-distress handling, review decisions, or safety-sensitive content display.                        |
| Generation jobs, model/workflow routing, provenance, watermark, provider policy, release gates                                                       | Isis generation control           | `libs/oshun/generation-control-isis/`, `apps/isis/`                                 | Call Isis for any media/model generation, external model intake, workflow execution, provider routing, watermark verification, or provenance-bound artifact release.                              |
| Embodied instruction, motion pipeline handoff, movement safety constraints                                                                           | Aja embodiment service            | `libs/oshun/embodiment-aja/`, `apps/aja/`                                           | Call Aja when Metis or the shell needs movement instruction, pose/motion assets, rehabilitation/yoga/sports movement checks, or embodied tutor feedback.                                          |
| Admin queues, review decisions, audit exploration, operator workflow, launch gates                                                                   | Oshun Admin                       | `apps/oshun/admin/`, `apps/oshun/admin-mobile/`, shared review and audit libs       | Call Admin for operator-facing review, escalation, audit search, readiness gates, queue triage, and privileged workflow decisions. Admin does not own domain object semantics.                    |
| Tenant console, SSO/SCIM/OneRoster, roles, bulk operations, API keys, webhooks, lifecycle messages, help/status authoring                            | Tenant platform                   | shared tenant, auth, connector, notification, audit, and admin roots                | Call Tenant platform for tenant isolation, roster/identity integrations, custom roles, tenant-scoped API/webhook management, and tenant lifecycle operations.                                     |
| Privacy, consent, residency, DSAR, retention, legal hold                                                                                             | Privacy and data governance       | `libs/shared/data-residency/`, consent, audit, support, and BFF policy roots        | Call Privacy for consent transitions, residency routing, deletion/export/restore, support access, legal hold, subprocessor impact, and data-retention enforcement.                                |
| Support, entitlements, billing, lifecycle communications                                                                                             | Customer operations platform      | support, billing, entitlement, notification, and message center roots               | Call Customer Ops for plan state, trial/paywall behavior, refunds, dunning, support case history, customer messaging, and support-copilot context.                                                |
| Analytics, tracing, dashboards, experiments, evaluation pipeline                                                                                     | Analytics and evaluation platform | `libs/oshun/analytics/`, tracing, evaluation, and dashboard roots                   | Call Analytics for event definitions, dashboard metrics, experiment assignment, tracing attributes, release scorecards, and regression eval reports.                                              |

## Boundary Rules

| Boundary                                                                                                  | Owner to call first                                       | Handoff rule                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Raw `domainId` enters an API, BFF route, assistant turn, notification payload, deep link, or admin filter | Domain registry                                           | Validate with `libs/oshun/domain-registry/src/guards.ts`; reject unknown domains before dispatch.                                                               |
| Shell wants to render mixed-domain content                                                                | Shell                                                     | Shell composes view models only after each owning domain service returns typed data and registry metadata.                                                      |
| Assistant answers about a domain artifact                                                                 | Domain owner, then Sophia, Iris, Lilith, Psyche as needed | Domain owner supplies artifact state; Sophia supplies evidence; Iris supplies consented continuity; Lilith checks persona/safety; Psyche controls live runtime. |
| Generated media or generated course asset is requested                                                    | Isis, plus domain owner                                   | Domain owner defines object semantics and release target; Isis owns workflow, provider, watermark, provenance, and generation gates.                            |
| Learning workflow references customer notes, sources, or passages                                         | Metis plus Nisaba/Sophia/Iris                             | Metis owns course/tutor state; Nisaba owns passage/notebook semantics; Sophia owns evidence grounding; Iris owns memory scope.                                  |
| Admin reviews a domain artifact                                                                           | Domain owner plus Admin                                   | Domain owner supplies contract and validation rules; Admin owns queue workflow, decision capture, audit view, and reviewer authorization.                       |
| Tenant-specific policy changes behavior                                                                   | Tenant platform plus affected owner                       | Tenant platform resolves tenant policy and isolation; affected owner applies policy to its own domain logic.                                                    |
| Privacy action affects stored domain objects                                                              | Privacy plus affected owner                               | Privacy owns consent, residency, DSAR, retention, and legal hold semantics; affected domain service executes domain-specific cascade and tombstone rules.       |

## Registry Field Ownership

| Registry field          | Owner                                   | Use                                                                                 |
| ----------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| `id`                    | Domain registry                         | Stable key for every boundary.                                                      |
| `displayName`           | Domain registry with product approval   | Human label for navigation, analytics dashboards, notifications, and admin filters. |
| `route`                 | Navigation plus domain owner            | Canonical shell route base.                                                         |
| `auth`                  | Auth plus domain owner                  | Required session kind, scopes, and step-up actions.                                 |
| `analytics-id`          | Analytics platform                      | Event taxonomy key.                                                                 |
| `notification-channel`  | Notification platform plus domain owner | Channel routing and preference scoping.                                             |
| `assistant-context-key` | Assistant platform plus domain owner    | Context envelope key for assistant handoffs.                                        |
| `bff-base-path`         | BFF plus domain owner                   | Domain BFF dispatch base.                                                           |
| `deep-link-prefix`      | Navigation                              | Canonical mobile and web deep-link prefix.                                          |
| `admin-taxonomy`        | Admin plus domain owner                 | Review queues, audit category, and content class labels.                            |
