# OSHUN Metis Subsystem Ownership Matrix

Status: Active

Date: April 9, 2026

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

Related:

- `docs/releases/v1/reports/metis-domain-gap-analysis-and-full-integration-report-2026-03-23.md`
- `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 document is the canonical ownership matrix for every Metis integration that
depends on the OSHUN core substrates:

- Sophia
- Isis
- Iris
- Lilith
- Psyche
- Yemaya
- Themis

It exists to answer one specific question without ambiguity:

When Metis needs grounding, generation, pedagogy, memory, embodiment, media, or
policy enforcement, which subsystem owns the system of record, what exactly does
Metis own, and who must approve launch-impacting changes?

If another document implies a different owner for a responsibility listed here,
this matrix and `docs/releases/v1/reports/subsystem-ownership-matrix.md` win.

## 2. Boundary Rules

- Metis owns learner-facing educational product logic, course assembly, tutoring
  orchestration, assessment flows, and cross-domain study handoffs.
- Metis does not become the durable memory owner, grounding source of record,
  model control plane, media runtime owner, or academic-integrity authority.
- Each substrate below owns its own system-of-record state and decision logic.
- Cross-subsystem integrations must use explicit contracts, adapters, or review
  checkpoints rather than direct ownership drift.
- A Metis feature is not launch-ready if it depends on a substrate capability
  but has no named signoff path for that substrate.
- Current GitHub review plumbing in `.github/CODEOWNERS` does not yet name every
  subsystem below. This matrix defines the canonical decision owners anyway; if
  reviewer routing differs, `@oshun/core-team` must enforce the boundary until
  CODEOWNERS is expanded.

## 3. Cross-Subsystem Ownership Matrix

| Subsystem | System-of-record owner inside the Metis stack                                                                 | Metis owns                                                                                           | Metis must call the subsystem for                                                                  | Required signoff before launch-critical changes                                                              | Must not drift into                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Sophia    | source ingestion, retrieval, citations, grounding packs, evidence lineage, knowledge graph links              | course planning, tutor/assessment orchestration, evidence-aware presentation                         | approved source bundles, grounding packs, citation traces, evidence inspection payloads            | Sophia owner plus Themis when grounded educational claims or source policy changes                           | ad hoc local grounding copies, source-quality decisions made only in Metis UI code                 |
| Isis      | model registry, provider routing, prompt/runtime policy, experiments, provenance, cost and batch execution    | educational prompts, rubric logic, tutor workflows, feature-level generation intents                 | model selection, prompt execution, provenance bundles, experiment assignment, cost attribution     | Isis owner plus Platform when cost or runtime policy changes affect release gates                            | direct provider calls from Metis product code, local model policy forks, unmanaged prompt drift    |
| Iris      | durable learner memory, consent state, memory scopes, continuity and preference persistence                   | mastery interpretation, study-state UX, learner-facing continuity cues                               | persistent session memory, study preference retrieval, consent-aware history and continuity writes | Iris owner plus Security when retention, consent, export, or privacy boundaries change                       | uncontrolled learner-memory writes, bypassed consent checks, product-local durable memory stores   |
| Lilith    | pedagogical dialogue policy, tutor persona behavior, coaching tone, escalation logic                          | subject-specific tutor flows, learning objectives, lesson scaffolding, remediation UX                | tutor persona bundles, Socratic/direct/scaffolded policy modes, motivational strategy selection    | Lilith owner plus Themis when pedagogy policy or sensitive-teaching safeguards change                        | generic tutor prompting without pedagogy policy review, persona forks hidden in Metis prompts      |
| Psyche    | real-time voice/avatar runtime, turn-taking, streaming session orchestration, low-latency multimodal delivery | live tutor entry points, session UX, learner controls, fallback paths                                | live voice/avatar sessions, realtime transport, embodiment handoff, streaming session state        | Psyche owner plus Themis when likeness, embodiment, or realtime safety policy changes                        | durable memory ownership, teacher-policy ownership, product-local realtime runtimes                |
| Yemaya    | rendered media asset pipelines, polished lecture outputs, narrated/video asset generation workflows           | course packaging, lesson sequencing, study-context presentation, asset placement in learner journeys | diagram/video/audio render jobs, narrated media bundles, branded educational assets                | Yemaya owner plus Metis owner when rendered assets alter learner-facing pedagogy or publication quality bars | direct publication of unmanaged media artifacts, Metis-only copies of render orchestration logic   |
| Themis    | academic integrity policy, copyright/originality review, moderation, appeals, rights and consent enforcement  | learner messaging, integrity UX, submission flow wiring, remediation and appeal entry points         | originality verdicts, copyright policy checks, moderation actions, appeal-ready evidence bundles   | Themis owner for any integrity, rights, moderation, or appeal contract change                                | product-only integrity rules, silent moderation, copyright decisions made without policy authority |

## 4. Canonical Contract Ownership

The Metis gap report identified the core shared objects that must be made
explicit. Their canonical ownership is:

| Shared object                | Canonical owner | Notes                                                                                                                 |
| ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `LearningSourceBundle`       | Sophia          | Metis consumes and presents it; Sophia owns source trust and grounding lineage.                                       |
| `GroundingPack`              | Sophia          | Required for grounded lesson, tutor, and assessment claims.                                                           |
| `CourseBuild`                | Metis           | Educational assembly object owned by Metis, but it may embed Sophia evidence and Isis provenance.                     |
| `LessonAssetBundle`          | Yemaya          | Metis sequences assets into a course, but rendered media production belongs to Yemaya.                                |
| `TutorPersonaProfile`        | Lilith          | Metis adds subject/task context; Lilith owns persona and pedagogy policy.                                             |
| `TutorSessionMemory`         | Iris            | Durable storage and privacy boundaries remain Iris-owned.                                                             |
| `LearnerMasteryState`        | Metis           | Metis owns mastery semantics; Iris may persist continuity and consent-aware recall around it.                         |
| `AssessmentEvidencePack`     | Sophia          | Sophia owns grounding evidence; Metis packages it into learner-visible assessment review.                             |
| `AvatarTeacherProfile`       | Psyche          | Runtime embodiment profile belongs to Psyche even when launched from Metis.                                           |
| `VoiceLikenessConsentRecord` | Themis          | Policy authority sits with Themis; Psyche consumes approved consent state at runtime.                                 |
| `LearningTelemetryStatement` | Metis           | Metis owns learner-product telemetry semantics; shared analytics infrastructure still validates transport and schema. |
| `PublicationPackage`         | Metis           | Metis owns educational publication assembly; Yemaya artifacts and Themis approvals attach to it.                      |
| `AcademicIntegrityVerdict`   | Themis          | Metis may display or operationalize the verdict, but it does not own the decision.                                    |

## 5. Release-Gate Signoff Rules

- Grounded educational content changes require Sophia signoff, and Themis
  signoff when source or policy thresholds change.
- Model, prompt, provider, experiment, and cost-control changes require Isis
  signoff.
- Tutor persona, coaching style, scaffolding strategy, or escalation-policy
  changes require Lilith signoff.
- Durable learner memory, continuity persistence, export, deletion, or
  consent-boundary changes require Iris signoff and Security review.
- Live voice, avatar, streaming, or embodiment changes require Psyche signoff,
  with Themis review for likeness and safety implications.
- Rendered lecture, narrated asset, or educational media-pipeline changes
  require Yemaya signoff.
- Academic integrity, moderation, originality, copyright, rights, or appeals
  changes require Themis signoff.

## 6. Escalation Rule

If a Metis initiative appears to require two subsystems to own the same
responsibility, stop and split the work into:

1. the product orchestration owner
2. the substrate system-of-record owner
3. the policy or approval owner

If that split still cannot be stated clearly, update this document and
`docs/releases/v1/reports/subsystem-ownership-matrix.md` before implementation
continues.
