Generació de Contractes de Recorder i Arquitectura de Projecció

Executive Overview

recorder-contract és el generador/comprovador determinista canònic per a artefactes de projecció de Recorder. Emet sortides d’esquema/contracte/exemple/glossari/tooltip sota Docs/generated/recorder/, ara incloent artefactes de projecció SDK sota Docs/generated/recorder/sdk/, i aplica controls de deriva que fallen tancats.

La generació de tooltips és ara metadades de projecció de classe mundial amb:

1. manifest de tooltip compatible amb versions anteriors (tooltips.json),
2. catàleg de termes ric (tooltips.catalog.json),
3. pointer/token bindings for code blocks and JSON examples vinculacions de punters/token per blocs de codi i exemples de JSON (tooltips.annotations.json),
4. glossari markdown (glossary.md) generat de la mateixa font de termes.

Autoritat d’Artifacte

Codi del generador autoritatiu:

• 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

Autoritat generada arrel:

• Docs/generated/recorder/

Autoritat del manifest de màquina:

• Docs/generated/recorder/index.json

index.json inclou la versió del contracte més metadades de hash SHA-256 per a cada artefacte. Quan hi ha artefactes de l’API sidecar presents, es fan complir les portes de compatibilitat dels artefactes generats mitjançant scripts/ci/sidecar_contract_gates.py.

Modes de Generador

recorder-contract admet dos modes deterministes:

1. GenerateMode::Generate
   • Regenera artefactes i reescriu l’arrel de sortida.
   • Elimina fitxers inesperats obsolets sota l’arrel de sortida.
   • Fails closed if output-root traversal encounters symlinks, hard-linked fitxers d’artefactes, o tipus d’entrada de sistema de fitxers no compatibles.
2. GenerateMode::Check
   • Els errors es tanquen en faltar fitxers, desplaçament de bytes o fitxers inesperats.
   • Fails closed if expected paths resolve through symlinked roots/components, fitxers no regulars, o fitxers d’artifacte enllaçats de manera rígida.

Integració CLI:

• generar contracte de gravació
• comprovació del contracte de gravació

Model de Determinisme

Els controls de determinisme inclouen:

1. ordenació d’artefactes estable a través de mapes/conjunts ordenats,
2. codificació JSON canònica a través de JCS,
3. hash SHA-256 explícit per a les entrades del manifest,
4. comparació de bytes en mode de comprovació contra fitxers compromesos.

Projecció de Schema Conscient de les Restriccions

La generació d’esquemes és en dues etapes:

1. inferir la forma estructural a partir d’artefactes de mostra deterministes,
2. aplicar restriccions de domini autoritzades mitjançant la superposició de JSON-pointer.

Les superposicions de restriccions inclouen:

1. polítiques estrictes de forma de text UUID per a tots els camps d’ID,
2. restriccions de cadena hostil i longitud màxima per a camps d’identificador/text,
3. política estricta de regex per tipus d’esdeveniment i límit de longitud,
4. política de regex key_id estricta (^[0-9a-f]{64}$),
5. restriccions de matriu de bytes de longitud fixa per als camps de hash/signatura,
6. representacions explícites nullable per a camps opcionals,
7. full BundleSelector algebra projection (BySegment, BySegments, ByTrace, ByTimeRange, ByEnvelopeIds, ByFilter, recursive projecció algebraica completa BundleSelector (BySegment, BySegments, ByTrace, ByTimeRange, ByEnvelopeIds, ByFilter, recursiu Composite) a través de l’esquema $defs.

La projecció falla tancada si falten els camins de punter esperats mentre s’apliquen restriccions.

Conjunt d’Artifacts Produïts

Fitxers emes actuals 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. glossari.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

Conformitat i Validació

recorder-contract les proves d’unitat validen:

1. determinisme de generació repetida,
2. consistència del hash/manifesta de bytes de fitxer,
3. els exemples generats es validen contra esquemes generats,
4. el catàleg de tooltip inclou tots els noms dels mètodes de contracte d’adaptador/proveïdor,
5. cobertura de termes bàsics de classe mundial requerida,
6. els punters del catàleg de tooltip es resolen contra els artefactes JSON generats,
7. les vinculacions d’annotations de tooltip només fan referència a les claus de termes definides,
8. schema/runtime invariance for key_id, hostile text fields, and identifier invariància de l’esquema/runtime per a key_id, camps de text hostils i restriccions de longitud màxima d’identificador.
9. emissió d’artefactes sidecar i inclusió de manifest.
10. consistència de l’error del registre del sidecar i de la línia base de compatibilitat.
11. consistència del contracte d’idempotència OpenAPI/compat del sidecar.
12. consistència de l’artifacte de configuració del sidecar (enllaç de esquema/compat/exemple/docs).
13. sidecar OpenAPI component typing strength for Bundle and VerificationVerdict (contractes d’objecte no flexibles, amigables amb generadors).
14. Emissió d’artefactes SDK i inclusió de manifest (types/methods/test_vectors/manifest).
15. Declaracions de script requerides al manifest de l’SDK i consistència del registre de llenguatge objectiu.
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 adapter/proveedor/sidecar superfícies.
17. Cobertura de mètodes SDK/vectors de prova per a superfícies bàsiques d’adaptador/proveïdor/sidecar.
18. Integration mapping contract drift checks for Decision Gate and OTel artifacts generats contra constants d’execució de l’adaptador.
19. Sidecar media-type contract drift checks ensuring runtime policy-derived request media allowlists are projected consistently in OpenAPI and artifacts de compatibilitat.

recorder-contract proves dedicades a la seguretat del camí validen:

1. el mode de generació rebutja arrels d’output enllaçades amb symlink,
2. el mode de generació rebutja els camins fills enllaçats simbòlicament sota l’arrel de sortida,
3. el mode de generació rebutja els fitxers d’artifacte esperats enllaçats de manera dura,
4. el mode de verificació informa sobre el desplaçament de bytes per a artefactes modificats,
5. el mode de comprovació rebutja els fitxers d’artifacte esperats amb enllaços durs,
6. el mode de comprovació rebutja els fitxers d’artifacte esperats enllaçats simbòlicament.

Orquestració i CI

Punt d’entrada d’orquestració d’un sol comandament:

• scripts/ci/generate_all.sh

Comportament:

1. generate: regenerate contract artifacts + regenerate Python SDK contract constants (sdk/python/generate.sh) + run sidecar contract gates + regenerar la documentació de cobertura de proves.
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 tancat).
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 contractes de referència compromesos.

Els fluxos de treball CI executen això en les portes de qualitat requerides.

Límits de Transferència de Projecció

Política de transferència i propietat del glossari de Website/i18n:

• Docs/roadmap/recorder_generated_contract_sync_and_glossary_policy.md

Això defineix la presència de fitxers requerits, la verificació de hash, l’estabilitat de la ruta i la propietat d’un sol origen del glossari/tooltip.