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

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