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

Audience: Engineers extending CLI behavior and operators automating Arxi Audiència: Enginyers que amplien el comportament de la CLI i operadors que automatitzen Arxi amb la sortida de màquina.

Taula de continguts

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

Executive Overview

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

F:crates/arxi-cli/src/main.rs L137-L187 F:crates/arxi-cli/src/main.rs L864-L909 F:crates/arxi-cli/src/commands.rs L19-L29 F:crates/arxi-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),
decision-gate (ingestió de fixture a través de l’adaptador de producció),
doctor (diagnòstics de magatzem i segment actiu).

F:crates/arxi-cli/src/main.rs L137-L272

L’arquitectura de dispatch utilitza routers de subcomandament 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/arxi-cli/src/main.rs L913-L980 F:crates/arxi-cli/src/commands.rs L19-L29

Model de Resolució en Temps d’Execució

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

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

Defaults importants:

store_path: arxi.db
recorder_id: arxi-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/arxi-cli/src/main.rs L102-L126 F:crates/arxi-cli/src/support/runtime.rs L20-L122 F:crates/arxi-cli/src/support/runtime.rs L247-L556 Selecció del backend de l’emmagatzematge:

Selecció del backend de la botiga:

file-backed SQLite or in-memory SQLite. SQLite amb fitxer o SQLite en memòria. F:crates/arxi-cli/src/support/runtime.rs L124-L179

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),
Ingesta del transcrit/fixture de runpack de Decision Gate a través de l’adaptador de producció.

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

Les proves d’integració cobreixen fluxos de treball bàsics i casos de fallada tancats. F:crates/arxi-cli/tests/commands.rs L78-L191 F:crates/arxi-cli/tests/commands.rs L193-L219

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 ARXI_LANG,
locals compatibles: en, ca,
retrocedir a l’anglès en cas de claus mancants.

F:crates/arxi-cli/src/main.rs L102-L103 F:crates/arxi-cli/src/support/util.rs L19-L31 F:crates/arxi-cli/src/support/util.rs L301-L345 F:crates/arxi-cli/src/i18n.rs L26-L63 F:crates/arxi-cli/src/i18n.rs L336-L356

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,
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/arxi-cli/src/main.rs L108-L123

Les entrades de mida excessiva són rebutjades abans de l’anàlisi/processament. F:crates/arxi-cli/src/support/util.rs L225-L277

bundle verify pot carregar una arrel de confiança explícita i dirigir-la a Verifier::with_trust_root, habilitant les comprovacions de política de confiança de signatures a la CLI. F:crates/arxi-cli/src/commands/bundle.rs L74-L116

La cobertura de la prova del sistema ara valida:

rebuig d’entrada de trust-root de config/selector/bundle de mida excessiva,
rebuig d’entrada de clau/frase de pas de signant de mida excessiva,
comportament de fallada tancada d’identificador malformat sense mutació del gravador,
validació de la paritat de la forma recorder-id en mode JSON config validate,
durada de l’auto-seal i comportament del cicle de vida combinat a través de fluxos de treball CLI reals,
record-with-attachments success roundtrip and hostile-input fail-closed record-with-attachments comportament d’èxit de viatge rodó i fallada tancada d’entrada hostil sense mutació del gravador,
query JSON pagination contract (applied_limit + next_cursor) and consulta de paginació JSON del contracte (applied_limit + next_cursor) i guàrdies de fallada tancades per sobre del límit,
Comportament d’èxit i de discrepància de fallada estricta de ingest-fixture de Decision Gate CLI,
aplicació de la política de fitxers signats segurs (symlink + permisos),
recuperació de rotació del signant i comportament de fallada tancada de metadades corruptes,
rebuig de l’enllaç simbòlic de contracte CLI output-root,
hostile bundle-verify parse-boundary rejection for invalid attachment content type. F:system-tests/tests/suites/operations.rs L238-L570 F:system-tests/tests/suites/recorder.rs L333-L678 F:system-tests/tests/suites/security.rs L267-L1024 F:system-tests/tests/suites/integration_decision_gate.rs L935-L1161

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/arxi-cli/src/support/util.rs L343-L345 F:crates/arxi-cli/src/commands/bundle.rs L112-L114

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Entrada i despach CLI	`crates/arxi-cli/src/main.rs`	Model Clap, flux de local/bootstrap, ruteig de despach de nivell superior.
Gestors de comandes	`crates/arxi-cli/src/commands.rs`	Agrega mòduls de gestors de grups de comandes.
Gestors de gravadors	`crates/arxi-cli/src/commands/recorder.rs`	Operacions de segment/envolta i lògica de rotació de signants.
Gestors de consultes i paquets	`crates/arxi-cli/src/commands/query.rs`, `crates/arxi-cli/src/commands/bundle.rs`	Filtres de consultes i fluxos de construcció/verificació/inspecció de paquets.
Gestors d’administració	`crates/arxi-cli/src/commands/admin.rs`	Validació de configuració, diagnòstics de doctor, comandes de contracte.
Helpers d’execució i utilitats	`crates/arxi-cli/src/support.rs`, `crates/arxi-cli/src/support/runtime.rs`, `crates/arxi-cli/src/support/util.rs`	Resolució d’execució, política de signants, anàlisi, IO limitat, helpers d’output.
Catàleg i18n	`crates/arxi-cli/src/i18n.rs`	Resolució de local i infraestructura de plantilles de missatges.
Proves d’integració CLI	`crates/arxi-cli/tests/commands.rs`	Cobertura de fluxos de treball de principi a fi per a la semàntica CLI.
Integració del generador de contractes	`crates/arxi-contract/src/lib.rs`	Autoritat d’artifactes generats determinísticament consumida per les comandes de contracte CLI.
Suite d’operacions de proves de sistema	`system-tests/tests/suites/operations.rs`	Valida les comprovacions de paritat de validació de configuració i el comportament de paginació/límit de consultes JSON.
Suite de gravadors de proves de sistema	`system-tests/tests/suites/recorder.rs`	Valida el recompte/duració/vida combinada d’auto-segellament i el comportament de gravació d’adjunt.
Suite de seguretat de proves de sistema	`system-tests/tests/suites/security.rs`	Valida el comportament de límits tancats de CLI a través de límits, hostilitat d’adjunts, política de signants, recuperació de rotació, seguretat de camins de contracte i entrades de paquet hostils.
Suite CLI de Decision Gate de proves de sistema	`system-tests/tests/suites/integration_decision_gate.rs`	Valida l’èxit de fixture d’ingestió de CLI d’adaptador de producció i el comportament de desajustament estricte.