Recorder Decision Gate Asset Core
Docs
Recorder Docs

Proof recording and tamper-evident evidence documentation.

Other product docs

Recorder Contract Generation and Projection Architecture

Executive Overview

recorder-contract is the canonical deterministic generator/checker for Recorder projection artifacts. It emits schema/contract/example/glossary/tooltip outputs under Docs/generated/recorder/, now including SDK projection artifacts under Docs/generated/recorder/sdk/, 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/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

Authoritative generated root:

  • Docs/generated/recorder/

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

recorder-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, hard-linked artifact files, 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, non-regular files, or hard-linked artifact files.

CLI integration:

  • recorder contract generate
  • recorder 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. contracts/integrations/decision_gate.mapping.json
  8. contracts/integrations/otel.mapping.json
  9. glossary.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

Conformance and Validation

recorder-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).
  13. sidecar OpenAPI component typing strength for Bundle and VerificationVerdict (generator-friendly, non-loose object contracts).
  14. SDK artifact emission and manifest inclusion (types/methods/test_vectors/manifest).
  15. SDK manifest required-script declarations and target-language registry consistency.
  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/provider/sidecar surfaces.
  17. SDK methods/test vectors coverage for adapter/provider/sidecar core surfaces.
  18. Integration mapping contract drift checks for Decision Gate and OTel generated artifacts against adapter runtime constants.
  19. Sidecar media-type contract drift checks ensuring runtime policy-derived request media allowlists are projected consistently in OpenAPI and compatibility artifacts.

recorder-contract dedicated path-safety tests validate:

  1. generate mode rejects symlinked output roots,
  2. generate mode rejects symlinked child paths under output root,
  3. generate mode rejects hard-linked expected artifact files,
  4. check mode reports byte drift for modified artifacts,
  5. check mode rejects hard-linked expected artifact files,
  6. 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 + regenerate Python SDK contract constants (sdk/python/generate.sh) + run sidecar contract gates + regenerate testing coverage docs.
  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 (fail closed).
  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 against committed baseline contracts.

CI workflows run this in required quality gates.

Projection Handoff Boundary

Website/i18n handoff and glossary ownership policy:

  • Docs/roadmap/recorder_generated_contract_sync_and_glossary_policy.md

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