Gravadora Decision Gate Asset Core
Docs
Recorder Docs

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

Altres documents de producte

Arquitectura de Recorder CLI i Fluxos de Treball de l’Operador

Audience: Engineers extending CLI behavior and operators automating Recorder amb sortida de màquina.

Taula de continguts

  1. Visió Executiva
  2. Superfície de Comandament i Ruteig
  3. Model de Resolució en Temps d’Execució
  4. Fluxos de treball operatius
  5. Model de Sortida i Localització
  6. Límits d’entrada i comportament de fallada tancada
  7. Semàntica del Codi de Sortida
  8. File per Fitxer Referència Creuada

Executive Overview

recorder és el límit operatiu per als fluxos de treball locals de Recorder. Orquestra recorder i recorder-store amb grups de comandes explícits i un mode JSON determinista per a l’automatització.

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

Superfície de Comandament i Ruteig

Grups de comandes de nivell superior:

  • recorder (operacions de segment i sobre)
  • recorder envelope record-with-attachments (ingest amb coneixement d’adjunts),
  • recorder signer (cicle de rotació de la clau de signatura explícita),
  • consulta (recuperació d’envelopes),
  • bundle (construir/verificar/inspeccionar),
  • config (comprovacions de configuració en temps d’execució),
  • contract (artifact de contracte generat generar/comprovar),
  • assegurament (profunditat de startup, mode de confiança arrel i comprovacions de porta OSS),
  • decision-gate (ingestió de fixture a través de l’adaptador de producció),
  • otel (ingestió de fixture d’exportació JSON d’OTel a través de l’adaptador de producció),
  • doctor (diagnòstics de magatzem i segment actiu).

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

L’arquitectura de dispatch utilitza routers de subcomandes explícits en lloc de coincidències de manipuladors implícits, amb les implementacions de comandes dividides per àrea de flux de treball. F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/commands.rs L19-L29

Model de Resolució en Temps d’Execució

Les configuracions d’execució es resolen amb precedència:

  1. Flags de la CLI,
  2. fitxer de configuració opcional,
  3. valors per defecte.

Defaults importants:

  • store_path: recorder.db
  • recorder_id: recorder-cli
  • schema_version: esquema actual
  • auto_seal: cap a menys que s’especifiqui un recompte i/o durada explícits
  • query.limit: per defecte 1000, màxim 10000
  • security_profile: segur

Model d’execució del signant:

  • càrrega de signers conscient del perfil (secure, standard, dev),
  • requisit per defecte segur que necessita material de clau PKCS#8 xifrat,
  • opt-down explícit per a la clau de text pla/seu de desenvolupament en dev,
  • metadades de rotació persistides (store_meta) amb comprovacions de consistència.

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ó del backend de la botiga:

Fluxos de treball operatius

Els fluxos de treball representatius es mapegen directament als gestors de comandes:

  • obrir/registrar/sellar/estat/llista cicle de vida del segment,
  • sobres de registre amb fitxers d’adjunt i entrades base64 en línia (record-with-attachments),
  • explicit key rotation (recorder signer rotate) with deterministic rotació de claus explícita (recorder signer rotate) amb emissió d’evidència system.adapter.key_rotated determinista,
  • consultes d’envelopes filtrades amb suport de cursor,
  • construir el paquet a partir del JSON del selector, verificar (opcionalment amb la confiança arrel) i inspeccionar,
  • generació/comprovació de projecció de contracte (contract generate|check),
  • comprovacions de desplegament d’assegurances (assurance startup|trust-root|gates),
  • Ingesta del transcrit/fixture de runpack de Decision Gate a través de l’adaptador de producció.
  • Ingesta de fixture d’exportació JSON d’OTel a través de l’adaptador de producció.

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

Les proves d’integració cobreixen fluxos de treball bàsics i casos de fallada tancada. 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

Model de Sortida i Localització

Modes de sortida:

  • --json: càrregues estructurades deterministes per a l’automatització,
  • mode de text: missatges d’operador localitzats.

El contracte de consulta en mode JSON ara emet:

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

Les fallades en mode JSON emeten un sobre determinista:

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

