Grabadora Puerta de Decisión Asset Core
Docs
Documentos del Grabador

Documentación de grabación de pruebas y evidencia a prueba de manipulaciones.

Otros documentos del producto

Arquitectura del Sistema de Grabación

Audience: Engineers working across Recorder crates or integrating Recorder with sistemas de plano de control como Decision Gate.

Tabla de Contenidos

  1. Resumen Ejecutivo
  2. Arquitectura en Capas
  3. Flujo de Datos de Extremo a Extremo
  4. Límites de Confianza y Postura de Seguridad
  5. Modelo de Determinismo
  6. Alcance de Implementación Actual
  7. Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

Recorder es un plano de datos para la grabación de evidencia determinista. Captura eventos no sellados en los límites de los adaptadores, los sella en sobres encadenados por hash, los persiste en historiales de segmentos de solo anexado y exporta paquetes portátiles para verificación offline.

El sistema está organizado como un espacio de trabajo de Rust con límites estrictos de crate: contratos centrales, modelo de sobre, orquestación de grabadores, backends de almacenamiento, una fachada ergonómica de SDK de Rust, un SDK de sidecar de Python generado por primera parte, semánticas de configuración de sidecar canónicas, operaciones de CLI y un servicio HTTP de sidecar en tiempo de ejecución. F:Cargo.toml L9-L26

Arquitectura en Capas

  1. Core contracts (recorder-core)
  2. Evidence model (recorder-envelope)
  3. Integration adapters (recorder-decision-gate-adapter, recorder-otel-adapter)
  4. Recording runtime (recorder)
  5. Persistence (recorder-store)
  6. Sidecar config authority (recorder-sidecar-config)
  7. Rust SDK facade (recorder-sdk)
  8. Generated sidecar SDK (recorder-client for Python)
  9. Operational surface (recorder-cli)
  10. Superficie del servicio de red (recorder-sidecar)
  1. Generación de contratos de proyección (recorder-contract)

Flujo de Datos de Extremo a Extremo

Adapter / CLI input
    -> Sidecar mutating route validation (tenant_id + recorder_id + idempotency key)
    -> IngestGateway bounded queue admission
    -> IngestWriterRuntime writer-native sealing + single-tx micro-batch commit
    -> Stream/global commit index assignment + idempotency + projection update
    -> BundleBuilder resolves selector + attachment closure + manifest
    -> Verifier runs 7 phases offline
    -> EvidenceProvider serves bundles/envelope queries to control-plane bridge

Puntos de entrada clave del flujo:

Límites de Confianza y Postura de Seguridad

Modelo de Determinismo

El determinismo se logra combinando:

  • codificación JCS canónica para datos hashables,
  • estructuras de ordenamiento deterministas (BTreeMap, vectores ordenados),
  • lógica de hash estable y de selector,
  • verificación reproducible sin conexión.

F:crates/recorder-envelope/src/encoding.rs L13-L31 F:crates/recorder/src/bundle_builder.rs L27-L30 F:crates/recorder/src/bundle_builder.rs L466-L477

Alcance de Implementación Actual

