@suaveplan/api-jobs-worker-proxy - Bidirectional MessagePort proxy that lets a worker-isolated API plugin register cron + queued jobs with the host's main-process job scheduler. Worker calls registerCron/registerQueued; main side stores handler refs and dispatches runJob RPC back to the worker when due. Universal. Stage-3 of the worker-isolation chain.

Bidirectional MessagePort proxy that lets a worker-isolated API plugin participate in the host's main-process job scheduler. The worker calls registerCron / registerQueued against a local handle implementing JobRegistrationHandle from @suaveplan/api-types; the proxy marshals the registration to the main side, which wires the closure into the real JobRegistrationHandle (typically backed by @suaveplan/job-scheduler). When the scheduler ticks a job, a runJob RPC flows back over the same port to invoke the worker's handler.

This is worker-isolation chain. The protocol layer (@suaveplan/api-worker-rpc) supplies correlation ids, abort forwarding, Zod-validated frames, and error reconstruction — this package adds only the jobs-specific verbs.

Documentation tree

client — createJobsProxyClient(port, opts) is the worker-tier entry point for the @suaveplan/api-jobs-worker-proxy package.…
- client — createJobsProxyClient(port, opts) is the worker-tier entry point for the @suaveplan/api-jobs-worker-proxy package.…
error-codes — This module owns the stable error-code registry for @suaveplan/api-jobs-worker-proxy. Every public failure path raise…
- error-codes — This module owns the stable error-code registry for @suaveplan/api-jobs-worker-proxy. Every public failure path raise…
handler-bridge — This module owns the shared wire schemas, the worker-side HandlerRegistry, and the runWithTimeout helper used by bo…
- handler-bridge — This module owns the shared wire schemas, the worker-side HandlerRegistry, and the runWithTimeout helper used by bo…
server — createJobsProxyServer(port, mainHandle, opts) runs in the host main process. It receives registerJob RPC frames fro…
- server — createJobsProxyServer(port, mainHandle, opts) runs in the host main process. It receives registerJob RPC frames fro…
testing — The testing module exposes a fully-wired in-process harness so consumers can exercise the worker-proxy surface without…
- testing — The testing module exposes a fully-wired in-process harness so consumers can exercise the worker-proxy surface without…

Module map

Subpath	File	Doc
`./worker-side`	`src/client/client.ts`	client.md
`./main-side`	`src/server/server.ts`	server.md
`./handler-bridge`	`src/handler-bridge/handler-bridge.ts`	handler-bridge.md
`./error-codes`	`src/error-codes/error-codes.ts`	error-codes.md
`./testing`	`src/testing/testing.ts`	testing.md

Scope notes

Out of scope: tick delivery for non-jobs RPC. Job ticks arrive via the runJob request envelope handled here; arbitrary request delivery for routes is the responsibility of the api-router-worker-bridge-style envelope path.
Out of scope: cron expression parsing. That is owned by @suaveplan/cron and runs on the main side.
Out of scope: per-tenant fan-out. Owned by @suaveplan/job-scheduler plus the tenant.provider capability.

Local conformance harness

The proposal originally referenced runJobsConformance from @suaveplan/job-scheduler/testing. That harness does not yet exist; this package therefore provides its own JOBS_CONFORMANCE_CASES + runJobsConformance under ./testing. The surface matches what the upstream harness is intended to be — a factory-driven scenario driver returning per-case pass/fail — so the in-repo substitute can be swapped out without changing consumers.

Verification

bunx turbo lint typecheck test --filter=@suaveplan/api-jobs-worker-proxy
bunx turbo test:coverage --filter=@suaveplan/api-jobs-worker-proxy