API Evangelist enhancements for the Counter stats API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Counter stats API
  version: 1.0.0
  x-description: Non-destructive enhancements captured by the API Evangelist enrichment pipeline on 2026-08-13.
    Derived from live probes of https://counter.dev and https://t.counter.dev and from the AGPL-3.0 server
    source at https://github.com/ihucos/counter.dev. Applying this overlay adds provenance, cross-cutting
    convention/error/lifecycle pointers, and per-operation runtime notes. It never mutates the original
    document.
extends: openapi/counter-dev-stats-api-openapi.yml
actions:
- target: $.info
  description: Record that this specification is derived by API Evangelist from the AGPL-3.0 source, not
    published by Counter.
  update:
    x-apievangelist-provenance:
      derived-by: API Evangelist
      derived-from: https://github.com/ihucos/counter.dev
      provider-publishes-spec: false
      date: '2026-08-13'
- target: $
  description: Attach the cross-cutting runtime semantics observed on the live service. None of this is
    published by Counter.
  update:
    x-conventions:
      artifact: conventions/counter-dev-conventions.yml
      idempotency: false
      pagination: none
      versioning: none
      request-id: false
      rate-limit-headers: false
      error-format: plain-text
      rfc9457: false
    x-error-catalog:
      artifact: errors/counter-dev-problem-types.yml
      note: Errors are bare plain-text strings; a 403 body is literally "Forbidden" whether the credential
        was missing or invalid.
    x-lifecycle:
      artifact: lifecycle/counter-dev-lifecycle.yml
      versioning-policy: false
      deprecation-policy: false
      status-page: false
      changelog: false
      sla: false
    x-sandbox:
      artifact: sandbox/counter-dev-sandbox.yml
      public-demo: true
      activation: demo=1 on /query, any non-empty demo on /dump
      credential-required: false
    x-data-model:
      artifact: data-model/counter-dev-data-model.yml
      per-visitor-entity: false
- target: $.components.securitySchemes.sessionCookie
  description: 'Correct the session cookie name: the source names it "swa" (backend/lib/ctx.go), not "session".'
  update:
    x-actual-cookie-name: swa
    x-source: https://github.com/ihucos/counter.dev/blob/master/backend/lib/ctx.go
- target: $.components.securitySchemes.apiToken
  description: Record the real properties and risks of the read-only token.
  update:
    x-token-properties:
      scope: read-only
      per-account: true
      count-per-account: 1
      transport: query-string
      rotation-endpoint: POST /resettoken
      caveat: Travels in the URL, so it lands in browser history, proxy logs and Referer headers. There
        is no header-based alternative.
- target: $.paths['/query'].get
  description: Attach observed runtime behaviour for query.
  update:
    x-observed-behavior: Returns a JSON document but labels it 'text/plain; charset=utf-8' - Ctx.Return
      never sets a Content-Type. Parse as JSON regardless. An unparseable 'from'/'to' returns 500 with
      the raw Go time-parsing error rather than a 400. Verified live 2026-08-13.
    x-verified: '2026-08-13'
- target: $.paths['/dump'].get
  description: Attach observed runtime behaviour for dump.
  update:
    x-observed-behavior: 'Frames are ''data: <json>'' only - the SSE ''event:'' and ''id:'' fields are
      not used, so the frame kind must be read from the JSON ''type'' key and Last-Event-ID resumption
      is unavailable. The ''nouser'' frame is delivered inside a 200 response, so an unauthenticated caller
      must detect failure from the frame type, not the status code. Dumps are throttled to at most one
      per second. See asyncapi/counter-dev-stats-asyncapi.yml.'
    x-verified: '2026-08-13'