freeze initial panda-rpki staging

docs/architecture.md

@@ -0,0 +1,21 @@
+# panda-rpki-validator M5 architecture
+
+The first public package is intentionally a single Cargo package. Its internal
+boundaries are:
+
+1. `model-crypto`: TAL/TA, ASN.1/RPKI objects, signatures and resources.
+2. `transport`: HTTP, RRDP, rsync and offline replay inputs.
+3. `sync-validation-engine`: snapshot/delta orchestration, CA-tree validation,
+   policy/TA constraints and parallel scheduling.
+4. `state-cache`: repository bytes, RocksDB state and cache lifecycle.
+5. `runtime-lifecycle`: run numbering, retention, TA refresh, failure reset and
+   artifact materialization for native and Docker execution.
+
+M4 contains the extracted normal synchronization and validation implementation
+across all five boundaries, plus the daemon and shell lifecycle wrapper used
+by the Docker image. Metrics, query, UI, RTR, Prometheus/Grafana, old installer
+control plane, remote scripts and `verification-only` are not dependencies of
+this package. M5 has established the first canonical normal-run and
+multi-architecture baseline; the remaining profile/performance gates against
+the old runtime must pass before this repository can be considered
+release-ready.

docs/output-abi.md

@@ -0,0 +1,61 @@
+# 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.