20260902 完成公开树清理与热点拆分

docs/Makefile

@@ -0,0 +1,18 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+.PHONY: help html linkcheck clean
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html:
+	@$(SPHINXBUILD) -W --keep-going -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+linkcheck:
+	@$(SPHINXBUILD) -W --keep-going -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf "$(BUILDDIR)"

docs/architecture.md

@@ -1,21 +0,0 @@
-# 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/make.bat

@@ -0,0 +1,19 @@
+@ECHO OFF
+pushd %~dp0
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -W --keep-going -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/output-abi.md

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

docs/requirements.txt

@@ -0,0 +1,2 @@
+Sphinx==9.1.0
+sphinx-rtd-theme==3.1.0

docs/source/architecture.rst

@@ -0,0 +1,25 @@
+Architecture
+============
+
+The repository uses a Rust workspace. The primary validator crate is
+crates/panda-rpki-validator and is organized around these responsibilities:
+
+* command-line parsing and operator-facing commands;
+* trust-anchor and publication-point retrieval;
+* parsing and validation of RPKI signed objects;
+* validation-tree scheduling and traversal;
+* storage, caches, and run state; and
+* report generation and output serialization.
+
+Source boundaries should follow these responsibilities. Large orchestration
+modules are refactored in small, test-protected steps so public behavior and
+fixed-input results remain stable.
+
+Data flow
+---------
+
+Trust-anchor inputs seed repository retrieval. Parsed objects enter the
+validation tree, which applies cryptographic and resource-validation rules.
+The resulting state is persisted and rendered into the configured reports.
+Network transport, cache lifetime, and output retention are operational
+concerns and must remain explicit in their respective modules.

docs/source/cli.rst

@@ -0,0 +1,22 @@
+Command-line interface
+======================
+
+The panda-rpki-validator binary is the primary command-line entry point.
+Commands and flags are part of the operator-facing compatibility surface.
+Discover the exact interface for a checkout with:
+
+.. code-block:: console
+
+   cargo run --locked -p panda-rpki-validator -- --help
+
+The repository also provides scripts/runtime/run_validator.sh for repeatable
+local executions and scripts/docker/build_image.sh for local container image
+builds. Scripts validate required commands and their documented environment
+variables before starting a run.
+
+The container entrypoint accepts run to select the runtime wrapper. That
+subcommand belongs to the container entrypoint, not the Rust validator binary.
+
+Automation should pin a reviewed source revision, retain generated reports,
+and treat command failures as operational signals rather than silently
+retrying forever.

docs/source/conf.py

@@ -0,0 +1,17 @@
+project = "panda-rpki"
+copyright = "2026, panda-rpki contributors"
+author = "panda-rpki contributors"
+release = "0.1.0"
+language = "en"
+
+extensions = []
+templates_path = []
+exclude_patterns = ["_build"]
+
+html_theme = "sphinx_rtd_theme"
+html_title = "panda-rpki documentation"
+html_static_path = []
+html_theme_options = {
+    "navigation_depth": 3,
+    "collapse_navigation": False,
+}

docs/source/configuration.rst

@@ -0,0 +1,32 @@
+Configuration
+=============
+
+The runtime helper reads configuration from .env at the package root by
+default. Set ENV_FILE to select another file:
+
+.. code-block:: console
+
+   ENV_FILE=/path/to/.env bash scripts/runtime/run_validator.sh
+
+The Compose deployment has a separate deployment configuration file at
+deploy/docker/.env. It supplies Compose variables as well as environment
+variables for the runtime wrapper. The helper recognizes controls for run
+retention, RIR selection, TAL input, resource-validation mode, storage
+locations, mirror reuse, retry intervals, and progress logging. Inspect
+deploy/docker/.env.example and the helper's usage output before changing
+production-like settings.
+
+Runtime state
+-------------
+
+By default, state, run reports, logs, and temporary files are placed below
+the package root. Set RUN_ROOT to move them elsewhere. These locations are
+runtime data, not source inputs, and should be retained or removed according
+to the operator's own recovery policy.
+
+Network safety
+--------------
+
+Use bounded timeouts and explicit network access policies in automation.
+Publication points are untrusted network inputs, so test configuration
+changes against known fixtures before applying them to a long-running service.

docs/source/contributing.rst

@@ -0,0 +1,11 @@
+Contributing
+============
+
+This checkout is being prepared for public release and does not yet accept
+external contributions. The source is distributed under the BSD 3-Clause
+License (see the repository ``LICENSE`` file); the contribution workflow and
+code of conduct must be established before maintainers solicit or accept
+contributions.
+
+For local development, keep changes focused, add tests before refactoring
+behavior-sensitive code, and run the checks in the testing guide.

docs/source/development.rst

@@ -0,0 +1,17 @@
+Development
+===========
+
+The Rust workspace contains the validator implementation, supporting crates,
+integration fixtures, and scripts for local and container workflows.
+
+Before proposing a behavioral change, add or extend focused unit tests, run
+the workspace test gates, and exercise a fixed-input compatibility comparison
+when storage, scheduling, validation traversal, or output behavior changes.
+
+Keep source comments focused on current behavior and invariants. Avoid
+embedding personal paths, internal work-item labels, historical branches, or
+deployment-specific addresses in public-facing source and documentation.
+
+The CI public-tree check rejects known internal-history patterns from the
+public text surface. If a new public document needs a term that resembles a
+rejected pattern, revise the check deliberately and explain why in review.

