fix(world-postgres): abort stalled HTTP delivery on shutdown

[joeyhotz]

Description

We observed this failure in a self-hosted deployment with a short termination grace period:

1. A revision received SIGTERM while Graphile Worker was delivering a step to the local Workflow HTTP route.
2. Graphile stopped taking new jobs and began its graceful-shutdown wait.
3. After that wait, Graphile aborted the task's helpers.abortSignal, but world-postgres discarded the signal, so its HTTP request kept waiting.
4. world.close() did not finish before the platform sent SIGKILL. The PostgreSQL job remained locked until Graphile's four-hour stale-lock recovery window.

The same missing abort forwarding exists on current main / the v5 beta.

This PR forwards helpers.abortSignal to fetch, including the response-body read. If graceful shutdown aborts a stalled delivery, the task rejects into Graphile's existing failure path. Graphile unlocks the same PostgreSQL row; the shutdown path inserts no replacement job.

Graphile records an attempt when it claims a row, before the HTTP call:

State when shutdown starts	Result
Delivery finishes during Graphile's grace period	Normal completion
Delivery is aborted and attempt budget remains	Same row is unlocked and becomes eligible after Graphile's normal retry backoff
Delivery is aborted on its final attempt	Same row is unlocked but is terminal

So this is a graceful lock-release fix, not guaranteed continuation of a final-attempt job. The adapter deliberately does not refund the attempt: aborting the client cannot prove that the server handler stopped, and replaying it as though the first delivery never happened could duplicate partial work.

The lifecycle changes are limited to what that shutdown requires:

• world.close() stops the queue, waits for runner.promise, then closes the streamer and internally owned pool.
• It still waits for runner.promise if Graphile.s automatic shutdown started first.
• A runner completion error cannot prevent queue, streamer, and pool cleanup; Graphile has already logged the worker failure.
• A failed world.close() call does not poison later cleanup attempts; a retry performs a fresh ordered shutdown.
• WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1 enables application-managed shutdown for the standard package target; applicationManagedShutdown: true provides the same opt-in for programmatic Worlds. The default remains false.

The application-managed mode prevents a second lifecycle race: Graphile's default handler re-sends the termination signal as soon as its worker pool stops, which can end the process before application-owned HTTP, database, or telemetry cleanup finishes.

SIGKILL can still preempt cleanup, and HTTP handlers must remain safe for at-least-once execution.

How did you test your changes?

Added loopback HTTP tests for aborting:

• While waiting for response headers.
• While reading a partial response body.
• Without creating a replacement job in either path.

Added lifecycle tests for:

• Waiting for Graphile.s completion promise when stop() returns early or reports that shutdown already started.
• Continuing queue, streamer, and pool cleanup when the runner completion promise rejects.
• Queue → streamer → internally owned pool close ordering.
• Retrying world.close() after a transient cleanup failure.
• Default, environment-configured, and programmatic application-managed shutdown behavior.
• Caller-owned pools remaining open.

Verification:

• pnpm --filter @workflow/world-postgres test (163 tests, including Testcontainers PostgreSQL conformance tests)
• pnpm --filter @workflow/world-postgres typecheck
• pnpm --filter @workflow/world-postgres build
• Executable documentation samples in packages/world-postgres/README.md (2 tests)
• Biome checks over the changed TypeScript files
• pnpm changeset status --since=upstream/main

A real PostgreSQL repro confirmed the attempt behavior above with pinned Graphile Worker 0.16.6 and current 0.17.3 (maxAttempts: 1 becomes unlocked/terminal; maxAttempts: 2 becomes unlocked/retryable). Graphile 0.17.3 does not provide an attempt-neutral cancellation primitive.

Docs Preview

The fork preview is pending Vercel Labs authorization. Direct page links will be added when the deployment is available.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 2342b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-postgres	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@joeyhotz is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[joeyhotz]

Pinging @vercel/workflow

[VaguelySerious]

LGTM, doing another AI pass before approving

[VaguelySerious]

AI review: blocking issues found

[joeyhotz]

Thanks @VaguelySerious, attended to the feedback. @vercel/workflow

[github-actions]

Backport PR opened against stable: #3082. Merge conflicts were resolved by AI — please review carefully. (backport job run)

