# Oshun V1 Data Model Overview

> Canonical narrative for the V1 data model. Contracts live in
> `libs/contracts/src` (machine-readable types) and persistence in
> `libs/oshun/persistence` (Prisma renderer, migration plan, tombstone
> semantics). This document explains the boundaries, the ownership map, and the
> cross-domain rules.

## Boundary rules

1. **Each domain owns its records**. Cross-domain reads go through contracts and
   adapters; cross-domain writes do not exist.
2. **Iris owns durable memory** (persistent assistant memory). No other
   subsystem persists conversation memory; Iris is the system-of-record per ADR.
3. **Sophia owns grounded evidence**: source bundles, citations, provenance
   manifests for grounded answers and editorial content.
4. **Lilith owns persona-policy records**: persona lineage, refusal classes,
   disclosure copy index, tone-evaluation history.
5. **Isis owns model and workflow records**: model registry, workflow registry,
   promotion history, kill-switch state, generation provenance bundles.
6. **Psyche owns realtime session state**: per-session in-flight buffers,
   voice/avatar runtime — explicitly not durable beyond the session.
7. **Shared platform** owns identity, entitlements, audit pipeline,
   notifications, experimentation.
8. **Tenant records** carry residency and are isolated by tenant at every layer
   — application code reads tenant from the authenticated principal, never from
   URL parameters.

## Contract index

`libs/contracts/src/` defines per-domain contracts:

- `agent/`, `aja/`, `arete/`, `iris/`, `living-scene/`, `llm/`, `metis/`,
  `nisaba/`, `nyx/`, `tara/`, `tts/`, `veritas/`, plus `common/` for shared
  types and `events/` for event payloads.
- The `contract-persistence-registry.ts` in `libs/oshun/persistence` enforces
  the contract-to-table mapping; the `index-requirements.ts` enforces required
  database indexes.
- Drift between contracts, the persistence registry, and Prisma schema is caught
  by the contract-persistence-registry test and the
  canonical-contract-index-and-query-requirements spec.

## Persistence patterns

- **Database**: PostgreSQL with pgvector for embedding columns. Domain-isolated
  databases per the `docker/docker-compose.dev.yml` setup: `yemaya`, `lilith`,
  `isis`, `sophia`, `hathor`, `bellona`, with a shared `oshun_dev` for
  cross-domain composition.
- **Migrations**: `libs/oshun/persistence/src/migration-plan.ts` produces
  structured plans; runs through Prisma `migrate deploy` in CI before production
  rollout; rollback rules captured per migration.
- **Tombstones**: `tombstone-semantics.ts` defines soft-delete semantics for
  records under DSAR or moderation removal — preserves audit while hiding from
  customer reads.
- **Indexes**: required indexes are declared with each contract and enforced by
  `index-requirements.test.ts`. Read-path EXPLAIN checks run in CI for hot
  queries.
- **Caching**: Redis for ephemeral state (session, rate limits, cohort caches).
  Cache invalidation on contract changes is tied to the migration plan.
- **Object storage**: MinIO in dev; S3-compatible in production. Holds generated
  assets, large evidence bundles, exports.
- **Search index**: per-domain indexes for full-text retrieval; vector indexes
  for embedding retrieval.

## Privacy and audit

- Every record's residency is captured on creation and immutable thereafter.
- Every record's retention class is captured on creation and enforced by
  retention jobs.
- Every consent-bearing record (memory, derived insights, voice embeddings)
  records consent state; revocation propagates within the documented SLA.
- Every decisive write emits an audit event per `admin-taxonomy.ts` or
  `customer-taxonomy.ts`; the audit pipeline preserves the event durably and
  supports write-once preservation.

## Provenance and signing

- Generated assets (Isis) carry C2PA / content-credentials manifests with signed
  entries in the provenance ledger.
- Grounded answers (Sophia) carry source-binding bundles with the bound source
  IDs, retrieval scores, and a manifest signature.
- Watermarks are attached to generated media bytes and verified via the
  watermark pipeline; the registry of emitted assets is used for recovery
  against externally-redistributed media.

## Versioning

- Contracts are versioned per
  `docs/releases/v1/specs/cross-domain-contract-versioning.md`.
- Breaking changes follow the standard rolling-deploy contract (additive first,
  then cleanup).
- Migration plans are produced for each contract change with rollback and
  forward-compatibility notes.

## Documentation cross-references

- Contract index and required queries:
  `docs/releases/v1/specs/canonical-contract-index-and-query-requirements.md`.
- Cross-domain contract versioning:
  `docs/releases/v1/specs/cross-domain-contract-versioning.md`.
- Domain-specific data models (deep dives):
  `docs/domains/<domain>/data-models.md` and the per-domain `extras/`
  directories under `docs/domains/`.
- Legacy pre-V1 ownership context: `docs/reference/data-ownership-matrix.md`
  (legacy, kept for migration planning only —
  `docs/releases/v1/reports/subsystem-ownership-matrix.md` is authoritative for
  V1).
- Persistence library reference: `libs/oshun/persistence/src/` with
  comprehensive tests for the registry, the migration plan, the index
  requirements, and the tombstone semantics.

## Update authority

Engineering platform lead and the contracts maintainer co-own this document.
Domain leads co-review domain-specific sections. Privacy lead and compliance
lead co-review the privacy and audit sections. Updates require
platform-engineering sign-off; changes to privacy or audit sections require
privacy and compliance sign-off.
