# OSHUN V1 Persistence Migration and Backfill Plan

This runbook is generated from `libs/oshun/persistence/src/migration-plan.ts`.
Every domain plan is dry-runnable and every backfill upsert is keyed by
`tenant_id`, `contract_schema`, and `source_record_id`.

## Shared Execution Contract

- Target schema: `libs/oshun/persistence/prisma/schema.prisma`
- Target database env: `OSHUN_V1_DATABASE_URL`
- Canonical staging table: `oshun_v1_contract_backfill_sources`
- Migration ledger table: `oshun_v1_migration_ledger`
- Schema dry run uses `prisma migrate diff --script`; apply pipes that
  current-state diff through `psql` with `ON_ERROR_STOP=1`.
- Backfills read adapter-exported canonical payloads from the staging table and
  use `ON CONFLICT` upserts.

## tara

- Migration key: `v1-contract-persistence-tara`
- Source database env: `TARA_DATABASE_URL`
- Source system: libs/tara/database plus @oshun/domain-tara canonical adapter
  exports
- Source extractor: domain-tara canonical ritual/session snapshot export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `210e9a00af3106eb2418225fc7c8f1bf3dafcead36c395494d82945b693a48eb`

| Order | Contract                       | Target table                       | Idempotency key                                |
| ----: | ------------------------------ | ---------------------------------- | ---------------------------------------------- |
|     1 | `DurationBucketSchema`         | `v1_tara_duration_bucket`          | `tenant_id, contract_schema, source_record_id` |
|     2 | `LineageTaxonomySchema`        | `v1_tara_lineage_taxonomy`         | `tenant_id, contract_schema, source_record_id` |
|     3 | `RitualStepSchema`             | `v1_tara_ritual_step`              | `tenant_id, contract_schema, source_record_id` |
|     4 | `RitualTemplateSchema`         | `v1_tara_ritual_template`          | `tenant_id, contract_schema, source_record_id` |
|     5 | `ContinuationStateSchema`      | `v1_tara_continuation_state`       | `tenant_id, contract_schema, source_record_id` |
|     6 | `RitualSessionSchema`          | `v1_tara_ritual_session`           | `tenant_id, contract_schema, source_record_id` |
|     7 | `SittingCompletionEventSchema` | `v1_tara_sitting_completion_event` | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-tara after
  exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## arete

- Migration key: `v1-contract-persistence-arete`
- Source database env: `ARETE_DATABASE_URL`
- Source system: libs/arete/database plus @oshun/domain-arete canonical adapter
  exports
- Source extractor: domain-arete habits, goals, routines, check-ins, reviews,
  and coaching export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `03985e51220ca10244a24d8d26cf62f88937d0de2a60c3730f33ca2112d2d94a`

| Order | Contract                | Target table                | Idempotency key                                |
| ----: | ----------------------- | --------------------------- | ---------------------------------------------- |
|     1 | `GoalSchema`            | `v1_arete_goal`             | `tenant_id, contract_schema, source_record_id` |
|     2 | `RoutineSchema`         | `v1_arete_routine`          | `tenant_id, contract_schema, source_record_id` |
|     3 | `HabitSchema`           | `v1_arete_habit`            | `tenant_id, contract_schema, source_record_id` |
|     4 | `CheckInSchema`         | `v1_arete_check_in`         | `tenant_id, contract_schema, source_record_id` |
|     5 | `JournalEntrySchema`    | `v1_arete_journal_entry`    | `tenant_id, contract_schema, source_record_id` |
|     6 | `WeeklyReviewSchema`    | `v1_arete_weekly_review`    | `tenant_id, contract_schema, source_record_id` |
|     7 | `StreakRecordSchema`    | `v1_arete_streak_record`    | `tenant_id, contract_schema, source_record_id` |
|     8 | `FrictionSignalSchema`  | `v1_arete_friction_signal`  | `tenant_id, contract_schema, source_record_id` |
|     9 | `InterventionSchema`    | `v1_arete_intervention`     | `tenant_id, contract_schema, source_record_id` |
|    10 | `CoachingSummarySchema` | `v1_arete_coaching_summary` | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-arete
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## veritas

