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

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