Eve library

Oshun V1 Data Model Overview

Guide

Revision 1

On this page

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.