# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

## Module map

| Subpath | File | Doc |
|---|---|---|
| `./worker-side` | [`src/client/client.ts`](./src/client/client.ts) | [client.md](./src/client/client.md) |
| `./main-side` | [`src/server/server.ts`](./src/server/server.ts) | [server.md](./src/server/server.md) |
| `./handler-bridge` | [`src/handler-bridge/handler-bridge.ts`](./src/handler-bridge/handler-bridge.ts) | [handler-bridge.md](./src/handler-bridge/handler-bridge.md) |
| `./error-codes` | [`src/error-codes/error-codes.ts`](./src/error-codes/error-codes.ts) | [error-codes.md](./src/error-codes/error-codes.md) |
| `./testing` | [`src/testing/testing.ts`](./src/testing/testing.ts) | [testing.md](./src/testing/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

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