- Migration key: `v1-contract-persistence-veritas`
- Source database env: `VERITAS_DATABASE_URL`
- Source system: libs/veritas/database plus @oshun/domain-veritas canonical
  adapter exports
- Source extractor: domain-veritas source, claim, evidence, story, topic,
  timeline export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `bf1899ef4980462701f21c2e11ca3d73393ee44dc65f2ac491067318aa8514b2`

| Order | Contract                  | Target table                    | Idempotency key                                |
| ----: | ------------------------- | ------------------------------- | ---------------------------------------------- |
|     1 | `SourceSchema`            | `v1_veritas_source`             | `tenant_id, contract_schema, source_record_id` |
|     2 | `ClaimSchema`             | `v1_veritas_claim`              | `tenant_id, contract_schema, source_record_id` |
|     3 | `EvidencePackSchema`      | `v1_veritas_evidence_pack`      | `tenant_id, contract_schema, source_record_id` |
|     4 | `CounterclaimSchema`      | `v1_veritas_counterclaim`       | `tenant_id, contract_schema, source_record_id` |
|     5 | `TimelineSchema`          | `v1_veritas_timeline`           | `tenant_id, contract_schema, source_record_id` |
|     6 | `StoryUpdateSchema`       | `v1_veritas_story_update`       | `tenant_id, contract_schema, source_record_id` |
|     7 | `CorrectionNoteSchema`    | `v1_veritas_correction_note`    | `tenant_id, contract_schema, source_record_id` |
|     8 | `RetractionCascadeSchema` | `v1_veritas_retraction_cascade` | `tenant_id, contract_schema, source_record_id` |
|     9 | `TopicHubSchema`          | `v1_veritas_topic_hub`          | `tenant_id, contract_schema, source_record_id` |
|    10 | `StorySchema`             | `v1_veritas_story`              | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-veritas
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## nyx

- Migration key: `v1-contract-persistence-nyx`
- Source database env: `NYX_DATABASE_URL`
- Source system: libs/nyx/database plus @oshun/domain-nyx canonical adapter
  exports
- Source extractor: domain-nyx sky-event, prediction-source, observation-window,
  calendar export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `988be37470d609da3f7d96fefc926366d5553bdc72d665c23c0d80380bdf5f69`

| Order | Contract                    | Target table                   | Idempotency key                                |
| ----: | --------------------------- | ------------------------------ | ---------------------------------------------- |
|     1 | `PredictionSourceRefSchema` | `v1_nyx_prediction_source_ref` | `tenant_id, contract_schema, source_record_id` |
|     2 | `ObservationWindowSchema`   | `v1_nyx_observation_window`    | `tenant_id, contract_schema, source_record_id` |
|     3 | `SkyEventSchema`            | `v1_nyx_sky_event`             | `tenant_id, contract_schema, source_record_id` |
|     4 | `CalendarSyncEntrySchema`   | `v1_nyx_calendar_sync_entry`   | `tenant_id, contract_schema, source_record_id` |
|     5 | `LoggedObservationSchema`   | `v1_nyx_logged_observation`    | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-nyx after
  exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## nisaba

- Migration key: `v1-contract-persistence-nisaba`
- Source database env: `NISABA_DATABASE_URL`
- Source system: libs/nisaba/database plus @oshun/domain-nisaba canonical
  adapter exports
- Source extractor: domain-nisaba textual object, graph, notebook, study-plan
  export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `e78cee59a2c319123ba996fe1a1830eec2f2da219f9174e3664e488683772d75`

