ci(openapi): enforce info.version bump on spec changes + version sidecar

[paperclip-resolver]

Fixes #233

Summary

Customer ask (Phil Goodrich) — bump info.version on every openapi.json paths/schema change, and give consumers a cheap way to detect those bumps. #230 shipped the one-off /account shape fix + version bump; this PR is the systemic guardrail so the next divergence doesn't slip through.

Changes

1. Policy — CONTRIBUTING.md gains an OpenAPI spec versioning section: SemVer rules (MAJOR / MINOR / PATCH), local-run instructions, and the consumer signal.
2. CI check (mechanism) — scripts/check-openapi-version.mjs is a self-contained Node script that compares the base-branch spec against the PR's spec by canonicalised .paths and .components.schemas (info x-* stamping is ignored, so build-time provenance churn never trips it). It fails CI when paths/schemas changed without an info.version bump, and when a bump lacks a CHANGELOG.md entry — self-enforcing changelog hygiene.
3. Consumer signal — scripts/stamp-openapi.mjs (already runs in build) now also emits public/openapi-version.json:

   { "version": "2.1.0", "x-generated-at": "...", "x-commit-sha": "..." }

   Consumers can poll https://docs.sharpapi.io/openapi-version.json (~120 bytes) instead of re-downloading the full ~170 KB spec. Seeded with current provenance; build refreshes it on every deploy.
4. Changelog — CHANGELOG.md seeded with 2.0.0 + 2.1.0 entries; future bumps enforced by the CI check.

⚠️ Action required before merge — missing CI workflow file

The CI workflow file that wires up the script (.github/workflows/openapi-version-check.yml) is not in this commit. The paperclip-resolver[bot] GitHub App installation on the Sharp-API org lacks the workflows permission, so the Git Data API rejected the tree write with x-accepted-github-permissions: actions=write. (Plain blobs and trees outside .github/workflows/ work fine — only workflow file writes are gated.)

A reviewer with workflows-write should add the file below before merging, either via the GitHub web UI ("Add file → Create new file") or via a regular git push from their own identity:

.github/workflows/openapi-version-check.yml (verbatim):

name: OpenAPI Version Check

on:
  pull_request:
    paths:
      - 'public/openapi.json'
      - 'CHANGELOG.md'
      - 'scripts/check-openapi-version.mjs'
      - '.github/workflows/openapi-version-check.yml'

permissions:
  contents: read

concurrency:
  group: openapi-version-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    name: Check spec version bump
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: '22'

      - name: Extract base spec
        # Read public/openapi.json as it exists on the PR's base branch so the
        # check compares paths/schemas against the merge target. An empty {} is
        # written when the file is new (no base), which the script treats as a skip.
        run: |
          git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
          git show "FETCH_HEAD:public/openapi.json" > /tmp/openapi.base.json 2>/dev/null \
            || echo '{}' > /tmp/openapi.base.json

      - name: Check version bump
        run: node scripts/check-openapi-version.mjs /tmp/openapi.base.json public/openapi.json

Alternatively: grant the paperclip-resolver[bot] App the Actions (or Workflows) write permission on the Sharp-API org install, then I can push the workflow on a subsequent run.

Verification

• scripts/check-openapi-version.mjs unit-tested against 5 branches in the worktree before commit:
  1. no semantic change, same version → exit 0
  2. path added, version unchanged → exit 1 (rejects with SemVer hint)
  3. version bumped, no CHANGELOG entry → exit 1
  4. version bumped + matching CHANGELOG entry → exit 0
  5. empty base (new spec) → exit 0 (skip)
• scripts/stamp-openapi.mjs smoke-run in the worktree: emits a valid openapi-version.json ({ "version": "2.1.0", ... }) and does not perturb the spec semantics (only info x-* fields, which the checker ignores).

Type: ci