test(kube): compose the save path against a real API server

[sunib]

Stacked on #57 (→ #55 → #54 → #53). This PR adds two commits; the PRs below it are unchanged. A third commit, the CI workflow, is not pushed yet: see Making it merge evidence.

Implements priority 3 of proposal 0006: real-API save composition and identity races.

Harness

The TestRealAPI cases (gateway/kube/composition_e2e_test.go, build tag e2e) compose:

• a real API server;
• the real gateway over the real kube backend;
• a host save endpoint;
• the real browser store and conditional editor, run under node by packages/krm-stream/e2e/store-driver.ts.

The Go side decides exactly when each stream event reaches the browser, so the races are staged on purpose rather than hoped for. No browser logic is reimplemented in Go.

Cases

0006 requirement	Case	What it asserts
Status churn, real status subresource	TestRealAPIStatusChurnUnderSpecProjection	A test-installed Widget CRD has a status subresource. Under krm-spec/v1: the status write advances RV (checked numerically); the gateway suppresses it (observation, and the stream stays quiet); the captured save gets a real 409; the guarded projected GET advances the base with no field conflicts (version-stale) and no status leak; a fresh intent saves; the controller's status survives; the echo settles the draft.
Contrast: full projection	TestRealAPIStatusChangeIsDeliveredUnderFullProjection	The same write is delivered, the base advances, and the save needs no refusal (PATCH 204 only).
Contrast: bookkeeping-only	TestRealAPIBookkeepingOnlyWriteUnderFullProjection	A new server-side-apply manager claiming an existing value changes only managedFields. It does advance RV, unlike a no-op reapply, which isn't a valid fixture. krm-full/v1 suppresses it, and the save goes 409 → version-stale → saved.
Overlapping recovery	TestRealAPIOverlappingRecovery	The save starts live and gets 409. The host holds the reconciliation GET until a closed upstream watch has begun a new snapshot (reset), and the read lands before synced. The guard refuses it (the base is still the delivered version), the draft is kept, and the editor reports recovering. After synced, Save does only a GET (version-stale), then one deliberate PATCH 204. There are no blind PATCH retries.
UID race	TestRealAPIReplacementBetweenPreflightAndPatch	A test-only transport barrier deletes and recreates the ConfigMap between the real conditionalsave handler's preflight GET and its PATCH. The response is a structured Kubernetes Status naming the replacement in details.uid. The replacement is unchanged, the editor reports unavailable, and the replacement opens with no old draft.
Never normalize 422 to conflicts	TestRealAPIValidationErrorIsNotAConflict	A real invalid-label 422 keeps its reason and metadata.labels causes, and the object is unchanged.

What the race revealed, and the fix (8d67d44)

Against a real API server, the replaced object's PATCH fails the captured resourceVersion check before the UID check. So it arrives as a plain 409 Conflict, indistinguishable from a stale write. Only when the RV matches does the uid precondition give 422 field is immutable, and that can't happen in a race. The example host also flattened every error to bare status text. Now:

• Kubernetes errors are answered with the Status JSON, keeping code, reason and causes. A non-API failure is reported without its text.
• After a 409, or a 422 caused by metadata.uid, one GET classifies the failure: a different UID becomes 409 "object was replaced" with details.uid; a vanished object becomes 404. Every other 422 passes through unchanged.
• The example editor reports a PATCH 404 as unavailable instead of throwing a host error.

Fake-client unit tests cover each branch.

Making it merge evidence

• task test-real-api runs the cases on the spike cluster. task test-cluster still runs everything tagged e2e.

• Pending push: commit bc78e95 (ci: run the real-API save composition on pull requests and on demand) adds .github/workflows/real-api.yml and the doc lines that point at it. GitHub refused it from this machine because the token here lacks the workflow scope; it is on the local test/real-api-save-races branch, on top of what is pushed. The workflow:

  • runs on pull requests that touch the save path (gateway, client src, the driver, the conditional-save example, the workflow), and on demand;
  • starts k3d with the Taskfile's K3s image and embedded etcd;
  • records the commit, server version, command and each case in its summary, and uploads the JSON results.

  ci.yml and the release gate stay cluster-free. A workflow_dispatch-only workflow can't run before it exists on main, so the PR trigger is what lets it produce evidence for this PR. Until it is pushed, the evidence is the local run below.

Evidence from this run

• Commit: 2268916cf8e08650de1468d5832e61b125de2391 (the pushed head; the 3× repeat, task test-cluster and task verify ran on a commit with identical code that also contained the workflow)
• Server: v1.36.4+k3s1 (k3d krm-stream-spike)
• Command: go test -tags e2e -count=1 -run '^TestRealAPI' -v . in gateway/kube

Results:

• All 6 cases passed, and passed again in a 3× repeat: 18/18.
• task test-cluster passed 43 tests with 0 failures and 0 skips, including the aggregated-API fallback and the shared-host example.
• task verify passes: client 144/144, browser 20/20.

The cases were also checked by breaking the code on purpose:

• restoring the old handler fails the UID-race and validation cases (plain-text bodies);
• a store guard that ignores the open snapshot fails the overlapping-recovery case (base=<new RV>).

Not run: the CI workflow, pending the push above. Nothing was skipped.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6d23becd-3c04-410d-8408-2ca97ac3b5a6

📥 Commits

Reviewing files that changed from the base of the PR and between 8c48eb2 and 2268916.

📒 Files selected for processing (12)

• CONTRIBUTING.md
• Taskfile.yml
• docs/proposals/0006-stream-and-save-implementation-plan.md
• docs/saving.md
• examples/conditional-save/README.md
• examples/conditional-save/editor.ts
• gateway/kube/composition_e2e_test.go
• gateway/kube/e2e_test.go
• gateway/kube/examples/conditionalsave/handler.go
• gateway/kube/examples/conditionalsave/handler_test.go
• packages/krm-stream/e2e/store-driver.ts
• packages/krm-stream/test/saving.test.ts

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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