Gravadora Decision Gate Asset Core
Docs
Recorder Docs

Documentació de gravació de proves i evidències que mostren manipulació.

Altres documents de producte

Arquitectura del Sistema de Gravació

Audience: Engineers working across Recorder crates or integrating Recorder with sistemes de control-plane com Decision Gate.

Taula de continguts

  1. Visió Executiva
  2. Arquitectura en Capes
  3. Flux de dades de principi a fi
  4. Límits de confiança i postura de seguretat
  5. Model de Determinisme
  6. Abast d’implementació actual
  7. File per Fitxer Referència Creuada

Executive Overview

Recorder és un pla de dades per a l’enregistrament d’evidències deterministes. Captura esdeveniments no segellats als límits dels adaptadors, els segella en sobres en cadena de hash, els persisteix en històries de segments només d’append, i exporta paquets portàtils per a la verificació fora de línia.

El sistema està organitzat com un espai de treball Rust amb límits estrictes de crate: contractes bàsics, model d’envolupament, orquestració de gravadors, backend d’emmagatzematge, una façana SDK ergonòmica de Rust, un SDK de sidecar de Python generat per la primera part, semàntica de configuració de sidecar canònica, operacions CLI i un servei HTTP de sidecar en temps d’execució. F:Cargo.toml L9-L26

Arquitectura en capes

  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. Superfície del servei de xarxa (recorder-sidecar)
  1. Generació de contractes de projecció (recorder-contract)

Flux de dades de principi a fi

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

Punts d’entrada clau del flux:

Límits de confiança i postura de seguretat

Model de Determinisme

El determinisme s’aconsegueix combinant:

  • codificació JCS canònica per a dades hashables,
  • estructures d’ordenació deterministes (BTreeMap, vectors ordenats),
  • lògica de hash estable i de selector,
  • verificació offline reproduïble.

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

Abast de la Implementació Actual

Implementat ara:

  • Cicle de gravació local complet i verificació de paquets.
  • SQLite/emmagatzematge en memòria.
  • recorder-sdk single-crate facade for Rust consumers, including deterministic valors per defecte del constructor i accessors d’adaptador/proveïdor/emmagatzematge directes.
  • recorder-client Python SDK with generated contract constants, typed sync/async clients de sidecar, i proves d’unitat/sistema.
  • Operacions impulsades per CLI i sortida localitzada.
  • CLI attachment-aware recording (record-with-attachments) with bounded file Gravació conscient d’adjuncions de CLI (record-with-attachments) amb fitxers limitats i entrades d’adjuncions en línia.
  • CLI Decision Gate fixture ingest command path wired to production adapter Ruta de comandament d’ingestió del dispositiu de Decision Gate del CLI connectada a la implementació de l’adaptador de producció.
  • CLI OTel fixture ingest command path wired to production adapter implementació.
  • System-test harness with registry-driven coverage, including OpenClaw gateway/CLI mock-flow and Decision Gate runpack-flow adapter-ingest proves d’integració.
  • 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 CLI ingest-fixture èxit/fallida estricta rutes.
  • Production Decision Gate adapter crate (crates/recorder-decision-gate-adapter) with deterministic MCP/runpack mapping, runpack-integrity strict/anomaly policy handling, and transcript controls de redacció/límits.
  • Production OTel adapter crate (crates/recorder-otel-adapter) with deterministic span/log mapping, strict identifier/time parsing, and bounded/redacted controls de càrrega.
  • OpenClaw integration harness mapping policy with deterministic sensitive-field Política de mapeig de l’integració d’OpenClaw amb redacció de camps sensibles determinista i gestió de càrregues limitades per a proves de connexió basades en fixtures.
  • Decision Gate integration system-tests wired to the production adapter crate, covering signed/unsigned lanes, root-hash and manifest-integrity mismatch Sistema d’integració de Decision Gate amb proves de sistema connectades a la caixa d’adaptador de producció, cobrint comportaments de fallada tancada per discrepàncies en les pistes signades/no signades, el hash arrel i la integritat del manifest, així com la reproducció/hash determinista i l’estabilitat.
  • Sidecar Docker operator profile (docker/sidecar) and system-test coverage for Dockerfile/Compose hardening plus containerized probe/record/query flux.
  • Sidecar readiness semantics now support fail-closed dependency modes: La semàntica de preparació del Sidecar ara admet modes de dependència que fallen tancats: preparació només d’emmagatzematge i preparació d’emmagatzematge + control empresarial.