| Order | Contract                 | Target table                   | Idempotency key                                |
| ----: | ------------------------ | ------------------------------ | ---------------------------------------------- |
|     1 | `ManuscriptSchema`       | `v1_nisaba_manuscript`         | `tenant_id, contract_schema, source_record_id` |
|     2 | `EditionSchema`          | `v1_nisaba_edition`            | `tenant_id, contract_schema, source_record_id` |
|     3 | `TranslationSchema`      | `v1_nisaba_translation`        | `tenant_id, contract_schema, source_record_id` |
|     4 | `PassageSchema`          | `v1_nisaba_passage`            | `tenant_id, contract_schema, source_record_id` |
|     5 | `LexiconEntrySchema`     | `v1_nisaba_lexicon_entry`      | `tenant_id, contract_schema, source_record_id` |
|     6 | `MorphologyEntrySchema`  | `v1_nisaba_morphology_entry`   | `tenant_id, contract_schema, source_record_id` |
|     7 | `AnnotationSchema`       | `v1_nisaba_annotation`         | `tenant_id, contract_schema, source_record_id` |
|     8 | `ConceptGraphNodeSchema` | `v1_nisaba_concept_graph_node` | `tenant_id, contract_schema, source_record_id` |
|     9 | `ConceptGraphEdgeSchema` | `v1_nisaba_concept_graph_edge` | `tenant_id, contract_schema, source_record_id` |
|    10 | `NotebookSchema`         | `v1_nisaba_notebook`           | `tenant_id, contract_schema, source_record_id` |
|    11 | `StudyPlanSchema`        | `v1_nisaba_study_plan`         | `tenant_id, contract_schema, source_record_id` |
|    12 | `CitationSchema`         | `v1_nisaba_citation`           | `tenant_id, contract_schema, source_record_id` |
|    13 | `ScholarProfileSchema`   | `v1_nisaba_scholar_profile`    | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-nisaba
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## metis

- Migration key: `v1-contract-persistence-metis`
- Source database env: `METIS_DATABASE_URL`
- Source system: services/metis plus @oshun/domain-metis canonical adapter
  exports
- Source extractor: metis course-build, grounding, publication, tutor-memory,
  telemetry export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `060cb5cba9b1ff53ea27412c9a6709d6e03e55b677e9c45cfe91af480b72e0f6`

| Order | Contract                           | Target table                            | Idempotency key                                |
| ----: | ---------------------------------- | --------------------------------------- | ---------------------------------------------- |
|     1 | `MetisCourseProposalSchema`        | `v1_metis_course_proposal`              | `tenant_id, contract_schema, source_record_id` |
|     2 | `LearningSourceBundleSchema`       | `v1_metis_learning_source_bundle`       | `tenant_id, contract_schema, source_record_id` |
|     3 | `GroundingPackSchema`              | `v1_metis_grounding_pack`               | `tenant_id, contract_schema, source_record_id` |
|     4 | `CourseBuildSchema`                | `v1_metis_course_build`                 | `tenant_id, contract_schema, source_record_id` |
|     5 | `LessonAssetBundleSchema`          | `v1_metis_lesson_asset_bundle`          | `tenant_id, contract_schema, source_record_id` |
|     6 | `PublicationPackageSchema`         | `v1_metis_publication_package`          | `tenant_id, contract_schema, source_record_id` |
|     7 | `TutorPersonaProfileSchema`        | `v1_metis_tutor_persona_profile`        | `tenant_id, contract_schema, source_record_id` |
|     8 | `TutorSessionMemorySchema`         | `v1_metis_tutor_session_memory`         | `tenant_id, contract_schema, source_record_id` |
|     9 | `LearningObjectiveMapSchema`       | `v1_metis_learning_objective_map`       | `tenant_id, contract_schema, source_record_id` |
|    10 | `AssessmentEvidencePackSchema`     | `v1_metis_assessment_evidence_pack`     | `tenant_id, contract_schema, source_record_id` |
|    11 | `LearningTelemetryStatementSchema` | `v1_metis_learning_telemetry_statement` | `tenant_id, contract_schema, source_record_id` |
|    12 | `AcademicIntegrityVerdictSchema`   | `v1_metis_academic_integrity_verdict`   | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-metis
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## library

