openapi.yaml declares voice/transcribe/captions/phone/podcast endpoints that 404 in production (SDK is codegen’d from it)

[yakimoto]

Found while grounding wave-context#72 (building real ADK modules + MCP tools against the shipped fleet products). Part of wave-context#48.

The problem

openapi.yaml declares endpoints for voice, transcribe, and captions that do not exist in the deployed spokes. Because the SDK is code-generated from this spec, the generated client exposes methods that will 404 against production.

The spec's servers: is https://api.wave.online/v1, and the gateway forwards /v1/<product> as-is to the product spoke — spoke-routing.ts is a pure prefix map with no path rewriting:

wave-gateway/src/spoke-routing.ts
  if (path === "/v1/voice"      || path.startsWith("/v1/voice/"))      return env.VOICE_ORIGIN      || null;
  if (path === "/v1/transcribe" || path.startsWith("/v1/transcribe/")) return env.TRANSCRIBE_ORIGIN || null;
  if (path === "/v1/captions"   || path.startsWith("/v1/captions/"))   return env.CAPTIONS_ORIGIN   || null;

So a declared path routes to the right spoke — and then the spoke 404s it, because each spoke owns its whole /v1 namespace and matches paths exactly.

Declared vs implemented

Spec declares	Spoke actually implements	Result
GET /voice/voices POST /voice/generate POST /voice/clone	wave-voice-edge/src/api.ts: POST /v1/voice + GET /v1/healthz only	all 3 → 404
GET /transcribe POST /transcribe GET /transcribe/{transcriptionId}	wave-transcribe-edge/src/api.ts: POST /v1/transcribe + GET /v1/healthz only	POST works; GET /transcribe and /{id} → 404
GET /captions POST /captions GET,DELETE /captions/{jobId} GET /captions/{jobId}/download	wave-captions-edge/src/api.ts: POST /v1/captions, POST /v1/live/{caption,pipeline,fanout}, GET /v1/healthz	POST works; the 4 job-resource routes → 404
GET,POST /phone/lines GET,POST /phone/calls	wave-phone-edge has no api.ts at all — src/ is favicon.ts, landing.ts, tokens.css.ts, worker.ts	unimplemented
GET /podcast/shows GET /podcast/shows/{showId}/episodes	wave-podcast-edge — same: landing shim only	unimplemented

Each spoke's router ends with an explicit catch-all, so this is by design, not a routing accident:

/** Route /v1/* requests. Owns the whole /v1 namespace (unknown /v1 path → 404). */
…
return json({ error: 'not found' }, 404);

Note also that /v1/phone and /v1/podcast appear nowhere in spoke-routing.ts, so those paths don't even reach a product spoke — they fall through to the WSC origin.

How I verified (and what I did not verify)

