# OSHUN V1 Contract-to-Prisma Alignment Audit

Status: Active

Date: March 23, 2026

Owners: OSHUN Engineering, OSHUN Platform

Related:

- `docs/releases/v1/specs/todos.md`
- `docs/releases/v1/reports/subsystem-ownership-matrix.md`
- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `libs/contracts/src/common/contract-prisma-alignment.ts`
- `libs/contracts/src/common/contract-prisma-alignment.test.ts`
- `libs/contracts/src/common/contract-prisma-migrations.test.ts`

## 1. Purpose

This document records the contract-to-persistence audit required by:

- `V1-ARCH-090` audit each canonical Zod contract schema in
  `libs/contracts/src/common/`
- `V1-ARCH-091` define the authoritative owner database and Prisma-model map
- `V1-ARCH-092` add missing Prisma persistence coverage for canonical objects
- `V1-ARCH-093` enforce drift detection in executable validation
- `V1-ARCH-095` add executable migration and rollback verification

The executable source of truth is
`libs/contracts/src/common/contract-prisma-alignment.ts`. This document is the
human-readable audit record and rationale.

## 2. Audit Method

The audit used four inputs together:

1. The canonical Zod schemas in `libs/contracts/src/common/`.
2. The current owner-boundary rules in
   `docs/releases/v1/reports/subsystem-ownership-matrix.md`.
3. The canonical object model in
   `docs/releases/v1/specs/web-app-admin-v1-prd.md`.
4. The domain Prisma schemas in `libs/*/database/prisma/schema.prisma`.

Alignment states:

- `direct`: a canonical Prisma model now exists for the contract and exposes the
  contract’s top-level persistence fields directly, with nested structures
  persisted as JSON or arrays where appropriate.
- `partial`: persistence exists, but the contract still depends on adapter
  composition, derived aggregates, or a split multi-table representation rather
  than one clean canonical Prisma model.

## 3. Summary

- Common contract files audited: `27`
- Direct mappings after schema additions: `21`
- Remaining partial mappings: `6`

New owner-schema coverage added by this task block:

- `libs/iris/database/prisma/schema.prisma`
- `libs/psyche/database/prisma/schema.prisma`
- `libs/arete/database/prisma/schema.prisma`
- `libs/lilith/database/prisma/schema.prisma`

Existing owner schemas extended with canonical models:

- `libs/yemaya/database/prisma/schema.prisma`
- `libs/sophia/database/prisma/schema.prisma`
- `libs/nisaba/database/prisma/schema.prisma`
- `libs/tara/database/prisma/schema.prisma`
- `libs/isis/database/prisma/schema.prisma`

## 4. Authoritative Mapping

