Status: Active
Date: March 23, 2026
Owners: OSHUN Engineering, OSHUN Platform
Related:
docs/releases/v1/specs/todos.mddocs/releases/v1/reports/subsystem-ownership-matrix.mddocs/releases/v1/specs/web-app-admin-v1-prd.mdlibs/contracts/src/common/contract-prisma-alignment.tslibs/contracts/src/common/contract-prisma-alignment.test.tslibs/contracts/src/common/contract-prisma-migrations.test.ts
1. Purpose#
This document records the contract-to-persistence audit required by:
V1-ARCH-090audit each canonical Zod contract schema inlibs/contracts/src/common/V1-ARCH-091define the authoritative owner database and Prisma-model mapV1-ARCH-092add missing Prisma persistence coverage for canonical objectsV1-ARCH-093enforce drift detection in executable validationV1-ARCH-095add 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:
- The canonical Zod schemas in
libs/contracts/src/common/. - The current owner-boundary rules in
docs/releases/v1/reports/subsystem-ownership-matrix.md. - The canonical object model in
docs/releases/v1/specs/web-app-admin-v1-prd.md. - 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.prismalibs/psyche/database/prisma/schema.prismalibs/arete/database/prisma/schema.prismalibs/lilith/database/prisma/schema.prisma
Existing owner schemas extended with canonical models:
libs/yemaya/database/prisma/schema.prismalibs/sophia/database/prisma/schema.prismalibs/nisaba/database/prisma/schema.prismalibs/tara/database/prisma/schema.prismalibs/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
Jsoncolumns orString[]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