Arquitectura de Prueba y Validación del Sistema de Grabación

Audience: Engineers maintaining release confidence, deterministic Audiencia: Ingenieros que mantienen la confianza en las versiones, validación determinista y artefactos de prueba listos para auditoría.

Tabla de Contenidos

Resumen Ejecutivo
Contrato de Prueba del Sistema
Inventario Impulsado por Registro
Matriz de Cobertura y Modelo de Brecha
Contrato de Artefacto y Transcripción
Herramientas de Ejecución
Estructura de la Suite
Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

El sistema de pruebas de grabación valida el comportamiento a través de límites de producción reales (CLI y ingestión de adaptadores), emite artefactos estructurados y rastrea la cobertura utilizando archivos TOML de registro + brechas. El arnés está diseñado para mantener las ejecuciones determinísticas e inspeccionables.

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

Contrato de Prueba del Sistema

Las pruebas del sistema requieren:

afirmaciones de fallo cerrado,
no hay corrección basada en el sueño,
comando de producción y superficies de datos,
emisión de artefactos por prueba obligatoria.

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

La activación de funciones mantiene las pruebas del sistema explícitas en CI y ejecuciones locales. F:system-tests/README.md L34-L45

Inventario Impulsado por Registro

system-tests/test_registry.toml es autoritativo para:

categorías,
metadatos por prueba,
puntos de entrada de comandos,
artefactos requeridos,
tiempo de ejecución estimado.

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

Matriz de Cobertura y Modelo de Brecha

system-tests/TEST_MATRIX.md define instantáneas de cobertura de objetivos P0/P1/P2. F:system-tests/TEST_MATRIX.md L12-L42

system-tests/test_gaps.toml rastrea las brechas abiertas/cerradas con criterios de aceptación explícitos y mapeo de categoría/prioridad. F:system-tests/test_gaps.toml L4-L74 F:system-tests/test_gaps.toml L75-L190

A partir del 2026-02-07, todas las brechas de núcleo P1 rastreadas están cerradas (deduplicación de selector compuesto, anclajes de prueba de segmento parcial, fallo cerrado por desajuste entre segmentos, fallo cerrado por cierre de adjuntos, paridad de SQLite/en memoria). A partir del 2026-02-14, la cobertura de estrés/performance P2 también está cerrada con artefactos de rendimiento de núcleo y sidecar deterministas y control de CI de matriz de perfil. A partir de la misma fecha, los hallazgos de seguridad de OSS Launch 0 están controlados por pruebas de sistema para límites/políticas de frontera CLI, rutas de manipulación estructural de manifiesto, materialización de corrupción de SQLite y aplicación de segmento único abierto. A partir de la misma fecha, el ciclo de vida HTTP de sidecar y la persistencia de idempotencia de reinicio están controlados por pruebas de sistema con flujos de trabajo reales de subproceso de sidecar + transporte TCP. A partir del 2026-02-08, el seguimiento de expansión de clase mundial de CLI OSS está completamente reflejado en pruebas de sistema: validación de forma de recorder-id, comprobaciones de fallo cerrado de entrada hostil de grabación de adjuntos, duración de auto-sellado/carriles de ciclo de vida combinados, paginación JSON de consulta + barandillas de sobre-límite, y rutas de comando de fallo/éxito estricto de ingest-fixture de Decision Gate CLI. A partir del 2026-02-08, el empaquetado de contenedores de sidecar también está controlado por pruebas de sistema a través de la suite sidecar_docker (comprobaciones de endurecimiento de activos + carril e2e de Docker Compose con política de salto/fallo explícita a través de RECORDER_REQUIRE_DOCKER). A partir del 2026-02-08, el carril de Docker Compose valida adicionalmente el comportamiento de sondeo de inicio/preparación de contenedores (/startup, /ready) antes y después de las transiciones de ciclo de vida de apertura de segmento. A partir del 2026-02-13, el carril de Docker Compose valida el endurecimiento del arranque secreto: el material de origen del token se proporciona a través de la entrada secreta de Docker, luego se materializa en una ruta de archivo de token tmpfs dentro del contenedor antes del inicio del sidecar. A partir del 2026-02-10, la cobertura de operaciones incluye un carril de generación de contratos que afirma artefactos de proyección tipada de SDK/OpenAPI (sdk/types.json, sdk/methods.json, componentes OpenAPI estrictos Bundle/VerificationVerdict) para la preparación del generador de SDK aguas abajo. A partir del 2026-02-11, la suite de operaciones está dividida por módulos (operations/{query,config,locale,contract}.rs) para mantener los archivos de prueba limitados y revisables mientras se preserva el comportamiento determinista de artefactos/informes. A partir del 2026-02-11, las suites de seguridad e integración también están divididas por archivos (security_{support,limits,signer,contract_bundle}.rs, integration_openclaw_{support,core,additional}.rs, integration_decision_gate_{support,contract_shape,ingest}.rs) para mantener las superficies de prueba revisables mientras se preserva el comportamiento determinista y los metadatos de ejecución. A partir de la misma fecha, la cobertura de seguridad incluye la validación de fallo cerrado por saturación de cola de operaciones de SQLite con artefactos de resumen de saturación determinista (sqlite_operation_queue_saturation_fails_closed). A partir del 2026-02-14, la cobertura de rendimiento incluye adicionalmente:

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 modelo de rendimiento de sidecar se divide en dos carriles explícitos:
regression lane (sidecar_perf): fixed deterministic workload for CI seguridad anti-regresión;
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 metadatos de recomendación de mitigación.

