Tighten browser pool update boundaries

[IlyaasK]

Summary

• plan replacement when an existing browser-pool name or viewport is removed because the API cannot clear those fields in place
• clear profile_id in place with the SDK-documented profile: {"id": ""} payload
• preserve semantically equivalent chrome_policy JSON so key ordering and whitespace changes remain no-op plans
• preserve stable API-computed values during unrelated updates without copying a null nested viewport.refresh_rate into a new viewport
• normalize omitted and explicitly empty extension_ids so imported pools with no extensions remain no-op plans
• document that each Kernel organization determines its maximum fill_rate_per_minute

Why

Terraform plans must describe what apply can actually perform. Name and viewport removal previously appeared as in-place updates but failed because the API cannot clear them. They now show replacement before approval. Profile removal remains an in-place update because the pinned Kernel SDK explicitly supports clearing the profile reference with an empty ID.

Formatting-only Chrome policy edits and omitted computed defaults also produced noisy plans. The plan modifiers keep semantically unchanged durable state stable while preserving unknown values when the API must choose a default for a newly configured nested viewport.

Fill-rate limits are organization-specific. The provider enforces only the nonnegative SDK contract and leaves each organization's effective maximum to the Kernel API.

Customer impact

• removing name or viewport truthfully shows destroy/create replacement
• replacement plans warn that completing replacement deletes the existing pool and all browsers in it; leased browsers block non-forceful deletion
• removing profile_id updates the existing pool without changing its ID
• equivalent Chrome policy JSON does not update the pool or rebuild idle browsers
• unrelated edits keep known API defaults stable in the plan
• imported pools with no extensions accept either omission or extension_ids = [] without drift

Verification

• focused race tests repeated 20 times for nested refresh-rate planning and browser-pool plan modifiers
• go test -short -timeout=2m ./...
• go vet ./...
• gofmt -l cmd internal
• bash scripts/check-docs.sh
• bash scripts/check-markdown-links.sh
• bash scripts/check-examples.sh
• structured branch review against the current feat: add opt-in idle browser rebuilds #114 head: clean after accepted findings

The live acceptance suite was not rerun after this restack. The original branch previously passed its live browser-pool checks; a fresh live run remains appropriate before merge if credentials are available.

Stacked on #114.

---

Note

Medium Risk
Changes Terraform plan/apply semantics for browser pools (replacement on name/viewport removal, in-place profile clear, and computed attribute planning), which can surprise operators but is covered by expanded unit tests rather than touching auth or payments.

Overview
Aligns kernel_browser_pool Terraform planning and updates with what the Kernel API can actually do in place versus what requires pool replacement.

Clear vs replace: Removing name or viewport now plans destroy/create (schema RequiresReplaceIf + ModifyPlan warning about deleting the pool and leased-browser blocking). Clearing profile_id is now a supported in-place patch (profile.id = ""), with the old “cannot clear profile” validation removed.

Quieter, stabler plans: Semantically equivalent chrome_policy JSON no longer forces updates (custom plan modifier). extension_ids is optional+computed with create-time default [] and UseStateForUnknown so omitted config on existing/imported pools does not drift; import seeds an empty list. Computed launch/metadata fields (headless, timeout_seconds, fill_rate_per_minute, etc.) keep prior state on unrelated edits; new viewport.refresh_rate stays unknown until the API default is known.

Docs and tests cover replacement planning, profile clear payloads, chrome policy equivalence, and extension list behavior.

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