- Migration key: `v1-contract-persistence-library`
- Source database env: `LIBRARY_DATABASE_URL`
- Source system: apps/oshun/bff library collection rows exported via
  /v1/library/collections
- Source extractor: BFF library-collections adapter snapshot export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `63485b006a5f065746bd80a029168a4d5c881221b4a02f9c1c414a3d8ea03cf9`

| Order | Contract                  | Target table                    | Idempotency key                                |
| ----: | ------------------------- | ------------------------------- | ---------------------------------------------- |
|     1 | `LibraryCollectionSchema` | `v1_library_library_collection` | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-library
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## atelier

- Migration key: `v1-contract-persistence-atelier`
- Source database env: `ATELIER_DATABASE_URL`
- Source system: apps/oshun/bff atelier scene rows exported via
  /v1/atelier/scenes
- Source extractor: BFF atelier-scenes adapter snapshot export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `4907d1d2682602bb488fb247ca81a4946cbfaabf775b31392eeb022969387dde`

| Order | Contract             | Target table               | Idempotency key                                |
| ----: | -------------------- | -------------------------- | ---------------------------------------------- |
|     1 | `AtelierSceneSchema` | `v1_atelier_atelier_scene` | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-atelier
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## studio

- Migration key: `v1-contract-persistence-studio`
- Source database env: `STUDIO_DATABASE_URL`
- Source system: apps/oshun/bff studio scene rows exported via
  /v1/lilith-studio/scenes
- Source extractor: BFF lilith-studio-scenes adapter snapshot export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `a517a430a590234d8065f681b6e39b4ffd4837c8b576796dde7c497379f49dc3`

| Order | Contract            | Target table             | Idempotency key                                |
| ----: | ------------------- | ------------------------ | ---------------------------------------------- |
|     1 | `StudioSceneSchema` | `v1_studio_studio_scene` | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-studio
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## messaging

- Migration key: `v1-contract-persistence-messaging`
- Source database env: `MESSAGING_DATABASE_URL`
- Source system: apps/oshun/bff Telegram/Discord/Slack account-link rows lifted
  into the polymorphic messaging.account_link canonical model
- Source extractor: BFF telegram/discord/slack link adapter snapshot export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `1ee2b22076580777c5283a0f295e46e60880c67c65d05b30ede88bf4f7464d14`

| Order | Contract                     | Target table                | Idempotency key                                |
| ----: | ---------------------------- | --------------------------- | ---------------------------------------------- |
|     1 | `MessagingAccountLinkSchema` | `v1_messaging_account_link` | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-messaging
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## identity

- Migration key: `v1-contract-persistence-identity`
- Source database env: `IDENTITY_DATABASE_URL`
- Source system: apps/oshun/bff SCIM user rows promoted to the
  identity.scim_identity canonical model
- Source extractor: BFF SCIM 2.0 adapter snapshot export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `c82fc1736cf4484b7726b0ee130924e2e2e7855d8343575a64116b75b233aeb4`

| Order | Contract             | Target table                | Idempotency key                                |
| ----: | -------------------- | --------------------------- | ---------------------------------------------- |
|     1 | `ScimIdentitySchema` | `v1_identity_scim_identity` | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key v1-contract-persistence-identity
  after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.

## cross-cutting

- Migration key: `v1-contract-persistence-cross-cutting`
- Source database env: `OSHUN_V1_DATABASE_URL`
- Source system: shared governance, consent, persona, review, tenant, support,
  and agent-run ledgers