Resolució de localització:

  • --lang substitueix RECORDER_LANG,
  • supported locales are generated from catalog files under crates/recorder-cli/i18n/locales/*.toml,
  • els valors de localització desconeguts fallen tancats amb una sortida no zero,
  • la configuració regional per defecte es manté en només quan la configuració regional no està especificada.

Integritat de localització garanteix:

  • build-time catalog validation enforces locale-tag uniqueness, default-locale presence, exact key parity against en, and exact placeholder-set parity for cada clau a totes les localitzacions,
  • message templates are generated into typed keys/macros and translation table codi (OUT_DIR/i18n_generated.rs),
  • runtime translation paths are strict and fail closed on unknown keys, desajustament de conjunt de marcadors de posició, o marcadors de posició no resolts,
  • no hi ha un retrocés silenciós als ID de clau o a l’anglès per a traduccions que falten,
  • locale provenance metadata is mandatory (machine or human_reviewed) and les màquines locals emeten un avís explícit d’execució,
  • JSON output payload contracts remain locale-neutral and stable across locale selecció.

Cobertura d’idiomes inclou:

  • recorder binari 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ímits d’entrada i comportament de fallada tancada

CLI imposa lectures de fitxers limitades:

  • config: 1 MiB,
  • càrrega útil JSON: 4 MiB,
  • fitxer d’adjunt/payload en línia: 16 MiB,
  • JSON del fixture de Decision Gate: 8 MiB,
  • JSON de fixtures OTel: 16 MiB,
  • selector JSON: 1 MiB,
  • paquet JSON: 32 MiB,
  • trust-root JSON: 1 MiB,
  • fitxer de clau de signatura: 64 KiB,
  • material de la frase de pas del signant: 1 KiB.

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

Els inputs de mida excessiva són rebutjats abans de la seva anàlisi/processament. F:crates/recorder-cli/src/support/util.rs L225-L277

bundle verify pot carregar una arrel de confiança explícita, dirigir-la a Verifier::with_trust_root, i opcionalment exportar un JSON de transcripció 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 grup de comandes proporciona comprovacions d’assumpció OSS explícites:

  • assurance startup executes runtime bootstrap and startup-verification path comprovacions amb afirmacions de profunditat mínima opcionals,
  • assurance trust-root valida les suposicions de parse/policy/key-set del trust-root,
  • assurance gates executes contract check gate semantics directly. F:crates/recorder-cli/src/commands/assurance.rs

La cobertura de la prova del sistema ara valida:

Semàntica del Codi de Sortida

  • Els errors generals de comanda retornen el codi de sortida 1 a través de emit_error.
  • JSON-mode command errors still return exit code 1 with machine-parseable Els errors de comanda en mode JSON continuen retornant el codi de sortida 1 amb una càrrega útil {"error": ...} que es pot analitzar per màquina.
  • bundle verify retorna el codi de sortida 2 quan l’estat del veredicte és Invàlid.

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

File per Fitxer Referència Creuada

ÀreaFitxerNotes
Entrada i dispatch de CLIcrates/recorder-cli/src/main.rs, crates/recorder-cli/src/main_cli_types.rsModel Clap, flux de localització/bootstrap, routatge de dispatch de nivell superior.
Gestors de comandescrates/recorder-cli/src/commands.rsAgrega mòduls de gestors de grups de comandes.
Gestors de gravadorscrates/recorder-cli/src/commands/recorder.rsOperacions de segment/envolta i lògica de rotació de signants.
Gestors de consultes i paquetscrates/recorder-cli/src/commands/query.rs, crates/recorder-cli/src/commands/bundle.rsFiltres de consultes i fluxos de treball de construcció/verificació/inspecció de paquets.
Gestors d’administraciócrates/recorder-cli/src/commands/admin.rsValidació de configuració, diagnòstics de doctor, comandes de contracte.
Gestors d’integraciócrates/recorder-cli/src/commands/integration.rsFluxos de treball d’ingestió de Decision Gate i OTel.
Helpers de runtime i utilitatscrates/recorder-cli/src/support.rs, crates/recorder-cli/src/support/runtime.rs, crates/recorder-cli/src/support/util.rsResolució en temps d’execució, política de signants, anàlisi, IO limitat, helpers d’output.
Catàleg i generació 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àlegs de localització validades en la construcció, claus/macros tipades, metadades de procedència i renderització estricta sense fallback.
Binàries OSS auxiliarscrates/recorder-cli/src/bin/recorder_oss_assurance_checks.rs, crates/recorder-cli/src/bin/recorder_oss_assurance_packet.rsBootstrap de localització (--lang i RECORDER_LANG) i superfícies d’ús/error localitzades amb càrregues útils JSON neutres a la localització.
Proves d’integració 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 fluxos de treball de principi a fi per a la semàntica de CLI.
Integració del generador de contractescrates/recorder-contract/src/lib.rsAutoritat d’artifacte generat determinista consumida per les comandes de contracte de CLI.
Suite d’operacions de proves 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 les comprovacions de paritat de validació de configuració i el comportament de paginació/limitació de JSON de consultes de contracte.
Suite de gravador de proves del sistemasystem-tests/tests/suites/recorder.rsValida el comportament de comptatge/duració/cicle de vida combinat d’auto-segellament i enregistrament d’adjunts.
Suite de seguretat de proves 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 comportament de límits de CLI tancats en fallida, hostilitat d’adjuncions, política de signants, recuperació de rotació, seguretat del camí del contracte i entrades hostils de paquets.
Suite de CLI de Decision Gate de proves 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 l’èxit d’ingestió de fixtures d’adaptador de producció de CLI i el comportament de desajustament de fallida estricta.
Crate d’adaptador OTelcrates/recorder-otel-adapter/src/lib.rsImplementació de mapeig d’ingestió JSON OTel de producció consumida per la comanda d’integració de CLI.