[Actions] sdk-python: wave.compose as a finished rendering — save, run, docs on the live shape, release, live e2e

[yakimoto]

Sub-epic: the Python SDK rendering of WAVE Composer — wave.compose as a finished product surface, not just a merged module.

POST https://api.wave.online/v1/compose takes a plain-language intent and returns a grounded proposal: which WAVE products to chain, in what order, at what live price. The Python SDK is one of four renderings of that one engine (API, CLI, SDK, MCP); all four must serve the same proposal without re-implementing it.

Today (receipt)

• Add wave.compose: the PR4 Composer rendering behind POST /v1/compose #50 Add wave.compose: the Composer rendering behind POST /v1/compose MERGED 2026-09-06T20:03:25Z (feat/compose). The module exists in source.
• The engine it calls is live. Probed unauthenticated this session: POST https://api.wave.online/v1/compose with no credentials returns 402 with an x402 payment challenge naming "resource": "/v1/compose". With a key holding composer:write it returns 200, carrying these keys: callShape, engine, executes, flowId, groundedAt, grounding, id, intent, manifestHash, next, priceRows, productIds, scopes, stages, tools.
• GET https://api.wave.online/.well-known/wave-skills/composer.json returns 200 and declares auth.scope: "composer:write" and pricing.meter: "wave_compose_builds".
• What is not done: no published release carries compose yet, the dataclasses/type hints are not proven against the live response, there is no save-flow path, no run/progress/artifact surface, and no e2e in this repo's CI calls the live gateway.

Done means (live proof)

• (a) Compose live against the engine — wave.compose(...) returns a proposal fetched from POST https://api.wave.online/v1/compose. Receipt: the merged PR (Add wave.compose: the PR4 Composer rendering behind POST /v1/compose #50) plus a captured live response.
• (b) Save flow — a composed proposal persists through the authenticated bearer path and reads back by id from Python.
• (c) Run + progress + artifacts — the library can hand a proposal to a run, expose stage progress as it streams, and list the resulting artifacts.
• (d) Types, docstrings and examples grounded on the LIVE response shape — every declared field and every doc example names the keys the API actually returns (stages, priceRows, scopes, engine, executes, flowId, candidates). A test fails if a declared field is absent from a live response.
• (e) Release cut — a version bump plus a release-workflow run id as the receipt, and the published package's compose import resolves from a clean install.
• (f) e2e vs the live gateway in this repo's CI — a test asserting 402 without a key and the 200 response shape with a key, green, with the run id recorded.

Owner

Lane builds it. Jake crossing: the merge to this public repo's default branch, and any release publish.

Depends on

The runner surface behind (c) is tracked on the API side; (a), (d), (e), (f) are independent and buildable now.

Layer

Actions — the Python face of WAVE's Knowledge / Actions / Awareness triple.