Arxi Puerta de Decisión Asset Core
Docs
Arxi Docs

Documentación de grabación de pruebas y evidencia a prueba de manipulaciones.

Otros documentos del producto

Arquitectura de Generación y Proyección de Contratos Arxi

Resumen Ejecutivo

arxi-contract es el generador/verificador determinista canónico para los artefactos de proyección de Arxi. Emite salidas de esquema/contrato/ejemplo/glosario/tooltip bajo Docs/generated/arxi/ y aplica controles de deriva que fallan en cerrado.

La generación de tooltips ahora es metadatos de proyección de clase mundial con:

  1. manifiesto de tooltips compatible hacia atrás (tooltips.json),
  2. catálogo de términos enriquecidos (tooltips.catalog.json),
  3. pointer/token bindings for code blocks and JSON examples vinculaciones de puntero/token para bloques de código y ejemplos de JSON (tooltips.annotations.json),
  4. markdown del glosario (glossary.md) generado a partir de la misma fuente de términos.

Autoridad del Artefacto

Código del generador autoritativo:

  • crates/arxi-contract/src/lib.rs
  • crates/arxi-contract/src/sidecar_api.rs
  • crates/arxi-contract/src/sidecar_api/openapi.rs
  • crates/arxi-contract/src/sidecar_api/artifacts.rs
  • crates/arxi-contract/src/sidecar_api/specs/mod.rs

Raíz generada autoritativa:

  • Docs/generated/arxi/

Autoridad del manifiesto de la máquina:

index.json incluye la versión del contrato más los metadatos del hash SHA-256 por artefacto. Cuando están presentes los artefactos de la API sidecar, se aplican puertas de compatibilidad desde los artefactos generados a través de scripts/ci/sidecar_contract_gates.py.

Modos de Generador

arxi-contract admite dos modos deterministas:

  1. GenerateMode::Generate
    • Regenera artefactos y reescribe la raíz de salida.
    • Elimina archivos inesperados y obsoletos en la raíz de salida.
    • Fails closed if output-root traversal encounters symlinks or unsupported Falla cerrada si la exploración de output-root encuentra enlaces simbólicos o tipos de entrada de sistema de archivos no soportados.
  2. GenerateMode::Check
    • Falla cerrada por archivos faltantes, desplazamiento de bytes o archivos inesperados.
    • Fails closed if expected paths resolve through symlinked roots/components Falla cerrada si las rutas esperadas se resuelven a través de raíces/componentes enlazados por symlink o archivos no regulares.

Integración de CLI:

  • arxi contract generate
  • verificación de contrato arxi

Modelo de Determinismo

Los controles de determinismo incluyen:

  1. ordenación estable de artefactos a través de mapas/conjuntos ordenados,
  2. codificación JSON canónica a través de JCS,
  3. hash SHA-256 explícito para entradas de manifiesto,
  4. comparación de bytes en modo de verificación contra archivos comprometidos.

Proyección de Esquema Consciente de Restricciones

La generación de esquemas es de dos etapas:

  1. inferir la forma estructural a partir de artefactos de muestra determinísticos,
  2. aplicar restricciones de dominio autoritativas mediante superposición de punteros JSON.

Las superposiciones de restricciones incluyen:

  1. políticas estrictas de forma de texto UUID para todos los campos de ID,
  2. restricciones de cadena hostil y longitud máxima para campos de identificador/texto,
  3. política estricta de regex para el tipo de evento y límite de longitud,
  4. política de regex estricta para key_id (^[0-9a-f]{64}$),
  5. restricciones de matriz de bytes de longitud fija para campos de hash/firma,
  6. representaciones nulas explícitas para campos opcionales,
  7. full BundleSelector algebra projection (BySegment, BySegments, ByTrace, ByTimeRange, ByEnvelopeIds, ByFilter, recursive proyección algebraica completa de BundleSelector (BySegment, BySegments, ByTrace, ByTimeRange, ByEnvelopeIds, ByFilter, Composite recursivo) a través del esquema $defs.

La proyección falla cerrada si faltan las rutas de puntero esperadas al aplicar restricciones.

Conjunto de Artefactos Producidos

Archivos emitidos actuales v1:

  1. index.json
  2. schemas/envelope.schema.json
  3. schemas/segment.schema.json
  4. schemas/bundle.schema.json
  5. contracts/adapter.json
  6. contracts/provider.json
  7. glosario.md
  8. tooltips.json
  9. tooltips.catalog.json
  10. tooltips.annotations.json
  11. examples/envelope.json
  12. examples/segment.json
  13. examples/bundle.json
  14. apis/sidecar.openapi.json
  15. apis/sidecar.errors.json
  16. apis/sidecar.enums.json
  17. apis/sidecar.examples.json
  18. apis/sidecar.compat.json
  19. config/sidecar.schema.json
  20. config/sidecar.compat.json
  21. config/sidecar.example.toml
  22. config/sidecar.md

Conformidad y Validación

arxi-contract las pruebas unitarias validan:

  1. determinismo de generación repetida,
  2. consistencia de hash de manifiesto/bytes de archivo,
  3. los ejemplos generados se validan contra los esquemas generados,
  4. el catálogo de tooltips incluye todos los nombres de métodos de contrato de adaptador/proveedor,
  5. cobertura de términos centrales de clase mundial requerida,
  6. los punteros del catálogo de tooltips se resuelven contra los artefactos JSON generados,
  7. las vinculaciones de anotación de tooltip solo hacen referencia a las claves de términos definidos,
  8. schema/runtime invariance for key_id, hostile text fields, and identifier invarianza de esquema/runtime para key_id, campos de texto hostiles y restricciones de longitud máxima de identificador.
  9. emisión de artefactos sidecar e inclusión en el manifiesto.
  10. consistencia del registro de errores del sidecar y la línea base de compatibilidad.
  11. consistencia del contrato de idempotencia de OpenAPI/compat del sidecar.
  12. consistencia del artefacto de configuración del sidecar (vínculo de esquema/compatibilidad/ejemplo/documentación).

arxi-contract pruebas de seguridad de ruta dedicadas validan:

  1. el modo de generación rechaza las raíces de salida vinculadas simbólicamente,
  2. el modo de generación rechaza las rutas hijas enlazadas simbólicamente bajo la raíz de salida,
  3. el modo de verificación informa sobre la deriva de bytes para los artefactos modificados,
  4. el modo de verificación rechaza los archivos de artefactos esperados vinculados simbólicamente.

Orquestación y CI

Punto de entrada de orquestación de un solo comando:

  • scripts/ci/generate_all.sh

Comportamiento:

  1. generate: regenerate contract artifacts + run sidecar contract gates + generate: regenerar artefactos de contrato + ejecutar puertas de contrato sidecar + regenerar documentos de cobertura de pruebas.
  2. check: run contract drift check + sidecar contract gates + docs drift check: ejecutar verificación de desviación del contrato + puertas del contrato sidecar + verificación de desviación de documentos (cerrar en caso de fallo).
  3. Optional release mode: if ARXI_SIDECAR_PERF_GATE=1, enforce sidecar SLO metrics via scripts/ci/sidecar_perf_gate.py against generated perf report artefactos.

Los flujos de trabajo de CI ejecutan esto en los controles de calidad requeridos.

Límite de Transferencia de Proyección

Política de entrega de i18n del sitio web y propiedad del glosario:

  • Docs/roadmap/arxi_generated_contract_sync_and_glossary_policy.md

Esto define la presencia de archivos requeridos, la verificación de hash, la estabilidad de la ruta y la propiedad de glosario/tooltip de una sola fuente.