Area: docs · sdk — gap · found via WaveHouse-Stats dogfooding (their PR #62, 2026-08-25)
Expected: someone installing @wavehouse/sdk can tell which server versions it is expected to work against, and how to pin the pair so their CI and their server don't drift.
Actual: no compatibility policy is stated anywhere. The two artifact families version and publish independently — the server as vX.Y.Z (GHCR :latest), the SDK as clients/ts/vX.Y.Z (npm latest) — and the npm channel already advances on a client-only release:
newest server release v0.1.0 (2026-08-19)
npm @wavehouse/sdk latest -> 0.1.1 (clients/ts/v0.1.1, 2026-08-20, no server image)
docs/src/content/docs/sdk/index.mdx:61 actively recommends floating ranges (@0, @0.1, or a bare CDN URL that "tracks the latest published release"), and inside 0.x a minor bump is allowed to be breaking. development.md:617-630 documents the tag scheme and the channel rule, but only as release mechanics — it never says what a consumer is supposed to do with two families that move apart.
Impact: a consumer pinned to a floating SDK range can land ahead of the server it talks to, with nothing that detects it. This is not hypothetical: the first-party Stats deployment moved its box image and CI SDK onto the stable channel and had to write the hazard down itself as a residual risk, because our docs don't answer it. The same question is the first one an external adopter or the SCC-2026 pilot will ask on upgrade.
Note: the adjacent, already-shipped variant of this — CI tracking :dev while the box's auto-update was held — cost that deployment two outages, and stayed invisible until #479 renamed a route family.
Ref: docs/src/content/docs/sdk/index.mdx:61, docs/src/content/docs/development.md:617-630, docs/src/content/docs/deployment.md:86
Scope: a stated policy plus pinning guidance in the SDK + deployment docs — not a version-negotiation mechanism (/version and the OpenAPI work in #302 are where that would live if it's ever wanted).
Related: #501 (release follow-ups — item 1 is the same two-families-one-pointer root cause on the GitHub "Latest" badge), #302, #503
From WaveHouse-Stats dogfooding (Wave-RF/WaveHouse-Stats#62, merged 2026-08-25); validated by code-read and by npm view @wavehouse/sdk dist-tags + gh release list against b2eee9d on 2026-08-26.
Area: docs · sdk — gap · found via WaveHouse-Stats dogfooding (their PR #62, 2026-08-25)
Expected: someone installing
@wavehouse/sdkcan tell which server versions it is expected to work against, and how to pin the pair so their CI and their server don't drift.Actual: no compatibility policy is stated anywhere. The two artifact families version and publish independently — the server as
vX.Y.Z(GHCR:latest), the SDK asclients/ts/vX.Y.Z(npmlatest) — and the npm channel already advances on a client-only release:docs/src/content/docs/sdk/index.mdx:61actively recommends floating ranges (@0,@0.1, or a bare CDN URL that "tracks the latest published release"), and inside0.xa minor bump is allowed to be breaking.development.md:617-630documents the tag scheme and the channel rule, but only as release mechanics — it never says what a consumer is supposed to do with two families that move apart.Impact: a consumer pinned to a floating SDK range can land ahead of the server it talks to, with nothing that detects it. This is not hypothetical: the first-party Stats deployment moved its box image and CI SDK onto the stable channel and had to write the hazard down itself as a residual risk, because our docs don't answer it. The same question is the first one an external adopter or the SCC-2026 pilot will ask on upgrade.
Note: the adjacent, already-shipped variant of this — CI tracking
:devwhile the box's auto-update was held — cost that deployment two outages, and stayed invisible until #479 renamed a route family.Ref:
docs/src/content/docs/sdk/index.mdx:61,docs/src/content/docs/development.md:617-630,docs/src/content/docs/deployment.md:86Scope: a stated policy plus pinning guidance in the SDK + deployment docs — not a version-negotiation mechanism (
/versionand the OpenAPI work in #302 are where that would live if it's ever wanted).Related: #501 (release follow-ups — item 1 is the same two-families-one-pointer root cause on the GitHub "Latest" badge), #302, #503
From WaveHouse-Stats dogfooding (
Wave-RF/WaveHouse-Stats#62, merged 2026-08-25); validated by code-read and bynpm view @wavehouse/sdk dist-tags+gh release listagainstb2eee9don 2026-08-26.