Implementado ahora:

  • Ciclo de vida completo de grabación local y verificación de paquetes.
  • Backend de almacenamiento SQLite/en memoria.
  • recorder-sdk single-crate facade for Rust consumers, including deterministic valores predeterminados del constructor y accesores directos de adaptador/proveedor/almacen.
  • recorder-client Python SDK with generated contract constants, typed sync/async clientes sidecar y pruebas de unidad/sistema.
  • Operaciones impulsadas por CLI y salida localizada.
  • CLI attachment-aware recording (record-with-attachments) with bounded file Grabación consciente de archivos adjuntos en CLI (record-with-attachments) con entradas de archivo limitado y adjuntos en línea.
  • CLI Decision Gate fixture ingest command path wired to production adapter Ruta del comando de ingestión del accesorio de la puerta de decisión de CLI conectada a la implementación del adaptador de producción.
  • CLI OTel fixture ingest command path wired to production adapter implementación.
  • System-test harness with registry-driven coverage, including OpenClaw gateway/CLI mock-flow and Decision Gate runpack-flow adapter-ingest pruebas de integración.
  • CLI expansion system-tests for recorder-id shape validation parity, attachment-recording fail-closed boundaries, auto-seal duration/combined lifecycle behavior, query JSON pagination/limit guardrails, and Decision Gate Rutas de éxito/fallo estricto de ingest-fixture en la CLI.
  • Production Decision Gate adapter crate (crates/recorder-decision-gate-adapter) with deterministic MCP/runpack mapping, runpack-integrity strict/anomaly policy handling, and transcript controles de límites de redacción.
  • Production OTel adapter crate (crates/recorder-otel-adapter) with deterministic span/log mapping, strict identifier/time parsing, and bounded/redacted controles de carga útil.
  • OpenClaw integration harness mapping policy with deterministic sensitive-field Política de mapeo del arnés de integración de OpenClaw con redacción determinista de campos sensibles y manejo de carga útil acotada para pruebas de acoplamiento impulsadas por fixture.
  • Decision Gate integration system-tests wired to the production adapter crate, covering signed/unsigned lanes, root-hash and manifest-integrity mismatch Sistema de pruebas de integración de Decision Gate conectado a la caja del adaptador de producción, cubriendo comportamientos de fallo cerrado por desajuste de carriles firmados/no firmados, raíz-hash y manifiesto-integridad.
  • Sidecar Docker operator profile (docker/sidecar) and system-test coverage for Dockerfile/Compose hardening plus containerized probe/record/query flujo.
  • Sidecar readiness semantics now support fail-closed dependency modes: La semántica de disponibilidad del sidecar ahora admite modos de dependencia que fallan en cerrado: disponibilidad solo de almacenamiento y disponibilidad de almacenamiento + control empresarial.

Postura actual de rendimiento/estrés:

  • P2 stress/performance system-test expansion is now implemented with deterministic artifact-first lanes: performance::stress_concurrent_append_query_sqlite, performance::performance_bundle_materialization_smoke, and sidecar_perf::sidecar_perf_smoke_generates_gate_report (regression lane), plus sidecar_capacity::sidecar_capacity_sweep_generates_report (carril de capacidad).
  • CI now runs a profile matrix (test informational + release gated) on the pinned perf runner via scripts/ci/perf_matrix.py and enforces release thresholds/regression policy via scripts/ci/perf_gate.py and system-tests/perf_baselines/linux_x86_64_ci.json.
  • Sidecar ingest 10k target is defined only on the capacity lane metric max_sustainable_rps and is enforced only for pinned runner policy class (linux_x86_64_pinned); the regression lane remains a deterministic fixed señal anti-regresión de carga de trabajo.
  • Sidecar perf throughput/latency lanes now run against persistent keep-alive HTTP client pools to avoid connection-churn distortion in write-path mediciones.
  • Bundle-path metric bundle_build_envelopes_per_sec remains a separate core métrica de materialización de paquete y no es un proxy de capacidad de ingestión.

Elementos de endurecimiento a nivel de sistema recientemente cerrados:

Referencia Cruzada Archivo por Archivo

