Defer runtime PackageServiceInstance class deletion (Cloudflare 10061)

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

@@ -166,6 +166,18 @@ 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: production still has the transferred
+binding, so runtime-worker tag `v2` is deferred until after the binding-only
+deploy.
+
 ## Rollback
 
 - **Runtime deploy failed before the migration applied:** nothing moved; the old

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

@@ -34,3 +34,9 @@ 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 `kody-runtime` is two production 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 runtime-worker tag `v2` `deleted_classes`.

packages/runtime-worker/wrangler.jsonc

@@ -74,10 +74,10 @@
 				},
 			],
 		},
-		{
-			"tag": "v2",
-			"deleted_classes": ["PackageServiceInstance"],
-		},
+		// Do not add deleted_classes for PackageServiceInstance in the same
+		// deploy that drops its remote binding. Production still has the
+		// transferred binding (error 10061). Re-add tag v2 after this
+		// binding-only deploy lands.
 	],
 	"observability": {
 		"enabled": true,
@@ -267,10 +267,8 @@
 						"PackageServiceInstance",
 					],
 				},
-				{
-					"tag": "v2",
-					"deleted_classes": ["PackageServiceInstance"],
-				},
+				// Keep preview in lockstep with production: no v2
+				// deleted_classes until the production binding is gone.
 			],
 			"worker_loaders": [
 				{

tools/ci/do-deletion-allowlist.json

@@ -25,11 +25,6 @@
 			"config": "packages/worker/wrangler.jsonc",
 			"tag": "v26",
 			"classes": ["PackageServiceInstance"]
-		},
-		{
-			"config": "packages/runtime-worker/wrangler.jsonc",
-			"tag": "v2",
-			"classes": ["PackageServiceInstance"]
 		}
 	]
 }