Repository navigation
Description
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
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)"]
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
src/contract/schemas.ts:workerViewSchemagainsbaselines(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 optionalworkerId;gatewayWaitingReasonSchemagainsno-baseline,baseline-stale,baseline-mismatch;inboxWorkerSchemaomitsbaselines.src/contract/operations.ts:baseline.removeinput gains optionalworkerId;requestedDevicecopiesbaseline(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 inadmin-declarations.ts,app.ts): the three routes drop their 501UNSUPPORTED_IN_GATEWAY_MODE(a gateway now answers them);DELETE /v1/baselines/{name}takes queryworkerIdand declares 400BAD_REQUEST, 404UNKNOWN_WORKER, 409WORKER_NOT_CONNECTED;POST /v1/baselinesdeclares 503WORKER_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, abaseline.listanswer) fillsbaselines; newWORKER_VIEW_BASELINE_EVENTS = ["baseline.saved", "baseline.removed", "baseline.stale"].src/contract/protocol.ts: the bump.src/gateway/worker-link.ts: readsbaseline.listin theincludeCatalogpass (F15); a relayed baseline event refreshes withincludeCatalog.src/gateway/worker-registry.ts:withoutReadFieldsdropsbaselines; the last baselines are kept aside and put back inroutingViews, 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)andwithBaseline(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 bymatchRequest,listsModelanddeviceFit. Whether an entry fits isbaselineMismatch(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:baselineMismatchjoins the gateway's allow-list forcore/index.js(F36);src/core/index.tsexports 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()copiesbaseline; the three codes joinCANNOT_SERVE_CODESandCANNOT_SERVE_REASONS;saveBaseline(leaseId, input)forwards to the lease's worker.src/gateway/dispatcher.ts:baseline.save,baseline.list,baseline.removehandlers; remove stripsworkerIdbefore it calls the worker, asworker.updatedoes (F35).src/daemon/dispatcher.ts: itsworker.listreads its ownbaseline.list(F19);baseline.removewithworkerIdisBAD_REQUEST.src/cli/format.ts,src/cli/commands/baseline.ts(An operator saves, lists and removes baselines on a worker #1206's): theBaselines:line, theWORKERcolumn,--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 boundsbaseline.list's answer. Absent while a worker is starting;[]when it holds none.- Baseline list entry: optional
workerId(string, 1 to 128 characters, the boundevents.replayputs on a worker id,EVENTS_WORKER_MAX), set only by a gateway'sbaseline.list. baseline.removeinput: optionalworkerId(1 to 128 characters, as above; any other value isBAD_REQUESTat the wire edge); HTTPDELETE /v1/baselines/{name}?workerId=<id>. A gateway requires it and strips it before forwarding: absent →BAD_REQUESTbaseline.remove on a gateway needs the worker that holds the baseline: pass --worker <id>; unknown →UNKNOWN_WORKERUnknown worker: <id>; no live link →WORKER_NOT_CONNECTEDworker <id> is not connected(F21). A worker refuses it:BAD_REQUESTworkerId names a gateway's worker, and this daemon is not a gateway; remove without --worker.- Gateway worker reasons:
no-baseline(CLI and console textDoes 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_BASELINEno worker holds a baseline named "<name>"; no holder fits →BASELINE_MISMATCH, message and details frombaselineMismatchon the first holder in worker id order; no fitting holder is fresh →BASELINE_STALEbaseline <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 bywithBaseline; so a holder that is disconnected or drained givesNO_CAPACITY(no-worker).lease.rejectedreasonunresolvable-spec. has-baselinereasons, 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.removedandbaseline.stale(An operator saves, lists and removes baselines on a worker #1206;EVENTS.md) carryworkerIdas 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).
WorkerLinkrefresh and the gateway's own save or remove: both write the view; the handler awaits a refresh withincludeCatalogafter 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_BASELINEby 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 failingUNKNOWN_BASELINE.aggregateStatusandinbox.getread views;status.get'sworkers[]carriesbaselines, 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
fitskey;warm-hitreads both throughdeviceFit. Console: a Baselines page and a device's baseline #1209 readsbaselinesfrom 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-baselinefollowscan-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" —
withBaselinenarrows per holder; "A device of an older version ... is never granted" —warm-hitrequires 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, orNO_DRIVERbefore any progress push excludes that worker" — the three baseline codes join it. src/gateway/routing/AGENTS.mdRules: "can-serveand the fleet table (assess) ask the same helpers in the same order" —has-baselineandassesssharebaselineEntryandwithBaseline.- 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.removeon a gateway takes aworkerId(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 answersUNKNOWN_BASELINEand is left out (the next holder asked; none left: that answer); the only holder disconnected (NO_CAPACITYat once); the only holder busy (waits;status.getwaiting[].workersgives the other workerno-baseline, a stale holderbaseline-stale, a mismatched onebaseline-mismatch; the console printsDoes not hold the baseline,Baseline is stale,Baseline is for another device, and the CLI'ssimlock listprints 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 liston 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 ownworker.listcarries itsbaseline.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:WORKERcolumn first,stale:line,No baselines on any worker.); remove with--worker(sent to that worker withoutworkerId; unknown workerUNKNOWN_WORKER; disconnectedWORKER_NOT_CONNECTED; CLI prompt and line endfrom <worker id>; HTTP?workerId=reaches the handler); remove without--worker(BAD_REQUEST, nothing sent to a worker; CLI asks nothing); a worker givenworkerId(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.tspasses, with the lines above.pnpm checkpasses, the protocol bump check included.pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjspasses: the three baseline routes are declared for a gateway andDELETE /v1/baselines/{name}lists itsworkerIdquery.routing.mdxlistshas-baselineamong the checks andUNKNOWN_BASELINE,BASELINE_STALEandBASELINE_MISMATCHin the fast-fail table;managing-workers.mdxshows theBaselines:line and how to save, list and remove baselines on a gateway.src/gateway/AGENTS.mdandsrc/gateway/routing/AGENTS.mddescribe the stage, the codes and the baseline reads.
Out of scope
- Copying a baseline between workers, or keeping workers in step (ADR 0061 non-goal).
- Removing a baseline from every worker at once.
- The console's Baselines page (Console: a Baselines page and a device's baseline #1209).
- A runtime warm target naming a baseline (Runtime warm-pool targets: warm.set and warm.list, kept in state.db #1143 to Console: Add device… from the catalog keeps one more warm #1146).
Depends on
Written by an agent.
Activity
test: a request naming a baseline fails at once when no worker holds …
feat(gateway): a request naming a baseline fails at once with unknown…
test: a request naming a baseline waits while its only holder is busy…
feat(gateway): has-baseline names no copy, a copy that differs and a …
test: the console and the CLI print the three baseline reasons for a …
test: a holder that answers UNKNOWN_BASELINE is left out and the next…
feat(gateway): a worker's baseline refusal before progress leaves it …
feat(gateway): the link reads a worker's baselines with its catalog a…
test: a warm hit for a baseline needs a ready copy of its current ver…
test: a warm hit for a baseline takes the baseline's mode (#1208)
9 remaining items
test: DELETE /v1/baselines/{name} passes its workerId query to baseli…
feat(http): the baseline routes drop their gateway refusal and DELETE…
docs: the gateway pages, manuals and the baseline page describe basel…
docs: the CLI and client pages show --worker and the gateway's baseli…
docs: the contract and gateway manuals name the baseline reads and th…
refactor: split the baseline remove confirmation and the registry's l…
test: a holder's first message and reason, a disconnected holder at o…
test: the gateway's baseline.save and baseline.remove error rows, and…
docs: the --worker row sits in the baseline remove table, not nuke's (#…
fix(gateway): listsModel reads a request naming a baseline as the bas…
test: baseline.remove maps a dropped uplink to WORKER_NOT_CONNECTED (#…
docs: gateway manual fits the 150-line budget (#1208)
test(e2e): a worker's worker list prints Baselines: none as its third…
feat(gateway): route baseline lease requests to a worker that holds t…