fix(control-plane-sdk): send the Idempotency-Key header on every required route (SPL-261)

[isuttell]

The break

packages/worker-runtime/src/steps/idempotency.ts reads the Idempotency-Key
header and nothing else. A route declaring idempotency: "required" is
therefore unusable by any client that carries the key in the request body alone.

PR #208 (SPL-150) flipped four Flag routes to required, and every Control
Panel Flag create began failing with:

Flag not created: Idempotency-Key header is required for this route

Seven e2e specs fail byte-identically on clean origin/main.

Route audit (derived from the #208 diff, not from the ticket)

#208 flipped exactly four routes, all in packages/contracts/src/routes/routes-flags.ts:

operationId	before	after
flags_create	none	required
flags_delete	none	required
flag_variants_create	optional	required
flag_variants_delete	none	required

But five routes were already required before #208 and were broken the same
way, silently: flag_variants_update, flag_config_update,
flag_targeting_rules_replace, flags_promote, experiments_start. Only
approval_request_reviews_create was correct. The two required data-plane
routes (sdk_evaluate, sdk_cached_evaluation_telemetry) are owned by
evaluation-api and served by @splitch/sdk, out of scope here.

The fix

withIdempotencyHeader moves out of approvals-client.ts — the one client that
had it right — into idempotency-header.ts and is applied at all ten required
call sites across flags-client.ts, experiments-client.ts and
approvals-client.ts. One mechanism, not two.

The key travels in both the body and the header with the same value, so a
JSON-only caller (MCP tools, CLI) and an SDK caller name the same replay. The two
DELETE routes have no request body, so they take the key from
ControlPlaneOperationOptions.idempotencyKey. A required route invoked with no
key throws in the SDK rather than coming back as a far-end VALIDATION_ERROR the
caller has to decode (ADR-0036).

No Control Panel files needed changing: every panel mutation already routes
through the typed SDK.

The regression contract

idempotency-header.contract.test.ts drives each required route through a
capturing fetch and asserts the header is on the wire. Its route list is
derived from routeRegistry filtered on idempotency === "required" && owner === "control-plane-api",
and a coverage assertion fails when a required route has no probe — so a
newly-flipped route cannot ship without a client that proves it sends the header.

Kill-proof, executed: removing the header from flags_create alone gives
1 failed | 10 passed with AssertionError: expected null to be 'idem_contract_probe';
restoring it gives Tests 11 passed (11).

Verification

• pnpm verify:ci: EXIT=0, Tasks: 85 successful, 85 total, Cached: 64 cached, 85 total. Every package touched was a cache miss: @splitch/control-plane-sdk:lint/build/typecheck/test, @splitch/control-panel:typecheck/test.
• Local e2e (flags, onboarding, experiments-setup), machine lock local-e2e-fleet held, --workers=1, SPLITCH_PLATFORM_TARGET=pr-ci: 14 passed, 1 failed. All six flags + onboarding specs named in the ticket now pass.

Not verified

• Production Flag create against the deployed revision. Deliberately not run; production is out of this branch's remit and is being escalated to the repo owner.
• experiments-setup.spec.ts still fails on Run 2 visibility. Instrumented runs show the Run start now returns 200 with the header on the wire, so idempotency is satisfied; the Experiment Setup screen simply never refetches Run history. That is a separate, previously-masked UI defect (surface adjacent to feat(control-panel): Flag editing with the Approval Request confirm gate (SPL-118) #245/SPL-121: guided Experiment creation into Run 1 (+ SPL-251 Run-start Idempotency-Key) #248), not this break.
• The run logged 8 SPL-181 miniflare D1 harness faults, a named out-of-scope known-red.

Refs SPL-261

🤖 Generated with Claude Code

---

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. To trigger a review, include @coderabbitai review in the PR description. 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9da171bf-37ab-4e1b-bd0f-b71c2793eba4

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.}

[isuttell]

Merged origin/main (#248, 09bdd59a) — two mechanisms reconciled onto one

#248 shipped its own private withIdempotencyHeader(options, body) inside
experiments-client.ts for the same defect. Git auto-merged my import of the
shared helper alongside their local definition of the same name, so the tree
briefly had a shadowing collision as well as a duplicate mechanism.

Resolution: the private helper is deleted. All three Experiment legs now go
through idempotency-header.ts. Nothing was renamed to dodge the collision.

The shared helper takes an operationId and consults the route registry, which
changes two of #248's legs:

leg	route idempotency	outcome
experiments_start	required	shared helper, key from body.idempotency_key. Unchanged behaviour.
experiments_create	optional	shared helper, key from input.idempotency_key. Unchanged behaviour.
experiments_update	none	reverted to plain hcRequestOptions.

experiments_update declares idempotency: "none" and
PatchExperimentRequestSchema is .strict() with no idempotency_key
field, so #248's mirror there could never fire for a legal caller, and
checkIdempotency returns before reading the header regardless.

Test kept vs deleted:

• Kept SPL-121: guided Experiment creation into Run 1 (+ SPL-251 Run-start Idempotency-Key) #248's Start and create header tests. They drive the panel client
  (createPanelExperimentsClient), whose mutations delegate to
  createExperimentsClient — a path idempotency-header.contract.test.ts does
  not walk. And experiments_create is optional, so the contract test's
  required-route sweep never reaches it at all. Not redundant; their comment
  updated to say which gap they cover.
• Deleted SPL-121: guided Experiment creation into Run 1 (+ SPL-251 Run-start Idempotency-Key) #248's "sends the update idempotency key as a header" test. It
  only went green because it cast an illegal field through as never; it
  asserted a property no legal caller of that route can reach.

Contract test after the merge: still green, and its coverage assertion has
nothing new to report — #248 changed no route contracts
(git diff 1d1f3fe9 09bdd59a -- packages/contracts/src/routes/ is empty).

pnpm verify:ci (one plain run, post-merge): EXIT=0,
Tasks: 85 successful, 85 total, Cached: 51 cached, 85 total. Every package
touched was a cache miss: @splitch/control-plane-sdk:lint/typecheck/test/build,
@splitch/control-panel:lint/typecheck/test/build.

Not re-run: e2e. The resolution changes request building on exactly one leg,
experiments_update, and only by removing a header the route declares it does
not read. Flag e2e is untouched.

Noted, not changed: mcp-operation-adapter.ts also sets idempotency-key
directly. It is a different transport (raw Headers + fetch for MCP JSON
args, not the hc typed-client options shape), it already applies the identical
registry rule (route.idempotency !== "none"), and it predates both PRs. Forcing
it through the hc-shaped helper would mean an adapter for the shape, so I left it
and am flagging it rather than silently unifying it.