version: 1
rules:
  require_primary_source: true
  require_version_applicability: true
  require_corroboration_for_major_change: true
  reject_unsourced_claims: true
  automatic_apply: false

# La documentación del tercero concreto que integra una empresa —Shopify, su WMS, su transportadora,
# su proveedor de pagos— no vive acá: acá van las fuentes de la profesión. Lo específico de la empresa
# va en organization/roles/integrations-engineer.md, y la versión de API que usa hoy, en el contrato
# de la integración.
#
# Cada entrada se verificó abriendo su URL el 2026-08-22. Lo que no se pudo abrir está al final,
# nombrado, en vez de citado como si se hubiera leído.
sources:
  # Define «idempotente» y qué métodos lo son. Es la referencia que separa el reintento seguro del que
  # duplica un efecto, y la que muestra que POST no está en esa lista.
  - name: RFC 9110 HTTP Semantics
    url: https://www.rfc-editor.org/rfc/rfc9110.html
    tier: standard
    topics: [http-semantics, idempotent-methods, status-codes, retry-safety]

  # Formato de error legible por máquina. Obsoleta a la RFC 7807: un contrato que cita «7807» está
  # citando el documento reemplazado, y la diferencia importa cuando el partner valida el cuerpo.
  - name: RFC 9457 Problem Details for HTTP APIs
    url: https://www.rfc-editor.org/rfc/rfc9457.html
    tier: standard
    topics: [error-model, partner-facing-contract, machine-readable-errors]

  # BCP 240, enero de 2025. Exige coincidencia exacta del redirect URI, y refresh tokens rotados o
  # atados al emisor para clientes públicos. Es la fuente para revisar un flujo OAuth de tienda o de
  # proveedor de identidad sin opinar de memoria.
  - name: RFC 9700 Best Current Practice for OAuth 2.0 Security
    url: https://www.rfc-editor.org/rfc/rfc9700.html
    tier: standard
    topics: [oauth, token-security, redirect-uri, refresh-token-rotation]

  # API10:2023 «Unsafe Consumption of APIs» es literalmente este cargo: el riesgo de confiar en el
  # tercero más de lo que se confiaría en un usuario. API9 cubre inventario y versiones expuestas.
  - name: OWASP API Security Top 10 2023
    url: https://owasp.org/API-Security/editions/2023/en/0x11-t10/
    tier: standard
    topics: [api-risk-model, unsafe-consumption, inventory-management, ssrf]

  # La versión vigente al 2026-08-22 es la 3.2.0, publicada el 2025-09-19, y define `webhooks` como
  # campo de primer nivel del documento: el contrato de lo que se le expone a un partner puede
  # declarar también lo que se le envía.
  - name: OpenAPI Specification
    url: https://spec.openapis.org/oas/latest.html
    tier: standard
    topics: [api-contract, partner-facing-contract, webhooks, versioning]

  # Convención de versionado con sólo versión mayor en la ruta y canales de estabilidad. Sirve como
  # término de comparación al decidir la política de cambio del contrato propio; es la guía de una
  # empresa, no una norma, y así se cita.
  - name: Google AIP-185 API Versioning
    url: https://google.aip.dev/185
    tier: profession
    topics: [versioning, breaking-changes, stability-channels]

  # Capítulo 21, «Handling Overload». De acá sale la regla de que reintenta sólo la capa que llama al
  # tercero: si reintentan varias, la explosión es combinatoria. También el presupuesto de reintento
  # como proporción del tráfico. No habla de dispersión (jitter): eso no se le atribuye.
  - name: Google SRE Book — Handling Overload
    url: https://sre.google/sre-book/handling-overload/
    tier: profession
    topics: [retry-budget, retry-amplification, overload, degradation]

  # Cadencia trimestral, cada versión estable soportada al menos 12 meses y con no menos de 9 meses de
  # solapamiento entre consecutivas. Es el ejemplo concreto de un tercero que sí publica su política:
  # el contraste con el que no la publica es lo que hay que diseñar.
  - name: Shopify — API versioning
    url: https://shopify.dev/docs/api/usage/versioning
    tier: standard
    topics: [third-party-versioning, deprecation-window, breaking-changes]

  # El proveedor declara por escrito que no garantiza el orden dentro de un topic ni entre topics del
  # mismo recurso, que la entrega no siempre está garantizada, y recomienda deduplicar por
  # `X-Shopify-Webhook-Id` y conciliar. Es la cita que sostiene «asumir al menos una vez y sin orden».
  - name: Shopify — Webhook best practices
    url: https://shopify.dev/docs/apps/build/webhooks/best-practices
    tier: standard
    topics: [webhooks, at-least-once, out-of-order, deduplication, reconciliation]

  # Guarda código y cuerpo de la primera respuesta por clave y los repite en el reintento, incluido un
  # 500; la clave puede podarse a partir de las 24 horas y entonces se genera una petición nueva; si
  # los parámetros cambian con la misma clave, error. Cada uno de esos tres detalles cambia el diseño,
  # y ninguno es deducible del concepto de idempotencia.
  - name: Stripe — Idempotent requests
    url: https://docs.stripe.com/api/idempotent_requests
    tier: standard
    topics: [idempotency-key, retry-safety, payments, deduplication-window]

  # Firma, cabeceras y verificación de webhooks, con comité técnico de varias empresas. La página
  # remite al repositorio para el número de versión del documento: **la versión del spec no se
  # verificó**, así que se cita como convención de la industria y no como norma con edición.
  - name: Standard Webhooks
    url: https://www.standardwebhooks.com/
    tier: standard
    topics: [webhooks, signature-scheme, headers, replay-protection]

  # Registrado para que nadie lo cite como estándar: es un Internet-Draft **expirado**. Última
  # revisión draft-07 del 2025-10-15, estado IESG «Expired», nunca llegó a RFC. La cabecera
  # `Idempotency-Key` es una convención adoptada por varios proveedores, no algo que se pueda exigir
  # por norma, y cada proveedor decide su ventana y su semántica.
  - name: draft-ietf-httpapi-idempotency-key-header (expirado)
    url: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
    tier: standard
    status: expired
    topics: [idempotency-key, not-a-standard]

# Mientras esto siga pendiente, la dispersión del backoff queda sin fuente registrada acá y no se
# afirma como recomendación de nadie.
pending:
  - name: AWS Builders Library — Timeouts, retries, and backoff with jitter
    url: https://builder.aws.com/content/timeouts-retries-and-backoff-with-jitter
    why: aws.amazon.com redirige acá y la página devolvió sólo el encabezado, así que no se leyó
    since: 2026-08-22