# ISIS Migration Rollback and Verification Scripts (MIG-005)

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.