[joeyhotz]

Description

We observed this failure in a self-hosted deployment with a short termination grace period:

1. A revision received SIGTERM while Graphile Worker was delivering a step to the local Workflow HTTP route.
2. Graphile stopped taking new jobs and began its graceful-shutdown wait.
3. After that wait, Graphile aborted the task's helpers.abortSignal, but world-postgres discarded the signal, so its HTTP request kept waiting.
4. world.close() did not finish before the platform sent SIGKILL. The PostgreSQL job remained locked until Graphile's four-hour stale-lock recovery window.

The same missing abort forwarding exists on current main / the v5 beta.

This PR forwards helpers.abortSignal to fetch, including the response-body read. If graceful shutdown aborts a stalled delivery, the task rejects into Graphile's existing failure path. Graphile unlocks the same PostgreSQL row; the shutdown path inserts no replacement job.

Graphile records an attempt when it claims a row, before the HTTP call:

State when shutdown starts	Result
Delivery finishes during Graphile's grace period	Normal completion
Delivery is aborted and attempt budget remains	Same row is unlocked and becomes eligible after Graphile's normal retry backoff
Delivery is aborted on its final attempt	Same row is unlocked but is terminal

So this is a graceful lock-release fix, not guaranteed continuation of a final-attempt job. The adapter deliberately does not refund the attempt: aborting the client cannot prove that the server handler stopped, and replaying it as though the first delivery never happened could duplicate partial work.

The lifecycle changes are limited to what that shutdown requires:

• world.close() stops the queue, waits for runner.promise, then closes the streamer and internally owned pool.
• It still waits for runner.promise if Graphile.s automatic shutdown started first.
• A runner completion error cannot prevent queue, streamer, and pool cleanup; Graphile has already logged the worker failure.
• A failed world.close() call does not poison later cleanup attempts; a retry performs a fresh ordered shutdown.
• WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1 enables application-managed shutdown for the standard package target; applicationManagedShutdown: true provides the same opt-in for programmatic Worlds. The default remains false.

The application-managed mode prevents a second lifecycle race: Graphile's default handler re-sends the termination signal as soon as its worker pool stops, which can end the process before application-owned HTTP, database, or telemetry cleanup finishes.

SIGKILL can still preempt cleanup, and HTTP handlers must remain safe for at-least-once execution.

How did you test your changes?

Added loopback HTTP tests for aborting:

• While waiting for response headers.
• While reading a partial response body.
• Without creating a replacement job in either path.

Added lifecycle tests for:

• Waiting for Graphile.s completion promise when stop() returns early or reports that shutdown already started.
• Continuing queue, streamer, and pool cleanup when the runner completion promise rejects.
• Queue → streamer → internally owned pool close ordering.
• Retrying world.close() after a transient cleanup failure.
• Default, environment-configured, and programmatic application-managed shutdown behavior.
• Caller-owned pools remaining open.

Verification:

• pnpm --filter @workflow/world-postgres test (163 tests, including Testcontainers PostgreSQL conformance tests)
• pnpm --filter @workflow/world-postgres typecheck
• pnpm --filter @workflow/world-postgres build
• Executable documentation samples in packages/world-postgres/README.md (2 tests)
• Biome checks over the changed TypeScript files
• pnpm changeset status --since=upstream/main

A real PostgreSQL repro confirmed the attempt behavior above with pinned Graphile Worker 0.16.6 and current 0.17.3 (maxAttempts: 1 becomes unlocked/terminal; maxAttempts: 2 becomes unlocked/retryable). Graphile 0.17.3 does not provide an attempt-neutral cancellation primitive.

Docs Preview

The fork preview is pending Vercel Labs authorization. Direct page links will be added when the deployment is available.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 2342b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-postgres	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@joeyhotz is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[joeyhotz]

Pinging @vercel/workflow

[VaguelySerious]

LGTM, doing another AI pass before approving

[VaguelySerious]

AI review: blocking issues found

[joeyhotz]

Thanks @VaguelySerious, attended to the feedback. @vercel/workflow

[github-actions]

Backport PR opened against stable: #3082. Merge conflicts were resolved by AI — please review carefully. (backport job run)