Postura actual de rendiment/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 capacitat).
  • 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 senyal anti-regressió de càrrega de treball.
  • Sidecar perf throughput/latency lanes now run against persistent keep-alive HTTP client pools to avoid connection-churn distortion in write-path mesures.
  • Bundle-path metric bundle_build_envelopes_per_sec remains a separate core mètrica de materialització de paquet i no és un proxy de capacitat d’ingesta.

Elements de reforç a nivell de sistema recentment tancats:

File per Fitxer Referència Creuada

ÀreaFitxerNotes
Límits de l’espai de treballCargo.tomlMembresia del crate i postura de lint.
Contractes bàsicscrates/recorder-core/src/lib.rsPrimitives i traits de domini compartit.
Model d’envelopacrates/recorder-envelope/src/lib.rsModel de dades d’evidència i contractes.
Temps d’execució del gravadorcrates/recorder/src/engine.rsIngesta, progressió de la cadena, cicle de vida del segment.
Façana del SDK de Rustcrates/recorder-sdk/src/lib.rs, crates/recorder-sdk/src/builder.rsConstructor ergonòmic i façana unificada de gravador/proveïdor per a consumidors de Rust.
Façana 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.pySuperfície de client sidecar síncron/asincrònica basada en contractes generats amb validació estricta de fallada tancada i mapeig d’errors tipats.
Paquet + verificadorcrates/recorder/src/bundle_builder.rsResolució de selectors i materialització de paquets.
Verificació de paquetscrates/recorder/src/verifier.rsVerificació fora de línia en 7 fases.
Traits d’emmagatzematgecrates/recorder-store/src/traits.rsInvariants del contracte de persistència.
Límits de la cua de SQLitecrates/recorder-store/src/sqlite/connection.rsComportament de dispatch async-a-sync limitat i fallada tancada per saturació.
Superfície CLIcrates/recorder-cli/src/main.rs, crates/recorder-cli/src/commands.rs, crates/recorder-cli/src/support.rsArquitectura de comandes operatives dividida entre dispatch, gestors de comandes i helpers d’execució/utilitat.
Servei sidecarcrates/recorder-sidecar/src/lib.rs, crates/recorder-sidecar/src/server.rsTemps d’execució HTTP, pila de middleware i cicle de vida del transport.
Configuració/seguretat 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ó de configuració de fallada tancada i autoritat de projecció més controls d’autenticació/límits del sidecar i comportament d’idempotència d’ingesta d’escriptura única.
Embalatge del contenidor sidecardocker/sidecar/Dockerfile, docker/sidecar/docker-compose.yml, docker/sidecar/config/sidecar.toml, crates/recorder-sidecar/src/bin/docker_bootstrap.rsPerfil de construcció/execució de contenidor de primera part alineat amb invariants de validació/seguretat del sidecar, incloent el bootstrap de token de font secreta en la ruta d’execució tmpfs endurida.
Generador de contractescrates/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.rsAutoritat d’artifacte generat determinista + verificacions de deriva.
Proves de sistemasystem-tests/README.mdContracte de validació de principi a fi.
Adaptador de Decision Gatecrates/recorder-decision-gate-adapter/src/adapter.rsImplementació de política de mapeig/redacció/integritat de producció per a la ingesta de Decision Gate.
Adaptador OTelcrates/recorder-otel-adapter/src/adapter.rsImplementació de política de mapeig/redacció/límits de producció per a la ingesta de JSON OTel.
Proves d’integració OpenClawsystem-tests/tests/suites/integration_openclaw.rsVerificació d’ingesta d’adaptador basada en fixtures per al acoblament de fluxos de treball externs.
Arquitectura d’integració OpenClawDocs/architecture/recorder_openclaw_integration_architecture.mdContracte de política de mapeig i redacció/càrrega limitada versionada.
Proves d’integració de Decision Gatesystem-tests/tests/suites/integration_decision_gate.rsVerificació d’ingesta de flux MCP basada en fixtures per al acoblament del pla de control.
Arquitectura d’integració de Decision GateDocs/architecture/recorder_decision_gate_integration_architecture.mdContracte de mapeig de flux MCP versionat, política d’integritat de runpack i redacció/límits de transcripció.
Arquitectura d’integració OTelDocs/architecture/recorder_otel_integration_architecture.mdContracte de mapeig de JSON OTel versionat, IDs/event types deterministes, i cablejat d’ingesta de sidecar/CLI.