Recorder Asset Core Decision Gate
Docs
Decision Gate Docs

Deterministic, replayable gate evaluation with auditable decisions.

Asset Core docs

OpenAPI Reference Library

Purpose

This guide is the discoverability contract for OpenAPI-backed Decision Gate reference packs. It answers, for every pack:

  1. Where is the canonical OpenAPI file?
  2. Is it hand-authored or sourced upstream?
  3. Which system-test enforces behavior?
  4. Where are the upstream API docs for human readers?

Canonical Contract

The machine-readable source-of-truth is:

  • references/openapi/reference_library.json

Validated by schema:

  • references/openapi/reference_library.schema.json

Every pack listed there must pass hard-gate checks in:

  • system-tests/src/suites/openapi_reference_library.rs

Current Pack Catalog

Pack IDDomainCanonical OpenAPIMirrorsSystem TestUpstream Docs
courtlistener-legal-citation-v1Legal citation verificationreferences/openapi/courtlistener-legal-citation-v1/openapi.jsonsystem-tests/tests/fixtures/legal_citation/courtlistener_reference_openapi.json and examples/agentic/legal-citation-verification/courtlistener_reference_openapi.jsonlegal_citation_reference_projection_first_end_to_end in system-tests/src/suites/legal_citation.rsREST Overview, Citation Lookup, API Root (v4)

Coverage and Execution Metadata

Each pack entry now declares:

  1. execution_modes: required set from offline_fixture and/or live_opt_in.
  2. coverage: required deterministic counts:
    • operations
    • fabricated_cases
    • known_good_cases
    • ambiguous_cases
    • invalid_cases
  3. live_mode: required env + CI policy contract:
    • enabled_by_env
    • required_env
    • optional_env
    • ci_policy (manual_only or disabled)

For CourtListener, required_env is intentionally empty because runtime auth uses pre-provisioned secret://courtlistener/api_token from the encrypted secret store. COURTLISTENER_API_TOKEN is only used by manual fixture-capture tooling, not runtime live smoke execution. Store the raw token value; typed runtime render metadata applies the required Token prefix on outbound auth. When keyring is unavailable/headless, set DECISION_GATE_SECRETS_PASSPHRASE before secrets init/put/list commands so the encrypted store can be unlocked.

Projection Authoring Rule (Canonical)

Projection metadata is evaluated on the normalized/resolved response schema. Component-level projection metadata referenced via $ref is first-class and preferred.

Do not inline duplicate response schemas just to satisfy importer checks. Keep one canonical projection location (usually the referenced component schema) and mirror that byte-for-byte across canonical/system/example pack copies.

Source Provenance Policy

For each pack, catalog provenance must explicitly declare origin:

  • hand_authored_fixture
  • upstream_openapi_snapshot
  • generated_from_upstream_docs

CourtListener currently uses hand_authored_fixture.

Hard-Gate Coverage

Standard CI enforces offline deterministic gates:

  1. Catalog JSON is schema-valid.
  2. All cataloged paths exist.
  3. Canonical and mirrored OpenAPI artifacts are byte-equal (including operation_fixture_corpus.json and live capture manifest files).
  4. Catalog system_test_name exists in Docs/generated/testing/proof_catalog.json.
  5. Catalog docs_paths exist in Docs/verification/registry.toml.
  6. Upstream URLs are absolute https:// and metadata-complete.
  7. Coverage and execution/live-mode metadata are structurally valid.

No live network reachability checks run in standard CI.

New Pack Checklist (PubMed/arXiv Ready)

Use this checklist when adding DG + PubMed, DG + arXiv, or similar:

  1. Create canonical directory: references/openapi/<pack-id>/
  2. Add canonical files:
    • openapi.json
    • typed_import_payload_example.json
    • citation_cases.json (or domain-equivalent deterministic corpus)
    • README.md
  3. Add mirror copies under:
    • system-tests/tests/fixtures/<domain_pack>/
    • examples/agentic/<domain-pack>/
  4. Add/extend system-test suite under system-tests/src/suites/.
  5. Register suite in system-tests/tests/providers.rs.
  6. Update crates/decision-gate-test-contracts/src/source_catalog.json and system-tests/TEST_MATRIX.md.
  7. Add pack entry to references/openapi/reference_library.json.
  8. Ensure docs_paths are registered in Docs/verification/registry.toml.
  9. Include named markdown links to upstream API docs in pack README.
  10. Declare execution_modes, coverage, and live_mode metadata.

Metadata Template

{
  "pack_id": "<kebab-case-pack-id>",
  "version": "v1",
  "domain": "<domain>",
  "status": "active",
  "provenance": "hand_authored_fixture",
  "canonical_openapi_path": "references/openapi/<pack-id>/openapi.json",
  "system_fixture_openapi_path": "system-tests/tests/fixtures/<pack>/openapi.json",
  "example_openapi_path": "examples/agentic/<pack>/openapi.json",
  "system_suite_path": "system-tests/src/suites/<suite>.rs",
  "system_test_name": "<exact_test_name>",
  "docs_paths": [
    "/docs/decision-gate/guides/openapi-reference-library"
  ],
  "upstream_docs": [
    {
      "label": "<human label>",
      "url": "https://...",
      "kind": "rest_overview",
      "verified_on_utc": "2026-02-21"
    }
  ],
  "execution_modes": [
    "offline_fixture",
    "live_opt_in"
  ],
  "coverage": {
    "operations": 4,
    "fabricated_cases": 6,
    "known_good_cases": 3,
    "ambiguous_cases": 1,
    "invalid_cases": 1
  },
  "live_mode": {
    "enabled_by_env": "COURTLISTENER_LIVE",
    "required_env": [],
    "optional_env": [
      "COURTLISTENER_BASE_URL",
      "COURTLISTENER_LIVE_CASE_LIMIT"
    ],
    "ci_policy": "manual_only"
  },
  "notes": "<deterministic note>"
}