Arxi Decision Gate Asset Core
Docs
Arxi Docs

Proof recording and tamper-evident evidence documentation.

Other product docs

Arxi Contract Generation and Projection Architecture

Executive Overview

arxi-contract is the canonical deterministic generator/checker for Arxi projection artifacts. It emits schema/contract/example/glossary/tooltip outputs under Docs/generated/arxi/ and enforces fail-closed drift checks.

Tooltip generation is now world-class projection metadata with:

  1. backward-compatible tooltip manifest (tooltips.json),
  2. rich term catalog (tooltips.catalog.json),
  3. pointer/token bindings for code blocks and JSON examples (tooltips.annotations.json),
  4. glossary markdown (glossary.md) generated from the same term source.

Artifact Authority

Authoritative generator code:

  • 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

Authoritative generated root:

  • Docs/generated/arxi/

Machine manifest authority:

index.json includes contract version plus per-artifact SHA-256 hash metadata. When sidecar API artifacts are present, compatibility gates are enforced from generated artifacts via scripts/ci/sidecar_contract_gates.py.

Generator Modes

arxi-contract supports two deterministic modes:

  1. GenerateMode::Generate
    • Regenerates artifacts and rewrites output root.
    • Removes stale unexpected files under output root.
    • Fails closed if output-root traversal encounters symlinks or unsupported filesystem entry types.
  2. GenerateMode::Check
    • Fails closed on missing files, byte drift, or unexpected files.
    • Fails closed if expected paths resolve through symlinked roots/components or non-regular files.

CLI integration:

  • arxi contract generate
  • arxi contract check

Determinism Model

Determinism controls include:

  1. stable artifact ordering via ordered maps/sets,
  2. canonical JSON encoding via JCS,
  3. explicit SHA-256 hashing for manifest entries,
  4. check-mode byte comparison against committed files.

Constraint-Aware Schema Projection

Schema generation is two-stage:

  1. infer structural shape from deterministic sample artifacts,
  2. apply authoritative domain constraints by JSON-pointer overlay.

Constraint overlays include:

  1. strict UUID text shape policies for all ID fields,
  2. hostile-string and max-length constraints for identifier/text fields,
  3. strict event-type regex policy and length ceiling,
  4. strict key_id regex policy (^[0-9a-f]{64}$),
  5. fixed-length byte-array constraints for hash/signature fields,
  6. explicit nullable representations for optional fields,
  7. full BundleSelector algebra projection (BySegment, BySegments, ByTrace, ByTimeRange, ByEnvelopeIds, ByFilter, recursive Composite) via schema $defs.

Projection fails closed if expected pointer paths are missing while applying constraints.

Produced Artifact Set

Current v1 emitted files:

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

Conformance and Validation

arxi-contract unit tests validate:

  1. repeated generation determinism,
  2. manifest hash/file-byte consistency,
  3. generated examples validate against generated schemas,
  4. tooltip catalog includes all adapter/provider contract method names,
  5. required world-class core term coverage,
  6. tooltip catalog pointers resolve against generated JSON artifacts,
  7. tooltip annotation bindings only reference defined term keys,
  8. schema/runtime invariance for key_id, hostile text fields, and identifier max-length constraints.
  9. sidecar artifact emission and manifest inclusion.
  10. sidecar error-registry and compatibility-baseline consistency.
  11. sidecar OpenAPI/compat idempotency contract consistency.
  12. sidecar config artifact consistency (schema/compat/example/docs linkage).

arxi-contract dedicated path-safety tests validate:

  1. generate mode rejects symlinked output roots,
  2. generate mode rejects symlinked child paths under output root,
  3. check mode reports byte drift for modified artifacts,
  4. check mode rejects symlinked expected artifact files.

Orchestration and CI

One-command orchestration entrypoint:

  • scripts/ci/generate_all.sh

Behavior:

  1. generate: regenerate contract artifacts + run sidecar contract gates + regenerate testing coverage docs.
  2. check: run contract drift check + sidecar contract gates + docs drift check (fail closed).
  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 artifacts.

CI workflows run this in required quality gates.

Projection Handoff Boundary

Website/i18n handoff and glossary ownership policy:

  • Docs/roadmap/arxi_generated_contract_sync_and_glossary_policy.md

This defines required file presence, hash verification, path stability, and single-source glossary/tooltip ownership.