Initial Commit

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

@@ -0,0 +1,47 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-jobs-worker-proxy (api-jobs-worker-proxy)
+
+**Package**: `@suaveplan/api-jobs-worker-proxy`
+**Status**: PROPOSED
+
+> Every requirement below carries a `**Verified by:**` line at authoring time.
+
+## ADDED Requirements
+
+### Requirement: Proxy preserves JobRegistrationHandle surface
+
+The package SHALL expose `createJobsProxyClient(port)` returning a `WorkerProxyOf<JobRegistrationHandle>`. Method names + parameter shapes MUST match the direct surface; only return types are `Promise`-wrapped.
+
+#### Scenario: surface matches WorkerProxyOf<JobRegistrationHandle>
+
+- **WHEN** `expectTypeOf<ReturnType<typeof createJobsProxyClient>>().toEqualTypeOf<WorkerProxyOf<JobRegistrationHandle>>()` is checked
+- **THEN** the assertion passes
+
+**Verified by:** `src/client/client.spec-conformance.test.ts::"surface matches WorkerProxyOf<JobRegistrationHandle>"`
+
+---
+
+### Requirement: Non-manifested job name is rejected
+
+The package SHALL surface main-side rejection of non-manifested job names as `JOBS_PROXY_NOT_MANIFESTED`. The host enforces — declared in the plugin's manifest `jobs[]` array — and rejects unknown names at the boundary.
+
+#### Scenario: unknown job name rejects
+
+- **WHEN** the worker calls `ctx.jobs.enqueue("unknown-job", {})`
+- **THEN** the call rejects with `SuaveplanError` of code `JOBS_PROXY_NOT_MANIFESTED`
+
+**Verified by:** `src/client/non-manifested.test.ts::"unknown job name rejects"`
+
+---
+
+### Requirement: Conformance suite passes against this proxy
+
+The package SHALL be runnable as the surface argument to `runJobsConformance` from `@suaveplan/job-scheduler/testing`. Every scenario MUST pass identically to the direct surface. This is the Stage-4-precondition gate.
+
+#### Scenario: runJobsConformance passes
+
+- **WHEN** `runJobsConformance("worker-proxy", makeFactory)` runs
+- **THEN** every scenario passes
+
+**Verified by:** `tests/conformance/run-jobs-conformance.test.ts::"runJobsConformance passes against proxy"`