Skip to content

A gateway routes a baseline request to a worker that holds it #1208

Closed

Description

@V3RON

Part of #327.

Scope

After this PR, a gateway sends a lease request that names a baseline only to a worker that holds a fresh copy of it. A request no worker can serve that way fails at once, with the code a single worker would give. simlock --gateway worker list shows each worker's baselines. An operator saves, lists and removes baselines through the gateway: a save goes to the worker that holds the lease, a list covers every worker, and a remove names its worker with --worker (HTTP DELETE /v1/baselines/{name}?workerId=<id>).

One PR: the worker view's baselines feed both the routing and the two read surfaces, and the forwarded save and remove refresh that same view. Split apart, no part has a user-visible slice. About 25 files across 9 modules (contract, gateway, daemon, cli, http, simlock-client, admin, ui, website), over the ~20 because the three baseline routes, the client and the CLI each gain the gateway's workerId; each is a line or two.

In short

Each worker's view on the gateway now carries the worker's baselines, read with baseline.list (#1206). A request naming a baseline is matched against them: a worker that holds no copy that fits and is fresh is passed over, and a worker that does is treated as if the request had named the baseline's model, OS, mode and image tag. Whether a holder's baseline fits the request is decided by #1207's baselineMismatch(baseline, request) (src/core/domain.ts), the one function the worker also calls. A warm device counts only when it is a copy of the current version of that baseline. A plain request no longer counts an idle baseline copy as warm.

flowchart LR
  R[lease.request with baseline] --> A["assess: narrow to holders; UNKNOWN_BASELINE, BASELINE_MISMATCH, BASELINE_STALE, then today's checks on the holders (new)"]
  A --> T[takes-requests] --> H[has-capabilities] --> C[can-serve] --> B["has-baseline (new)"]
  B --> HE[healthy] --> I[idle-queue] --> W["warm-hit: + baseline and version (changed)"] --> F[free-slot ...]
  V["worker view: + baselines (new)"] -.-> A
  V -.-> B
  V -.-> W
Loading

A baseline holder is a worker whose view lists a baseline under the requested name (a disconnected worker's kept view counts; an incompatible one does not). A holder fits when baselineMismatch finds no differing field. A holder's copy is fresh when its stale reason is none.

The operator's session, after (today --baseline and baseline are unknown). The lease grant and every error print as one JSON line, as the CLI prints them today (F34); worker list and baseline print human lines:

$ simlock --gateway worker list
wrk_a (mac-mini-1): connected -- ios 0/4, android 1/2, 1 lease(s) -- simlock 0.6.0 -- macOS 26.1 arm64; xcode 26.1 (17B55), emulator 36.5.11
  Load: CPU 12% busy (12 cores) · memory 20.1 GiB of 36.0 GiB available · swap 0 B used · pressure normal · disk 210.4 GiB of 926.4 GiB free · read 3s ago
  Baselines: checkout v2: android Pixel 9, Android 36 (google_apis), full; smoke v1: ios iPhone 17, iOS 27.0, slim, stale
wrk_b (mac-mini-2): connected -- ios 0/4, android 0/2, 0 lease(s) -- simlock 0.6.0 -- macOS 26.1 arm64; xcode 26.1 (17B55)
  Baselines: none
$ simlock --gateway baseline list
WORKER  NAME      VERSION  PLATFORM  MODEL      OS    MODE  IMAGE        SIZE    SAVED             NOTE
wrk_a   checkout  2        android   Pixel 9    36    full  google_apis  4.8 GB  2026-11-02 13:10  app 4.2, test user
wrk_a   smoke     1        ios       iPhone 17  27.0  slim  -            1.1 GB  2026-10-30 09:02
  stale: runtime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installed
$ simlock --gateway lease --platform android --baseline checkout --detach
{"device":{"id":"<device id>","spec":{"physical":false,"platform":"android","model":"Pixel 9","osVersion":"36","imageTag":"google_apis","baseline":{"name":"checkout","version":2}},…},"lease":{"id":"wrk_a.L7",…},…}
$ simlock --gateway lease --platform android --baseline chekout
{"error":{"code":"UNKNOWN_BASELINE","message":"no worker holds a baseline named \"chekout\""}}
$ simlock --gateway lease --platform ios --baseline smoke
{"error":{"code":"BASELINE_STALE","message":"baseline smoke is stale: runtime com.apple.CoreSimulator.SimRuntime.iOS-27-0 is not installed"}}
$ SIMLOCK_TOKEN=<operator token> simlock --gateway baseline save checkout --lease wrk_a.L7 --note "app 4.3"
Saved baseline checkout v3: android Pixel 9, Android 36 (google_apis), full, 4.8 GB. Lease wrk_a.L7 ended.
$ SIMLOCK_TOKEN=<operator token> simlock --gateway baseline remove smoke --yes
{"error":{"code":"BAD_REQUEST","message":"baseline.remove on a gateway needs the worker that holds the baseline: pass --worker <id>"}}
$ SIMLOCK_TOKEN=<operator token> simlock --gateway baseline remove smoke --worker wrk_a
Remove baseline smoke v1 from wrk_a? [y/N] y
Removed baseline smoke v1 from wrk_a.
$ simlock --gateway baseline list     # a fleet with no baselines
No baselines on any worker.

<reason> in BASELINE_STALE and the message of BASELINE_MISMATCH are those of the first holder in worker id order (Shared values). The save line is #1206's, unchanged. Remove's line and prompt are #1206's plus from <worker id>; the prompt's version is read from the gateway's baseline.list entry with that name and worker. Without --worker on a gateway the CLI asks nothing and sends the remove, so the gateway's BAD_REQUEST is the answer and nothing is removed. In the Baselines: line each entry is <name> v<version>: and the save line's spec words (platform, model, iOS <os> or Android <os>, the image tag in brackets when there is one, the mode), then , stale for a stale one; entries are joined by ; in the order the worker lists them. The gateway's baseline list rows run in worker id order, each worker's rows in #1206's order; WORKER is the worker id (what --worker takes). The Baselines: line is absent while the view has no baselines read (a worker that is starting).

Request through the gateway, checkout (android Pixel 9, 36, full) on wrk_a only Today After
--platform android any worker any worker; an idle checkout copy is no warm hit
--platform android --baseline checkout unknown option wrk_a
--platform android --baseline checkout --os 35 unknown option BASELINE_MISMATCH at once, wrk_a's message
--platform android --baseline checkout --os ">=35" unknown option wrk_a (36 is in the range, baselineMismatch)
--platform ios --baseline smoke --mode full (stale and mismatched on every holder) unknown option BASELINE_MISMATCH at once (mismatch is checked before stale)
--platform android --baseline nothere unknown option UNKNOWN_BASELINE at once
--platform ios --baseline smoke (stale on every holder) unknown option BASELINE_STALE at once
--platform android --baseline checkout, wrk_a disconnected unknown option NO_CAPACITY at once (row 5 of ADR 0009 §4)
--platform android --baseline checkout, wrk_a busy unknown option waits in the fleet queue; simlock list shows wrk_b: does not hold the baseline

If this goes wrong, a request naming a baseline is sent to a worker without it and fails with that worker's UNKNOWN_BASELINE, or waits in the queue instead of failing at once.

Technical spec

Facts

Commit 019ba5c3d.

# Fact Source
F1 A routable request carries platform, model, class, OS, image tag, mode, physical and requires; no baseline src/gateway/routing/pipeline.ts:5-14
F2 A worker reason is one of 14 codes, in the gateway type and the contract enum src/gateway/routing/pipeline.ts:22-36; src/contract/schemas.ts:350-365
F3 assess rejects in order: no taker NO_CAPACITY, NO_DRIVER, UNKNOWN_MODEL, RUNTIME_MISSING, then no taker that matches NO_CAPACITY; a known worker is one not incompatible src/gateway/routing/serviceability.ts:62-95, :115-117
F4 RejectionCode holds five codes; details holds platform, model, class, OS or capabilities src/gateway/routing/serviceability.ts:20-43
F5 can-serve keeps a worker whose catalog matchRequestes, else names no-driver, unknown-model or runtime-missing src/gateway/routing/stages/can-serve.ts:4-16
F6 A request with no model routes by class (phone when none is named), and with no OS by the newest paired runtime src/gateway/routing/request-match.ts:77-89, :60-71
F7 warm-hit scores 1 when a ready device fits deviceFit and the mode rule; deviceFit builds a requirement of image tag, OS, platform and model or class src/gateway/routing/stages/warm-hit.ts:10-21; src/gateway/routing/request-match.ts:39-58
F8 The policy's stage list is code: takes-requests, has-capabilities, can-serve, healthy, idle-queue, warm-hit, free-slot, ram-budget, free-capacity src/gateway/routing.ts:70-82
F9 routable() copies the waiter's request fields one by one src/gateway/fleet-coordinator.ts:1589-1600
F10 A worker's UNKNOWN_MODEL, RUNTIME_MISSING, NO_DRIVER or CAPABILITY_MISSING before progress excludes it for that request, refreshes its catalog and walks again; each code maps to a worker reason src/gateway/fleet-coordinator.ts:1148-1153, :135-140, :116-121
F11 The walk assesses over views minus excluded workers; a reject with an exclusion held ends the request with the last worker refusal src/gateway/fleet-coordinator.ts:848-858, :962-978
F12 The gateway forwards requestedDevice(input), which copies model, class, platform, OS, mode, image tag and physical src/gateway/dispatcher.ts:689-692; src/gateway/fleet-coordinator.ts:1069-1072; src/contract/operations.ts:288-298
F13 The worker view schema has no baselines src/contract/schemas.ts:1180-1218
F14 workerViewFields builds the view from status, devices, catalog and config reads; catalog and config are optional src/contract/worker-view.ts:43-49, :77-117
F15 WorkerLink reads devices on every refresh and catalog and config only with includeCatalog, as one bounded unit src/gateway/worker-link.ts:417-426
F16 A relayed lease.*, device.*, install or update event refreshes the view; includeCatalog only for WORKER_VIEW_CATALOG_EVENTS (component.installed) src/gateway/worker-link.ts:571-575, :606-613; src/contract/worker-view.ts:32
F17 One view read is bounded at 10 s; a failed refresh keeps the last view and is logged src/gateway/AGENTS.md:49-50; src/gateway/worker-link.ts:326-334
F18 A registry refresh keeps fields it does not carry; a starting refresh drops the read fields; routingViews puts the last catalog back for routing src/gateway/worker-registry.ts:335-361, :79-95, :144-155
F19 A worker answers its own worker.list from its own status, devices, catalog and config src/daemon/dispatcher.ts:883-913
F20 A gateway answers worker.list with its registry's views src/gateway/dispatcher.ts:441
F21 worker.update names one worker: UNKNOWN_WORKER with no view, WORKER_NOT_CONNECTED with no live link, then awaits that worker's refresh before answering src/gateway/dispatcher.ts:459-482
F22 Release goes to the lease's worker through the lease index (UNKNOWN_LEASE for an id it does not hold), and the index entry is removed after it src/gateway/fleet-coordinator.ts:416-432, :1471-1479
F23 #forwardToWorker answers WORKER_UNREACHABLE with no live link and adds no time limit of its own src/gateway/fleet-coordinator.ts:1422-1452
F24 The gateway's handler table is typed total over the contract src/gateway/dispatcher.ts:30-33, :226-289
F25 A worker refuses a gateway-only operation with UNSUPPORTED_IN_WORKER_MODE src/daemon/dispatcher.ts:300-302
F26 formatWorkers prints one line per worker, then a load line and install lines under it src/cli/format.ts:7-42
F27 The CLI and the console map every worker reason to text in a record typed over the enum src/cli/commands/list.ts:62-78; ui/src/model/waiting.ts:82-99
F28 The Inbox's worker shape omits catalog, devices, downloads and leases from the view src/contract/schemas.ts:1229-1230
F29 A dispatch target's refresh takes includeCatalog src/gateway/fleet-ports.ts:51
F30 The gateway dispatcher's test harness runs a real WorkerRegistry, FleetLeaseCoordinator and createRoutingPolicy("warm-then-free") over ScriptedWorkerClients src/gateway/dispatcher.test.ts:192-240; src/gateway/test-support.ts:280
F31 The protocol range is one version; a worker answering PROTOCOL_VERSION_UNSUPPORTED is marked incompatible and asked nothing else src/contract/protocol.ts:13; src/gateway/worker-link.ts:215-220
F32 The website's routing page lists the filters and the fast-fail codes; the managing-workers page shows the worker list output website/src/content/docs/docs/gateway/routing.mdx:10-16, :45-55; website/src/content/docs/docs/gateway/managing-workers.mdx:10-35
F33 A worker id on the wire is bounded at 128 characters src/contract/events-page.ts:25; src/ports/uplink-websocket.ts:412
F34 A CLI error is one JSON line {"error":{"code","message"}} on stderr src/cli/errors.ts:36-43
F35 worker.update strips workerId from the input before it calls the worker src/gateway/dispatcher.ts:473-475
F36 The gateway may import from core/index.js only the names .oxlintrc.json allows .oxlintrc.json:8-40
F37 A declared DELETE route takes a query schema and lists its error codes per HTTP status; WORKER_NOT_CONNECTED is 409, UNKNOWN_WORKER 404, WORKER_UNREACHABLE 503 src/http/admin-declarations.ts:131-145; src/contract/errors.ts:513-525
F38 Test seams beside the gateway's: the CLI renders worker list and the waiting reasons from a fake client; the console maps each reason; a worker's own worker.list; the HTTP routes src/cli/index.test.ts:4596, :9147-9160; ui/src/model/waiting.test.ts:255; src/daemon/dispatcher.test.ts:537; src/http/app.test.ts:575

Modules touched

Searches: RoutableRequest, WorkerReasonCode, gatewayWaitingReasonSchema, CANNOT_SERVE_CODES, workerViewFields, workerViewSchema, routable(, requestedDevice(, formatWorkers, GATEWAY_REASON_TEXT, WORKER_WHY_TEXT, unsupportedByDesign, inboxWorkerSchema.

flowchart LR
  D["gateway/dispatcher.ts (changed)"] --> FC["fleet-coordinator.ts (changed)"]
  D --> REG[worker-registry.ts]
  FC --> RT["routing.ts (changed)"]
  RT --> AS["routing/serviceability.ts (changed)"]
  RT --> HB["routing/stages/has-baseline.ts (new)"]
  RT --> WH["routing/stages/warm-hit.ts (changed)"]
  AS --> RM["routing/request-match.ts (changed)"]
  HB --> RM
  WH --> RM
  WL["worker-link.ts (changed)"] --> WV["contract/worker-view.ts (changed)"]
  WL --> REG2["worker-registry.ts (changed)"]
  DD["daemon/dispatcher.ts (changed)"] --> WV
  CLI["cli format.ts, baseline.ts (changed)"] --> CL["simlock-client removeBaseline (changed)"]
  H["http baseline routes (changed)"] --> D
  AS --> BM["core/domain.ts baselineMismatch (#1207)"]
Loading
sequenceDiagram
  participant A as Agent
  participant G as Gateway
  participant W1 as wrk_a (holds checkout)
  participant W2 as wrk_b
  A->>G: lease.request {platform, baseline: checkout}
  G->>G: assess, stages over views (has-baseline keeps wrk_a)
  G->>W1: lease.request {..., baseline: checkout, noWait}
  W1-->>G: UNKNOWN_BASELINE (removed since the last read)
  G->>W1: refresh view with baselines
  G->>G: walk again without wrk_a: no holder left
  G-->>A: UNKNOWN_BASELINE, wrk_a's message
Loading
  • src/contract/schemas.ts: workerViewSchema gains baselines (an array of An operator saves, lists and removes baselines on a worker #1206's baseline list entry); An operator saves, lists and removes baselines on a worker #1206's entry gains optional workerId; gatewayWaitingReasonSchema gains no-baseline, baseline-stale, baseline-mismatch; inboxWorkerSchema omits baselines.
  • src/contract/operations.ts: baseline.remove input gains optional workerId; requestedDevice copies baseline (if A lease names a baseline and gets a copy of it #1207 has not).
  • src/http/ (An operator saves, lists and removes baselines on a worker #1206's baseline routes in admin-declarations.ts, app.ts): the three routes drop their 501 UNSUPPORTED_IN_GATEWAY_MODE (a gateway now answers them); DELETE /v1/baselines/{name} takes query workerId and declares 400 BAD_REQUEST, 404 UNKNOWN_WORKER, 409 WORKER_NOT_CONNECTED; POST /v1/baselines declares 503 WORKER_UNREACHABLE (F37).
  • src/simlock-client/client.ts, types.ts, src/admin/index.ts: removeBaseline(name, { workerId }), the option optional.
  • src/contract/worker-view.ts: WorkerReads.baselines (optional, a baseline.list answer) fills baselines; new WORKER_VIEW_BASELINE_EVENTS = ["baseline.saved", "baseline.removed", "baseline.stale"].
  • src/contract/protocol.ts: the bump.
  • src/gateway/worker-link.ts: reads baseline.list in the includeCatalog pass (F15); a relayed baseline event refreshes with includeCatalog.
  • src/gateway/worker-registry.ts: withoutReadFields drops baselines; the last baselines are kept aside and put back in routingViews, as the catalog is (F18).
  • src/gateway/routing/pipeline.ts: RoutableRequest.baseline?: string; the three reason codes.
  • src/gateway/routing/request-match.ts: baselineEntry(worker, name) and withBaseline(worker, request) (the request narrowed to the holder's entry: model, exact OS, mode, image tag; class dropped; a non-holder's request unchanged), used by matchRequest, listsModel and deviceFit. Whether an entry fits is baselineMismatch (A lease names a baseline and gets a copy of it #1207, src/core/domain.ts), called here and nowhere else in the gateway; no field is compared here.
  • .oxlintrc.json: baselineMismatch joins the gateway's allow-list for core/index.js (F36); src/core/index.ts exports it if A lease names a baseline and gets a copy of it #1207 has not.
  • src/gateway/routing/stages/has-baseline.ts (new), stages/warm-hit.ts, routing/index.ts, routing/serviceability.ts, src/gateway/routing.ts.
  • src/gateway/fleet-coordinator.ts: routable() copies baseline; the three codes join CANNOT_SERVE_CODES and CANNOT_SERVE_REASONS; saveBaseline(leaseId, input) forwards to the lease's worker.
  • src/gateway/dispatcher.ts: baseline.save, baseline.list, baseline.remove handlers; remove strips workerId before it calls the worker, as worker.update does (F35).
  • src/daemon/dispatcher.ts: its worker.list reads its own baseline.list (F19); baseline.remove with workerId is BAD_REQUEST.
  • src/cli/format.ts, src/cli/commands/baseline.ts (An operator saves, lists and removes baselines on a worker #1206's): the Baselines: line, the WORKER column, --worker; src/cli/commands/list.ts: three reason texts.
  • ui/src/model/waiting.ts: three reason texts (F27).
  • Manuals: src/gateway/AGENTS.md (Fleet request step 6, Reads), src/gateway/routing/AGENTS.md (Assess, stage table).
  • Website: gateway/routing.mdx, gateway/managing-workers.mdx.

Contract and event changes

This PR bumps the protocol by one.

  • workerViewSchema.baselines: optional array of An operator saves, lists and removes baselines on a worker #1206's baseline list entry, bounded as An operator saves, lists and removes baselines on a worker #1206 bounds baseline.list's answer. Absent while a worker is starting; [] when it holds none.
  • Baseline list entry: optional workerId (string, 1 to 128 characters, the bound events.replay puts on a worker id, EVENTS_WORKER_MAX), set only by a gateway's baseline.list.
  • baseline.remove input: optional workerId (1 to 128 characters, as above; any other value is BAD_REQUEST at the wire edge); HTTP DELETE /v1/baselines/{name}?workerId=<id>. A gateway requires it and strips it before forwarding: absent → BAD_REQUEST baseline.remove on a gateway needs the worker that holds the baseline: pass --worker <id>; unknown → UNKNOWN_WORKER Unknown worker: <id>; no live link → WORKER_NOT_CONNECTED worker <id> is not connected (F21). A worker refuses it: BAD_REQUEST workerId names a gateway's worker, and this daemon is not a gateway; remove without --worker.
  • Gateway worker reasons: no-baseline (CLI and console text Does not hold the baseline), baseline-stale (Baseline is stale), baseline-mismatch (Baseline is for another device).
  • Gateway fast failures, checked in this order before today's table: no holder → UNKNOWN_BASELINE no worker holds a baseline named "<name>"; no holder fits → BASELINE_MISMATCH, message and details from baselineMismatch on the first holder in worker id order; no fitting holder is fresh → BASELINE_STALE baseline <name> is stale: <reason>, the first fitting holder's reason. Then today's checks (F3) run over the fitting, fresh holders, each with its request narrowed by withBaseline; so a holder that is disconnected or drained gives NO_CAPACITY (no-worker). lease.rejected reason unresolvable-spec.
  • has-baseline reasons, in the same order: no entry → no-baseline; entry does not fit → baseline-mismatch; entry stale → baseline-stale.
  • Events: none new. The relayed baseline.saved, baseline.removed and baseline.stale (An operator saves, lists and removes baselines on a worker #1206; EVENTS.md) carry workerId as every relayed event does.

Other code on the same state

Searches: routingViews( (4 hits), .catalog in src/gateway/ (31), withoutReadFields (2), #cannotServe (6), requestedDevice( (5), views() in src/gateway/dispatcher.ts (9).

  • WorkerLink refresh and the gateway's own save or remove: both write the view; the handler awaits a refresh with includeCatalog after the worker answers (as F21 does), and the link's coalescing (F15) makes that refresh start after the call, so the answer is followed by a view that has the change.
  • A save or remove made on the worker directly: the relayed baseline event refreshes the view (F16). Until it lands (one view read, at most 10 s, F17), a request may be refused UNKNOWN_BASELINE by the gateway or by the worker; the worker's answer excludes it and the walk goes on (F10, F11).
  • The cannot-serve memo (F10): it is per request, so a baseline saved later serves new requests only.
  • routingViews (F18): a starting worker keeps its last baselines for routing, as its catalog, so a request whose only holder restarts waits instead of failing UNKNOWN_BASELINE.
  • aggregateStatus and inbox.get read views; status.get's workers[] carries baselines, the Inbox's worker omits them (F28).
  • A lease names a baseline and gets a copy of it #1207 writes the device's baseline on the device record and its fits key; warm-hit reads both through deviceFit. Console: a Baselines page and a device's baseline #1209 reads baselines from the view.

Failure modes

Call Outcome What happens Limit, counted from
Gateway → worker baseline.list (view read) ok baselines replaced 10 s for the whole read, from the read's start (F17)
Gateway → worker baseline.list error reply, or no answer the refresh fails, the last view stays, as a failed catalog read (F17) 10 s, as above
Gateway → worker lease.request naming a baseline UNKNOWN_BASELINE, BASELINE_STALE or BASELINE_MISMATCH before progress the worker is excluded for that request, its view is refreshed with baselines, the walk goes on; with no holder left the request ends with that answer gateway.leaseRequestTimeoutMs, from the dispatch
Gateway → worker baseline.save ok index entry removed, view refreshed, the worker's answer with the gateway lease id none of its own, as release (F23)
Gateway → worker baseline.save UNKNOWN_LEASE index entry dropped, as release (F22), relayed none
Gateway → worker baseline.save or baseline.remove other error reply (FORBIDDEN, BASELINE_IN_USE, UNKNOWN_BASELINE) relayed as the worker gave it none
Gateway → worker baseline.save or baseline.remove no live link, or the uplink drops WORKER_UNREACHABLE (save, F23) or WORKER_NOT_CONNECTED (remove, F21) none
Gateway baseline.list a worker disconnected its last baselines are listed (views are kept, F18) none, no worker call

State: the gateway writes only its in-memory views; a restart rebuilds them on reconnect. Two removes of one baseline at once: the worker answers the second UNKNOWN_BASELINE. The baseline.list error row needs no test (as the catalog's today); the others are cases of Tests lines 1 and 3.

Rules in play

  • ADR 0061 §6: "A routing stage has-baseline follows can-serve" — the stage, the two fast-fail codes, the warm-hit key, and the save, remove and list routes as written.
  • ADR 0061 §5: "A request naming a baseline takes the baseline's model, OS, mode and image tag" — withBaseline narrows per holder; "A device of an older version ... is never granted" — warm-hit requires the entry's version.
  • ADR 0009 §4: "the walk runs again and a waiting request that has moved to rows 1 to 5 is rejected" — the baseline rows sit in the same table.
  • ADR 0009 §5: "A worker's UNKNOWN_MODEL, RUNTIME_MISSING, or NO_DRIVER before any progress push excludes that worker" — the three baseline codes join it.
  • src/gateway/routing/AGENTS.md Rules: "can-serve and the fleet table (assess) ask the same helpers in the same order" — has-baseline and assess share baselineEntry and withBaseline.
  • Architecture rule 10, "A rule is enforced in exactly one place": the mismatch rule is A lease names a baseline and gets a copy of it #1207's baselineMismatch; the gateway calls it, it compares no field itself.
  • ADR 0061 §6: "baseline.remove on a gateway takes a workerId (stripped before it is forwarded)".
  • src/contract/AGENTS.md:62-66: the bump.
  • Documentation rule 9: the gateway pages change in this PR.

Tests

Seams: GatewayDispatcher in src/gateway/dispatcher.test.ts, with its harness (F30) and views that carry baselines; model on its "lease lifecycle and device.exec (#118)" block. Stage-level cases may go in src/gateway/routing.test.ts. What the gateway dispatcher cannot see goes to the seam that owns it (F38): CLI output in src/cli/index.test.ts (runCli over a fake client), the console texts in ui/src/model/waiting.test.ts, a worker's own answers in src/daemon/dispatcher.test.ts, the workerId query in src/http/app.test.ts.

  • Through a gateway, a request naming a baseline goes only to a worker that holds it, fresh: one worker holds it (granted there, also when another has more free capacity; --os ">=35" on a 36 baseline granted); none holds it (UNKNOWN_BASELINE, no worker asked); only stale copies (BASELINE_STALE, the first holder's reason); every holder differs (BASELINE_MISMATCH, the first holder's message; also when the holders are stale too); a holder answers UNKNOWN_BASELINE and is left out (the next holder asked; none left: that answer); the only holder disconnected (NO_CAPACITY at once); the only holder busy (waits; status.get waiting[].workers gives the other worker no-baseline, a stale holder baseline-stale, a mismatched one baseline-mismatch; the console prints Does not hold the baseline, Baseline is stale, Baseline is for another device, and the CLI's simlock list prints them with a lower-case first letter); a warm hit needs the current version (its ready copy of the current version is a warm hit, an older version's or for a plain request is not).
  • An operator runs simlock worker list on a gateway: each worker shows its baselines: worker with baselines (Baselines: line, image tag in brackets, stale marked; CLI seam); worker with none (Baselines: none; CLI seam); starting worker (no line, still routed by its last baselines; gateway seam); a worker's own worker.list carries its baseline.list (daemon dispatcher seam).
  • An operator saves, lists and removes baselines through a gateway: save goes to the lease's worker (worker lease id sent, index entry gone, view refreshed, the save line printed); list of every worker (each entry with its workerId; CLI: WORKER column first, stale: line, No baselines on any worker.); remove with --worker (sent to that worker without workerId; unknown worker UNKNOWN_WORKER; disconnected WORKER_NOT_CONNECTED; CLI prompt and line end from <worker id>; HTTP ?workerId= reaches the handler); remove without --worker (BAD_REQUEST, nothing sent to a worker; CLI asks nothing); a worker given workerId (BAD_REQUEST, daemon dispatcher seam).

Done when

  • pnpm exec vitest run --project unit src/gateway src/contract src/cli src/daemon/dispatcher.test.ts src/http ui/src/model/waiting.test.ts passes, with the lines above.
  • pnpm check passes, the protocol bump check included.
  • pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs passes: the three baseline routes are declared for a gateway and DELETE /v1/baselines/{name} lists its workerId query.
  • routing.mdx lists has-baseline among the checks and UNKNOWN_BASELINE, BASELINE_STALE and BASELINE_MISMATCH in the fast-fail table; managing-workers.mdx shows the Baselines: line and how to save, list and remove baselines on a gateway.
  • src/gateway/AGENTS.md and src/gateway/routing/AGENTS.md describe the stage, the codes and the baseline reads.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 2, 2026
  2. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:draftScope written; technical spec or its spec check missing.
    on Nov 2, 2026
  3. self-assigned this
    on Nov 3, 2026
  4. 9 remaining items

  5. added a commit that references this issue on Nov 4, 2026
    eec996e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

task:readySpec checked. An agent may implement it once its Depends on allow.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions