Eve library

ISIS Migration Rollback and Verification Scripts (MIG-005)

Guide

Revision 1

On this page

Date: 2026-02-22
Checklist Item: MIG-005
Ticket: ISIS-0174

Goal#

Provide executable scripts for migration verification and rollback controls aligned with the job lifecycle migration design and rollback criteria.

Scripts#

scripts/isis/verify_job_lifecycle_migration.sh#

Runs invariant diagnostics for migration safety and completion checks:

  • Non-canonical statuses
  • Non-terminal jobs missing outbox rows
  • Terminal timestamp/field consistency
  • Missing canonical workflowId
  • Missing canonical cost metadata
  • Output provenance linkage drift (when outputs and provenance tables exist)

Outputs a JSON report to tmp/isis-migration/ by default.

Usage:

bash
ISIS_DATABASE_URL=postgres://... \
FAIL_ON_VIOLATIONS=true \
scripts/isis/verify_job_lifecycle_migration.sh

scripts/isis/rollback_job_lifecycle_migration.sh#

Executes field-level rollback for migration backfill markers with dry-run by default:

  • Workflow backfill rollback (metadata.workflowIdBackfill)
  • Cost backfill rollback (metadata.costBackfill)
  • Optional rollback of failed legacy recovery transitions

Outputs a JSON rollback report to tmp/isis-migration/ by default.

Usage:

bash
# Dry-run (default)
ISIS_DATABASE_URL=postgres://... \
scripts/isis/rollback_job_lifecycle_migration.sh

# Apply rollback
ISIS_DATABASE_URL=postgres://... \
DRY_RUN=false \
ROLLBACK_WORKFLOW_BACKFILL=true \
ROLLBACK_COST_BACKFILL=true \
scripts/isis/rollback_job_lifecycle_migration.sh

scripts/isis/verify_migration_snapshot.sh#

Captures deterministic migration-state snapshot metrics for WS17 backfills:

  • Workflow taxonomy completeness (workflows + workflow_versions)
  • Historical job taxonomy consistency (jobs)
  • Output provenance + consistency linkage (outputs + provenance)
  • Backfill marker coverage for WS17-002 / WS17-003 / WS17-004

Outputs a JSON snapshot report to tmp/isis-migration/ by default.

Usage:

bash
ISIS_DATABASE_URL=postgres://... \
scripts/isis/verify_migration_snapshot.sh

scripts/isis/verify_migration_before_after.sh#

Compares two snapshot reports using deterministic direction rules:

  • Deficit metrics must not regress (after <= before)
  • Marker metrics must not regress by default (after >= before)
  • Optional strict-improvement controls via env flags

Outputs a before/after comparison report to tmp/isis-migration/ by default.

Usage:

bash
BEFORE_REPORT=tmp/isis-migration/migration-snapshot-before.json \
AFTER_REPORT=tmp/isis-migration/migration-snapshot-after.json \
STRICT=true \
scripts/isis/verify_migration_before_after.sh

Example sequence:

bash
# 1) baseline snapshot
ISIS_DATABASE_URL=postgres://... \
REPORT_FILE=tmp/isis-migration/migration-snapshot-before.json \
scripts/isis/verify_migration_snapshot.sh

# 2) run migration/backfill scripts (WS17-002/003/004)

# 3) post-migration snapshot
ISIS_DATABASE_URL=postgres://... \
REPORT_FILE=tmp/isis-migration/migration-snapshot-after.json \
scripts/isis/verify_migration_snapshot.sh

# 4) deterministic before/after verification
BEFORE_REPORT=tmp/isis-migration/migration-snapshot-before.json \
AFTER_REPORT=tmp/isis-migration/migration-snapshot-after.json \
STRICT=true \
scripts/isis/verify_migration_before_after.sh

scripts/isis/migrate_workflow_taxonomy.sh#

Executes WS17-002 workflow taxonomy/provenance backfill endpoint with dry-run support:

  • Calls /api/v1/workflows/admin/taxonomy/backfill
  • Supports scoped execution via X-Isis-Project-Id when provided
  • Emits deterministic JSON report and enforces failed-update gating

Usage:

bash
ISIS_API_KEY=... \
ISIS_WORKFLOW_REGISTRY_URL=https://workflow-registry-staging.example.com \
DRY_RUN=true \
LIMIT=50000 \
scripts/isis/migrate_workflow_taxonomy.sh

scripts/isis/run_ws17_migration_dry_run_pipeline.sh#

Runs end-to-end WS17 staging dry-run rehearsal with synthetic high-volume dataset support:

  • Captures baseline migration snapshot
  • Seeds synthetic workflows/jobs/outputs for WS17-002/003/004 coverage
  • Executes workflow/job/output backfill scripts with DRY_RUN=true
  • Captures post-run snapshot and validates no-regression before/after checks
  • Optionally cleans up synthetic seeded records
  • Produces consolidated pipeline report with step-level pass/fail details

Usage:

bash
STRICT=true \
ENABLE_SYNTHETIC_DATASET=true \
CLEANUP_SYNTHETIC_DATASET=true \
ISIS_DATABASE_URL=postgres://... \
ISIS_API_KEY=... \
ISIS_WORKFLOW_REGISTRY_URL=https://workflow-registry-staging.example.com \
ISIS_GENERATION_API_URL=https://generation-api-staging.example.com \
ISIS_OUTPUT_REGISTRY_URL=https://output-registry-staging.example.com \
scripts/isis/run_ws17_migration_dry_run_pipeline.sh

Migration Completion Certificate Artifacts#

Release-prerequisite migration certificate artifacts are generated and validated via:

  • scripts/isis/generate-v2-migration-completion-certificate.mjs
  • scripts/isis/validate-v2-migration-completion-certificate.mjs

Default artifacts:

  • docs/domains/isis/remediation-v2/ISIS_V2_MIGRATION_COMPLETION_CERTIFICATE.json
  • docs/domains/isis/remediation-v2/ISIS_V2_MIGRATION_COMPLETION_CERTIFICATE.md

Usage:

bash
# Generate static certificate from repository state + compliance gate
node scripts/isis/generate-v2-migration-completion-certificate.mjs

# Validate deterministic synchronization
node scripts/isis/validate-v2-migration-completion-certificate.mjs

# Release-time enforcement with runtime dry-run evidence
node scripts/isis/generate-v2-migration-completion-certificate.mjs \
  --dry-run-report=tmp/isis-migration/ws17-migration-dry-run-pipeline-<timestamp>.json \
  --release-id=ws17-prod-cutover-<date> \
  --environment=production
node scripts/isis/validate-v2-migration-completion-certificate.mjs \
  --require-release-eligible=true

WS17 Schema Evolution Rollback Packs#

Rollback-safe packs were added for each WS17 schema evolution milestone (all default to DRY_RUN=true and emit JSON reports):

  • scripts/isis/rollback_ws17_001_workflow_schema_evolution.sh
  • scripts/isis/rollback_ws17_002_workflow_taxonomy_backfill.sh
  • scripts/isis/rollback_ws17_003_historical_job_taxonomy.sh
  • scripts/isis/rollback_ws17_004_output_provenance_backfill.sh
  • Pack orchestrator: scripts/isis/rollback_schema_evolution_milestones.sh

Example:

bash
# Dry-run all milestone packs
ISIS_DATABASE_URL=postgres://... \
DRY_RUN=true \
scripts/isis/rollback_schema_evolution_milestones.sh

# Apply only WS17-003 and WS17-004 rollback packs
ISIS_DATABASE_URL=postgres://... \
MILESTONES=WS17-003,WS17-004 \
DRY_RUN=false \
scripts/isis/rollback_schema_evolution_milestones.sh

Destructive schema rollback safety gate for WS17-001:

bash
ISIS_DATABASE_URL=postgres://... \
DRY_RUN=false \
ALLOW_DESTRUCTIVE_SCHEMA_ROLLBACK=true \
CONFIRM_SCHEMA_ROLLBACK=WS17-001 \
scripts/isis/rollback_ws17_001_workflow_schema_evolution.sh

Safety Notes#

  • rollback_job_lifecycle_migration.sh defaults to DRY_RUN=true.
  • Snapshot/backup requirements still apply before any production rollback.
  • Prefer forward-fix over destructive rollback when data safety is uncertain.
  • Use verify_job_lifecycle_migration.sh before and after rollback execution.