Arquitectura de Flujos de Trabajo de Arxi CLI y Operador

Audience: Engineers extending CLI behavior and operators automating Arxi Audiencia: Ingenieros que extienden el comportamiento de la CLI y operadores que automatizan Arxi con salida de máquina.

Tabla de Contenidos

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

Resumen Ejecutivo

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

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

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),
decision-gate (ingestión de fixture a través del adaptador de producción),
doctor (diagnósticos de almacenamiento y de segmento activo).

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

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/arxi-cli/src/main.rs L913-L980 F:crates/arxi-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:

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

Importantes valores predeterminados:

store_path: arxi.db
recorder_id: arxi-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/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ón de backend de almacenamiento:

file-backed SQLite or in-memory SQLite. SQLite respaldado por archivos o SQLite en memoria. F:crates/arxi-cli/src/support/runtime.rs L124-L179

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

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

Las pruebas de integración cubren flujos de trabajo básicos y casos de fallo cerrado. F:crates/arxi-cli/tests/commands.rs L78-L191 F:crates/arxi-cli/tests/commands.rs L193-L219

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 ARXI_LANG,
locales soportados: en, ca,
retroceder al inglés en caso de claves faltantes.

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

Las entradas de gran tamaño son rechazadas antes de la análisis/procesamiento. F:crates/arxi-cli/src/support/util.rs L225-L277

bundle verify puede cargar una raíz de confianza explícita y dirigirla a Verifier::with_trust_root, lo que permite realizar verificaciones de políticas de confianza de firma en la CLI. F:crates/arxi-cli/src/commands/bundle.rs L74-L116

La cobertura de la prueba del sistema ahora valida:

rechazo de entrada de config/selector/bundle/trust-root sobredimensionado,
rechazo de entrada de clave/frase de paso de firmante sobredimensionada,
comportamiento de fallo cerrado de identificador malformado sin mutación del grabador,
validación de paridad de forma de recorder-id en modo JSON config validate,
duración del auto-sello y comportamiento combinado del ciclo de vida a través de flujos de trabajo CLI reales,
record-with-attachments success roundtrip and hostile-input fail-closed record-with-attachments comportamiento de éxito en el viaje de ida y vuelta y fallo cerrado con entrada hostil sin mutación del grabador,
query JSON pagination contract (applied_limit + next_cursor) and consulta de paginación JSON del contrato (applied_limit + next_cursor) y guardrails de fallo cerrado por sobre límite,
Comportamiento de éxito y desajuste de fallo estricto de ingest-fixture en Decision Gate CLI,
aplicación de políticas de archivo de firmante seguro (symlink + permisos),
recuperación de rotación de firmantes y comportamiento de fallo cerrado de metadatos corruptos,
rechazo de symlink de salida-root del contrato CLI,
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 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/arxi-cli/src/support/util.rs L343-L345 F:crates/arxi-cli/src/commands/bundle.rs L112-L114

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Entrada y despacho de CLI	`crates/arxi-cli/src/main.rs`	Modelo Clap, flujo de local/bootstrap, enrutamiento de despacho de nivel superior.
Manejadores de comandos	`crates/arxi-cli/src/commands.rs`	Agrega módulos manejadores de grupos de comandos.
Manejadores de grabación	`crates/arxi-cli/src/commands/recorder.rs`	Operaciones de segmento/envase y lógica de rotación de firmantes.
Manejadores de consulta y paquete	`crates/arxi-cli/src/commands/query.rs`, `crates/arxi-cli/src/commands/bundle.rs`	Filtros de consulta y flujos de trabajo de construcción/verificación/inspección de paquetes.
Manejadores de administración	`crates/arxi-cli/src/commands/admin.rs`	Validación de configuración, diagnósticos de doctor, comandos de contrato.
Ayudantes de tiempo de ejecución y utilidades	`crates/arxi-cli/src/support.rs`, `crates/arxi-cli/src/support/runtime.rs`, `crates/arxi-cli/src/support/util.rs`	Resolución en tiempo de ejecución, política de firmantes, análisis, IO acotado, ayudantes de salida.
Catálogo de i18n	`crates/arxi-cli/src/i18n.rs`	Resolución de local y infraestructura de plantillas de mensajes.
Pruebas de integración de CLI	`crates/arxi-cli/tests/commands.rs`	Cobertura de flujo de trabajo de extremo a extremo para la semántica de CLI.
Integración del generador de contratos	`crates/arxi-contract/src/lib.rs`	Autoridad de artefacto generado determinista consumida por comandos de contrato de CLI.
Suite de operaciones de prueba del sistema	`system-tests/tests/suites/operations.rs`	Valida las verificaciones de paridad de validación de configuración y el comportamiento de paginación/límite de consulta de contrato JSON.
Suite de grabación de prueba del sistema	`system-tests/tests/suites/recorder.rs`	Valida 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 sistema	`system-tests/tests/suites/security.rs`	Valida el comportamiento de límite de CLI que falla cerrado 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 sistema	`system-tests/tests/suites/integration_decision_gate.rs`	Valida el éxito de la fijación de ingestión de CLI de adaptador de producción y el comportamiento de desajuste de fallo estricto.