Defer runtime PackageServiceInstance class deletion (Cloudflare 10061)

docs/contributing/architecture/runtime-worker-migration-runbook.md

@@ -166,6 +166,21 @@ npm run deploy -- --config packages/runtime-worker/wrangler-production.generated
 npm run deploy -- --config packages/worker/wrangler-production.generated.json
 ```
 
+## Deleting a transferred class
+
+A class that arrived on `kody-runtime` through `transferred_classes` keeps a
+remote binding until a deploy publishes config without that binding. Cloudflare
+rejects a same-deploy `deleted_classes` migration while that binding still
+exists (error 10061). Drop the binding first, then add the `deleted_classes`
+migration and its `tools/ci/do-deletion-allowlist.json` entry on a later deploy.
+
+`PackageServiceInstance` is in that window on production: the transferred
+binding is still present, so top-level runtime-worker tag `v2` is deferred until
+after the binding-only deploy. Preview keeps `v2` and the matching
+`tools/ci/do-deletion-allowlist.json` entry because a fresh worker applies `v1`
+`new_sqlite_classes` and cannot create an unexported class (error 10070). The
+follow-up reuses that allowlist entry when it restores top-level `v2`.
+
 ## Rollback
 
 - **Runtime deploy failed before the migration applied:** nothing moved; the old

docs/contributing/decisions/0025-no-package-services-primitive.md

@@ -34,3 +34,13 @@ Leftover `kind = 'service'` `user_storage_buckets` rows stay until the
 `storage_bucket_estimate_backfill` lane clears the matching StorageRunner
 Durable Objects and then deletes the inventory. Account export and deletion keep
 discovering those storage ids until that purge succeeds.
+
+Deleting `PackageServiceInstance` on production `kody-runtime` is two deploys.
+The class arrived through a `transferred_classes` migration, so Cloudflare still
+has a remote binding after the source binding is gone. A same-deploy
+`deleted_classes` migration fails with error 10061. Drop the remote binding
+first, then apply top-level runtime-worker tag `v2` `deleted_classes`. The
+`tools/ci/do-deletion-allowlist.json` entry for that tag stays for preview `v2`
+and is the same contract the follow-up reuses. Preview keeps `v2` because a
+fresh worker applies `v1` `new_sqlite_classes` and cannot create an unexported
+class (error 10070).

packages/runtime-worker/wrangler.jsonc

@@ -74,10 +74,11 @@
 				},
 			],
 		},
-		{
-			"tag": "v2",
-			"deleted_classes": ["PackageServiceInstance"],
-		},
+		// Production still has the transferred PackageServiceInstance
+		// binding (error 10061). Do not add deleted_classes here until
+		// after this binding-only deploy lands. Preview keeps tag v2
+		// because a fresh worker applies v1 new_sqlite_classes and
+		// cannot create an unexported class (error 10070).
 	],
 	"observability": {
 		"enabled": true,