feat(codegen): merge a hand-maintained beta spec overlay for store_state

[joshdholtz]

The public v2 spec (from docs) is release-filtered and drops endpoints we actually call — the store_state family — because khepri marks them x-release-status: development.

This adds a small hand-owned overlay (docs/specs/v2-beta-overlay.yaml) that preprocess-spec.py merges onto the public spec before codegen. The merge is additive — the public spec always wins — so the overlay only fills gaps, and entries get deleted as endpoints graduate to public.

• scripts/seed-beta-overlay.py seeds it from khepri's openapi-dev.yaml (one-time; re-run to reseed). Result: 4 store_state paths + 24 schemas.
• make gen now generates the store_state schema types (+3667/-24 in types_gen.go, purely additive).

This is the mechanism + the direct store_state endpoints. Follow-ups: migrate store_state_direct.go off its hand-written types onto the generated ones, add coverage-map entries, and auto-prune the overlay in the weekly spec-sync.

---

Note

Low Risk
Spec and codegen pipeline changes only; no runtime behavior until generated types are adopted in client code.

Overview
Adds a hand-maintained beta overlay (docs/specs/v2-beta-overlay.yaml) so development-only store_state APIs missing from the public v2 spec can still drive oapi-codegen.

make gen now passes that overlay into preprocess-spec.py after v2-developer.yaml. The merge is additive (public spec wins on conflicts), so the overlay only fills gaps until endpoints ship in the public spec.

The overlay currently defines four product store_state paths (get/set state, equalize subscription prices, operation polling, screenshot upload reservation) plus shared components (App Store / Play Store store-state shapes, Play billing schemas, standard error responses).

^{Reviewed by Cursor Bugbot for commit 9b35576. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear-code]

DX-880 CLI: hand-maintained beta spec overlay for not-yet-public endpoints (store_state)

Problem

The public v2 spec we fetch from docs (openapi-v2.yaml) is a release-filtered artifact. khepri generates three flavors gated by an x-release-status tag (public / beta / development) — only public reaches the docs. So endpoints the CLI actually uses but that are marked development — the whole store_state family (POST/GET /products/{id}/store_state, store_state_screenshot_upload, operations) — are absent from our spec, even though they're production-used and publicly callable (khepri: "treat body changes as breaking").

Consequences: spec-diff can't classify store_state (no drift signal when it changes upstream), the coverage map can't map it, and its client types are hand-written in internal/api/store_state_direct.go instead of generated.

Switching wholesale to khepri's full openapi-dev.yaml was rejected: it needs a token for a private repo and would generate the CLI from every dev-status endpoint. Instead:

Design — hand-maintained overlay (decided: hand-maintained, not auto-pulled)

1. docs/specs/v2-beta-overlay.yaml — a small, hand-maintained file holding only the not-yet-public endpoints the CLI depends on: the store_state paths + their components/schemas. Seed it by copying those operations from khepri api/developer_api_v2/spec/public/openapi-dev.yaml (the ones tagged x-release-status: development).
2. Merge in scripts/preprocess-spec.py — deep-merge public + overlay (paths + components.schemas) before oapi-codegen and spec-diff run. The overlay wins on conflicts.
3. Then: drop the hand-written store_state_direct.go types in favor of generated ones, and add the store_state endpoints to docs/specs/cli-coverage.yaml so drift tracking covers them.
4. Self-pruning: in the weekly spec-sync, after merge, if a path appears in both public and overlay it has graduated to GA → warn (or auto-remove) it from the overlay. The overlay shrinks to nothing over time, then the file is deleted.

Why this shape

• Public stays the source of truth; we only supplement the specific endpoints we deliberately use, not the whole dev surface.
• No CI token / private-repo dependency (revisit auto-pull from khepri later if manual upkeep bites).
• Overlay is self-cleaning — zero permanent divergence.

Relationships

• Builds on [[DX-873]] (the spec-sync fetch fix repoints at the public URL; this adds the overlay on top).
• [[DX-874]] (re-sync) should merge public + overlay so store_state etc. are covered.
• Partially unblocks [[DX-852]]: once the overlay is in, store_state's POST body is specced, answering the "minimal body" question.

Scoped from khepri (developer_api_v2/spec) + revenuecat-cli, 2026-08-06. Josh chose the hand-maintained variant.

Review in Linear

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.