suaveplan/openspec/specs/api-jobs-worker-proxy/spec.md

Capability: api-jobs-worker-proxy

Package: @suaveplan/api-jobs-worker-proxy Status: SHIPPED · 2026-05-25

The @suaveplan/api-jobs-worker-proxy package provides the worker ↔ main bridge that lets a worker-isolated API plugin participate in the host's main-process job scheduler. Worker code calls registerCron / registerQueued against the local proxy; the proxy marshals the registration to main via @suaveplan/api-worker-rpc, where it is bound into the host's real JobRegistrationHandle. When the host scheduler ticks, a runJob RPC flows back to the worker and invokes the registered handler closure.

Requirements

Requirement: Proxy preserves JobRegistrationHandle surface

The package SHALL expose createJobsProxyClient(port) returning an object implementing capabilities.JobRegistrationHandle from @suaveplan/api-types. Method names + parameter shapes MUST match the direct surface (registerCron(name, () => Promise<void>): void, registerQueued(name, (payload: unknown) => Promise<void>): void); the proxy adds only close(reason?) and a sizes accessor.

Scenario: surface matches JobRegistrationHandle

• WHEN a TypeScript consumer assigns the result of createJobsProxyClient(port) to a capabilities.JobRegistrationHandle variable
• THEN the assignment type-checks without widening

Verified by: src/client/client.test.ts::"registerCron round-trips, scheduler tick fires handler" plus typecheck of src/client/client.ts.

---

Requirement: Non-manifested job name is rejected

The package SHALL surface main-side rejection of non-manifested job names as JOBS_PROXY.JOB_NOT_DECLARED. The host enforces — declared in the plugin's manifest jobs[] array, supplied as declaredJobs — and rejects unknown names at the boundary.

Scenario: unknown job name rejects

• WHEN the worker calls ctx.jobs.registerCron("unknown-job", fn) with an onHandlerError observer attached
• THEN the observer fires with a JobsProxyError whose code is JOBS_PROXY.JOB_NOT_DECLARED

Verified by: src/client/client.test.ts::"non-declared job name triggers JOB_NOT_DECLARED via onHandlerError"

---

Requirement: Kind mismatch rejects

The package SHALL reject registrations whose kind (cron vs queued) does not match the manifest declaration with the same JOBS_PROXY.JOB_NOT_DECLARED code, since the name-to-kind binding is a manifest invariant.

Scenario: cron registered as queued (or vice versa) rejects

• WHEN the worker registers a queued-declared name as cron
• THEN the rejection observer fires with JOB_NOT_DECLARED

Verified by: src/client/client.test.ts::"declared queued name but registered as cron is rejected"

---

Requirement: Worker handler exceptions surface back to scheduler

When the main-side scheduler ticks a job and the worker-side handler throws or rejects, the proxy SHALL propagate the failure to the scheduler as a JobsProxyError of code JOBS_PROXY.HANDLER_THREW. The worker-side observer (if any) also receives the same error.

Scenario: handler throws → scheduler tick rejects

• WHEN the worker registers a cron handler that throws and the scheduler ticks that name
• THEN the tick promise rejects with a JobsProxyError whose code is JOBS_PROXY.HANDLER_THREW

Verified by: src/client/client.test.ts::"worker handler that throws surfaces via onHandlerError"

---

Requirement: Per-handler timeout is honored

The proxy SHALL apply an optional per-handler timeout (handlerTimeoutMs, default 0 = disabled). When a handler exceeds the budget the proxy SHALL surface JOBS_PROXY.JOB_TIMEOUT to both the scheduler and the onHandlerError observer.

Scenario: long-running handler exceeds budget

• WHEN handlerTimeoutMs is 5 and the worker handler sleeps 200ms, then the scheduler ticks
• THEN the tick promise rejects and the observer receives JOBS_PROXY.JOB_TIMEOUT

Verified by: src/client/client.test.ts::"handlerTimeoutMs aborts long-running handlers"

---

Requirement: Conformance suite passes against this proxy

The package SHALL ship a conformance suite (JOBS_CONFORMANCE_CASES

• runJobsConformance(factory)) covering cron round-trip, queued round-trip with payload, and rejection of non-declared names. The suite MUST pass against the in-process harness factory.

Scenario: runJobsConformance passes

• WHEN runJobsConformance(factory) runs against the standard in-process harness
• THEN every scenario reports ok: true

Verified by: tests/conformance/run-jobs-conformance.test.ts::"every scenario reports ok against the standard harness factory"

---

Implementation summary

• Layout: packages/api-stack/api/api-jobs-worker-proxy/
• Subpath exports: ./worker-side, ./main-side, ./handler-bridge, ./error-codes, ./testing
• Deps: @suaveplan/api-types, @suaveplan/api-worker-rpc, @suaveplan/error, tslib, zod
• Codes (5): JOB_NOT_DECLARED, HANDLER_THREW, PROXY_DISPOSED, JOB_TIMEOUT, DUPLICATE_REGISTRATION
• 44 tests / 100/100/100/100 statement/branch/function/line coverage
• Bidirectional over a single MessagePort: paired createRawWorkerRpcClient + serveWorkerRpc on each side.

Local substitute for runJobsConformance

The proposal referenced @suaveplan/job-scheduler/testing::runJobsConformance. That harness does not yet exist on genesis. The local runJobsConformance shipped under ./testing is a forward-compatible substitute: it takes the same factory shape and returns per-case pass/fail, so consumers can later swap to the upstream harness with no public-surface change.