feat: add portable runtime e2e tests and worker replacement on deprecation

[jumski]

This PR introduces portable runtime E2E tests that verify the edge-worker runs correctly across multiple JavaScript runtimes (Node.js, Bun, and Supabase/Deno), alongside several fixes to worker lifecycle management and heartbeat behavior.

Portable Runtime E2E Tests

A new e2e:portable-runtimes NX target and corresponding CI job (edge-worker-portable-runtime-e2e) run a shared set of example scenarios against all three runtimes. The test suite covers max_concurrency, conn_max_pg_default, conn_max_pg_override, and conn_env_var examples.

A shared portable_examples.js module centralizes handler definitions and configuration for these scenarios, replacing duplicated inline logic that previously lived in each Supabase function's index.ts. The individual function files (max_concurrency, conn_max_pg_default, conn_max_pg_override, conn_env_var) now delegate to startPortableExample.

A portable-process-worker.mjs fixture bootstraps the worker under Node or Bun using the compiled dist/index.js output, driven by environment variables.

Worker Replacement in HTTP Mode

SupabasePlatformAdapter now supports replacing a deprecated or stopped worker within the same process lifetime rather than requiring a full restart:

• ensureWorkerStarted loops until a healthy worker exists, serializing concurrent replacement attempts via workerReplacementPromise so only one replacement runs at a time.
• replaceWorker stops the old worker, generates a fresh UUID for the replacement (falling back to SB_EXECUTION_ID only for the first worker), and starts the new worker.
• workerId is tracked as instance state rather than read directly from the environment on each request.
• Worker now exposes isCreated, isStarting, isRunning, isDeprecated, and isStopped getters, backed by corresponding additions to WorkerLifecycle, FlowWorkerLifecycle, and the ILifecycle interface.

Heartbeat Deprecation Default

Queries.sendHeartbeat now returns { is_deprecated: true } when the DB returns no row (e.g., the worker record was deleted), rather than false. This ensures a worker whose DB record disappears is treated as deprecated and triggers replacement rather than continuing to run silently.

Test and CI Fixes

• startWorker and startWorkerWithAuth in the E2E helpers now retry if the HTTP response succeeds but the worker doesn't become active within 5 seconds, rather than failing immediately.
• stopped_at and authorization tests are updated to tolerate long-lived local edge isolates from previous runs sharing the same queue, avoiding false failures caused by stale worker state.
• Two new unit tests cover the deprecated-worker replacement path and concurrent replacement serialization in SupabasePlatformAdapter.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3b9e1f4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[jumski]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix: handle stop during startup with safe state transitions and hard-exit #639
• fix: preserve portable worker compatibility #633
• fix: make startOnlyOnce awaitable, deduplicate stop calls, and add packed-tarball smoke test #632
• feat: add portable runtime e2e tests and worker replacement on deprecation #631 👈 (View in Graphite)
• docs: add Node and Bun process worker deployment guide #630
• ci: add edge-worker Bun smoke test job #629
• feat: publish @pgflow/edge-worker to npm with Node/Bun process runtime support #628
• feat: add ProcessPlatformAdapter for Node.js process environments #627
• feat: add start_mode to worker functions to skip HTTP pings for process workers #626
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 3b9e1f4

Command	Status	Duration	Result
nx run edge-worker:test:integration	✅ Succeeded	4m 26s	View ↗
nx run edge-worker:e2e:portable-runtimes	✅ Succeeded	1m 37s	View ↗
nx run edge-worker:e2e	✅ Succeeded	1m 23s	View ↗
nx run client:e2e	✅ Succeeded	1m 18s	View ↗
nx affected -t verify-exports --base=origin/mai...	✅ Succeeded	3s	View ↗
nx affected -t build --configuration=production...	✅ Succeeded	4s	View ↗
nx run cli:e2e	✅ Succeeded	8s	View ↗
nx affected -t lint typecheck test --parallel -...	✅ Succeeded	47s	View ↗
Additional runs (2)	✅ Succeeded	...	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-08-18 08:34:23 UTC

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-631.pgflow.pages.dev

📝 Details:

• Branch: portable-worker-runtime-e2e
• Commit: 2cbcca22eada60b2819cef9f55ab0b9ce51c1090
• View Logs

_Last updated: _