API Evangelist enhancements for the Counter tracking API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Counter tracking 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-tracking-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['/track'].get
  description: Attach observed runtime behaviour for track.
  update:
    x-observed-behavior: 'NOT IDEMPOTENT despite being a GET - each call increments Redis counters, so
      a retry or a prefetch double-counts. Responds ''Access-Control-Allow-Origin: *'' and ''Cache-Control:
      public, immutable'' with an end-of-day Expires, which is part of how repeat visits are suppressed
      without cookies. Bots, HeadlessChrome, PetalBot, AdsBot, localhost/127.0.0.1 origins and ''.translate.goog''
      origins are dropped. Verified live: returns the plain-text body ''OK'' with an Origin header present.'
    x-verified: '2026-08-13'
- target: $.paths['/trackpage'].post
  description: Attach observed runtime behaviour for trackpage.
  update:
    x-observed-behavior: 'NOT IDEMPOTENT. An unknown or empty ''id'' returns 500 with the plain-text body
      ''No such user with uuid: '' rather than a 400 (observed live 2026-08-13).'
    x-verified: '2026-08-13'