Canonical narrative for the V1 data model. Contracts live in
libs/contracts/src(machine-readable types) and persistence inlibs/oshun/persistence(Prisma renderer, migration plan, tombstone semantics). This document explains the boundaries, the ownership map, and the cross-domain rules.
Boundary rules#
- Each domain owns its records. Cross-domain reads go through contracts and adapters; cross-domain writes do not exist.
- Iris owns durable memory (persistent assistant memory). No other subsystem persists conversation memory; Iris is the system-of-record per ADR.
- Sophia owns grounded evidence: source bundles, citations, provenance manifests for grounded answers and editorial content.
- Lilith owns persona-policy records: persona lineage, refusal classes, disclosure copy index, tone-evaluation history.
- Isis owns model and workflow records: model registry, workflow registry, promotion history, kill-switch state, generation provenance bundles.
- Psyche owns realtime session state: per-session in-flight buffers, voice/avatar runtime — explicitly not durable beyond the session.
- Shared platform owns identity, entitlements, audit pipeline, notifications, experimentation.
- 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/, pluscommon/for shared types andevents/for event payloads.- The
contract-persistence-registry.tsinlibs/oshun/persistenceenforces the contract-to-table mapping; theindex-requirements.tsenforces 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.ymlsetup:yemaya,lilith,isis,sophia,hathor,bellona, with a sharedoshun_devfor cross-domain composition. - Migrations:
libs/oshun/persistence/src/migration-plan.tsproduces structured plans; runs through Prismamigrate deployin CI before production rollout; rollback rules captured per migration. - Tombstones:
tombstone-semantics.tsdefines 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.tsorcustomer-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.mdand the per-domainextras/directories underdocs/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.mdis 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.