# OSHUN V1 Cross-Cutting Contract → Persistence Mapping

This document maps each `v1_cross_cutting_*` table in
`libs/oshun/persistence/prisma/schema.prisma` to the canonical Zod contract that
defines its payload shape, plus the domain library that emits records into it.

A "cross-cutting" table is a domain-agnostic warehouse mirror of an artifact
that flows between services (personas across domains, consent records across
tenants, model cards across providers, etc.). The audit of the V1 release plan
flagged these tables as "orphaned" — meaning there was no documented mapping.
The contracts directory (`libs/contracts/src/common/`) contains canonical
schemas for the 20 cross-cutting tables; this document is the missing index that
ties them together.

## Mapping

| #   | V1 Table                                     | Contract file                 | Canonical schema                                        | Notes                                                               |
| --- | -------------------------------------------- | ----------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
| 1   | `v1_cross_cutting_persona`                   | `common/persona.ts`           | `PersonaSchema` / `PersonaSummarySchema`                | Sources: lilith/database `Persona`. Cross-tenant persona promotion. |
| 2   | `v1_cross_cutting_voice_profile`             | `common/voice-profile.ts`     | `VoiceProfileSchema`                                    | Sources: lilith/database `VoiceProfile`.                            |
| 3   | `v1_cross_cutting_avatar_pack`               | `common/avatar-pack.ts`       | `AvatarPackSchema`                                      | Sources: lilith/database `AvatarPack`.                              |
| 4   | `v1_cross_cutting_consent_record`            | `common/consent-record.ts`    | `ConsentRecordSchema`                                   | Sources: iris/database, yemaya/database.                            |
| 5   | `v1_cross_cutting_memory_scope`              | `common/memory-scope.ts`      | `MemoryScopeSchema`                                     | Sources: iris/database.                                             |
| 6   | `v1_cross_cutting_evidence_pack`             | `common/evidence-pack.ts`     | `EvidencePackSchema`                                    | Sources: psyche/database, veritas/database.                         |
| 7   | `v1_cross_cutting_citation_trail`            | `common/citation.ts`          | `CitationTrailSchema`                                   | Sources: veritas/database.                                          |
| 8   | `v1_cross_cutting_grounded_answer_envelope`  | `common/grounded-answer.ts`   | `GroundedAnswerSchema` / `GroundedAnswerEnvelopeSchema` | Sources: iris/database.                                             |
| 9   | `v1_cross_cutting_workflow_template`         | `common/workflow-template.ts` | `WorkflowTemplateSchema`                                | Sources: maat/database.                                             |
| 10  | `v1_cross_cutting_model_card`                | `common/model-card.ts`        | `ModelCardSchema`                                       | Sources: isis/database, psyche/database.                            |
| 11  | `v1_cross_cutting_model_version`             | `common/model-version.ts`     | `ModelVersionSchema`                                    | Sources: isis/database.                                             |
| 12  | `v1_cross_cutting_provenance_bundle`         | `common/provenance-bundle.ts` | `ProvenanceBundleSchema`                                | Sources: psyche/database, veritas/database.                         |
| 13  | `v1_cross_cutting_review_package`            | `common/review-package.ts`    | `ReviewPackageSchema`                                   | Sources: maat/database.                                             |
| 14  | `v1_cross_cutting_incident`                  | `common/incident.ts`          | `IncidentSchema`                                        | Sources: maat/database.                                             |
| 15  | `v1_cross_cutting_policy_bundle`             | `common/policy-bundle.ts`     | `PolicyBundleSchema`                                    | Sources: maat/database, yemaya/database.                            |
| 16  | `v1_cross_cutting_support_case`              | `common/support-case.ts`      | `SupportCaseSchema`                                     | Sources: yemaya/database.                                           |
| 17  | `v1_cross_cutting_tenant`                    | `common/tenant.ts`            | `TenantSchema`                                          | Sources: yemaya/database.                                           |
| 18  | `v1_cross_cutting_tenant_hierarchy_edge`     | `common/tenant.ts`            | `TenantHierarchyEdgeSchema`                             | Lives in the same contract file as `TenantSchema`.                  |
| 19  | `v1_cross_cutting_tenant_policy_inheritance` | `common/tenant.ts`            | `TenantPolicyInheritanceSchema`                         | Lives in the same contract file as `TenantSchema`.                  |
| 20  | `v1_cross_cutting_agent_run`                 | `common/agent-run.ts`         | `AgentRunSchema`                                        | Sources: maat/database, isis/database.                              |

## Historical aliases

`AdminWorkflowTemplateSchema` in `common/admin-workflow-template.ts` remains for
maat's workflow studio compatibility, but the cross-cutting persistence table
uses the canonical `WorkflowTemplateSchema` from `common/workflow-template.ts`.

## Adding to `contract-prisma-alignment.ts`

`libs/contracts/src/common/contract-prisma-alignment.ts` maintains
contract-to-Prisma ownership entries. For the cross-cutting tables documented
here, each existing entry (e.g., the entry for `persona.ts`) should add an owner
pointing at `libs/oshun/persistence/prisma/schema.prisma` with the
`V1CrossCutting*` model. That update is deferred to a follow-up PR because the
alignment file is hand-maintained and each entry needs its `requiredFields`
projection authored against the Prisma model — it's not amenable to a single
mechanical pass.

This mapping document is the source of truth in the meantime: any code that
writes to a `v1_cross_cutting_*` table must validate against the contract listed
here.
