Recorder Decision Gate Asset Core
Docs
Recorder Docs

Proof recording and tamper-evident evidence documentation.

Other product docs

Recorder CLI and Operator Workflows Architecture

Audience: Engineers extending CLI behavior and operators automating Recorder with machine output.

Table of Contents

  1. Executive Overview
  2. Command Surface and Routing
  3. Runtime Resolution Model
  4. Operational Workflows
  5. Output and Localization Model
  6. Input Hard Limits and Fail-Closed Behavior
  7. Exit Code Semantics
  8. File-by-File Cross Reference

Executive Overview

recorder is the operational boundary for local Recorder workflows. It orchestrates recorder and recorder-store with explicit command groups and deterministic JSON mode for automation.

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

Command Surface and Routing

Top-level command groups:

  • recorder (segment + envelope operations),
  • recorder envelope record-with-attachments (attachment-aware ingest),
  • recorder signer (explicit signing-key rotation lifecycle),
  • query (envelope retrieval),
  • bundle (build/verify/inspect),
  • config (runtime config checks),
  • contract (generated contract artifact generate/check),
  • assurance (startup depth, trust-root mode, and OSS gate checks),
  • decision-gate (fixture ingest via production adapter),
  • otel (OTel JSON export fixture ingest via production adapter),
  • doctor (store and active-segment diagnostics).

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

Dispatch architecture uses explicit subcommand routers rather than implicit handler matching, with command implementations split by workflow area. F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/commands.rs L19-L29

Runtime Resolution Model

Runtime settings are resolved with precedence:

  1. CLI flags,
  2. optional config file,
  3. defaults.

Important defaults:

  • store_path: recorder.db
  • recorder_id: recorder-cli
  • schema_version: current schema
  • auto_seal: none unless explicit count and/or duration provided
  • query.limit: default 1000, max 10000
  • security_profile: secure

Signer runtime model:

  • profile-aware signer loading (secure, standard, dev),
  • secure default requiring encrypted PKCS#8 key material,
  • explicit opt-down for plaintext/dev seed in dev,
  • persisted rotation metadata (store_meta) with consistency checks.

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

Store backend selection:

Operational Workflows

Representative workflows map directly to command handlers:

  • open/record/seal/status/list segment lifecycle,
  • record envelopes with attachment file and inline base64 inputs (record-with-attachments),
  • explicit key rotation (recorder signer rotate) with deterministic system.adapter.key_rotated evidence emission,
  • filtered envelope queries with cursor support,
  • bundle build from selector JSON, verify (optionally with trust root), and inspect,
  • contract projection generation/check (contract generate|check),
  • assurance deployment checks (assurance startup|trust-root|gates),
  • Decision Gate transcript/runpack fixture ingest through production adapter.
  • OTel JSON export fixture ingest through production adapter.

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

Integration tests cover baseline workflows and fail-closed cases. 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

Output and Localization Model

Output modes:

  • --json: structured deterministic payloads for automation,
  • text mode: localized operator messaging.

JSON-mode query contract now emits:

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

JSON-mode failures emit a deterministic envelope:

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

