Initial Commit

openspec/archive/2026-05-25-api-jobs-worker-proxy/proposal.md

@@ -0,0 +1,45 @@
+# `@suaveplan/api-jobs-worker-proxy` — worker-side proxy to main-process job scheduler
+
+**Package**: `@suaveplan/api-jobs-worker-proxy`
+**Status**: PROPOSED
+**Type**: new-package
+**Stage**: 3 (Worker isolation infrastructure)
+
+## Why
+
+Per design doc §5.4, plugins register jobs (cron + on-demand + per-tenant fan-out) via their manifest, and the host's job scheduler — `@suaveplan/job-scheduler` — owns the actual scheduling, ticking, and per-tenant fan-out. Worker-tier plugins still need a `ctx.jobs` slot that lets them do the runtime work (enqueue an on-demand run, observe a registration handle), so this proxy surfaces those operations over `MessagePort`. Job TICKS themselves arrive at the worker via the same request-dispatch path used by routes — this proxy is for the registration-handle side of the contract, not the tick delivery.
+
+## What changes
+
+Net-new package.
+
+**ADDED exports:**
+
+- `./client` — `createJobsProxyClient(port): WorkerProxyOf<JobRegistrationHandle>`. Worker-side `ctx.jobs.enqueue(...)`, `ctx.jobs.pause(...)`, `ctx.jobs.resume(...)` calls marshal to the main-process `@suaveplan/job-scheduler`.
+- `./error-codes` — `JOBS_PROXY_*` codes (`JOBS_PROXY_NOT_MANIFESTED`, `JOBS_PROXY_BACKPRESSURE`, `JOBS_PROXY_PORT_CLOSED`, `JOBS_PROXY_HANDLER_THROW`).
+- `./testing` — paired `MessageChannel` + stub scheduler.
+
+## Out of scope
+
+- **Job tick delivery** — ticks arrive via `api-router-worker-bridge`-style envelopes (a "job invocation" envelope analogous to "request invocation"). This package handles the OUTBOUND registration-handle calls.
+- **Cron expression parsing** — `@suaveplan/cron`'s job; main-side.
+- **Per-tenant fan-out** — `@suaveplan/job-scheduler` + `tenant.provider` on the main side.
+
+## Source mapping
+
+Genesis-original. Design doc sections: §5.2a, §5.4.
+
+| Requirement | Design doc section |
+|---|---|
+| Proxy over the host's `@suaveplan/job-scheduler` | §5.4 |
+| Outbound handle calls marshalled via `MessagePort` | §5.2a |
+| Tick delivery is request-style envelope (handled by sibling package) | §6 |
+
+## Verification approach
+
+- `src/client/client.test.ts` — `enqueue` / `pause` / `resume` round-trip; non-manifested job rejected.
+- `tests/conformance/run-jobs-conformance.test.ts` — `runJobsConformance` from `@suaveplan/job-scheduler/testing` passes. **Required before Stage 4 can complete.**
+
+## Migration impact
+
+None — additive only.