[world-postgres] Add a producer role that enqueues without a runner or startup recovery

[Ehco1996]

Description

A process that only ever enqueues cannot avoid getting a consumer. queue() begins with await start(), and start() both starts a graphile-worker runner and calls reenqueueActiveRuns(). In the common "API process starts runs, worker process executes them" topology — where only the worker compiled the "use workflow" / "use step" code and serves .well-known/workflow/v1/* — both of those are unwanted in the API. Its runner claims due jobs and then fails their HTTP delivery whenever the worker has no ready endpoint (a rolling update, for instance), manufacturing failures the worker's own runner never produces, because that one dies together with its executor and leaves the job waiting. And every API replica runs full startup recovery, so N replicas rolling means N re-enqueues of every active run on top of the worker's own.

This adds role?: 'producer' | 'worker' to PostgresWorldConfig, defaulting to 'worker' — today's behaviour, no change for existing users. WORKFLOW_POSTGRES_ROLE is read lazily as a fallback, matching how the package's other options pick up environment configuration when it is selected through WORKFLOW_TARGET_WORLD. Under 'producer', start() still creates the worker utils, runs workerUtils.migrate(), and runs the pg-boss job migration, so a producer can enqueue into a fresh database; what it never does is call graphile's run() (none of the setupListeners / startRunnerWhenExecutorIsReady / deferRunnerStart paths) or reenqueueActiveRuns(). queue() is untouched, and close() already tolerates a null runner, so it ends only what was opened. Nothing about the recovery predicate changes: this removes N of the N+1 recovery sources behind #3119 and #3758 for this topology, and leaves the remaining one — the worker's own — exactly as it is.

How did you test your changes?

Unit tests in the two existing world-postgres suites, which already mock graphile-worker, so "no runner" is asserted directly on run() rather than inferred from a timeout.

src/reenqueue.test.ts (World level):

• starts a graphile runner and recovers active runs in the default role — pins the unchanged default.
• does not start a graphile runner in the producer role — run() not called, migrate() still called.
• does not re-enqueue active runs in the producer role — two active runs listed, no addJob.
• still enqueues messages in the producer role — world.queue(...) lands a workflow_flows job, still no runner.
• reads the producer role from WORKFLOW_POSTGRES_ROLE.
• ignores an unrecognized WORKFLOW_POSTGRES_ROLE — falls through to worker.
• closes only what a producer opened — runner.stop() not called, workerUtils.release() called once.

src/queue.test.ts (queue level):

• never starts a runner in the producer role, even when a local executor is reachable — a real loopback HTTP server is listening and PORT is set, so the unfixed code starts the runner synchronously inside start(); the producer starts none, enqueues fine, and the server receives no request.

All six new cases fail against unmodified main and pass with the change.

Commands run locally:

• pnpm exec biome ci --max-diagnostics=200 — exit 0 (warning count unchanged; the only warning in the touched files is the pre-existing createTaskHandler complexity one).
• node scripts/check-no-unrun-tests.mjs — pass.
• node scripts/check-changesets.mjs — pass, 1 pending changeset, 1 package released.
• tsc --noEmit in packages/world-postgres — clean. (pnpm turbo typecheck could not run end to end here: the dependency graph builds @workflow/swc-plugin, which needs a Rust toolchain with the wasm32-unknown-unknown target that this machine does not have.)
• vitest run src/ in packages/world-postgres — 4 files, 35 tests passed.
• vitest run src -t "packages/world-postgres/README.md" in packages/docs-typecheck — 3 samples pass, including the new one.
• bun ./scripts/lint.ts in docs — 0 errors.
• The three test/*.test.ts integration suites could not run: they start a Postgres testcontainer and there is no container runtime available here. They are untouched by this change, which adds no storage or SQL code.

Docs: role documented alongside queueConcurrency and applicationManagedShutdown in packages/world-postgres/README.md (options table, environment-variable table, and a short "Producer-only processes" section), in docs/content/docs/v5/configuration/worlds.mdx, and as WORKFLOW_POSTGRES_ROLE in docs/content/worlds/v5/postgres.mdx.

Closes #3968

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

🤖 Generated with Claude Code

PostgresWorldRoleSchema is exported as a value from the package index alongside the PostgresWorldRole type, so a consumer can pass role: PostgresWorldRoleSchema.enum.producer instead of spelling the literal.

[changeset-bot]

🦋 Changeset detected

Latest commit: 633b58d

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	Minor

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]

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

A member of the Team first needs to authorize it.