Locale resolution:

  • --lang overrides RECORDER_LANG,
  • supported locales are generated from catalog files under crates/recorder-cli/i18n/locales/*.toml,
  • unknown locale values fail closed with non-zero exit,
  • default locale remains en only when locale is unspecified.

Localization integrity guarantees:

  • build-time catalog validation enforces locale-tag uniqueness, default-locale presence, exact key parity against en, and exact placeholder-set parity for every key across all locales,
  • message templates are generated into typed keys/macros and translation table code (OUT_DIR/i18n_generated.rs),
  • runtime translation paths are strict and fail closed on unknown keys, placeholder-set mismatch, or unresolved placeholders,
  • no silent fallback to key IDs or English exists for missing translations,
  • locale provenance metadata is mandatory (machine or human_reviewed) and machine locales emit an explicit runtime disclaimer,
  • JSON output payload contracts remain locale-neutral and stable across locale selection.

Locale coverage includes:

  • recorder main binary,
  • 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

Input Hard Limits and Fail-Closed Behavior

CLI enforces bounded file reads:

  • config: 1 MiB,
  • payload JSON: 4 MiB,
  • attachment file/inline payload: 16 MiB,
  • Decision Gate fixture JSON: 8 MiB,
  • OTel fixture JSON: 16 MiB,
  • selector JSON: 1 MiB,
  • bundle JSON: 32 MiB,
  • trust-root JSON: 1 MiB,
  • signer key file: 64 KiB,
  • signer passphrase material: 1 KiB.

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

Oversized inputs are rejected before parsing/processing. F:crates/recorder-cli/src/support/util.rs L225-L277

bundle verify can load an explicit trust root, route it to Verifier::with_trust_root, and optionally export deterministic verifier transcript JSON via --verdict-transcript-output. F:crates/recorder/src/verification_transcript.rs F:crates/recorder-cli/src/commands/bundle.rs L74-L116

assurance command group provides explicit OSS assumption checks:

  • assurance startup executes runtime bootstrap and startup-verification path checks with optional minimum-depth assertions,
  • assurance trust-root validates trust-root parse/policy/key-set assumptions,
  • assurance gates executes contract check gate semantics directly. F:crates/recorder-cli/src/commands/assurance.rs

System-test coverage now validates:

Exit Code Semantics

  • General command errors return exit code 1 via emit_error.
  • JSON-mode command errors still return exit code 1 with machine-parseable {"error": ...} payload.
  • bundle verify returns exit code 2 when verdict status is Invalid.

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

File-by-File Cross Reference

AreaFileNotes
CLI entry and dispatchcrates/recorder-cli/src/main.rs, crates/recorder-cli/src/main_cli_types.rsClap model, locale/bootstrap flow, top-level dispatch routing.
Command handlerscrates/recorder-cli/src/commands.rsAggregates command-group handler modules.
Recorder handlerscrates/recorder-cli/src/commands/recorder.rsSegment/envelope operations and signer rotation logic.
Query and bundle handlerscrates/recorder-cli/src/commands/query.rs, crates/recorder-cli/src/commands/bundle.rsQuery filters and bundle build/verify/inspect workflows.
Admin handlerscrates/recorder-cli/src/commands/admin.rsConfig validate, doctor diagnostics, contract commands.
Integration handlerscrates/recorder-cli/src/commands/integration.rsDecision Gate and OTel fixture ingest workflows.
Runtime and utility helperscrates/recorder-cli/src/support.rs, crates/recorder-cli/src/support/runtime.rs, crates/recorder-cli/src/support/util.rsRuntime resolution, signer policy, parsing, bounded IO, output helpers.
i18n catalog and generationcrates/recorder-cli/build.rs, crates/recorder-cli/i18n/locales/en.toml, crates/recorder-cli/i18n/locales/ca.toml, crates/recorder-cli/src/i18n.rsBuild-validated locale catalogs, typed keys/macros, provenance metadata, and strict no-fallback rendering.
Auxiliary OSS binariescrates/recorder-cli/src/bin/recorder_oss_assurance_checks.rs, crates/recorder-cli/src/bin/recorder_oss_assurance_packet.rsLocale bootstrap (--lang and RECORDER_LANG) and localized usage/error surfaces with locale-neutral JSON payloads.
CLI integration testscrates/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.rsEnd-to-end workflow coverage for CLI semantics.
Contract generator integrationcrates/recorder-contract/src/lib.rsDeterministic generated artifact authority consumed by CLI contract commands.
System-test operations suitesystem-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.rsValidates config-validate parity checks and query JSON pagination/limit contract behavior.
System-test recorder suitesystem-tests/tests/suites/recorder.rsValidates auto-seal count/duration/combined lifecycle and attachment-recording roundtrip behavior.
System-test security suitesystem-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.rsValidates fail-closed CLI boundary behavior across limits, attachment hostility, signer policy, rotation recovery, contract path safety, and hostile bundle inputs.
System-test Decision Gate CLI suitesystem-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.rsValidates production-adapter CLI ingest-fixture success and strict-fail mismatch behavior.
OTel adapter cratecrates/recorder-otel-adapter/src/lib.rsProduction OTel JSON ingest mapping implementation consumed by CLI integration command.