Add /enhance path to openapi.yaml (wave-gateway#799)

[yakimoto]

User description

Summary

Adds the missing OpenAPI entry for POST /v1/enhance — an AI video super-resolution route that
has been live-routed with no spec entry and no SDK method (closes the contract-drift gap flagged
against wave-gateway#799).

• New Enhance tag + POST /enhance path, mirroring the existing Render/MoQ/AV Mux-Demux
  paths' style (x402 PaymentRequired idiom, binary in/out, per-job receipt headers).
• v1 ships exactly one model, espcn (ESPCN super-resolution — a fixed exact 3x factor baked
  into the trained model weights, not a runtime parameter); any other model value 400s.
• Auth: bearer API key, enhance:write scope. Unauthenticated → 402 with the same x402
  challenge shape used elsewhere in this spec ($ref: '#/components/responses/PaymentRequired').
• Billing note: bills against the wave_enhance_minutes meter — the OUTPUT artifact's rendered
  duration, rounded up to the next whole minute. (I checked the actual spoke source before
  writing this: it does not currently apply a resolution-weighting factor to the minute
  count — that weighting is an open, undecided pricing question upstream, not shipped code — so
  the spec documents plain output-duration minutes rather than inventing a formula.)
• Documents the request contract (raw body or ?url= fetch, 200 MiB cap), the per-job receipt
  response headers (x-enhance-model, x-enhance-scale-factor, x-enhance-*-dimensions,
  x-wave-meter, x-wave-usage-minutes), and the error shapes actually returned by the spoke
  (400/401/402/403/413/422/429/501/502/503).

Breaking: yes

After merging origin/main (which since diverged and independently added an auto-generated
skills-index draft placeholder for POST /enhance — x-schema-status: draft, application/json
additionalProperties: true body), this PR's hand-authored operation replaces that placeholder.
oasdiff correctly flags this as breaking (request-body-media-type-removed,
response-media-type-removed — the placeholder's application/json media types are gone,
replaced by the real video/*/application/octet-stream binary shapes). This is intentional and
correct, not an oversight: the placeholder was never an accurate contract (verified live —
POST https://api.wave.online/v1/enhance returns the x402 402 challenge for an unauthenticated
call, consistent with binary-body semantics, not the draft's generic JSON shape), and no consumer
could have been calling it successfully with application/json in the first place. Acknowledging
per this repo's breaking-change gate rather than silently overriding it.

Validation

Ran this repo's own CI checks locally (.github/workflows/foundation-gate.yml):

$ npx --yes @redocly/cli@2.40.0 lint openapi.yaml
openapi.yaml: validated in 90ms
Woohoo! Your API description is valid. 🎉
You have 53 warnings.

53 warnings is the exact pre-existing baseline this workflow's own comment documents (no new
warnings or errors introduced by this change).

$ node .github/scripts/assert-refs.mjs openapi.yaml
assert-refs: 204 $ref(s) in openapi.yaml, all resolve

CI on this PR may show as failed/cancelled due to the ongoing GitHub Actions "Service
Unavailable" incident — that is unrelated to this change; see the local runs above for the real
result.

Test plan

• npx @redocly/cli lint openapi.yaml passes with the pre-existing warning count only
• assert-refs.mjs confirms every $ref in the file still resolves
• Operator merge (this PR is not merged by the agent that opened it — public repo, human-only merge)

Note

Medium Risk
Intentionally breaking OpenAPI media types and operation shape for SDK codegen; documents x402 billing and auth lanes for a live paid route, but does not change gateway runtime behavior.

Overview
Replaces the skills-index draft POST /enhance placeholder (operationId enhance, generic application/json body) with a hand-authored enhanceVideo contract aligned to the live gateway: binary video/* / application/octet-stream input (or ?url= HTTPS fetch, 200 MiB cap), streaming binary output, espcn-only query param, bearer or x402 pay-per-call (wave_enhance_minutes), and receipt/billing response headers plus the full 4xx/5xx set.

Adds an Enhance tag, moves the path next to other product surfaces (and drops the duplicate draft block at the bottom of openapi.yaml), and updates POST /studio-ai/enhancements copy to point async library jobs at Studio AI vs synchronous bytes at /enhance. Regenerates generated/api-types.d.ts and contract-drift.json, and adds a shared-drift allowlist entry for POST /enhance while the published spec still marks the operation draft.

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

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

Note

Add POST /enhance endpoint for synchronous AI video super-resolution to openapi.yaml

• Adds a new POST /enhance path to openapi.yaml with operationId enhanceVideo, supporting the espcn model for synchronous video super-resolution.
• Accepts input as either a raw binary request body or an https URL via ?url= query parameter, with a 200 MiB size limit.
• Returns the enhanced video as a binary stream with billing metadata headers (x-enhance-model, x-enhance-scale-factor, x-wave-meter, x-wave-usage-minutes, etc.).
• Supports both BearerAuth and unauthenticated x402 pay-per-call billing against wave_enhance_minutes.
• Updates the existing POST /studio-ai/enhancements description to distinguish it from the new synchronous endpoint.

^{Macroscope summarized bab8755.}

Summary by Sourcery

Expand the public API contract with production-ready video enhancement, MoQ token, and attestation specifications while refreshing generated types and drift metadata.

New Features:

• Document the synchronous POST /enhance video super-resolution API with binary input/output, espcn processing, authentication and x402 payment behavior, billing metadata, and supported error responses.
• Add MoQ publish and subscribe token-minting API contracts and reusable x402 payment schemas.
• Add the WAVE Attestation Standard v1 specification, JSON schema, verifier reference, and well-known key documentation.

Enhancements:

• Replace the draft /enhance placeholder with a complete hand-authored contract and distinguish it from asynchronous Studio AI enhancement jobs.
• Add Render and Wave Attestation component schemas to the OpenAPI contract.

CI:

• Add body-content policy validation for public repository surfaces.

Documentation:

• Record the Enhance, MoQ, and attestation surfaces in the changelog.

Chores:

• Refresh generated API types and published contract-drift tracking for the new API surfaces.

---

CodeAnt-AI Description

Document the live /v1/enhance video super-resolution endpoint

What Changed

• Replaces the draft placeholder with a complete POST /enhance contract for synchronous AI video enhancement
• Documents raw video uploads or secure HTTPS source URLs, the single espcn model with fixed 3x upscaling, binary streaming responses, billing, and receipt headers
• Adds documented authentication and x402 payment behavior, input limits, validation errors, rate limits, and retryable backend failures
• Generated API types now expose the typed enhanceVideo operation and distinguish it from asynchronous Studio AI enhancement jobs
• Adds drift tracking and changelog coverage for the live endpoint

Impact

✅ Typed SDK support for video enhancement
✅ Clearer binary input and output contracts
✅ Clearer payment, billing, and failure handling

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_9a7d1ce7-336e-40e3-bcfd-b76367566d57)

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🚫 Excluded labels (none allowed) (1)

• rr:skip-coderabbit

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 52ab8576-2cf8-4e6c-8fee-234ffd06d38c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — The gateway runtime is unchanged, but the PR intentionally replaces an existing draft operation with a fully typed binary and pay-per-call contract, changing the generated SDK surface and request/response media types. This public API-schema compatibility change warrants human review.

Not approved because:

• Credit balance exhausted. Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings. You can add or adjust custom eligibility rules. Learn more.}

[qodo-code-review]

PR Summary by Qodo

Document POST /v1/enhance in OpenAPI (AI super-resolution, x402)

✨ Enhancement 📝 Documentation 🕐 10-20 Minutes

AI Description

• Add missing OpenAPI spec for POST /v1/enhance AI super-resolution route.
• Define auth scope, x402 PaymentRequired behavior, and duration-based billing headers.
• Document input modes (body or URL fetch), size limits, and expected error responses.

Diagram

graph TD
  client["API Client"] --> gw["Gateway \"/v1/enhance\""] --> enhance["Enhance Spoke"] --> resp["Binary Video + Receipt Headers"]
  enhance --> src{{"HTTPS Source (optional)"}}
  enhance --> meter[("Usage Meter \"wave_enhance_minutes\"")]

  subgraph Legend
    direction LR
    _c["Client"] ~~~ _s["Service"] ~~~ _e{{"External"}} ~~~ _d[("Meter/Store")]
  end

Loading

High-Level Assessment

The PR’s approach—documenting the already-live route directly in openapi.yaml and reusing existing shared response components (Unauthorized/PaymentRequired/Forbidden/UpstreamError)—is the simplest way to close contract drift without introducing new abstractions. Considered extracting shared header/parameter components, but this endpoint is currently singular and the added indirection would not materially improve maintainability yet.

Files changed (1) +143 / -0

Documentation (1) +143 / -0

openapi.yamlAdd Enhance tag and POST /enhance endpoint contract +143/-0

Add Enhance tag and POST /enhance endpoint contract

• Introduces a new 'Enhance' tag and documents 'POST /enhance' (served under /v1 via the server URL) for AI video super-resolution. Specifies model selection (v1 'espcn' only), body-or-URL input with a 200 MiB cap, binary streaming output, receipt/billing headers, and the full set of expected error responses including x402 PaymentRequired.

openapi.yaml

[devin-ai-integration]

Devin Review found 3 potential issues.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 📜 Skill insights (0)

1. Octet-stream response missing ✓ Resolved 🐞 Bug ≡ Correctness

Description

The /enhance 200 response claims it streams back using the same Content-Type as the source,
and the requestBody allows application/octet-stream, but the response only declares video/*.
This leaves application/octet-stream responses undocumented and may cause generated clients to
mishandle or reject that response type.

Code

openapi.yaml[R1680-1683]

+            video/*:
+              schema:
+                type: string
+                format: binary

Evidence

The spec explicitly allows application/octet-stream in the request body, and also says the
response uses the same content-type as the source, but the 200 response only declares video/* as
a possible media type.

openapi.yaml[1635-1648]
openapi.yaml[1650-1653]
openapi.yaml[1679-1684]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`POST /enhance` accepts `application/octet-stream` uploads and states that the response will be streamed back with the same content-type as the source, but the OpenAPI `200` response only declares `video/*`. This makes the contract internally inconsistent and leaves octet-stream responses undocumented.

## Issue Context
The requestBody explicitly allows `application/octet-stream`, so clients may legitimately send it. If the server mirrors that content-type back (as described), the OpenAPI response content types should include it.

## Fix Focus Areas
- openapi.yaml[1635-1684]

## Suggested fix
Under `responses: '200': content:`, add an `application/octet-stream` entry (same binary schema as `video/*`). If the implementation never returns octet-stream, instead adjust the description to match the actual fixed response content-type.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. openapi.yaml exceeds 500 lines 📘 Rule violation ⚙ Maintainability

Description

openapi.yaml is well over 500 lines, and this PR adds additional content to it. This violates the
rule limiting touched source files to 500 non-empty, non-comment lines.

Code

openapi.yaml[R75-78]

+  - name: Enhance
+    description: >-
+      AI video super-resolution. v1 ships one model, `espcn` (ESPCN, a fixed exact 3x upscale) —
+      unrecognized `model` values 400. Requires the `enhance:write` entitlement; x402-payable

Evidence

PR Compliance ID 2497975 requires each touched source file to be <= 500 non-empty, non-comment
lines. The PR modifies openapi.yaml, and the file’s current line numbering is far beyond 500
(e.g., lines in the 1700s exist), demonstrating it exceeds the limit.

Rule 2497975: Limit source file length to 500 lines of code
openapi.yaml[1691-1740]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The touched file `openapi.yaml` exceeds the 500 non-empty, non-comment line limit.

## Issue Context
This PR adds new `Enhance` tag/path content to `openapi.yaml`, which is already far beyond 500 lines.

## Fix Focus Areas
- openapi.yaml[75-80]
- openapi.yaml[1599-1616]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context used

✅ Compliance rules (platform): 1 rule

Review mode: ⚖️ Balanced: This adds a public API contract covering authentication, payment, SSRF-sensitive URL fetching, billing, binary handling, and many error paths; one careful complete review is warranted, but the logic is localized to a single endpoint rather than dense across independent sites.

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-code-review]

Qodo Fixer

No findings are within the configured fix scope. To change which findings are fixed, adjust the setting on your Qodo configuration page.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_1a6e3fe0-9b47-4c10-8219-752aa83502f7)

[wave-bugbot]

🟢 WAVE BugBot — clear

No confident findings on the changed lines.

_{Local review · $0 inference · wave-dispatch}

[codeant-ai]

🤖 CodeAnt AI — Review Status

Status	Commit	Started (UTC)	Finished (UTC)
✅ Incremental review completed	9d746fe	Sep 06, 2026 · 05:25	05:26
✅ Reviewed your PR	0568b27	Sep 06, 2026 · 03:32	03:34

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e342da75-f29d-4a74-b977-bd37662a2f4a)

[codeant-ai]

CodeAnt Nitpicks

1 code suggestion

1. This raw conflict marker leaves the changelog with an unresolved merge artifact and causes the following MoQ and attestation entries to be duplicated.

Comment mismatch · CHANGELOG.md:65

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_92378563-2c4b-400d-932e-3625ea7bc16c)