[joeyhotz]

Description

We observed this failure in a self-hosted deployment with a short termination grace period:

1. A revision received SIGTERM while Graphile Worker was delivering a step to the local Workflow HTTP route.
2. Graphile stopped taking new jobs and began its graceful-shutdown wait.
3. After that wait, Graphile aborted the task's helpers.abortSignal, but world-postgres discarded the signal, so its HTTP request kept waiting.
4. world.close() did not finish before the platform sent SIGKILL. The PostgreSQL job remained locked until Graphile's four-hour stale-lock recovery window.

The same missing abort forwarding exists on current main / the v5 beta.

This PR forwards helpers.abortSignal to fetch, including the response-body read. If graceful shutdown aborts a stalled delivery, the task rejects into Graphile's existing failure path. Graphile unlocks the same PostgreSQL row; the shutdown path inserts no replacement job.

Graphile records an attempt when it claims a row, before the HTTP call:

State when shutdown starts	Result
Delivery finishes during Graphile's grace period	Normal completion
Delivery is aborted and attempt budget remains	Same row is unlocked and becomes eligible after Graphile's normal retry backoff
Delivery is aborted on its final attempt	Same row is unlocked but is terminal

So this is a graceful lock-release fix, not guaranteed continuation of a final-attempt job. The adapter deliberately does not refund the attempt: aborting the client cannot prove that the server handler stopped, and replaying it as though the first delivery never happened could duplicate partial work.

The lifecycle changes are limited to what that shutdown requires:

• world.close() stops the queue, waits for runner.promise, then closes the streamer and internally owned pool.
• It still waits for runner.promise if Graphile.s automatic shutdown started first.
• A runner completion error cannot prevent queue, streamer, and pool cleanup; Graphile has already logged the worker failure.
• A failed world.close() call does not poison later cleanup attempts; a retry performs a fresh ordered shutdown.
• WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1 enables application-managed shutdown for the standard package target; applicationManagedShutdown: true provides the same opt-in for programmatic Worlds. The default remains false.

The application-managed mode prevents a second lifecycle race: Graphile's default handler re-sends the termination signal as soon as its worker pool stops, which can end the process before application-owned HTTP, database, or telemetry cleanup finishes.

SIGKILL can still preempt cleanup, and HTTP handlers must remain safe for at-least-once execution.

How did you test your changes?

Added loopback HTTP tests for aborting:

• While waiting for response headers.
• While reading a partial response body.
• Without creating a replacement job in either path.

Added lifecycle tests for:

• Waiting for Graphile.s completion promise when stop() returns early or reports that shutdown already started.
• Continuing queue, streamer, and pool cleanup when the runner completion promise rejects.
• Queue → streamer → internally owned pool close ordering.
• Retrying world.close() after a transient cleanup failure.
• Default, environment-configured, and programmatic application-managed shutdown behavior.
• Caller-owned pools remaining open.

Verification:

• pnpm --filter @workflow/world-postgres test (163 tests, including Testcontainers PostgreSQL conformance tests)
• pnpm --filter @workflow/world-postgres typecheck
• pnpm --filter @workflow/world-postgres build
• Executable documentation samples in packages/world-postgres/README.md (2 tests)
• Biome checks over the changed TypeScript files
• pnpm changeset status --since=upstream/main

A real PostgreSQL repro confirmed the attempt behavior above with pinned Graphile Worker 0.16.6 and current 0.17.3 (maxAttempts: 1 becomes unlocked/terminal; maxAttempts: 2 becomes unlocked/retryable). Graphile 0.17.3 does not provide an attempt-neutral cancellation primitive.

Docs Preview

The fork preview is pending Vercel Labs authorization. Direct page links will be added when the deployment is available.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 2342b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-postgres	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@joeyhotz is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[joeyhotz]

Pinging @vercel/workflow

[VaguelySerious]

LGTM, doing another AI pass before approving

[VaguelySerious]

AI review: blocking issues found

[joeyhotz]

Thanks @VaguelySerious, attended to the feedback. @vercel/workflow

[github-actions]

Backport PR opened against stable: #3082. Merge conflicts were resolved by AI — please review carefully. (backport job run)

[joeyhotz]

Description

