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 de CLI de Grabadora y Flujos de Trabajo del Operador

Audience: Engineers extending CLI behavior and operators automating Recorder con salida de máquina.

Tabla de Contenidos

  1. Resumen Ejecutivo
  2. Superficie de Comando y Enrutamiento
  3. Modelo de Resolución en Tiempo de Ejecución
  4. Flujos de Trabajo Operativos
  5. Modelo de Salida y Localización
  6. Límites Duros de Entrada y Comportamiento de Cierre por Fallo
  7. Semántica del Código de Salida
  8. Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

recorder es el límite operativo para los flujos de trabajo locales de Recorder. Orquesta recorder y recorder-store con grupos de comandos explícitos y modo JSON determinista para la automatización.

F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/main_cli_types.rs F:crates/recorder-cli/src/commands.rs L19-L29 F:crates/recorder-cli/src/support.rs L19-L23

Superficie de Comando y Enrutamiento

Grupos de comandos de nivel superior:

  • recorder (operaciones de segmento + sobre)
  • recorder envelope record-with-attachments (ingestión consciente de adjuntos),
  • recorder signer (ciclo de vida de rotación de clave de firma explícita),
  • consulta (recuperación de sobre),
  • bundle (construir/verificar/inspeccionar),
  • config (verificaciones de configuración en tiempo de ejecución),
  • contrato (artefacto de contrato generado generar/verificar),
  • aseguramiento (profundidad de inicio, modo raíz de confianza y verificaciones de puerta OSS),
  • decision-gate (ingestión de fixture a través del adaptador de producción),
  • otel (ingesta de fixture de exportación JSON de OTel a través del adaptador de producción),
  • doctor (diagnósticos de almacenamiento y de segmento activo).

F:crates/recorder-cli/src/main_cli_types.rs

La arquitectura de despacho utiliza enrutadores de subcomandos explícitos en lugar de coincidencias de manejadores implícitas, con implementaciones de comandos divididas por área de flujo de trabajo. F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/commands.rs L19-L29

Modelo de Resolución en Tiempo de Ejecución

Los ajustes de tiempo de ejecución se resuelven con precedencia:

  1. flags de CLI,
  2. archivo de configuración opcional,
  3. valores predeterminados.

Importantes valores predeterminados:

  • store_path: recorder.db
  • recorder_id: recorder-cli
  • schema_version: esquema actual
  • auto_seal: ninguno a menos que se proporcione un conteo y/o duración explícitos
  • query.limit: predeterminado 1000, máximo 10000
  • security_profile: seguro

Modelo de tiempo de ejecución del firmante:

  • carga de firmante consciente del perfil (secure, standard, dev),
  • predeterminado seguro que requiere material de clave PKCS#8 cifrado,
  • opción explícita de optar por no recibir para texto plano/semilla de desarrollo en dev,
  • metadatos de rotación persistidos (store_meta) con verificaciones de consistencia.

F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/main_cli_types.rs F:crates/recorder-cli/src/support/runtime.rs L20-L122 F:crates/recorder-cli/src/support/runtime.rs L247-L556

Selección de backend de almacenamiento:

Flujos de Trabajo Operativos

Los flujos de trabajo representativos se mapean directamente a los controladores de comandos:

  • ciclo de vida del segmento de abrir/grabar/sellar/estado/lista,
  • registrar sobres con archivo adjunto y entradas en base64 en línea (record-with-attachments),
  • explicit key rotation (recorder signer rotate) with deterministic rotación de clave explícita (recorder signer rotate) con emisión de evidencia system.adapter.key_rotated determinista,
  • consultas de sobre envolvente filtradas con soporte de cursor,
  • construir el paquete a partir del JSON del selector, verificar (opcionalmente con la raíz de confianza) e inspeccionar,
  • generación/verificación de proyección de contrato (contract generate|check),
  • comprobaciones de implementación de garantía (assurance startup|trust-root|gates),
  • Ingesta de transcripción/fixture de runpack de Decision Gate a través del adaptador de producción.
  • Ingesta de fixture de exportación JSON de OTel a través del adaptador de producción.

F:crates/recorder-cli/src/commands/recorder.rs L20-L524 F:crates/recorder-cli/src/commands/query.rs L20-L88 F:crates/recorder-cli/src/commands/bundle.rs L20-L170 F:crates/recorder-cli/src/commands/admin.rs L20-L194

