Eve library

OSHUN V1 Contract-to-Prisma Alignment Audit

Guide

Revision 1

On this page

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