Grabadora Puerta de Decisión Asset Core
Docs
Documentos del Grabador

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

Otros documentos del producto

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

Resumen Ejecutivo

recorder-contract es el generador/verificador determinista canónico para los artefactos de proyección de Recorder. Emite salidas de esquema/contrato/ejemplo/glosario/tooltip bajo Docs/generated/recorder/, ahora incluyendo artefactos de proyección de SDK bajo Docs/generated/recorder/sdk/, 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/recorder-contract/src/lib.rs
  • crates/recorder-contract/src/contract_generation.rs
  • crates/recorder-contract/src/contract_generation_artifacts.rs
  • crates/recorder-contract/src/contract_generation_schema.rs
  • crates/recorder-contract/src/contract_generation_samples.rs
  • crates/recorder-contract/src/contract_generation_sdk_types.rs
  • crates/recorder-contract/src/contract_generation_sdk_sidecar.rs
  • crates/recorder-contract/src/contract_generation_sdk_vectors.rs
  • crates/recorder-contract/src/sidecar_api.rs
  • crates/recorder-contract/src/sidecar_api/openapi.rs
  • crates/recorder-contract/src/sidecar_api/artifacts.rs
  • crates/recorder-contract/src/sidecar_api/specs/mod.rs
  • crates/recorder-contract/src/tooltips.rs
  • crates/recorder-contract/src/tooltips_base_terms.rs
  • crates/recorder-contract/src/tooltips_builders.rs

Raíz generada autoritativa:

  • Docs/generated/recorder/

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

recorder-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, hard-linked archivos de artefactos, 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, archivos no regulares, o archivos de artefactos con enlace duro.

Integración de CLI:

  • generar contrato de grabadora
  • verificación del contrato del grabador

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. contracts/integrations/decision_gate.mapping.json
  8. contracts/integrations/otel.mapping.json
  9. glosario.md
  10. tooltips.json
  11. tooltips.catalog.json
  12. tooltips.annotations.json
  13. examples/envelope.json
  14. examples/segment.json
  15. examples/bundle.json
  16. apis/sidecar.openapi.json
  17. apis/sidecar.errors.json
  18. apis/sidecar.enums.json
  19. apis/sidecar.examples.json
  20. apis/sidecar.compat.json
  21. config/sidecar.schema.json
  22. config/sidecar.compat.json
  23. config/sidecar.example.toml
  24. config/sidecar.md
  25. sdk/types.json
  26. sdk/methods.json
  27. sdk/test_vectors.json
  28. sdk/manifest.json

Conformidad y Validación

recorder-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).
  13. sidecar OpenAPI component typing strength for Bundle and VerificationVerdict (contratos de objeto no flexibles, amigables para generadores).
  14. Emisión de artefactos SDK e inclusión de manifiestos (types/methods/test_vectors/manifest).
  15. Declaraciones de script requeridas en el manifiesto del SDK y consistencia del registro de idioma objetivo.
  16. SDK type projection hardening (field-level constraints + OpenAPI component bindings) and SDK method projection hardening (request/response schema refs, error/enum contract linkage, auth/idempotency metadata) for adaptador/proveedor/superficies de sidecar.
  17. Cobertura de métodos/vectores de prueba del SDK para superficies centrales de adaptador/proveedor/sidecar.
  18. Integration mapping contract drift checks for Decision Gate and OTel artículos generados contra constantes de tiempo de ejecución del adaptador.
  19. Sidecar media-type contract drift checks ensuring runtime policy-derived request media allowlists are projected consistently in OpenAPI and artefactos de compatibilidad.

recorder-contract pruebas de seguridad de rutas 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 generación rechaza los archivos de artefactos esperados vinculados de forma rígida,
  4. el modo de verificación informa sobre la deriva de bytes para los artefactos modificados,
  5. el modo de verificación rechaza los archivos de artefactos esperados vinculados de forma rígida,
  6. 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 + regenerate Python SDK contract constants (sdk/python/generate.sh) + run sidecar contract gates + regenerar la documentación de cobertura de pruebas.
  2. check: run contract drift check + Python SDK drift/unit/system gates (sdk/python/check.sh, sdk/python/test.sh) + sidecar contract gates + docs drift check (fallar cerrado).
  3. Optional perf matrix mode: if RECORDER_PERF_MATRIX=1 (or legacy RECORDER_SIDECAR_PERF_GATE=1), execute debug/test + release perf suites via scripts/ci/perf_matrix.py and enforce release gate policy via scripts/ci/perf_gate.py contra contratos de línea base comprometidos.

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/recorder_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.