ÁreaArchivoNotas
Límites del espacio de trabajoCargo.tomlMembresía del crate y postura de lint.
Contratos centralescrates/recorder-core/src/lib.rsPrimitivas y rasgos de dominio compartidos.
Modelo de sobrecrates/recorder-envelope/src/lib.rsModelo de datos de evidencia y contratos.
Tiempo de ejecución del grabadorcrates/recorder/src/engine.rsIngesta, progresión de la cadena, ciclo de vida del segmento.
Fachada del SDK de Rustcrates/recorder-sdk/src/lib.rs, crates/recorder-sdk/src/builder.rsConstructor ergonómico y fachada unificada de grabador/proveedor para consumidores de Rust.
Fachada del SDK de Pythonsdk/python/src/recorder_client/client.py, sdk/python/src/recorder_client/client_common.py, sdk/python/src/recorder_client/sync_client.py, sdk/python/src/recorder_client/async_client.py, sdk/python/src/recorder_client/models.py, sdk/python/src/recorder_client/errors.pySuperficie de cliente sidecar síncrono/asíncrono impulsada por contratos generados con validación estricta de cierre en fallo y mapeo de errores tipados.
Paquete + verificadorcrates/recorder/src/bundle_builder.rsResolución de selectores y materialización de paquetes.
Verificación de paquetescrates/recorder/src/verifier.rsVerificación fuera de línea en 7 fases.
Rasgos de almacenamientocrates/recorder-store/src/traits.rsInvariantes del contrato de persistencia.
Límite de cola de SQLitecrates/recorder-store/src/sqlite/connection.rsComportamiento de despacho asíncrono a síncrono limitado y cierre en fallo de saturación.
Superficie de CLIcrates/recorder-cli/src/main.rs, crates/recorder-cli/src/commands.rs, crates/recorder-cli/src/support.rsArquitectura de comando operativo dividida en despacho, controladores de comandos y ayudantes de tiempo de ejecución/utilidad.
Servicio sidecarcrates/recorder-sidecar/src/lib.rs, crates/recorder-sidecar/src/server.rsTiempo de ejecución HTTP, pila de middleware y ciclo de vida del transporte.
Configuración/seguridad del sidecarcrates/recorder-sidecar-config/src/config.rs, crates/recorder-sidecar-config/src/validation.rs, crates/recorder-sidecar/src/middleware/auth.rs, crates/recorder-sidecar/src/middleware/bounds.rs, crates/recorder-sidecar/src/ingest.rsValidación de configuración de cierre en fallo y autoridad de proyección más controles de autenticación/límites del sidecar y comportamiento de idempotencia de ingesta de un solo escritor.
Empaquetado de contenedor sidecardocker/sidecar/Dockerfile, docker/sidecar/docker-compose.yml, docker/sidecar/config/sidecar.toml, crates/recorder-sidecar/src/bin/docker_bootstrap.rsPerfil de construcción/tiempo de ejecución de contenedor de primera parte alineado con las invariantes de validación/seguridad del sidecar, incluyendo el arranque de token de fuente secreta en la ruta de tiempo de ejecución tmpfs endurecida.
Generador de contratoscrates/recorder-contract/src/lib.rs, crates/recorder-contract/src/sidecar_api.rs, crates/recorder-contract/src/sidecar_api/openapi.rs, crates/recorder-contract/src/sidecar_api/artifacts.rs, crates/recorder-contract/src/sidecar_api/specs/mod.rsAutoridad de artefacto generado determinista + comprobaciones de deriva.
Pruebas del sistemasystem-tests/README.mdContrato de validación de extremo a extremo.
Adaptador de Decision Gatecrates/recorder-decision-gate-adapter/src/adapter.rsImplementación de mapeo/redacción/política de integridad de producción para la ingesta de Decision Gate.
Adaptador OTelcrates/recorder-otel-adapter/src/adapter.rsImplementación de mapeo/redacción/política de límites de producción para la ingesta de JSON de OTel.
Pruebas de integración de OpenClawsystem-tests/tests/suites/integration_openclaw.rsVerificación de ingesta de adaptador impulsada por fixture para acoplamiento de flujo de trabajo externo.
Arquitectura de integración de OpenClawDocs/architecture/recorder_openclaw_integration_architecture.mdContrato de mapeo y redacción/política de carga útil limitada versionada.
Pruebas de integración de Decision Gatesystem-tests/tests/suites/integration_decision_gate.rsVerificación de ingesta de flujo de MCP impulsada por fixture para acoplamiento de plano de control.
Arquitectura de integración de Decision GateDocs/architecture/recorder_decision_gate_integration_architecture.mdMapeo de flujo de MCP versionado, política de integridad de runpack y contrato de redacción/límites de transcripción.
Arquitectura de integración de OTelDocs/architecture/recorder_otel_integration_architecture.mdContrato de mapeo de JSON de OTel versionado, IDs/eventos deterministas y cableado de ingesta de sidecar/CLI.