Arxi Generació de Contractes i Arquitectura de Projecció

Executive Overview

arxi-contract és el generador/comprovador determinista canònic per als artefactes de projecció Arxi. Emet sortides de esquema/contracte/exemple/glossari/tooltip sota Docs/generated/arxi/ i imposa comprovacions de deriva de fallada tancada.

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

Autoritat generada arrel:

• Docs/generated/arxi/

Autoritat del manifest de màquina:

• Docs/generated/arxi/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

arxi-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 or unsupported Es tanquen si la travessia de l’arrel de sortida troba enllaços simbòlics o tipus d’entrada de sistema de fitxers no suportats.
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 Falla tancada si els camins esperats es resolen a través de arrels/componentes enllaçats o fitxers no regulars.

Integració CLI:

• arxi contract generate
• arxi contract comprovar

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. glossari.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

Conformitat i Validació

Les proves unitàries de arxi-contract 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).

arxi-contract proves de seguretat dedicades 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 verificació informa sobre el desplaçament de bytes per a artefactes modificats,
4. 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 + run sidecar contract gates + generate: regenerar artefactes de contracte + executar portes de contracte sidecar + regenerar documents de cobertura de proves.
2. check: run contract drift check + sidecar contract gates + docs drift comprovar (fallar tancat).
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 artefactes.

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