Arquitectura de Prova i Validació del Sistema Recorder

Audience: Engineers maintaining release confidence, deterministic Audiència: Enginyers que mantenen la confiança en les versions, la validació determinista i els artefactes de prova preparats per a auditoria.

Taula de continguts

Visió Executiva
System-Test Contract
Inventari Dirigit per Registre
Matriz de cobertura i model de buit
Artifact i Contracte de Transcripció
Eina d’Execució
Estructura de la Suite
File per Fitxer Referència Creuada

Executive Overview

El sistema de proves de validació de comportament a través de límits de producció reals (CLI i ingestió d’adaptadors), emet artefactes estructurats i fa un seguiment de la cobertura mitjançant fitxers TOML de registre + buits. El sistema està dissenyat per mantenir les execucions deterministes i inspectables.

F:system-tests/README.md L12-L39 F:system-tests/AGENTS.md L12-L35

Contracte de Prova del Sistema

Les proves del sistema requereixen:

afirmacions de fallada tancada,
sense correcció basada en el son,
comandes de producció i superfícies de dades,
emissió d’artefactes per prova obligatòria.

F:system-tests/AGENTS.md L14-L37

La restricció de funcions manté les proves del sistema explícites en CI i en execucions locals. F:system-tests/README.md L34-L45

Inventari Dirigit per Registre

system-tests/test_registry.toml és autoritari per:

categories,
metadades per prova,
punts d’entrada de comandes,
artefactes requerits,
temps d’execució estimat.

F:system-tests/test_registry.toml L5-L14 F:system-tests/test_registry.toml L15-L480

Matriz de cobertura i model de buit

system-tests/TEST_MATRIX.md defineix instantànies de cobertura objectiva P0/P1/P2. F:system-tests/TEST_MATRIX.md L12-L42

system-tests/test_gaps.toml fa un seguiment dels buits oberts/tancats amb criteris d’acceptació explícits i mapeig de categoria/prioritat. F:system-tests/test_gaps.toml L4-L74 F:system-tests/test_gaps.toml L75-L190

A partir del 2026-02-07, totes les llacunes del nucli P1 rastrejades estan tancades (selector compost deduplicat, ancoratges de prova de segment parcial, fallades de tancament per incompatibilitat entre segments, tancament d’adjunció fallat, paritat SQLite/en memòria). A partir del 2026-02-14, la cobertura de stress/perf P2 també està tancada amb artefactes de rendiment del nucli i del sidecar deterministes i control de CI de matriu de perfils. A partir de la mateixa data, els resultats de seguretat de l’OSS Launch 0 estan controlats per proves de sistema per a límits/polítiques de frontera CLI, camins de manipulació estructural del manifest, materialització de corrupció de SQLite i aplicació d’un sol segment obert. A partir de la mateixa data, el cicle de vida HTTP del sidecar i la persistència de la idempotència de reinici estan controlats per proves de sistema amb subprocessos reals del sidecar + fluxos de transport TCP. A partir del 2026-02-08, el seguiment de l’expansió de classe mundial del CLI OSS està totalment reflectit en les proves de sistema: paritat de validació de forma de recorder-id, comprovacions de fallada tancada d’entrada hostil d’adjunció, durada de segell automàtic/carrils de cicle de vida combinats, paginació JSON de consulta + baranes de sobre límit, i camins de comanda estricta de fallada/èxit ingest-fixture del Decision Gate CLI. A partir del 2026-02-08, l’embalatge del contenidor del sidecar també està controlat per proves de sistema a través del conjunt sidecar_docker (comprovacions de reforç d’actius + carril e2e de Docker Compose amb política d’omit/fracàs explícita a través de RECORDER_REQUIRE_DOCKER). A partir del 2026-02-08, el carril de Docker Compose valida addicionalment el comportament de la prova de preparació/inici del contenidor (/startup, /ready) abans i després de les transicions del cicle de vida d’obertura de segment. A partir del 2026-02-13, el carril de Docker Compose valida el reforç secret de bootstrap: el material font del token es proporciona a través de l’entrada secreta de Docker, després es materialitza en un camí de fitxer de token tmpfs dins del contenidor abans de l’inici del sidecar. A partir del 2026-02-10, la cobertura d’operacions inclou un carril de generació de contractes que afirma artefactes de projecció tipada SDK/OpenAPI (sdk/types.json, sdk/methods.json, components estrictes Bundle/VerificationVerdict d’OpenAPI) per a la preparació del generador SDK a muntant avall. A partir del 2026-02-11, el conjunt d’operacions està dividit en mòduls (operations/{query,config,locale,contract}.rs) per mantenir els fitxers de prova delimitats i revisables mentre es preserva el comportament determinista d’artefactes/informes. A partir del 2026-02-11, els conjunts de seguretat i integració també estan dividits en fitxers (security_{support,limits,signer,contract_bundle}.rs, integration_openclaw_{support,core,additional}.rs, integration_decision_gate_{support,contract_shape,ingest}.rs) per mantenir les superfícies de prova revisables mentre es preserva el comportament determinista i la metadada d’execució. A partir de la mateixa data, la cobertura de seguretat inclou la validació de saturació de la cua d’operacions de SQLite amb artefactes de resum de saturació determinista (sqlite_operation_queue_saturation_fails_closed). A partir del 2026-02-14, la cobertura de rendiment inclou addicionalment:

performance::stress_concurrent_append_query_sqlite,
performance::performance_bundle_materialization_smoke,
sidecar_perf::sidecar_perf_smoke_generates_gate_report,
sidecar_capacity::sidecar_capacity_sweep_generates_report, with profile-matrix orchestration (scripts/ci/perf_matrix.py) and release gating (scripts/ci/perf_gate.py) against committed baseline policy files (system-tests/perf_baselines/*.json). El model de rendiment del sidecar es divideix en dues vies explícites:
regression lane (sidecar_perf): fixed deterministic workload for CI seguretat anti-regressió;
capacity lane (sidecar_capacity): release-only saturation sweep used to characterize max sustainable ingest throughput and enforce pinned-runner floors. The sidecar regression/capacity lanes are aligned with the current single-writer v1 contract: stream-scoped query requests include required tenant_id and recorder_id, and envelope writes include canonical stream identity fields. As of 2026-02-14 (perf architecture split), both lanes emit explicit workload.* metadata and lane identity (regression/capacity) in artifacts; capacity reports additionally emit max_sustainable_rps, knee_rps, and error/latency-at-knee fields. As of 2026-02-15, benchmark orchestration is standardized through scripts/perf/run.py presets (smoke, regression, capacity) with schema-v2 normalized report emission under target/perf/v2/*.json, triage output under target/perf/triage/latest.md, and capability-aware gate evaluation via the same baseline policy surface. As of the same date, core macro performance reports are emitted both at legacy target/performance/latest.json and per-suite paths target/performance/stress/latest.json, target/performance/bundle/latest.json to prevent suite overwrite ambiguity. As of the same date (Phase 3 expansion), the sidecar regression lane executes multi-trial timed windows and emits percentile confidence-spread metadata, the core performance suite emits query-cardinality and SQLite durability sweeps plus bundle scale-curve and deterministic replay hash-equality metrics, and the capacity lane emits explicit authoritative vs non-authoritative gate labeling. As of 2026-02-16, sidecar regression memory metrics are split into hot-path high-water (rss_growth_bytes) and quiesced retained-growth (rss_growth_quiesced_bytes) signals, with rss_reclaim_ratio emitted for allocator high-water context. As of 2026-02-16, sidecar durability characterization coverage includes post-saturation graceful-stop restart timing (restart_ready_ms) and restart-correctness hardening for rolled parallel load paths; integration coverage now explicitly guards against multi-open-segment persistence across restart boundaries. As of the same date, durability measurement strictness captures live wal_size_bytes plus coupled PRAGMA wal_checkpoint(NOOP) state per case and emits durability_wal_ratio_vs_1000_comparable so WAL-ratio decisions can fail-closed when baseline WAL sampling is non-comparable. As of the same date, sidecar perf coverage also includes an informational retained-memory attribution lane (sidecar_perf_rss_retained_memory_attribution_characterization, ignored by default due runtime) that emits target/sidecar-perf/rss_attribution_latest.json with sequential/parallel quiesce-window RSS checkpoints and smaps_rollup class deltas. As of the same date, sidecar perf coverage also includes an ignored ingest- tuning characterization lane (sidecar_perf_rss_ingest_tuning_characterization) that sweeps ingest queue and batch knobs across sequential/parallel workers, emits target/sidecar-perf/rss_ingest_tuning_latest.json, and records a data-derived mechanism classification (queue_backlog_dominated, batch_churn_dominated, o mixed) més metadades de recomanació de mitigació.

Artifact i Contracte de Transcripció

Cada execució de prova emet com a mínim:

summary.json,
summary.md,
tool_transcript.json.

TestReporter i TestArtifacts creen arrels d’execució deterministes, imposen una política de reutilització d’arrels d’execució i produeixen documents de resum estàndard. CliSession ara resol recorder tant a través del perfil directe com dels dissenys binaris deps i prefereix la resolució de target/debug de l’espai de treball abans de la recuperació de la construcció, la qual cosa manté l’execució de comandes a la pista d’operació determinista a través dels dissenys de processos cargo test i cargo nextest a Windows i Unix.

F:system-tests/tests/helpers/artifacts.rs L65-L131 F:system-tests/tests/helpers/artifacts.rs L133-L214 F:system-tests/tests/helpers/cli.rs L19-L107 F:system-tests/tests/helpers/cli.rs L109-L240

Eina d’Execució

Python helpers:

test_runner.py: registry-based execution with optional parallelism, test_runner.py: execució basada en registre amb paral·lelisme opcional, arrels d’artifacts per a cada prova i generació de manifest.
coverage_report.py: genera documents a partir del registre + buits.
gap_tracker.py: llista/mostra/tanca buits i genera indicacions d’implementació.

CI també aplica portes de cobertura a nivell de codi font a través de scripts/ci/coverage_gate.sh, que executa cargo llvm-cov --workspace --all-features --all-targets --summary-only i falla tancat quan la cobertura de línies del workspace o del sidecar cau per sota dels llindars de política, o quan els fitxers de controlador/middlewar/server del sidecar cauen per sota d’un mínim de línies per fitxer. La porta s’executa tant en els fluxos de treball de PR com en els principals després de les pistes de prova.

F:scripts/system_tests/test_runner.py L64-L112 F:scripts/system_tests/test_runner.py L119-L199 F:scripts/system_tests/coverage_report.py L43-L101 F:scripts/system_tests/gap_tracker.py L92-L140 F:scripts/ci/coverage_gate.sh F:.github/workflows/ci_pr.yml F:.github/workflows/ci_main.yml

Estructura de la Suite

Els mòduls de la suite cobreixen:

smoke: inici del CLI i comprovacions d’ajuda/version,
bundle: construcció/verificació/inspecció i detecció d’alteracions,
persistència: reinici, determinisme i comprovacions de paritat SQLite/en memòria,
operations: query ordering/cursor plus JSON pagination/limit guardrails and recorder-id + auto-seal config validation parity checks, plus typed comprovacions de projecció del SDK de generació de contractes,
security: bounded CLI input surfaces, malformed-identifier rejection, secure signer-file policy, signer-rotation recovery/corruption behavior, contract path safety, hostile bundle parse-boundary checks, and hostile record-with-attachments boundary checks, plus SQLite operation queue comportament de fallada tancada per saturació amb artefactes de resum deterministes,
recorder: lifecycle plus auto-seal count/duration/combined behavior and recorder: comptatge/duració del cicle de vida més auto-segellament/comportament combinat i comprovacions de persistència de gravació d’adjunts sobre el límit real de la CLI,
sidecar: real sidecar process lifecycle over HTTP (record/query/build/verify) and restart-boundary idempotency comprovacions de persistència de conflictes de reproducció,
sidecar_perf: deterministic regression-lane sidecar perf artifact emission per a la validació de CI,
sidecar_capacity: release-only capacity-lane sidecar saturation sweep for caracterització/gatellatge del rendiment del corredor fixat,
sidecar_docker: Dockerfile/Compose/config hardening checks and Docker Compose build/up/down with containerized sidecar startup/readiness probe checks plus record/query workflow, including secret-source + tmpfs token bootstrap paritat,
integration_openclaw: fixture-driven OpenClaw gateway/CLI ingest, signed/unsigned verification lanes, sequence-gap policy checks, sensitive integration_openclaw: ingesta de gateway/CLI OpenClaw basada en fixtures, carrils de verificació signats/no signats, comprovacions de política de buits de seqüència, redacció de camps sensibles i comprovacions de gestió de càrregues limitades.
integration_decision_gate: fixture-driven Decision Gate MCP runpack flow ingest through the production recorder-decision-gate-adapter crate, signed/unsigned verification lanes, runpack-integrity strict-vs-anomaly policy checks (including manifest self-integrity recomputation), sensitive transcript-field redaction, bounded transcript payload handling checks, CLI decision-gate ingest-fixture command-path validation, and a fixture conformance gate that enforces canonical Decision Gate tool request/response shapes (including export-vs-verify checked_files semàntica).

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Contracte i estàndards	`system-tests/AGENTS.md`	Requisits de comportament i artefacte per a les proves del sistema.
Visió general de l’execució	`system-tests/README.md`	Com executar i ampliar suites.
Instantània de cobertura	`system-tests/TEST_MATRIX.md`	Matriu P0/P1/P2.
Registre de proves	`system-tests/test_registry.toml`	Inventari autoritzat i ordres d’execució.
Dades del rastrejador de buits	`system-tests/test_gaps.toml`	Buits de cobertura i criteris d’acceptació.
Ajuda d’artefactes	`system-tests/tests/helpers/artifacts.rs`	Contracte de generació de resum i arrel d’execució.
Ajuda de CLI	`system-tests/tests/helpers/cli.rs`	Execució real de comandes CLI i captura de transcripcions.
Ajuda de sidecar	`system-tests/tests/helpers/sidecar.rs`	Inici/parada real del procés sidecar i captura de transcripcions HTTP.
Ajuda de rendiment de sidecar	`system-tests/tests/helpers/perf_sidecar.rs`	Client compartit de manteniment, generació de càrrega útil determinista i utilitats de metadades/informes de carrils per a suites de rendiment de sidecar.
Ajuda de Docker	`system-tests/tests/helpers/docker.rs`	Probes del daemon/compose de Docker i helpers de comandes per a carrils contenitzats.
Suite de sidecar	`system-tests/tests/suites/sidecar.rs`	Cicle de vida HTTP de sidecar (registre/consulta/construcció/verificació) i validació d’idempotència de reinici.
Suites de rendiment de sidecar	`system-tests/tests/suites/sidecar_perf.rs`, `system-tests/tests/suites/sidecar_capacity.rs`	Generació d’artefactes de carril de regressió i carril de capacitat per a la política de rendiment d’ingestió de sidecar, més carril d’atribució de memòria retinguda ignorada (`target/sidecar-perf/rss_attribution_latest.json`) i carril de caracterització d’ajustament d’ingestió (`target/sidecar-perf/rss_ingest_tuning_latest.json`).
Orquestració de rendiment	`scripts/perf/run.py`, `scripts/perf/report_schema_v2.json`, `scripts/perf/collect_runner_fingerprint.py`, `scripts/perf/update_baseline.py`	Punt d’entrada de preset canònic, contracte d’informe schema-v2, captura de petjada del corredor i flux de treball de refresc de línia base governat.
Ajuda de perfilatge de rendiment	`scripts/perf/profile_hotspot.sh`	Flux de treball ràpid de suite de fallades a perfilador per a triatge de punts calents.
Suite de Docker de sidecar	`system-tests/tests/suites/sidecar_docker.rs`	Enduriment d’embalatge de contenidors de sidecar i validació del flux de treball de Docker Compose, incloent probes d’inici/preparació i comportament de bootstrap de token tmpfs de font secreta.
Suite d’integració d’OpenClaw	`system-tests/tests/suites/integration_openclaw.rs`, `system-tests/tests/suites/integration_openclaw_support.rs`, `system-tests/tests/suites/integration_openclaw_core.rs`, `system-tests/tests/suites/integration_openclaw_additional.rs`	Validació d’ingestió d’adaptador impulsada per fixtures per a fluxos simulats de gateway + CLI.
Fixtures d’OpenClaw	`system-tests/tests/fixtures/openclaw_gateway_mock_events.json`	Fixture d’esdeveniments de flux simulat de gateway alineada amb l’esquema d’esdeveniments d’OpenClaw.
Fixtures d’OpenClaw	`system-tests/tests/fixtures/openclaw_cli_mock_events.json`	Fixture d’esdeveniments de flux de tipus fallback de CLI alineada amb l’esquema d’esdeveniments d’OpenClaw.
Arquitectura d’integració d’OpenClaw	Docs/architecture/recorder_openclaw_integration_architecture.md	Mapeig versionat, redacció i contracte de política de càrrega útil limitada.
Adaptador de producció de Decision Gate	`crates/recorder-decision-gate-adapter/src/adapter.rs`	Implementació de mapeig canònic de Decision Gate a Recorder exercitada per proves del sistema.
Suite d’integració de Decision Gate	`system-tests/tests/suites/integration_decision_gate.rs`, `system-tests/tests/suites/integration_decision_gate_support.rs`, `system-tests/tests/suites/integration_decision_gate_contract_shape.rs`, `system-tests/tests/suites/integration_decision_gate_ingest.rs`	Validació de flux de runpack MCP impulsada per fixtures per al acoblament del pla de control.
Fixture de Decision Gate	`system-tests/tests/fixtures/decision_gate_runpack_mock_flow.json`	Fixture de flux simulat de runpack MCP alineada amb la transcripció de Decision Gate i el disseny del manifest de runpack.
Arquitectura d’integració de Decision Gate	Docs/architecture/recorder_decision_gate_integration_architecture.md	Mapeig de flux MCP versionat, política d’integritat de runpack i contracte de redacció/límits de transcripció.
Anàlisi d’entorn	`system-tests/src/config/env.rs`	Anàlisi d’entorn estricta per a la configuració de proves.
Script de corredor	`scripts/system_tests/test_runner.py`	Motor d’execució impulsat per registre.
Generador de docs de cobertura	`scripts/system_tests/coverage_report.py`	Canalització de docs de proves generades.
Script de gestió de buits	`scripts/system_tests/gap_tracker.py`	Eines del cicle de vida de buits.