We observed this failure in a self-hosted deployment with a short termination grace period:

1. A revision received SIGTERM while Graphile Worker was delivering a step to the local Workflow HTTP route.
2. Graphile stopped taking new jobs and began its graceful-shutdown wait.
3. After that wait, Graphile aborted the task's helpers.abortSignal, but world-postgres discarded the signal, so its HTTP request kept waiting.
4. world.close() did not finish before the platform sent SIGKILL. The PostgreSQL job remained locked until Graphile's four-hour stale-lock recovery window.

The same missing abort forwarding exists on current main / the v5 beta.

This PR forwards helpers.abortSignal to fetch, including the response-body read. If graceful shutdown aborts a stalled delivery, the task rejects into Graphile's existing failure path. Graphile unlocks the same PostgreSQL row; the shutdown path inserts no replacement job.

Graphile records an attempt when it claims a row, before the HTTP call:

State when shutdown starts	Result
Delivery finishes during Graphile's grace period	Normal completion
Delivery is aborted and attempt budget remains	Same row is unlocked and becomes eligible after Graphile's normal retry backoff
Delivery is aborted on its final attempt	Same row is unlocked but is terminal

So this is a graceful lock-release fix, not guaranteed continuation of a final-attempt job. The adapter deliberately does not refund the attempt: aborting the client cannot prove that the server handler stopped, and replaying it as though the first delivery never happened could duplicate partial work.

The lifecycle changes are limited to what that shutdown requires:

• world.close() stops the queue, waits for runner.promise, then closes the streamer and internally owned pool.
• It still waits for runner.promise if Graphile.s automatic shutdown started first.
• A runner completion error cannot prevent queue, streamer, and pool cleanup; Graphile has already logged the worker failure.
• A failed world.close() call does not poison later cleanup attempts; a retry performs a fresh ordered shutdown.
• WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1 enables application-managed shutdown for the standard package target; applicationManagedShutdown: true provides the same opt-in for programmatic Worlds. The default remains false.

The application-managed mode prevents a second lifecycle race: Graphile's default handler re-sends the termination signal as soon as its worker pool stops, which can end the process before application-owned HTTP, database, or telemetry cleanup finishes.

SIGKILL can still preempt cleanup, and HTTP handlers must remain safe for at-least-once execution.

How did you test your changes?

Added loopback HTTP tests for aborting:

• While waiting for response headers.
• While reading a partial response body.
• Without creating a replacement job in either path.

Added lifecycle tests for:

• Waiting for Graphile.s completion promise when stop() returns early or reports that shutdown already started.
• Continuing queue, streamer, and pool cleanup when the runner completion promise rejects.
• Queue → streamer → internally owned pool close ordering.
• Retrying world.close() after a transient cleanup failure.
• Default, environment-configured, and programmatic application-managed shutdown behavior.
• Caller-owned pools remaining open.

Verification:

• pnpm --filter @workflow/world-postgres test (163 tests, including Testcontainers PostgreSQL conformance tests)
• pnpm --filter @workflow/world-postgres typecheck
• pnpm --filter @workflow/world-postgres build
• Executable documentation samples in packages/world-postgres/README.md (2 tests)
• Biome checks over the changed TypeScript files
• pnpm changeset status --since=upstream/main

A real PostgreSQL repro confirmed the attempt behavior above with pinned Graphile Worker 0.16.6 and current 0.17.3 (maxAttempts: 1 becomes unlocked/terminal; maxAttempts: 2 becomes unlocked/retryable). Graphile 0.17.3 does not provide an attempt-neutral cancellation primitive.

Docs Preview

The fork preview is pending Vercel Labs authorization. Direct page links will be added when the deployment is available.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 2342b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-postgres	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@joeyhotz is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[joeyhotz]

Pinging @vercel/workflow

[VaguelySerious]

LGTM, doing another AI pass before approving

[VaguelySerious]

AI review: blocking issues found

[joeyhotz]

Thanks @VaguelySerious, attended to the feedback. @vercel/workflow

[github-actions]

Backport PR opened against stable: #3082. Merge conflicts were resolved by AI — please review carefully. (backport job run)

[joeyhotz]

Description

We observed this failure in a self-hosted deployment with a short termination grace period:

