Eve library

OSHUN V1 Persistence Migration and Backfill Plan

Spec

Revision 1

On this page

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.