Parent: wave-av/wave-cli#31
Why
The spec currently describes products that do not work, which means codegen emits SDK methods that 404 in a developer's hands. That is worse than a gap — a missing method is an honest absence; a generated method that fails is a broken promise.
Grounded
openapi.yaml fully specs 13 products. Verified against live probes 2026-07-24:
studio-ai — studio.wave.online does not resolve. Specced. Absent.realtime — /v1/rooms → 501 REALTIME_NOT_IMPLEMENTED (despite 18.6k LoC in the repo). Four paths specced.voice, podcast, collab, editor, chapters, phone — bare {"ok":true} health, /v1/* 404s. All specced.transcribe, captions — /v1/* → 405 (a POST handler exists; unverified but plausible).
So 11 of 13 specced products are SKELETON or ABSENT.
Scope
Reconcile openapi.yaml against wave-catalog and live probes, and give the spec a way to tell the truth about implementation status:
- a vendor extension (e.g.
x-wave-status: live | preview | planned) on each path, sourced from the catalog rather than hand-maintained
- teach
sdks/codegen/parse_spec.py to respect it — planned paths do not emit a client method, or emit one that fails loudly and early with a clear "not implemented yet" rather than a mystery 404
- a CI check that fails when the spec and the catalog disagree, so this cannot silently rot again
Boundary
Does not delete the specs for unimplemented products — they are the design, and they are useful. It marks them, so generated clients stop lying.
Done when
A generated SDK contains no method that returns 404/501 against prod, and CI fails on spec↔catalog drift. Receipt: the CI run, plus a deliberate drift commit shown failing.
Parent: wave-av/wave-cli#31
Why
The spec currently describes products that do not work, which means codegen emits SDK methods that 404 in a developer's hands. That is worse than a gap — a missing method is an honest absence; a generated method that fails is a broken promise.
Grounded
openapi.yamlfully specs 13 products. Verified against live probes 2026-07-24:studio-ai—studio.wave.onlinedoes not resolve. Specced. Absent.realtime—/v1/rooms→ 501REALTIME_NOT_IMPLEMENTED(despite 18.6k LoC in the repo). Four paths specced.voice,podcast,collab,editor,chapters,phone— bare{"ok":true}health,/v1/*404s. All specced.transcribe,captions—/v1/*→ 405 (a POST handler exists; unverified but plausible).So 11 of 13 specced products are SKELETON or ABSENT.
Scope
Reconcile
openapi.yamlagainstwave-catalogand live probes, and give the spec a way to tell the truth about implementation status:x-wave-status: live | preview | planned) on each path, sourced from the catalog rather than hand-maintainedsdks/codegen/parse_spec.pyto respect it —plannedpaths do not emit a client method, or emit one that fails loudly and early with a clear "not implemented yet" rather than a mystery 404Boundary
Does not delete the specs for unimplemented products — they are the design, and they are useful. It marks them, so generated clients stop lying.
Done when
A generated SDK contains no method that returns 404/501 against prod, and CI fails on spec↔catalog drift. Receipt: the CI run, plus a deliberate drift commit shown failing.