# Isis Backfilled Scope Integrity Checks Runbook

Last Updated: 2026-02-25  
Scope: Ownership and tenant/project scope integrity checks for WS17 backfilled
records.

## Purpose

Provide deterministic multi-tenant integrity verification for records affected
by WS17 backfills:

1. Workflow taxonomy backfill (`WS17-002`)
2. Historical job taxonomy backfill (`WS17-003`)
3. Output provenance backfill (`WS17-004`)

The check validates owner continuity, scope mismatches, and lineage scoping
violations in backfilled records.

## Verification Script

Use:

- `scripts/isis/verify_backfilled_scope_integrity.sh`

Outputs:

- JSON report: `tmp/isis-migration/backfilled-scope-integrity-*.json`
- Markdown report: `tmp/isis-migration/backfilled-scope-integrity-*.md`

## Prerequisites

- `psql` and `jq` installed.
- `ISIS_DATABASE_URL` (or `DATABASE_URL`) configured.
- Read access to `workflows`, `jobs`, `outputs`, `provenance`, `lineage_edges`.

## Execution

```bash
STRICT=true \
ISIS_DATABASE_URL="postgres://..." \
scripts/isis/verify_backfilled_scope_integrity.sh
```

## Controls

| Variable                               | Default | Description                                                                 |
| -------------------------------------- | ------- | --------------------------------------------------------------------------- |
| `SAMPLE_LIMIT`                         | `25`    | Maximum samples per issue class.                                            |
| `REQUIRE_TENANT_SCOPE_FOR_BACKFILLED`  | `false` | Enforce tenant scope presence checks for backfilled jobs/outputs.           |
| `REQUIRE_PROJECT_SCOPE_FOR_BACKFILLED` | `false` | Enforce project scope presence checks for backfilled jobs/outputs.          |
| `MAX_WORKFLOW_OWNER_GAPS`              | `0`     | Allowed count of WS17-002 workflows with missing owner.                     |
| `MAX_JOB_OWNER_GAPS`                   | `0`     | Allowed count of WS17-003 jobs with missing owner scope.                    |
| `MAX_JOB_SCOPE_MISMATCHES`             | `0`     | Allowed job metadata/output scope mismatch count.                           |
| `MAX_OUTPUT_SCOPE_MISMATCHES`          | `0`     | Allowed output/provenance scope mismatch count for WS17-004 outputs.        |
| `MAX_LINEAGE_SCOPE_VIOLATIONS`         | `0`     | Allowed cross-tenant/project lineage-edge violations in backfilled outputs. |
| `MAX_MISSING_TENANT_SCOPE`             | `0`     | Allowed missing tenant scope count (when tenant scope is required).         |
| `MAX_MISSING_PROJECT_SCOPE`            | `0`     | Allowed missing project scope count (when project scope is required).       |

## Remediation Guidance

If checks fail:

1. Review JSON `failureReasons` and issue samples.
2. Correct scope fields in affected records (owner/tenant/project alignment).
3. Remove or repair cross-scope lineage edges violating policy.
4. Re-run script until threshold checks pass.