- Source extractor: cross-cutting canonical shared contract export
- Dry-run command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script`
- Apply command:
  `pnpm exec prisma migrate diff --from-url "$OSHUN_V1_DATABASE_URL" --to-schema-datamodel libs/oshun/persistence/prisma/schema.prisma --script | psql "$OSHUN_V1_DATABASE_URL" -v ON_ERROR_STOP=1`
- Dry-run hash:
  `384f075265e469cfce77319ac292228b50df3bca694a06b960c750b7397f2e69`

| Order | Contract                        | Target table                                 | Idempotency key                                |
| ----: | ------------------------------- | -------------------------------------------- | ---------------------------------------------- |
|     1 | `TenantSchema`                  | `v1_cross_cutting_tenant`                    | `tenant_id, contract_schema, source_record_id` |
|     2 | `TenantHierarchyEdgeSchema`     | `v1_cross_cutting_tenant_hierarchy_edge`     | `tenant_id, contract_schema, source_record_id` |
|     3 | `TenantPolicyInheritanceSchema` | `v1_cross_cutting_tenant_policy_inheritance` | `tenant_id, contract_schema, source_record_id` |
|     4 | `ConsentRecordSchema`           | `v1_cross_cutting_consent_record`            | `tenant_id, contract_schema, source_record_id` |
|     5 | `MemoryScopeSchema`             | `v1_cross_cutting_memory_scope`              | `tenant_id, contract_schema, source_record_id` |
|     6 | `PersonaSchema`                 | `v1_cross_cutting_persona`                   | `tenant_id, contract_schema, source_record_id` |
|     7 | `VoiceProfileSchema`            | `v1_cross_cutting_voice_profile`             | `tenant_id, contract_schema, source_record_id` |
|     8 | `AvatarPackSchema`              | `v1_cross_cutting_avatar_pack`               | `tenant_id, contract_schema, source_record_id` |
|     9 | `EvidencePackSchema`            | `v1_cross_cutting_evidence_pack`             | `tenant_id, contract_schema, source_record_id` |
|    10 | `CitationTrailSchema`           | `v1_cross_cutting_citation_trail`            | `tenant_id, contract_schema, source_record_id` |
|    11 | `GroundedAnswerEnvelopeSchema`  | `v1_cross_cutting_grounded_answer_envelope`  | `tenant_id, contract_schema, source_record_id` |
|    12 | `WorkflowTemplateSchema`        | `v1_cross_cutting_workflow_template`         | `tenant_id, contract_schema, source_record_id` |
|    13 | `ModelCardSchema`               | `v1_cross_cutting_model_card`                | `tenant_id, contract_schema, source_record_id` |
|    14 | `ModelVersionSchema`            | `v1_cross_cutting_model_version`             | `tenant_id, contract_schema, source_record_id` |
|    15 | `ProvenanceBundleSchema`        | `v1_cross_cutting_provenance_bundle`         | `tenant_id, contract_schema, source_record_id` |
|    16 | `ReviewPackageSchema`           | `v1_cross_cutting_review_package`            | `tenant_id, contract_schema, source_record_id` |
|    17 | `IncidentSchema`                | `v1_cross_cutting_incident`                  | `tenant_id, contract_schema, source_record_id` |
|    18 | `PolicyBundleSchema`            | `v1_cross_cutting_policy_bundle`             | `tenant_id, contract_schema, source_record_id` |
|    19 | `SupportCaseSchema`             | `v1_cross_cutting_support_case`              | `tenant_id, contract_schema, source_record_id` |
|    20 | `AgentRunSchema`                | `v1_cross_cutting_agent_run`                 | `tenant_id, contract_schema, source_record_id` |

Rollback plan:

- Stop domain writers or route them to the old read path.
- Delete only rows recorded for migration key
  v1-contract-persistence-cross-cutting after exporting the target tables.
- Reset unprocessed staging rows in oshun_v1_contract_backfill_sources by
  clearing processed_at and error_message for this domain.
- Restore the previous adapter read path and rerun the dry-run SQL before
  retrying.