docs/source/getting-started.rst

@@ -0,0 +1,46 @@
+Getting started
+===============
+
+Prerequisites
+-------------
+
+Install the Rust toolchain named by rust-toolchain.toml, Docker for the
+container workflow, and Python 3.12 or later for documentation builds.
+
+Build and test
+--------------
+
+From the repository root, run:
+
+.. code-block:: console
+
+   cargo build --locked --workspace
+   cargo test --locked --workspace
+
+The validator crate is located at crates/panda-rpki-validator. Its binary
+accepts trust-anchor inputs and produces validated RPKI output. Use the local
+help command to inspect the command surface available in the checkout:
+
+.. code-block:: console
+
+   cargo run --locked -p panda-rpki-validator -- --help
+
+The bootstrap TAL and trust-anchor files in fixtures are not an offline
+repository snapshot. To make a deterministic offline validation run, supply a
+reviewed payload replay archive and locks file through the documented command
+line options. Do not treat live RRDP or rsync retrieval as reproducible input.
+
+Local container workflow
+------------------------
+
+The Docker scripts build a local image and run the repository verification
+workflow:
+
+.. code-block:: console
+
+   bash scripts/docker/build_image.sh --arch amd64 --allow-dirty
+
+For the Compose workflow, copy deploy/docker/.env.example to deploy/docker/.env
+and use deploy/docker/scripts/start.sh. The image name in that file must match
+the image tag built locally. Do not place credentials or generated outputs
+under version control.

docs/source/index.rst

@@ -0,0 +1,27 @@
+panda-rpki documentation
+=========================
+
+panda-rpki is a Rust implementation of an RPKI relying-party validator.
+It retrieves RPKI publication data, validates the associated objects, and
+emits machine-readable reports for operational systems.
+
+This documentation describes the current source tree and supported local
+development workflows. Public release terms, release artifacts, and a public
+security reporting channel are not established yet.
+
+Built with Sphinx using a theme provided by Read the Docs.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   getting-started
+   configuration
+   cli
+   operations
+   testing
+   development
+   architecture
+   output-abi
+   contributing
+   security

docs/source/operations.rst

@@ -0,0 +1,19 @@
+Operations
+==========
+
+An operational run obtains RPKI repository data through the configured
+transport, validates objects from the selected trust anchors, and writes
+reports and state below RUN_ROOT. The helper script can repeat a run at an
+interval and retain a bounded run history.
+
+Before operating a long-running instance:
+
+* choose explicit paths for state and logs;
+* set bounded network timeouts;
+* preserve reports needed for diagnosis;
+* monitor exit status, validation failures, and storage growth; and
+* test upgrades with the compatibility fixtures described in the testing guide.
+
+The current checkout is not a published production release. Operators are
+responsible for reviewing the source revision and deployment configuration
+they use.

docs/source/output-abi.rst

@@ -0,0 +1,19 @@
+Output compatibility
+====================
+
+Reports and serialized records are consumed by automation, so their fields,
+ordering assumptions, and error semantics are compatibility-sensitive.
+Changes to output code require focused tests and a fixed-input comparison
+before they are treated as behavior-preserving.
+
+When changing an output format:
+
+* document the intended consumer impact;
+* preserve stable fields where possible;
+* add a narrow unit or integration test for the changed contract;
+* compare output from equivalent fixed inputs; and
+* state any deliberate incompatibility in release notes once a public release
+  process exists.
+
+Do not interpret this document as a versioned external API promise. A public
+versioning and release policy has not been established for this checkout.

docs/source/security.rst

@@ -0,0 +1,11 @@
+Security
+========
+
+panda-rpki processes cryptographic material and untrusted network data.
+Treat credentials, trust-anchor inputs, runtime state, logs, and generated
+reports as potentially sensitive operational data.
+
+No public vulnerability-reporting channel is established for this pre-release
+checkout. Do not include a private contact address in a future public release
+until its ownership, response process, and disclosure policy have been
+approved.

docs/source/testing.rst

@@ -0,0 +1,33 @@
+Testing
+========
+
+Fast checks
+-----------
+
+Run the workspace checks from the repository root:
+
+.. code-block:: console
+
+   cargo fmt --all -- --check
+   cargo test --locked --workspace
+   cargo clippy --locked --workspace --all-targets -- -D warnings
+
+Compatibility fixtures
+----------------------
+
+The tests/compat directory defines fixed-input, two-run comparisons. They
+protect runtime equivalence while changes are made to traversal, storage, and
+output code. The fixture manifest records only test inputs and comparison
+scope; it does not describe a historical source baseline.
+
+Documentation checks
+--------------------
+
+Install the documentation dependencies and build both local documentation
+targets:
+
+.. code-block:: console
+
+   python -m pip install -r docs/requirements.txt
+   sphinx-build -W --keep-going -b html docs/source docs/_build/html
+   sphinx-build -W --keep-going -b linkcheck docs/source docs/_build/linkcheck