# Normal run output ABI

This document defines the compatibility surface between the existing `rpki`
runtime and `panda-rpki-validator`. It covers normal snapshot and delta runs;
`verification-only` is deliberately outside this component.

## Persistent volume

The image exposes one data root, `/var/lib/panda-rpki-validator` by default.
The root may be changed by deployment configuration, but the relative layout
must remain:

```text
<data-root>/
├── state/
│   ├── db/                 # work DB and repo-bytes state
│   ├── rsync-mirror/       # reusable rsync mirror when enabled
│   └── ...                 # lifecycle, TA refresh and failure-isolation state
├── runs/run_XXXX/          # retained normal run directories
├── logs/
└── tmp/
```

The component and the old runtime must never share a state root during A/B
comparison.

## Required normal-run files

Every successful snapshot/delta run must produce the following files under its
run directory:

| File | Contract |
|---|---|
| `run-meta.json` | run id/sequence, status, sync mode, timing and lifecycle metadata |
| `run-summary.json` | status, counts, artifact index, stage timing and exit information |
| `daemon-status.json` | current runner status and last-run information |
| `report.json` | validation report and object/publication-point summaries |
| `input.cir` | canonical synchronized validation input |
| `result.ccr` | canonical validated state/cache output |
| `vrps.csv` | VRP payload with the existing header, order and canonical sorting |
| `vaps.csv` | VAP payload with the existing header, order and canonical sorting |
| `validation-contract.json` | effective validation configuration and binding |
| `stage-timing.json` | stage-level timing used by diagnostics and performance gates |
| `stdout.log` / `stderr.log` | child process logs |
| `process-time.txt` | resource/time measurement when enabled |

`db-stats-estimate.txt` and lifecycle helper files remain part of the diagnostic
surface whenever the corresponding feature is enabled. Missing required files,
changed schema, changed CSV columns/order, or an undeclared semantic difference
fails compatibility even if a VRP count is produced.

## Canonical comparison

The compatibility harness compares exit code, sync mode, publication-point
outcome, accepted/rejected objects, VRP/VAP, report, CIR/CCR and state/cache
digests. It normalizes only lifecycle wall-clock timestamps, CCR `producedAt`,
absolute paths, fields explicitly marked as component/image version or
provenance, and runtime duration/resource telemetry (including digests derived
from timestamped audit events). The validation time is a fixed input and is
compared exactly. Every normalization is recorded in the baseline manifest;
output differences outside that list are failures.