Contrato de Artefacto y Transcripción

Cada ejecución de prueba emite como mínimo:

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

TestReporter y TestArtifacts crean raíces de ejecución deterministas, imponen la política de reutilización de raíces de ejecución y producen documentos de resumen estandarizados. CliSession ahora resuelve recorder tanto en el perfil directo como en los diseños binarios de deps y prefiere la resolución de target/debug del espacio de trabajo antes de la recuperación de la construcción, lo que mantiene la ejecución de comandos en la línea de operación determinista entre los diseños de procesos de cargo test y cargo nextest en Windows y 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

Herramientas de Ejecución

Ayudantes de Python:

test_runner.py: registry-based execution with optional parallelism, test_runner.py: ejecución basada en registro con paralelismo opcional, raíces de artefactos por prueba y generación de manifiestos.
coverage_report.py: genera documentación a partir del registro + brechas.
gap_tracker.py: lista/muestra/cierra brechas y genera indicaciones de implementación.

CI también aplica puertas de cobertura a nivel de código fuente a través de scripts/ci/coverage_gate.sh, que ejecuta cargo llvm-cov --workspace --all-features --all-targets --summary-only y falla cerrada cuando la cobertura de líneas del espacio de trabajo o del sidecar cae por debajo de los umbrales de política, o cuando los archivos de manejador/middleware/servidor del sidecar caen por debajo de un mínimo de líneas por archivo. La puerta se ejecuta tanto en PR como en los flujos de trabajo principales después de las pruebas.

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

Los módulos de la suite cubren:

smoke: inicio de CLI y comprobaciones de ayuda/versiones,
bundle: construcción/verificación/inspección y detección de manipulaciones,
persistencia: reinicio, determinismo y comprobaciones de paridad de SQLite/en memoria,
operations: query ordering/cursor plus JSON pagination/limit guardrails and recorder-id + auto-seal config validation parity checks, plus typed verificaciones de proyección del SDK de generación de contratos,
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 comportamiento de fallo cerrado por saturación con artefactos de resumen deterministas,
recorder: lifecycle plus auto-seal count/duration/combined behavior and recorder: ciclo de vida más conteo/duración de auto-sellado/comportamiento combinado y comprobaciones de persistencia de grabación de adjuntos sobre el límite real de la CLI,
sidecar: real sidecar process lifecycle over HTTP (record/query/build/verify) and restart-boundary idempotency verificación de persistencia de conflictos de repetición,
sidecar_perf: deterministic regression-lane sidecar perf artifact emission para la validación de CI,
sidecar_capacity: release-only capacity-lane sidecar saturation sweep for caracterización/gateo del rendimiento del corredor anclado,
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 paridad de bootstrap,
integration_openclaw: fixture-driven OpenClaw gateway/CLI ingest, signed/unsigned verification lanes, sequence-gap policy checks, sensitive integration_openclaw: ingestión de gateway/CLI OpenClaw impulsada por fixtures, carriles de verificación firmados/no firmados, comprobaciones de política de brechas de secuencia, redacción de campos sensibles y comprobaciones de manejo de cargas útiles limitadas.
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).

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Contrato y estándares	`system-tests/AGENTS.md`	Requisitos de comportamiento y artefactos para pruebas del sistema.
Resumen de ejecución	`system-tests/README.md`	Cómo ejecutar y extender suites.
Instantánea de cobertura	`system-tests/TEST_MATRIX.md`	Matriz P0/P1/P2.
Registro de pruebas	`system-tests/test_registry.toml`	Inventario autoritativo y comandos de ejecución.
Datos de seguimiento de brechas	`system-tests/test_gaps.toml`	Brechas de cobertura y criterios de aceptación.
Ayudante de artefactos	`system-tests/tests/helpers/artifacts.rs`	Contrato de generación de resumen y raíz de ejecución.
Ayudante de CLI	`system-tests/tests/helpers/cli.rs`	Ejecución real de comandos de CLI y captura de transcripciones.
Ayudante de sidecar	`system-tests/tests/helpers/sidecar.rs`	Inicio/parada de procesos sidecar reales y captura de transcripciones HTTP.
Ayudante de rendimiento de sidecar	`system-tests/tests/helpers/perf_sidecar.rs`	Cliente compartido de keep-alive, generación de carga útil determinista y utilidades de metadatos/informes de carriles para suites de rendimiento de sidecar.
Ayudante de Docker	`system-tests/tests/helpers/docker.rs`	Sondeos de daemon/compose de Docker y ayudantes de comandos para carriles en contenedores.
Suite de sidecar	`system-tests/tests/suites/sidecar.rs`	Ciclo de vida HTTP de sidecar (grabar/consultar/construir/verificar) y validación de idempotencia de reinicio.
Suites de rendimiento de sidecar	`system-tests/tests/suites/sidecar_perf.rs`, `system-tests/tests/suites/sidecar_capacity.rs`	Generación de artefactos de carriles de regresión y capacidad para la política de rendimiento de ingestión de sidecar, además de carriles de atribución de memoria retenida ignorados (`target/sidecar-perf/rss_attribution_latest.json`) y carriles de caracterización de ajuste de ingestión (`target/sidecar-perf/rss_ingest_tuning_latest.json`).
Orquestación de rendimiento	`scripts/perf/run.py`, `scripts/perf/report_schema_v2.json`, `scripts/perf/collect_runner_fingerprint.py`, `scripts/perf/update_baseline.py`	Punto de entrada de preset canónico, contrato de informe schema-v2, captura de huella dactilar del ejecutor y flujo de trabajo de actualización de línea base regulada.
Ayudante de perfilado de rendimiento	`scripts/perf/profile_hotspot.sh`	Flujo de trabajo rápido de suite de fallos a perfilador para triaje de hotspots.
Suite de Docker de sidecar	`system-tests/tests/suites/sidecar_docker.rs`	Endurecimiento del empaquetado de contenedores de sidecar y validación del flujo de trabajo de Docker Compose, incluyendo sondeos de inicio/listo y comportamiento de arranque de token tmpfs de fuente secreta.
Suite de integración de 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ón de ingestión de adaptador impulsada por fixtures para flujos de gateway + CLI simulados.
Fixtures de OpenClaw	`system-tests/tests/fixtures/openclaw_gateway_mock_events.json`	Fixture de evento de flujo simulado de gateway alineado con el esquema de eventos de OpenClaw.
Fixtures de OpenClaw	`system-tests/tests/fixtures/openclaw_cli_mock_events.json`	Fixture de evento de flujo estilo fallback de CLI alineado con el esquema de eventos de OpenClaw.
Arquitectura de integración de OpenClaw	Docs/architecture/recorder_openclaw_integration_architecture.md	Mapeo versionado, redacción y contrato de política de carga útil acotada.
Adaptador de producción de Decision Gate	`crates/recorder-decision-gate-adapter/src/adapter.rs`	Implementación canónica de mapeo de Decision Gate a Recorder ejercida por pruebas del sistema.
Suite de integración 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ón de flujo de runpack de MCP impulsada por fixtures para acoplamiento de plano de control.
Fixture de Decision Gate	`system-tests/tests/fixtures/decision_gate_runpack_mock_flow.json`	Fixture de flujo simulado de runpack de MCP alineado con la transcripción de Decision Gate y el diseño del manifiesto de runpack.
Arquitectura de integración de Decision Gate	Docs/architecture/recorder_decision_gate_integration_architecture.md	Mapeo de flujo de MCP versionado, política de integridad de runpack y contrato de redacción/acotación de transcripciones.
Análisis de entorno	`system-tests/src/config/env.rs`	Análisis estricto del entorno para la configuración de pruebas.
Script de ejecutor	`scripts/system_tests/test_runner.py`	Motor de ejecución impulsado por registro.
Generador de documentos de cobertura	`scripts/system_tests/coverage_report.py`	Canal de documentos de pruebas generados.
Script de gestión de brechas	`scripts/system_tests/gap_tracker.py`	Herramientas para el ciclo de vida de brechas.