| Contract File          | Canonical Schema(s)                                                                               | Owner DB  | Prisma Model(s)                                                        | State     | Audit Result                                                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `asset.ts`             | `AssetSchema`, `AssetVersionSchema`, `AssetFolderSchema`                                          | `yemaya`  | `Asset`, `Folder`                                                      | `partial` | Core asset persistence exists, but filename/path/thumbnails/version history/license/provenance/lock state remain adapter-level or derived rather than direct Prisma fields. |
| `audit.ts`             | `AuditEventSchema`, `RetentionPolicySchema`, `ComplianceReportSchema`, `DataSubjectRequestSchema` | `shared`  | `yemaya.AuditLog`, `isis.RetentionPolicy`, `veritas.DpaSubjectRequest` | `partial` | Audit-related persistence exists across multiple owners; `ComplianceReport` still has no dedicated Prisma model and the file is intentionally multi-owner.                  |
| `avatar-pack.ts`       | `AvatarPackSchema`                                                                                | `psyche`  | `AvatarPack`                                                           | `direct`  | Added canonical avatar-pack registry persistence in Psyche.                                                                                                                 |
| `claim.ts`             | `ClaimSummarySchema`, `ClaimEvidenceSchema`                                                       | `veritas` | `Claim`, `ClaimVerification`, `ClaimEvidence`                          | `partial` | Claim persistence exists, but canonical slug/domain/visibility/verdict/debate-link shape is still split across multiple tables and adapter logic.                           |
| `collection.ts`        | `CollectionSummarySchema`                                                                         | `yemaya`  | `Collection`                                                           | `direct`  | Added canonical saved-bundle persistence in Yemaya.                                                                                                                         |
| `concept.ts`           | `ConceptSummarySchema`                                                                            | `sophia`  | `Concept`                                                              | `direct`  | Added canonical cross-domain concept persistence in Sophia.                                                                                                                 |
| `consent-record.ts`    | `ConsentRecordSchema`                                                                             | `iris`    | `ConsentRecord`                                                        | `direct`  | Added canonical consent-record persistence in Iris.                                                                                                                         |
| `continuity-state.ts`  | `ContinuityStateSchema`, `ContinuityCheckpointSchema`                                             | `iris`    | `ContinuityState`                                                      | `direct`  | Added canonical continuity-state persistence in Iris.                                                                                                                       |
| `evidence-pack.ts`     | `EvidencePackSchema`                                                                              | `sophia`  | `EvidencePack`                                                         | `direct`  | Added canonical evidence-pack persistence in Sophia.                                                                                                                        |
| `incident.ts`          | `IncidentSchema`                                                                                  | `yemaya`  | `Incident`                                                             | `direct`  | Added canonical incident persistence for shell/admin operations in Yemaya.                                                                                                  |
| `memory-scope.ts`      | `MemoryScopeSchema`                                                                               | `iris`    | `MemoryScope`                                                          | `direct`  | Added canonical memory-scope persistence in Iris.                                                                                                                           |
| `model-card.ts`        | `ModelCardSchema`                                                                                 | `isis`    | `ModelCard`                                                            | `direct`  | Added canonical model-card persistence in Isis.                                                                                                                             |
| `model-version.ts`     | `ModelVersionSchema`                                                                              | `isis`    | `ModelVersion`                                                         | `direct`  | Added canonical model-version persistence in Isis.                                                                                                                          |
| `notebook.ts`          | `NotebookSummarySchema`                                                                           | `sophia`  | `Notebook`                                                             | `direct`  | Added canonical notebook persistence in Sophia.                                                                                                                             |
| `passage.ts`           | `PassageSummarySchema`                                                                            | `nisaba`  | `Passage`                                                              | `direct`  | Added canonical passage persistence in Nisaba.                                                                                                                              |
| `persona.ts`           | `PersonaSummarySchema`                                                                            | `lilith`  | `Persona`                                                              | `direct`  | Added canonical persona registry persistence in Lilith.                                                                                                                     |
| `policy-bundle.ts`     | `PolicyBundleSchema`                                                                              | `lilith`  | `PolicyBundle`                                                         | `direct`  | Added canonical policy-bundle persistence in Lilith.                                                                                                                        |
| `practice.ts`          | `PracticeSummarySchema`                                                                           | `arete`   | `Practice`                                                             | `direct`  | Added canonical practice persistence in Arete.                                                                                                                              |
| `project.ts`           | `ProjectSchema`, `ProjectMemberSchema`, `ProjectCommentSchema`, `ProjectActivitySchema`           | `yemaya`  | `Project`, `ProjectMember`, `Comment`, `Activity`                      | `partial` | Core project persistence exists, but canonical cover/settings/tag/aggregate/access and comment-position semantics are still not one direct Prisma model surface.            |
| `provenance-bundle.ts` | `ProvenanceBundleSchema`                                                                          | `isis`    | `ProvenanceBundle`                                                     | `direct`  | Added canonical provenance-bundle persistence in Isis.                                                                                                                      |
| `review-package.ts`    | `ReviewPackageSchema`                                                                             | `isis`    | `ReviewPackage`                                                        | `direct`  | Added canonical review-package persistence in Isis.                                                                                                                         |
| `ritual.ts`            | `RitualSummarySchema`                                                                             | `tara`    | `Ritual`                                                               | `direct`  | Added canonical ritual persistence in Tara.                                                                                                                                 |
| `source.ts`            | `SourceSchema`                                                                                    | `sophia`  | `Source`                                                               | `direct`  | Added canonical source persistence in Sophia so grounding-owned source records are no longer inferred from Veritas or document-only models.                                 |
| `support-case.ts`      | `SupportCaseSchema`                                                                               | `yemaya`  | `SupportCase`                                                          | `direct`  | Added canonical support-case persistence in Yemaya.                                                                                                                         |
| `user.ts`              | `UserSchema`, `UserPreferencesSchema`, `NotificationSchema`, `UserStatsSchema`                    | `yemaya`  | `User`, `UserPreference`, `Notification`                               | `partial` | User persistence exists, but username/role/phone/company/job-title/stats and shell-level preference semantics are still not a clean canonical Prisma projection.            |
| `voice-profile.ts`     | `VoiceProfileSchema`                                                                              | `psyche`  | `VoiceProfile`                                                         | `direct`  | Added canonical voice-profile registry persistence in Psyche.                                                                                                               |
| `workflow-template.ts` | `WorkflowTemplateSchema`                                                                          | `isis`    | `WorkflowTemplate`                                                     | `partial` | Workflow persistence exists, but canonical slug/family/version/governance/portability/execution-profile/output-package fields are still not fully represented in Prisma.    |

## 5. Remaining Partial Mismatches

The remaining partial mappings are intentional carry-forward items rather than
uncatalogued drift:

- `asset.ts`: canonical provenance, licensing, lock state, folder aggregates,
  and version history are richer than current Yemaya asset persistence.
- `audit.ts`: the contract file spans shared audit, retention, privacy-request,
  and reporting concerns across multiple owner schemas.
- `claim.ts`: Veritas claim storage still uses a split fact-checking structure
  instead of one canonical claim aggregate.
- `project.ts`: project access semantics, view aggregates, and comment
  positioning are still partly computed outside Prisma.
- `user.ts`: the repo still lacks a dedicated shared-auth Prisma owner, so
  Yemaya remains the current partial persistence anchor.
- `workflow-template.ts`: Isis workflow persistence remains execution-centric
  and needs future expansion to fully absorb canonical governance and
  portability fields.

## 6. Implementation Notes

- Missing persistence coverage was added with canonical owner schemas and
  canonical top-level fields.
- Nested contract structures are persisted as `Json` columns or `String[]`
  arrays where that preserves the canonical contract shape without forcing an
  unnecessary normalization pass in this task block.
- Drift enforcement is executable:
  `libs/contracts/src/common/contract-prisma-alignment.test.ts`
- Migration and rollback verification is executable:
  `libs/contracts/src/common/contract-prisma-migrations.test.ts`

## 7. Completion Criteria Satisfied

This task block now provides:

- a documented audit of every common contract file
- an authoritative owner-database and Prisma-model manifest
- missing canonical Prisma persistence coverage for previously unmapped objects
- executable drift detection against the manifest
- executable migration and rollback diff checks for every added owner schema