1. A revision received SIGTERM while Graphile Worker was delivering a step to the local Workflow HTTP route.
2. Graphile stopped taking new jobs and began its graceful-shutdown wait.
3. After that wait, Graphile aborted the task's helpers.abortSignal, but world-postgres discarded the signal, so its HTTP request kept waiting.
4. world.close() did not finish before the platform sent SIGKILL. The PostgreSQL job remained locked until Graphile's four-hour stale-lock recovery window.

The same missing abort forwarding exists on current main / the v5 beta.

This PR forwards helpers.abortSignal to fetch, including the response-body read. If graceful shutdown aborts a stalled delivery, the task rejects into Graphile's existing failure path. Graphile unlocks the same PostgreSQL row; the shutdown path inserts no replacement job.

Graphile records an attempt when it claims a row, before the HTTP call:

State when shutdown starts	Result
Delivery finishes during Graphile's grace period	Normal completion
Delivery is aborted and attempt budget remains	Same row is unlocked and becomes eligible after Graphile's normal retry backoff
Delivery is aborted on its final attempt	Same row is unlocked but is terminal

So this is a graceful lock-release fix, not guaranteed continuation of a final-attempt job. The adapter deliberately does not refund the attempt: aborting the client cannot prove that the server handler stopped, and replaying it as though the first delivery never happened could duplicate partial work.

The lifecycle changes are limited to what that shutdown requires:

• world.close() stops the queue, waits for runner.promise, then closes the streamer and internally owned pool.
• It still waits for runner.promise if Graphile.s automatic shutdown started first.
• A runner completion error cannot prevent queue, streamer, and pool cleanup; Graphile has already logged the worker failure.
• A failed world.close() call does not poison later cleanup attempts; a retry performs a fresh ordered shutdown.
• WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1 enables application-managed shutdown for the standard package target; applicationManagedShutdown: true provides the same opt-in for programmatic Worlds. The default remains false.

The application-managed mode prevents a second lifecycle race: Graphile's default handler re-sends the termination signal as soon as its worker pool stops, which can end the process before application-owned HTTP, database, or telemetry cleanup finishes.

SIGKILL can still preempt cleanup, and HTTP handlers must remain safe for at-least-once execution.

How did you test your changes?

Added loopback HTTP tests for aborting:

• While waiting for response headers.
• While reading a partial response body.
• Without creating a replacement job in either path.

Added lifecycle tests for:

• Waiting for Graphile.s completion promise when stop() returns early or reports that shutdown already started.
• Continuing queue, streamer, and pool cleanup when the runner completion promise rejects.
• Queue → streamer → internally owned pool close ordering.
• Retrying world.close() after a transient cleanup failure.
• Default, environment-configured, and programmatic application-managed shutdown behavior.
• Caller-owned pools remaining open.

Verification:

• pnpm --filter @workflow/world-postgres test (163 tests, including Testcontainers PostgreSQL conformance tests)
• pnpm --filter @workflow/world-postgres typecheck
• pnpm --filter @workflow/world-postgres build
• Executable documentation samples in packages/world-postgres/README.md (2 tests)
• Biome checks over the changed TypeScript files
• pnpm changeset status --since=upstream/main

A real PostgreSQL repro confirmed the attempt behavior above with pinned Graphile Worker 0.16.6 and current 0.17.3 (maxAttempts: 1 becomes unlocked/terminal; maxAttempts: 2 becomes unlocked/retryable). Graphile 0.17.3 does not provide an attempt-neutral cancellation primitive.

Docs Preview

The fork preview is pending Vercel Labs authorization. Direct page links will be added when the deployment is available.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 2342b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-postgres	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@joeyhotz is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[joeyhotz]

Pinging @vercel/workflow

[VaguelySerious]

LGTM, doing another AI pass before approving

[VaguelySerious]

AI review: blocking issues found

[joeyhotz]

Thanks @VaguelySerious, attended to the feedback. @vercel/workflow

[github-actions]

Backport PR opened against stable: #3082. Merge conflicts were resolved by AI — please review carefully. (backport job run)

[joeyhotz]

Description

We observed this failure in a self-hosted deployment with a short termination grace period:

1. A revision received SIGTERM while Graphile Worker was delivering a step to the local Workflow HTTP route.
2. Graphile stopped taking new jobs and began its graceful-shutdown wait.
3. After that wait, Graphile aborted the task's helpers.abortSignal, but world-postgres discarded the signal, so its HTTP request kept waiting.
4. world.close() did not finish before the platform sent SIGKILL. The PostgreSQL job remained locked until Graphile's four-hour stale-lock recovery window.

The same missing abort forwarding exists on current main / the v5 beta.

This PR forwards helpers.abortSignal to fetch, including the response-body read. If graceful shutdown aborts a stalled delivery, the task rejects into Graphile's existing failure path. Graphile unlocks the same PostgreSQL row; the shutdown path inserts no replacement job.

Graphile records an attempt when it claims a row, before the HTTP call:

State when shutdown starts	Result
Delivery finishes during Graphile's grace period	Normal completion
Delivery is aborted and attempt budget remains	Same row is unlocked and becomes eligible after Graphile's normal retry backoff
Delivery is aborted on its final attempt	Same row is unlocked but is terminal

So this is a graceful lock-release fix, not guaranteed continuation of a final-attempt job. The adapter deliberately does not refund the attempt: aborting the client cannot prove that the server handler stopped, and replaying it as though the first delivery never happened could duplicate partial work.

The lifecycle changes are limited to what that shutdown requires:

• world.close() stops the queue, waits for runner.promise, then closes the streamer and internally owned pool.
• It still waits for runner.promise if Graphile.s automatic shutdown started first.
• A runner completion error cannot prevent queue, streamer, and pool cleanup; Graphile has already logged the worker failure.
• A failed world.close() call does not poison later cleanup attempts; a retry performs a fresh ordered shutdown.
• WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1 enables application-managed shutdown for the standard package target; applicationManagedShutdown: true provides the same opt-in for programmatic Worlds. The default remains false.

The application-managed mode prevents a second lifecycle race: Graphile's default handler re-sends the termination signal as soon as its worker pool stops, which can end the process before application-owned HTTP, database, or telemetry cleanup finishes.

SIGKILL can still preempt cleanup, and HTTP handlers must remain safe for at-least-once execution.

How did you test your changes?

Added loopback HTTP tests for aborting:

• While waiting for response headers.
• While reading a partial response body.
• Without creating a replacement job in either path.

Added lifecycle tests for:

• Waiting for Graphile.s completion promise when stop() returns early or reports that shutdown already started.
• Continuing queue, streamer, and pool cleanup when the runner completion promise rejects.
• Queue → streamer → internally owned pool close ordering.
• Retrying world.close() after a transient cleanup failure.
• Default, environment-configured, and programmatic application-managed shutdown behavior.
• Caller-owned pools remaining open.

Verification:

• pnpm --filter @workflow/world-postgres test (163 tests, including Testcontainers PostgreSQL conformance tests)
• pnpm --filter @workflow/world-postgres typecheck
• pnpm --filter @workflow/world-postgres build
• Executable documentation samples in packages/world-postgres/README.md (2 tests)
• Biome checks over the changed TypeScript files
• pnpm changeset status --since=upstream/main

A real PostgreSQL repro confirmed the attempt behavior above with pinned Graphile Worker 0.16.6 and current 0.17.3 (maxAttempts: 1 becomes unlocked/terminal; maxAttempts: 2 becomes unlocked/retryable). Graphile 0.17.3 does not provide an attempt-neutral cancellation primitive.

Docs Preview

The fork preview is pending Vercel Labs authorization. Direct page links will be added when the deployment is available.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 2342b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-postgres	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@joeyhotz is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[joeyhotz]

Pinging @vercel/workflow

[VaguelySerious]

LGTM, doing another AI pass before approving

[VaguelySerious]

AI review: blocking issues found

[joeyhotz]

Thanks @VaguelySerious, attended to the feedback. @vercel/workflow

[github-actions]

Backport PR opened against stable: #3082. Merge conflicts were resolved by AI — please review carefully. (backport job run)

[joeyhotz]

Description

We observed this failure in a self-hosted deployment with a short termination grace period:

