Skip to content

Through a gateway, an iOS lease goes only to a worker that serves its mode #1652

Open

Description

@V3RON

Part of #1645.

Scope

Through a gateway, an iOS lease that names a mode, or takes one from a baseline, goes only to a worker that serves that mode. When no worker serves it, the lease fails at once with MODE_UNAVAILABLE. A worker that refuses on a stale view is skipped and the others are tried. simlock catalog through a gateway shows the fleet's served modes.

If this goes wrong, a full lease through a gateway is refused while another worker serves full, or it reaches a slim-only worker and fails there.

Technical spec

Commit 1cd9315.

Rows

Behaviours: B6, B7, B8
Interfaces: I6, I7
Existing code: X11, X12, X13, X14, X15 (the routing page), X17

Facts

# Fact Source
F1 A request naming a baseline is checked first, and the rest of the table runs over the fitting holders with the request narrowed by withBaseline, so its mode is the baseline's src/gateway/routing/serviceability.ts:115-122, src/gateway/routing/request-match.ts:54-65
F2 A relayed code in CANNOT_SERVE_CODES before a progress push refreshes that worker's catalog and admits the request again without it src/gateway/fleet-dispatch.ts:450-455
F3 select takes its views from fleet-dispatch, so only a stage (not assess) keeps a worker from being picked src/gateway/fleet-dispatch.ts:201-216

Modules touched

src/gateway/routing/ (request-match.ts (servesMode), serviceability.ts, stages/can-serve.ts, pipeline.ts, AGENTS.md), src/gateway/ (fleet-dispatch.ts, fleet-refusals.ts, aggregate.ts, AGENTS.md), src/contract/ (lease-schemas.ts, protocol.ts), src/cli/commands/list.ts:62-84 and ui/src/model/waiting.ts:82-104 (the reason's text), src/gateway/test-support.ts (a catalog with modes), docs/internal/flows/device-selection.md, and the website pages gateway/routing.mdx, gateway/fleet-console.mdx (the refusal table). Searches: CANNOT_SERVE, RejectionCode, WorkerReasonCode, gatewayWaitingReasonSchema, assessLeading, canServe, addCatalogEntry, slimCategories in src/gateway.

Rules in play

  • ADR 0082 §4: route by the catalog field, refuse at once, a relayed refusal is "cannot serve".
  • ADR 0009 §4 and §5: the new row sits after the NO_DRIVER row; the new code joins the "cannot serve" codes.
  • src/gateway/routing/AGENTS.md: "can-serve and assess ask the same helpers in the same order" (servesMode in both); stages stay pure.
  • src/contract/AGENTS.md (Protocol version): I7's enum values bump max by one in this PR.
  • Documentation rule 9: the website pages above change in this PR.

Tests

Seam: gateway assess and select over worker views (model: src/gateway/routing/serviceability.test.ts, src/gateway/fleet-routing-ranges-and-except.test.ts), the gateway dispatcher with fake links (model: src/gateway/fleet-coordinator-walk.test.ts) and the merged catalog (model: src/gateway/aggregate-catalog.test.ts).

  • B6: an iOS lease through a gateway is routed by mode: --mode full with one slim-only worker (I6); slim-only plus both (second picked); slim-only plus no modes field (second picked); --mode slim with one full-only worker (I6, slim wording); no mode with only a slim-only worker (routed); full baseline on a slim-only worker (I6, baseline wording); slim-only first in id order plus both (no dispatch to the first); explain gives mode-unavailable; --physical to a slim-only worker (routed)
  • B7: a worker's relayed MODE_UNAVAILABLE before a progress push: stale slim-only view plus a worker serving both (granted on the second); the stale slim-only worker alone (the worker's I2)
  • B8: the merged iOS catalog: two slim-only workers (["slim"]); slim-only and full-only (["full","slim"]); slim-only and one with no field (absent)

Done when

  • pnpm test:changed passes, with every Tests line above as a test.
  • pnpm check passes, the protocol-bump check included: max is one above the value main holds when this lands.
  • The website build passes: pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs.
  • gateway/routing.mdx lists the MODE_UNAVAILABLE row in its refusal table.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 17, 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 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    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