• Read each spoke's src/api.ts at origin/main via git show (branch-truth, not a working tree).
• Read wave-gateway/src/spoke-routing.ts at origin/main to confirm passthrough, no rewrite.
• Live probing could not settle this and should not be used to: unauthenticated requests return 402 for any path under a routed product prefix — /v1/voice/definitely-not-real returns 402 exactly like /v1/voice/generate. The billing gate fires before routing, so a 402 proves only that the prefix is routed, never that the endpoint exists. (An unrouted prefix returns 403.)
• Not verified: the /editor/*, /studio-ai/*, /search/*, /sentiment/*, /collab/* groups. Those have no entry in spoke-routing.ts, so they fall through to WSC, whose source I did not read. They may well be real — this report deliberately does not claim either way.

Why it matters

A spec is a contract, and this one is the input to SDK codegen — so an over-declared path becomes a shipped client method that fails at runtime for whoever calls it. It is also the artifact an agent or integrator reads to decide what WAVE can do. This is the same failure class the Content Engine exists to catch (a confident, precise, well-formatted artifact that is wrong), just in a different medium.

Suggested fix

1. Cut the unimplemented paths from openapi.yaml, or move them behind an explicit x-wave-phase: planned extension that codegen skips, so "planned" never renders as a callable SDK method.
2. Correct the three real ones to the paths that actually exist: POST /voice, POST /transcribe, POST /captions (relative to the /v1 server base) — noting that voice returns audio bytes and captions returns a caption file, not JSON.
3. Add a CI check that diffs declared paths against the spokes' routers, so the spec can't silently drift from the deployed surface again.

[yakimoto]

Explicit follow-up: five endpoint groups in this spec are still unadjudicated.

The original report deliberately scoped its claims to what I read the source for (voice / transcribe / captions / phone / podcast). These groups were not verified either way and should not be assumed correct just because they weren't listed as broken:

• /editor/projects (+ /{projectId}, /{projectId}/export)
• /studio-ai/enhancements, /studio-ai/preview
• /search, /search/quick, /search/suggest, /search/semantic
• /sentiment, /sentiment/analyze
• /collab/rooms (+ /{roomId})

None of them has an entry in wave-gateway/src/spoke-routing.ts, so they fall through to the WSC origin rather than a product spoke. They may be entirely real — WSC may serve all of them — but I did not read WSC's router, so I'm not claiming either way.

This matters because the SDK is generated from this spec: if any of these are also over-declared, they're already shipped client methods that 404, exactly like the voice/captions ones. Given that five of five groups I did check turned out to be wrong, the prior on the rest isn't good.

Worth resolving as part of suggested fix #3 (the CI check diffing declared paths against implementations) — that check will settle all of these mechanically and keep them settled, which is better than another one-off manual read.

[yakimoto]

Resolving the five groups I flagged as unadjudicated — and correcting my own claim about what can be probed.

Earlier in this thread I said live probing cannot establish endpoint existence, because an unauthenticated request under any routed prefix returns 402 (the billing gate fires before routing). That is true, but I stopped one step short. There is a usable signal, and it comes from the gateway's own source:

// wave-gateway/src/scopes.ts — requiredScope()
// Under an enforced prefix but unmapped → FAIL-CLOSED (never silently allow an unbilled route).
if (ENFORCED_PREFIXES.some((p) => path.startsWith(p))) return { deny: true };

So under /v1/: 402 = the prefix is mapped (billing gate fired first), 403 = the gateway refused to map it at all. That discriminates at the group level, needs no credential, and is mechanical.

Running it against production, with a known-bogus control:

/v1/editor/x                       402
/v1/studio-ai/x                    402
/v1/search/x                       402
/v1/sentiment/x                    402
/v1/collab/x                       402
/v1/definitely-not-real-xyz        403   <-- control

All five groups are mapped. That is corroborated by source: editor, studio-ai, search, sentiment, and collab all appear in V1_GROUPS (wave-gateway/src/scope-groups.ts), the 139-group catalog mined from WSC's own /v1 route trees.

What this does and does not settle. It settles that these five groups exist and route — my earlier "the prior on the rest isn't good" was too pessimistic, and I'd rather correct it than leave it standing. It does not settle that any specific path under them exists, because the 402 is returned before routing. Group-level existence is the ceiling of what this probe can prove.

The gap that remains is exactly where the real bugs are. I found three dead paths in @wave-av/adk this way (wave-av/adk#63): /v1/graphics/show and /v1/moderation/action both return 403 — same bucket as the nonsense control — because the catalog has graphics-engine, not graphics, and no moderation at all. The third, /v1/captions/start, returns a healthy-looking 402 and still 404s, because /v1/captions/* routes to the captions spoke whose router exact-matches /v1/captions and returns {"error":"not found"} for everything else. Only spoke source catches that class.

So the CI check in suggested fix #3 should be two-tier:

1. Group tier (cheap, unauthenticated, catches 403s). Assert every declared path's first /v1 segment is in V1_GROUPS. Pure static comparison against wave-gateway/src/scope-groups.ts — no network needed at all, and it would have caught two of the three ADK bugs.
2. Path tier (the one that matters). For any prefix routed to a spoke, assert the declared path appears in that spoke's router at origin/main. This is the only tier that catches /v1/captions/start, and it is the class this whole issue is about.

Neither tier requires a credential or bills a metered call.