A reserve of running slots, and a request waits for a device on its way #369

Part of #359.

Scope

After this PR an operator can keep running slots free of warm devices with warmPool.reserveRunning, so a request for a model nobody predicted boots at once instead of shutting a warm device down first. And a request for a device that is already on its way, booting or being created, waits for it instead of starting a second one.

In short

The reserve is a number of running slots per platform that idle warm devices may not fill. Default none, which is today's behaviour. The global budget subtracts the sum of the platform reserves.

$ simlock config set warmPool.reserveRunning.ios 1
$ simlock daemon restart
# iOS running limit 3: at most 2 idle devices stay warm
$ simlock lease --model "iPhone 15"      # with two warm iPhone 17
{"state":"booting"}                      # no warm device shut down first

on its way: a device that serves the request, is either under a boot claim or in provisioning, and that no other request already owns: the pool's own boots and creations. A device another request is booting or creating is ignored, as today. A request that finds one waits and is granted when it is ready. Under --no-wait the case is ignored and the request plans as today.

flowchart LR
  R[request arrives] --> P{ready device serves it?}
  P -->|yes| G[grant]
  P -->|no| W{device on its way serves it?}
  W -->|yes, and nobody owns it| H[wait, granted when ready]
  W -->|no| S[shut-down device? boot it]
  S -->|none| C[provision, as today]

If this goes wrong: a request waits on a boot that fails, until its own deadline, instead of booting its own; or the reserve is counted twice and the pool is smaller than configured.

Technical spec

File and line references are to main at 4a52f6e, after #368.

Modules touched

flowchart LR
  classDef changed fill:#f3d9a4,stroke:#8a6a2a
  CFG[warm-pool/config.ts]:::changed --> POL[warm-pool/policy.ts]:::changed
  PLAN[acquisition-planner.ts]:::changed --> CLAIMS[device-operation-claims.ts]:::changed
  PLAN --> DOM[domain.ts]
  ACQ[lease-acquisition-coordinator.ts] --> PLAN

• src/core/warm-pool/config.ts: reserveRunning: { ios: number; android: number }, non-negative integers, default 0 each. src/core/warm-pool/policy.ts: the per-platform budget subtracts the platform's reserve; the global budget subtracts their sum. A reserve above the platform's maxRunning means no warm device for that platform.
• src/core/device-operation-claims.ts: a claim gains an optional owner (a waiter id). The planner's boot-shutdown claim and the request path's provision carry the waiter's id; the pool's boots and creations carry none. DeviceOperationClaims gains claim(deviceId): { kind, owner? } | undefined; isClaimed is unchanged. A device with no claim at all is never on its way: a request's device between its registration and its boot claim, and a provisioning record a crash left behind, both look like that and are ignored.
• src/core/device-provisioner.ts:82-96: provision takes an optional claim: { kind: "boot", owner?: string } and, when given, takes that claim on the new device in the same decision section that registers it, holding it until the handoff. The request path passes its waiter id; the pool (in Warm targets: devices booted ahead of demand, exempt from idle shutdown, pre-created under fresh identity #370) passes a claim with no owner.
• src/core/acquisition-planner.ts:86-98: after the ready search and before the shutdown search, and only when noWait is false, find a device for which servesRequest holds (with the !isClaimed term moved out of it), that is provisioning or shutdown, and whose claim is of kind boot with no owner. If found, return wait. Under noWait the search is skipped and the plan is as today.
• A second request for the same model while the first is booting or creating its own device is unchanged: that device has an owner, so the second request plans as today.
• src/core/lease-acquisition-coordinator.ts: no change. A waiter woken by device.ready's kick re-plans and is granted the ready device, as today.
• Docs: docs/CONFIGURATION.md gains warmPool.reserveRunning.<platform> and a sentence on waiting for a device on its way under the lease section; docs/internal/ARCHITECTURE.md "Device requests" lists the new planner case; docs/internal/adr/0015-...md is not edited (ADR 0017 declares the narrowing).

Contract and event changes

config.get returns the new required warmPool.reserveRunning, so the protocol version moves to 17. device.shutdown with initiator warm-pool gains a cause: an idle device in a slot the reserve holds. No new events.

Rules in play

• architecture.md rules 10 (the budget stays in policy.ts; the planner reads claims, not the pool) and 15 (the planner learns a claim kind, never the pool).
• safety.md rule 10 for the new config values.

Tests

• policy.ts: with reserveRunning.ios: 1 and maxRunning 3, a third idle iOS device is proposed for shutdown and a second is not.
• policy.ts: with reserves ios 1 and android 1, the global budget is the global limit minus 2.
• policy.ts: a reserve above the platform limit proposes every idle device of that platform for shutdown.
• config: a negative or non-integer reserve fails the load naming warmPool.reserveRunning.ios.
• planner: a request whose only serving device is under an unowned boot claim plans wait; under noWait it plans as if the device were absent.
• planner: a request whose only serving device is provisioning under an unowned boot claim plans wait; one under a claim owned by another waiter, or with no claim at all, is ignored and the request provisions, as today.
• lease engine: a request waiting on a pool boot that fails re-plans on the kick and provisions its own device.
• planner: a serving device under an eviction or cleanup claim is ignored and the request provisions, as before.
• planner: a device on its way of another mode does not make the request wait.
• lease engine: a request arriving during a warm-pool boot that serves it is granted that device when the boot settles, and device.provisioned does not fire.

Done when

• With warmPool.reserveRunning.ios: 1 and an iOS running limit of 3, hold three fake iOS leases and release them one by one: the first released device stays shutdown with no device.ready after its device.reclaimed (two still leased leave no room under the reserve); once all three are released, two of the three are ready and one is shutdown (which one is not specified), and simlock status shows two warm iOS devices.
• With a warm-pool boot in flight for a fake iPhone 17, simlock lease --model "iPhone 17" is granted that device and simlock events shows one device.ready and no device.provisioned for it; the same lease with --no-wait provisions its own device, as today.
• simlock config prints warmPool.reserveRunning with both platforms at 0 by default.

Out of scope

• Targets (Warm targets: devices booted ahead of demand, exempt from idle shutdown, pre-created under fresh identity #370). Status reporting of the reserve (The warm pool in status, doctor, one event, and the console #371).

Depends on

• The warm pool module: one budget, a keep rule that fits, and an off switch #368

Approval

• Approved for delivery

Written by an agent.