Biblioteca de Referencia OpenAPI

Propósito

Esta guía es el contrato de descubribilidad para los paquetes de referencia de Decision Gate respaldados por OpenAPI. Responde, para cada paquete:

¿Dónde está el archivo OpenAPI canónico?
¿Es creado a mano o proviene de una fuente superior?
¿Qué prueba de sistema refuerza el comportamiento?
¿Dónde están los documentos de la API para lectores humanos?

Contrato Canónico

La fuente de verdad legible por máquina es:

references/openapi/reference_library.json

Validado por esquema:

references/openapi/reference_library.schema.json

Cada paquete listado allí debe pasar controles de puerta dura en:

system-tests/src/suites/openapi_reference_library.rs

Catálogo Actual de Paquetes

Pack ID	Dominio	OpenAPI Canónico	Espejos	Prueba del Sistema	Documentos de Upstream
`courtlistener-legal-citation-v1`	Verificación de citas legales	`references/openapi/courtlistener-legal-citation-v1/openapi.json`	`system-tests/tests/fixtures/legal_citation/courtlistener_reference_openapi.json` y `examples/agentic/legal-citation-verification/courtlistener_reference_openapi.json`	`legal_citation_reference_projection_first_end_to_end` en `system-tests/src/suites/legal_citation.rs`	Descripción general de REST, Búsqueda de citas, Raíz de API (v4)

Cobertura y Metadatos de Ejecución

Cada entrada de paquete ahora declara:

execution_modes: conjunto requerido de offline_fixture y/o live_opt_in.
coverage: required deterministic counts:
- operaciones
- casos_fabricados
- casos_buenos_conocidos
- casos_ambiguos
- casos_inválidos
live_mode: required env + CI policy contract:
- habilitado_por_entorno
- required_env
- optional_env
- ci_policy (manual_only o disabled)

Para CourtListener, required_env está intencionadamente vacío porque la autenticación en tiempo de ejecución utiliza secret://courtlistener/api_token pre-provisionado del almacén de secretos encriptados. COURTLISTENER_API_TOKEN solo se utiliza por herramientas manuales de captura de fixtures, no en la ejecución de humo en vivo en tiempo de ejecución. Almacene el valor del token en bruto; los metadatos de renderizado en tiempo de ejecución aplican el prefijo requerido Token en la autenticación saliente. Cuando el llavero no está disponible/sin cabeza, establezca DECISION_GATE_SECRETS_PASSPHRASE antes de los comandos secrets init/put/list para que el almacén encriptado pueda ser desbloqueado.

Regla de Autorización de Proyección (Canónica)

Los metadatos de proyección se evalúan en el esquema de respuesta normalizado/resuelto. Los metadatos de proyección a nivel de componente referenciados a través de $ref son de primera clase y preferidos.

No duplique esquemas de respuesta en línea solo para satisfacer las verificaciones del importador. Mantenga una ubicación de proyección canónica (generalmente el esquema de componente referenciado) y refleje eso byte por byte en las copias de paquetes canónicos/sistema/ejemplo.

Política de Procedencia de la Fuente

Para cada paquete, el catálogo provenance debe declarar explícitamente el origen:

hand_authored_fixture
upstream_openapi_snapshot
generado_a_partir_de_documentos_upstream

CourtListener actualmente utiliza hand_authored_fixture.

Cobertura de Hard-Gate

La CI estándar impone puertas deterministas fuera de línea:

El JSON del catálogo es válido según el esquema.
Todos los caminos catalogados existen.
Canonical and mirrored OpenAPI artifacts are byte-equal (including operation_fixture_corpus.json y archivos de manifiesto de captura en vivo).
El catálogo system_test_name existe en Docs/generated/testing/proof_catalog.json.
El catálogo docs_paths existe en Docs/verification/registry.toml.
Las URL de upstream son absolutas https:// y completas en metadatos.
La cobertura y los metadatos de ejecución/modo en vivo son estructuralmente válidos.

No se realizan verificaciones de conectividad de red en vivo en la CI estándar.

Nueva Lista de Verificación de Paquete (Listo para PubMed/arXiv)

Utiliza esta lista de verificación al agregar DG + PubMed, DG + arXiv, o similar:

Create canonical directory: references/openapi/<pack-id>/
Add canonical files:
- openapi.json
- typed_import_payload_example.json
- citation_cases.json (o corpus determinista equivalente al dominio)
- README.md
Add mirror copies under:
- system-tests/tests/fixtures/<domain_pack>/
- examples/agentic/<domain-pack>/
Agregar/extender la suite de pruebas del sistema en system-tests/src/suites/.
Registrar la suite en system-tests/tests/providers.rs.
Actualiza crates/decision-gate-test-contracts/src/source_catalog.json y system-tests/TEST_MATRIX.md.
Agregar entrada de paquete a references/openapi/reference_library.json.
Asegúrese de que docs_paths estén registrados en Docs/verification/registry.toml.
Incluya enlaces de markdown nombrados a la documentación de la API upstream en el README del paquete.
Declare execution_modes, coverage y live_mode metadata.

Plantilla de Metadatos

{
  "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>"
}