skills/plugins/document-navigator/docs/api-stack/api/api-jobs-worker-proxy

@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