vdm/docs/adr/0011-admission-control-and-the-segment-budget.md

# ADR 0011 — Admission control, the segment budget, and who counts what

**Status:** proposed · **Date:** 2026-09-09 · **Lane:** DAEMON, needs CORE sign-off
**Companion request:** `daemon/docs/core-requests-m1.md` (the engine API this depends on)
**Blocks:** `daemon/src/sched/` — no scheduler code lands before this is accepted.

## Context

Two lanes are each building a global concurrency governor, neither brief mentions the
other, and they are counting different things.

* **CORE** is adding `maxActiveSegments` (default 32) inside the engine — a ceiling on
  segments actually transferring at once. It is the mechanism that makes the RSS target in
  `docs/04` §8 hold (`core/docs/buffer-sizing.md`), so it is not optional.
* **DAEMON** is briefed to build "a concurrency governor (global max active, per-queue max,
  per-host caps)", backed by `connection.maxConcurrentDownloads`, `Queue.maxConcurrent`,
  schedules and queue order.

Left alone this lands in one of two states, and both are bad in a way that is hard to
diagnose after the fact:

1. **Double-throttling.** Both lanes enforce a global ceiling, so the effective limit is
   the minimum of two numbers the user set independently. The link runs at half rate and
   it reads as a performance bug in the engine, not as a policy collision.
2. **The gap.** Each lane assumes the other holds the line. Nobody does, 20 downloads open
   160 connections, and the RSS budget that `maxActiveSegments` exists to defend is gone.

There is a third problem underneath both. With `maxActiveSegments = 32` and
`connection.maxSegmentsPerDownload` capped at 32, one download can hold the entire segment
budget. If the daemon admits a second task and the engine has no slot to give it, the task
is *running* and transferring nothing: every DAEMON assumption that admission implies
progress — stall detection, speed accounting, queue drain, "when queue completes" — is
then wrong. CORE owns that fairness rule. DAEMON cannot write a governor without knowing
what it is.

## Decision

### 1. Every ceiling is enforced exactly once, by the lane that owns the unit it counts

This is the whole ADR in one line. The two governors stay two governors, on two axes, with
strictly non-overlapping units:

| Ceiling | Unit | Enforced by | Configured by |
|---|---|---|---|
| `connection.maxConcurrentDownloads` | tasks | DAEMON | user |
| `Queue.maxConcurrent` | tasks | DAEMON | user |
| per-host **task** cap | tasks | DAEMON | host table |
| schedules, windows, queue order, priority | tasks | DAEMON | user |
| `connection.maxActiveSegments` | segments | **CORE** | user |
| `connection.maxSegmentsPerDownload` | segments | **CORE** | user, per task |
| per-host **segment** cap | segments | **CORE** | host table, pushed by DAEMON |
| `bufferBytes` / `maxTotalBufferBytes` | bytes | **CORE** | user |
| speed limits (global → queue → task) | bytes/s | **CORE** | user, pushed by DAEMON |

Corollaries, and these are the parts that actually prevent the two failure modes:

* **DAEMON never counts segments to make an admission decision.** Not directly, and not by
  inferring occupancy from a download count. Its governor sees tasks.
* **CORE never refuses admission.** `start()` always accepts. The engine paces the task
  inside the segment budget; it does not decide that the task should not be running. A
  refusal would be a policy decision, and policy lives in the daemon with the queues and
  the SQL behind it.
* The pattern generalises: **DAEMON decides policy and configures; CORE enforces every
  ceiling counted in engine-internal units.** Rate limiting (`docs/04` §6) already works
  this way. Recording it here so it is not re-litigated per subsystem.

### 2. The one legitimate coupling — a clamp, not a second enforcement

DAEMON reads `maxActiveSegments` in exactly one place:

```
effective_max_running_tasks = min(connection.maxConcurrentDownloads,
                                  connection.maxActiveSegments)
```

with the same clamp applied per queue against that queue's share. The purpose is narrow:
never admit more concurrently-running tasks than the segment budget can give one segment
each. It is expressed in tasks, it throttles nothing that CORE also throttles, and it is
the reason §3's fairness rule is satisfiable.

At the shipped defaults (`maxConcurrentDownloads` 5, `maxActiveSegments` 32) the clamp is
not binding. It binds when a user raises concurrency to 64 or lowers the segment budget.

### 3. CORE's fairness rule — what DAEMON is allowed to assume

CORE owns this. It is recorded here because DAEMON's governor is built on top of it.

1. **Min-1 before seconds.** No task receives a second segment slot while any admitted task
   holds zero. A task's first slot always outranks another task's growth.
2. Beyond the first slot, remaining budget is distributed round-robin over running tasks in
   the priority order DAEMON supplies, up to each task's effective per-task cap:
   `min(spec.segments ?? maxSegmentsPerDownload, per-host segment cap, 1 if not resumable)`.
3. Slots are released on segment completion, pause, and failure. **A steal is
   slot-neutral** — the stealing worker already holds the slot it re-ranges.
