# Isis Output Lineage and Provenance Audit Runbook

Last Updated: 2026-02-25  
Scope: Output integrity audit coverage for orphaned outputs, broken lineage
edges, and missing provenance links.

## Purpose

Provide deterministic audit evidence for WS17-007 integrity requirements:

1. Orphaned outputs (eligible outputs detached from provenance and lineage).
2. Broken lineage edges (`lineage_edges` rows pointing to missing outputs or
   self-referential edges).
3. Missing provenance coverage from both output and provenance perspectives.

## Audit Automation

Use `scripts/isis/generate_output_lineage_provenance_audit_report.sh`.

Report outputs:

- JSON: `tmp/isis-audits/output-lineage-provenance-audit-*.json`
- Markdown: `tmp/isis-audits/output-lineage-provenance-audit-*.md`

## Prerequisites

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

## Execution

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

## Threshold Controls

| Variable                         | Default | Description                                                      |
| -------------------------------- | ------- | ---------------------------------------------------------------- |
| `SAMPLE_LIMIT`                   | `25`    | Maximum samples per issue class in report payloads.              |
| `MAX_ORPHANED_OUTPUTS`           | `0`     | Allowed orphaned output count.                                   |
| `MAX_BROKEN_LINEAGE_EDGES`       | `0`     | Allowed broken lineage edge count.                               |
| `MAX_OUTPUTS_MISSING_PROVENANCE` | `0`     | Allowed count of eligible outputs missing provenance linkage.    |
| `MAX_ORPHAN_PROVENANCE_ROWS`     | `0`     | Allowed count of provenance rows that reference missing outputs. |

## Remediation Guidance

If the audit fails:

1. Run provenance backfill:
   - `POST /api/v1/outputs/admin/provenance/backfill`
   - `isis outputs backfill-provenance`
2. Repair or remove invalid lineage edges.
3. Re-run the audit script until all threshold checks pass.