1. A revision received SIGTERM while Graphile Worker was delivering a step to the local Workflow HTTP route.
2. Graphile stopped taking new jobs and began its graceful-shutdown wait.
3. After that wait, Graphile aborted the task's helpers.abortSignal, but world-postgres discarded the signal, so its HTTP request kept waiting.
4. world.close() did not finish before the platform sent SIGKILL. The PostgreSQL job remained locked until Graphile's four-hour stale-lock recovery window.

The same missing abort forwarding exists on current main / the v5 beta.

This PR forwards helpers.abortSignal to fetch, including the response-body read. If graceful shutdown aborts a stalled delivery, the task rejects into Graphile's existing failure path. Graphile unlocks the same PostgreSQL row; the shutdown path inserts no replacement job.

Graphile records an attempt when it claims a row, before the HTTP call:

State when shutdown starts	Result
Delivery finishes during Graphile's grace period	Normal completion
Delivery is aborted and attempt budget remains	Same row is unlocked and becomes eligible after Graphile's normal retry backoff
Delivery is aborted on its final attempt	Same row is unlocked but is terminal

So this is a graceful lock-release fix, not guaranteed continuation of a final-attempt job. The adapter deliberately does not refund the attempt: aborting the client cannot prove that the server handler stopped, and replaying it as though the first delivery never happened could duplicate partial work.

The lifecycle changes are limited to what that shutdown requires:

• world.close() stops the queue, waits for runner.promise, then closes the streamer and internally owned pool.
• It still waits for runner.promise if Graphile.s automatic shutdown started first.
• A runner completion error cannot prevent queue, streamer, and pool cleanup; Graphile has already logged the worker failure.
• A failed world.close() call does not poison later cleanup attempts; a retry performs a fresh ordered shutdown.
• WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1 enables application-managed shutdown for the standard package target; applicationManagedShutdown: true provides the same opt-in for programmatic Worlds. The default remains false.

The application-managed mode prevents a second lifecycle race: Graphile's default handler re-sends the termination signal as soon as its worker pool stops, which can end the process before application-owned HTTP, database, or telemetry cleanup finishes.

SIGKILL can still preempt cleanup, and HTTP handlers must remain safe for at-least-once execution.

How did you test your changes?

Added loopback HTTP tests for aborting:

• While waiting for response headers.
• While reading a partial response body.
• Without creating a replacement job in either path.

Added lifecycle tests for:

• Waiting for Graphile.s completion promise when stop() returns early or reports that shutdown already started.
• Continuing queue, streamer, and pool cleanup when the runner completion promise rejects.
• Queue → streamer → internally owned pool close ordering.
• Retrying world.close() after a transient cleanup failure.
• Default, environment-configured, and programmatic application-managed shutdown behavior.
• Caller-owned pools remaining open.

Verification:

• pnpm --filter @workflow/world-postgres test (163 tests, including Testcontainers PostgreSQL conformance tests)
• pnpm --filter @workflow/world-postgres typecheck
• pnpm --filter @workflow/world-postgres build
• Executable documentation samples in packages/world-postgres/README.md (2 tests)
• Biome checks over the changed TypeScript files
• pnpm changeset status --since=upstream/main

A real PostgreSQL repro confirmed the attempt behavior above with pinned Graphile Worker 0.16.6 and current 0.17.3 (maxAttempts: 1 becomes unlocked/terminal; maxAttempts: 2 becomes unlocked/retryable). Graphile 0.17.3 does not provide an attempt-neutral cancellation primitive.

Docs Preview

The fork preview is pending Vercel Labs authorization. Direct page links will be added when the deployment is available.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)
• 📝 Ping @vercel/workflow in a comment once the PR is ready, and the above checklist is complete

[changeset-bot]

🦋 Changeset detected

Latest commit: 2342b1e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@workflow/world-postgres	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@joeyhotz is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[joeyhotz]

Pinging @vercel/workflow

[VaguelySerious]

LGTM, doing another AI pass before approving

[VaguelySerious]

AI review: blocking issues found

[joeyhotz]

Thanks @VaguelySerious, attended to the feedback. @vercel/workflow

[github-actions]

Backport PR opened against stable: #3082. Merge conflicts were resolved by AI — please review carefully. (backport job run)