4. A paused task holds no slots.
5. Therefore **admission implies progress**: a task DAEMON starts gets at least one
   transferring segment, subject only to the connect timeout and the per-host cap.
6. **Invariant:** `budget().tasks_starved == 0` in steady state. DAEMON asserts this. If it
   observes a non-zero value persisting past 2 s it logs a governor-invariant warning and
   surfaces it in `velox ls --json`; it does **not** compensate by throttling admission.
   Compensating is how the two governors would silently grow back into one.

Consequence for the starvation question in the brief: one download **cannot** take the
whole budget away from the next, because rule 1 makes the next task's first slot outrank
the incumbent's second. A single download alone in the system does legitimately grow to 32
segments, and gives slots back as tasks arrive — growth is opportunistic, the first slot is
guaranteed.

### 4. Per-host caps are split by unit, from one table

Both briefs say "per-host caps" and they are not the same cap.

* CORE enforces per-host **segment** caps — it owns the connections and is the only place
  segments are counted (`docs/04` §3, "clamped per-host by settings").
* DAEMON enforces a per-host **task** cap, set to that host's segment cap, so it can never
  admit more tasks for one host than that host can be given one segment each. Without this,
  rule 3.1 is unsatisfiable: four tasks on a host capped at 4 connections is fine, five is
  a guaranteed starved task no fairness rule can fix.
* The table itself is DAEMON state (SQLite, `settings`), pushed into the engine via
  `set_host_segment_cap()`. One source of truth, two enforcement points, different units.

### 5. Probes do not consume segment slots

A `download.probe` is a HEAD or a one-byte ranged GET. Charging it against the segment
budget would let a burst of probes starve transfers, and probes are on the latency path for
`capture.offer`'s 750 ms deadline. CORE bounds concurrent probes with its own small pool
(proposed: 4) outside the segment budget. `capture.offer` never blocks on a probe under any
circumstances — it answers `ignore` first and probes after.

### 6. Contract gap — `connection.maxActiveSegments` does not exist on the wire yet

`Settings.schema.json` has `maxSegmentsPerDownload`, `bufferBytes`,
`maxConcurrentDownloads`; it has neither `maxActiveSegments` nor `maxTotalBufferBytes`.
PROTO accepted the B2a follow-up bundle (`contracts/proto-answers-m1.md`) but it has not
landed, and `SettingKey` is a closed enum against `additionalProperties: false` — a daemon
**cannot** add the key locally without failing conformance.

Until PROTO lands it: DAEMON holds `maxActiveSegments` as a daemon-local value defaulted to
32, passes it to `set_max_active_segments()` at startup, and does not expose it through
`settings.get` / `settings.set`. Filed as request C4 in `daemon/docs/core-requests-m1.md`
(to PROTO, alongside CORE's existing ask).

## Alternatives considered

**DAEMON enforces both.** The governor would have to predict each task's effective segment
count to spend a segment budget in task units — but that count depends on the probe result,
the per-host cap, the resumability demotion and live steals, all engine-internal and all
changing continuously. Predicting it means either over-admitting (the gap) or leaving the
link idle. Rejected: it asks the daemon to model the engine.

**CORE enforces both.** The engine would take every task and decide which run. That drags
queues, schedules, priority, and "when queue completes" into `core/`, which the layering
rule forbids and which would need SQL to be correct. Rejected.

**A shared semaphore object handed to both lanes.** Superficially the "one counter" answer,
but it makes a mutable engine resource part of the daemon's API surface, inverts the
dependency direction, and is the first thing that will deadlock under pause-during-steal.
Rejected: one counter, one owner, read-only snapshots for everyone else.

## Consequences

* `daemon/src/sched/` may be written against a task-unit model only. A segment count
  appearing in an admission decision is a review-blocking defect.
* DAEMON needs an occupancy read-out rather than an inference — the engine API requested in
  `daemon/docs/core-requests-m1.md` §1 (`budget()`, `segments_active(TaskId)`, a coalesced
  change callback). Without it, projecting `TaskSummary.segments` (which ADR 0010 pinned to
  the *effective* count) is guesswork.
* CORE's fairness rule needs a test that DAEMON can point at: N tasks admitted, budget
  smaller than N × their per-task caps, assert every task holds ≥ 1 segment.
* If CORE cannot honour min-1 for a reason not anticipated here, this ADR is wrong rather
  than incomplete — say so before `sched/` exists, which is the entire point of settling it
  now.

## Open, for CORE to confirm or amend

1. Min-1 before seconds (§3.1) — is it implementable inside the stealer without a
   priority inversion at slot release?
2. Probe pool outside the segment budget, size 4 (§5).
3. Does `set_max_active_segments()` apply live, draining as slots free rather than killing
   in-flight segments?
4. `Priority` shape: an integer, or DAEMON handing over an ordered task list per tick?
5. Coalescing rate for the budget-change callback — 4 Hz to match the event-batching rate?