Las pruebas de integración cubren flujos de trabajo básicos y casos de fallo cerrado. F:crates/recorder-cli/tests/commands.rs F:crates/recorder-cli/tests/commands/core.rs F:crates/recorder-cli/tests/commands/query_and_rotation.rs F:crates/recorder-cli/tests/commands/attachments_and_dg.rs

Modelo de Salida y Localización

Modos de salida:

  • --json: cargas útiles estructuradas deterministas para automatización,
  • modo de texto: mensajería de operador localizada.

JSON-mode query contract ahora emite:

  • {"envelopes": [...], "next_cursor": ..., "applied_limit": ...}.

Las fallas en modo JSON emiten un sobre determinista:

  • {"error": "<mensaje>"}.

Resolución de locales:

  • --lang anula RECORDER_LANG,
  • supported locales are generated from catalog files under crates/recorder-cli/i18n/locales/*.toml,
  • los valores de localidad desconocidos fallan cerrados con una salida diferente de cero,
  • la configuración regional predeterminada permanece en solo cuando la configuración regional no está especificada.

Garantías de integridad de localización:

  • build-time catalog validation enforces locale-tag uniqueness, default-locale presence, exact key parity against en, and exact placeholder-set parity for cada clave en todos los locales,
  • message templates are generated into typed keys/macros and translation table código (OUT_DIR/i18n_generated.rs),
  • runtime translation paths are strict and fail closed on unknown keys, desajuste de conjunto de marcadores de posición, o marcadores de posición no resueltos,
  • no existe un retroceso silencioso a las ID de clave o al inglés para traducciones faltantes,
  • locale provenance metadata is mandatory (machine or human_reviewed) and las máquinas locales emiten un aviso de exención de responsabilidad en tiempo de ejecución explícito,
  • JSON output payload contracts remain locale-neutral and stable across locale selección.

La cobertura de locales incluye:

  • recorder binario principal,
  • recorder_oss_assurance_checks,
  • recorder_oss_assurance_packet.

F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/build.rs F:crates/recorder-cli/i18n/locales/en.toml F:crates/recorder-cli/i18n/locales/ca.toml F:crates/recorder-cli/src/i18n.rs F:crates/recorder-cli/src/support/util.rs F:crates/recorder-cli/src/bin/recorder_oss_assurance_checks.rs F:crates/recorder-cli/src/bin/recorder_oss_assurance_packet.rs F:crates/recorder-cli/tests/i18n_compile_fail.rs F:crates/recorder-cli/tests/commands/core.rs

Límites Duros de Entrada y Comportamiento de Cierre por Fallo

CLI impone lecturas de archivos limitadas:

  • config: 1 MiB,
  • payload JSON: 4 MiB,
  • archivo adjunto/payload en línea: 16 MiB,
  • JSON del dispositivo Decision Gate: 8 MiB,
  • JSON de accesorio OTel: 16 MiB,
  • selector JSON: 1 MiB,
  • paquete JSON: 32 MiB,
  • trust-root JSON: 1 MiB,
  • archivo de clave del firmante: 64 KiB,
  • material de frase de paso del firmante: 1 KiB.

F:crates/recorder-cli/src/main.rs

Las entradas sobredimensionadas son rechazadas antes de la análisis/procesamiento. F:crates/recorder-cli/src/support/util.rs L225-L277

bundle verify puede cargar una raíz de confianza explícita, dirigirla a Verifier::with_trust_root, y opcionalmente exportar un JSON de transcripción de verificador determinista a través de --verdict-transcript-output. F:crates/recorder/src/verification_transcript.rs F:crates/recorder-cli/src/commands/bundle.rs L74-L116

assurance grupo de comandos proporciona verificaciones explícitas de suposiciones OSS:

  • assurance startup executes runtime bootstrap and startup-verification path verificaciones con afirmaciones de profundidad mínima opcionales,
  • assurance trust-root valida las suposiciones de análisis/política/conjunto de claves de trust-root,
  • assurance gates executes contract check gate semantics directly. F:crates/recorder-cli/src/commands/assurance.rs

La cobertura de la prueba del sistema ahora valida:

Semántica del Código de Salida

  • Los errores de comando generales devuelven el código de salida 1 a través de emit_error.
  • JSON-mode command errors still return exit code 1 with machine-parseable Los errores de comando en modo JSON aún devuelven el código de salida 1 con la carga útil {"error": ...} que puede ser analizada por máquina.
  • bundle verify devuelve el código de salida 2 cuando el estado del veredicto es Inválido.

F:crates/recorder-cli/src/support/util.rs L343-L345 F:crates/recorder-cli/src/commands/bundle.rs L112-L114

Referencia Cruzada Archivo por Archivo

ÁreaArchivoNotas
Entrada y despacho de CLIcrates/recorder-cli/src/main.rs, crates/recorder-cli/src/main_cli_types.rsModelo Clap, flujo de localización/bootstrap, enrutamiento de despacho de nivel superior.
Manejadores de comandoscrates/recorder-cli/src/commands.rsAgrega módulos manejadores de grupos de comandos.
Manejadores de grabadoracrates/recorder-cli/src/commands/recorder.rsOperaciones de segmento/envuelto y lógica de rotación de firmantes.
Manejadores de consultas y paquetescrates/recorder-cli/src/commands/query.rs, crates/recorder-cli/src/commands/bundle.rsFiltros de consulta y flujos de trabajo de construcción/verificación/inspección de paquetes.
Manejadores de administracióncrates/recorder-cli/src/commands/admin.rsValidación de configuración, diagnósticos de doctor, comandos de contrato.
Manejadores de integracióncrates/recorder-cli/src/commands/integration.rsFlujos de trabajo de ingestión de Decision Gate y OTel fixture.
Ayudantes de tiempo de ejecución y utilidadescrates/recorder-cli/src/support.rs, crates/recorder-cli/src/support/runtime.rs, crates/recorder-cli/src/support/util.rsResolución en tiempo de ejecución, política de firmantes, análisis, E/S limitada, ayudantes de salida.
Catálogo y generación de i18ncrates/recorder-cli/build.rs, crates/recorder-cli/i18n/locales/en.toml, crates/recorder-cli/i18n/locales/ca.toml, crates/recorder-cli/src/i18n.rsCatálogos de localización validados en la construcción, claves/macros tipadas, metadatos de procedencia y renderizado estricto sin retroceso.
Binarios auxiliares de OSScrates/recorder-cli/src/bin/recorder_oss_assurance_checks.rs, crates/recorder-cli/src/bin/recorder_oss_assurance_packet.rsBootstrap de localización (--lang y RECORDER_LANG) y superficies de uso/error localizadas con cargas útiles JSON neutrales en cuanto a la localización.
Pruebas de integración de CLIcrates/recorder-cli/tests/commands.rs, crates/recorder-cli/tests/commands/helpers.rs, crates/recorder-cli/tests/commands/core.rs, crates/recorder-cli/tests/commands/query_and_rotation.rs, crates/recorder-cli/tests/commands/attachments_and_dg.rsCobertura de flujo de trabajo de extremo a extremo para la semántica de CLI.
Integración del generador de contratoscrates/recorder-contract/src/lib.rsAutoridad de artefacto generado determinista consumido por comandos de contrato de CLI.
Suite de operaciones de prueba del sistemasystem-tests/tests/suites/operations/mod.rs, system-tests/tests/suites/operations/query.rs, system-tests/tests/suites/operations/config.rs, system-tests/tests/suites/operations/locale.rs, system-tests/tests/suites/operations/contract.rsValida las comprobaciones de paridad de validación de configuración y el comportamiento de paginación/límite de consulta de contratos JSON.
Suite de grabadora de prueba del sistemasystem-tests/tests/suites/recorder.rsValida el conteo/duración/vida útil combinada de auto-sello y el comportamiento de ida y vuelta de grabación de adjuntos.
Suite de seguridad de prueba del sistemasystem-tests/tests/suites/security.rs, system-tests/tests/suites/security_support.rs, system-tests/tests/suites/security_limits.rs, system-tests/tests/suites/security_signer.rs, system-tests/tests/suites/security_contract_bundle.rsValida el comportamiento de límite de CLI cerrado en caso de fallo a través de límites, hostilidad de adjuntos, política de firmantes, recuperación de rotación, seguridad de ruta de contrato y entradas de paquete hostiles.
Suite de CLI de Decision Gate de prueba del sistemasystem-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.rsValida el éxito de la ingestión de fixture de adaptador de producción de CLI y el comportamiento de desajuste de fallo estricto.
Crate de adaptador OTelcrates/recorder-otel-adapter/src/lib.rsImplementación de mapeo de ingestión JSON de OTel de producción consumida por el comando de integración de CLI.