fix: preserve portable worker compatibility

[jumski]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 621f55e

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 👈 (View in Graphite)
• 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
• 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 75cf582

Command	Status	Duration	Result
nx test:types:health dsl	✅ Succeeded	9s	View ↗

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

---

☁️ Nx Cloud last updated this comment at 2026-08-18 13:12:50 UTC

[graphite-app]

Critical Bug: Validation requires process.off to exist, but the type system treats offSignal as optional.

The validation throws an error if processLike.off is undefined, breaking compatibility with environments where process.off() doesn't exist (like older Node.js versions or some runtime environments).

This contradicts:

1. The optional type: offSignal?: (signal: ProcessSignal, handler: ...) => void
2. The usage with optional chaining: this.deps.offSignal?.(signal, this.signalHandler) at line 160 in ProcessPlatformAdapter

Fix: Remove the !processLike.off check from the validation:

if (
  !processLike?.env ||
  !processLike.on ||
  !processLike.exit ||
  !cryptoLike?.randomUUID
) {
  throw new Error('Process runtime is not available');
}

Then update line 41 to handle the missing method:

offSignal: processLike.off ? (signal, handler) => processLike.off?.(signal, handler) : undefined,

Suggested change

	if (
	!processLike?.env ||
	!processLike.on ||
	!processLike.off ||
	!processLike.exit ||
	!cryptoLike?.randomUUID
	) {
	if (
	!processLike?.env ||
	!processLike.on ||
	!processLike.exit ||
	!cryptoLike?.randomUUID
	) {

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

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

📝 Details:

• Branch: portable-worker-release-followups
• Commit: c13c75874f3d9d1b122f78e97ce0cfdd5b9fbf3b
• View Logs

_Last updated: _

[Keegs12]

P1 — shutdown can race initial Supabase worker startup

SupabasePlatformAdapter.stopWorker() can call worker.stop() while the first HTTP request is still awaiting worker.startOnlyOnce(). Worker.stop() immediately calls lifecycle.transitionToStopping(), but a pending WorkerLifecycle is still Created or Starting; neither state permits a direct transition to Stopping. The shutdown callback can therefore reject before the worker drains or gets stopped_at recorded, and startup may continue after shutdown was requested.

Affected paths: pkgs/edge-worker/src/platform/SupabasePlatformAdapter.ts and pkgs/edge-worker/src/core/Worker.ts.

Please coordinate startup/stop through one lifecycle gate—await/cancel startupPromise before transitioning, or add an explicit startup-cancellation path—and add coverage for shutdown during acknowledgeStart() in both Created and Starting states.

[Keegs12]

P3 — process.off is required despite the optional contract

ProcessDeps.offSignal and ProcessLike.off are optional, and cleanup already uses optional chaining, but getProcessDeps() rejects any runtime without process.off. That turns a supported compatibility case into a startup failure.

Please remove !processLike.off from the required-runtime check, construct offSignal only when available, and add coverage for a process-like runtime with on but no off. This is also the unresolved compatibility concern already raised on this PR.

[Keegs12]

P2 — first process signal can block indefinitely during startup

ProcessPlatformAdapter.startWorker() installs SIGTERM/SIGINT/SIGQUIT handlers before performStartWorker() completes. A first signal enters gracefulExit() → stopWorker() and waits on startupPromise; if DB connection, queue creation, flow compilation, or startup hangs, the first signal never completes and only a second signal exits immediately with code 1.

This regresses the previous post-start handler ordering. Please make startup cancellation/bounded cleanup explicit, or provide a bootstrap signal path that does not wait indefinitely, and add a test where startup never resolves but the first signal still terminates deterministically.

[jumski]

thanks for the feedback @Keegs12 i'll handle it shortly!