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
outputsandprovenancetables exist)
Outputs a JSON report to tmp/isis-migration/ by default.
Usage:
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:
# 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:
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:
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:
# 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-Idwhen provided - Emits deterministic JSON report and enforces failed-update gating
Usage:
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:
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.mjsscripts/isis/validate-v2-migration-completion-certificate.mjs
Default artifacts:
docs/domains/isis/remediation-v2/ISIS_V2_MIGRATION_COMPLETION_CERTIFICATE.jsondocs/domains/isis/remediation-v2/ISIS_V2_MIGRATION_COMPLETION_CERTIFICATE.md
Usage:
# 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.shscripts/isis/rollback_ws17_002_workflow_taxonomy_backfill.shscripts/isis/rollback_ws17_003_historical_job_taxonomy.shscripts/isis/rollback_ws17_004_output_provenance_backfill.sh- Pack orchestrator:
scripts/isis/rollback_schema_evolution_milestones.sh
Example:
# 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:
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.shdefaults toDRY_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.shbefore and after rollback execution.