vdm/docs/adr/0013-task-state-machine-ownership.md

ADR 0013 — Task state-machine ownership: CORE, DAEMON, and the shared paused

Status: proposed · Date: 2026-09-09 · Lane: DAEMON, drafted at PROTO's request (D1 in core/docs/proto-requests-m1.md), for CORE and PROTO to review and sign off. Needs: explicit accept from CORE and PROTO before daemon/src/sched/ calls into CORE's task-start API, since the calling convention below is derived from this split.

Context

docs/04 §1 hands CORE the download lifecycle (probing → connecting → downloading ⇄ paused → retry_wait → assembling → verifying → complete | failed), but queued and every scheduler transition are DAEMON's, and neither brief says where the seam is. PROTO raised this as D1 and proposed a split; CORE agreed (contracts/proto-answers-m1.md D1); both declined to write it down alone — a two-lane decision recorded by the lane that owns neither half is exactly the failure mode contracts/README.md rule 4 exists to prevent. DAEMON drafts it because DAEMON is the one lane touching both halves (it owns the SQL row and the RPC surface; it calls into CORE).

The wire side is already frozen and does not need to change: TaskState (contracts/schema/types/TaskState.schema.json) has the twelve values with no field naming who drove a transition, and event.task.state carries previousState — a client renders what it's told and keeps no state machine of its own. This ADR is about who decides a transition, not the wire shape of one.

This is also where ADR 0011 (admission control) and the state machine meet: queued → connecting is the admission event, and retry_wait looks identical to starvation from inside the segment-budget accounting. Both are addressed below because getting them wrong independently produces the same false alarm from two different directions.

Decision

1. Ownership, by state

State	Driven by	Entered from	Notes
new	DAEMON	(creation)	download.add persists the row before CORE knows the task exists.
queued	DAEMON	new, paused (resume, subject to §3)	Scheduler admission pool. CORE has no concept of "queued" — retry_wait re-enters connecting directly inside CORE and never passes back through queued.
probing	CORE	queued	DAEMON calls CORE's start() once admitted (ADR 0011 §1); CORE owns everything from here until it hands back a terminal or paused state.
connecting	CORE	probing, retry_wait
downloading	CORE	connecting
paused	shared	any CORE state, queued	See §2 — this is the one state either side may enter unilaterally.
retry_wait	CORE	connecting, downloading	CORE's own backoff timer (docs/04 §7); DAEMON does not schedule retries.
assembling	CORE	downloading	Normally a no-op rename; a real state for HLS/DASH muxing.
verifying	CORE	assembling	Checksum verification when requested.
complete	CORE	verifying	Terminal.
failed	CORE	any CORE state	Terminal. max_retries_exhausted after retry_wait, or any non-retryable error.
cancelled	DAEMON	any state	Terminal. Always user- or policy-initiated (download.cancel, category/queue removal) — CORE never cancels on its own; it only executes the teardown DAEMON asked for and confirms.

Reading the table as a picture:

DAEMON:  new ──▶ queued ──▶[admit]──▶ (hand to CORE)
                   ▲                        │
                   │ resume            CORE: probing ─▶ connecting ─▶ downloading
          pause────┤                              │           │  ▲       │  │
      (either side)│                        retry_wait◀────────┘  │      │  │
                   ▼                              │  (backoff done)│      ▼  ▼
                paused ◀──────────(auto-pause)─────┘         assembling  paused
                                                                    │   (auto)
                                                              verifying
                                                                    │
                                                               complete
        (from anywhere, DAEMON-driven) ──────────────────────▶ cancelled
        (from any CORE state, CORE-driven, non-retryable) ───▶ failed

2. paused is shared, and idempotency is the whole contract

Both sides can put a task in paused, for disjoint reasons:

• DAEMON-initiated: user clicks pause, a schedule window closes, a queue is stopped, Queue.onComplete, or the admission governor reconciling a lowered maxActiveSegments (ADR 0011 §2 — pausing the lowest-priority excess). DAEMON calls CORE's pause(TaskId).
• CORE-initiated ("auto-pause"): auth_required (401/407, docs/04 §7), server_file_changed (F1's carrier, contracts/proto-answers-m1.md), disk full. CORE transitions to paused on its own and reports it up through the existing state-change callback — the same path every other CORE-driven transition uses. This is not a new mechanism.

The contract that makes this safe:

• pause() is idempotent. DAEMON calling pause() on a task CORE already auto-paused is a no-op, not an error — DAEMON does not need to know CORE got there first. Symmetrically, if CORE were ever mid-transition to paused when DAEMON's pause request arrives, the result is still paused, once.
• DAEMON persists why a task is paused, in the tasks table, not in TaskState itself (the wire type stays a flat enum — this is DAEMON-local bookkeeping, not a contract change). A pauseReason distinguishing at least user, schedule, queue_stopped, admission_reconcile, and CORE's error.code when auto-paused. This is what makes §3's resume rule possible — but it needs a contract fix first: see the gap in open item 3 below. error.code is not currently carried on a transition into paused at all.
• CORE does not need to track why it's paused past the current occurrence. Once paused, CORE's job is done; DAEMON is the only side that later decides whether to resume, and DAEMON is also the only side with persistent storage to remember the reason across a restart.

3. Resume must not cross reasons

The bug this section exists to prevent: a schedule window opens, DAEMON blindly resumes every paused task in that queue, and it resumes a task CORE paused because it's waiting on credentials that were never provided. The task immediately re-fails or re-pauses, looks like a flapping bug, and burns a retry.

Rule: DAEMON resumes a task only when the reason it recorded matches the event that justifies resuming. A schedule window opening resumes tasks paused for schedule. A user clicking "resume" resumes anything (explicit user intent overrides any reason). auth_required and server_file_changed are resumed only by the paths that actually address them — download.provideAuth (F2) and the user's restart-decision response (F1) — never by the scheduler. This means queued is not the only state a schedule can put a task back into a run cycle from; the scheduler's "should this task be running right now" check must skip tasks paused for a reason it doesn't own.

4. retry_wait is not starvation

ADR 0011 §3.6 defines a starved task as a running task with segments_active(id) == 0, and asserts tasks_starved == 0 in steady state past a bounded delay. A task in retry_wait also holds zero segments, deliberately, for up to 60 s (docs/04 §7's backoff cap) — and it is not admission-starved, it is CORE's own policy holding it idle.

Resolution: retry_wait must be distinguishable from true starvation without DAEMON guessing from timing. CORE's starved_tasks() (ADR 0011) excludes any task CORE itself holds at zero by policy — retry_wait and CORE-initiated paused both fall outside tasks_starved by construction, because that accessor is about the segment allocator failing to grant a slot to a task that wants one, not about a task that isn't asking. A task in retry_wait still counts against connection.maxConcurrentDownloads from DAEMON's side (it is running, not requeued) but contributes nothing to the segment allocator's guarantee pass until it re-enters connecting.

5. Restart — CORE holds no persistent state, DAEMON reloads to queued

Per the M1 DoD ("kill and restart the daemon mid-download: all tasks reload with correct state and resume") and the layering rule (CORE has no SQL, no state survives a CORE restart except what's on disk in .veloxpart.meta, which CORE reads back itself): on daemon startup, DAEMON loads every non-terminal task from SQLite. Any task whose persisted TaskState was a CORE-owned state (probing through verifying) is rewritten to queued in memory before the scheduler sees it — the on-disk TaskState is a last-known-value, not a resumable position, because CORE's in-process state died with the process. The scheduler re-admits it exactly like any other queued task; CORE re-derives where to actually resume from .veloxpart.meta and re-validates with If-Range (docs/04 §5), independent of what SQL said the state was.

paused tasks reload as paused, with their pauseReason intact, and are not auto-admitted — §3 applies identically after a restart as it does live.

Consequences

• daemon/src/sched/ calls start(TaskId) exactly once per admission (queued → probing), never re-enters a CORE-owned state directly, and treats every CORE-owned state as opaque past that call except for reading it back for projection.
• The tasks table needs a pauseReason column (DAEMON-local; not a wire type) before sched/'s pause/resume logic can be written correctly — flagging as a concrete follow-up, not blocking this ADR's acceptance.
• CORE's starved_tasks() (ADR 0011) must exclude retry_wait and CORE-auto-paused tasks by construction; if that isn't already true in CORE's accessor, it needs to be before DAEMON relies on the starvation invariant, since otherwise every backoff cycle would trip DAEMON's governor-invariant warning as a false positive.
• No contracts/ change. TaskState, event.task.state, and previousState are already sufficient; this ADR is entirely about which process calls which function when.

Alternatives considered

A single owner drives every transition (CORE, told about queues). Rejected — this is the D1 problem restated with CORE holding the SQL-shaped concepts (queued, schedules, priority) that the layering rule (CLAUDE.md §3) forbids it from touching.

DAEMON drives every transition, treating CORE as a dumb byte-mover. Rejected — CORE's internal states (retry_wait, assembling, verifying) depend on engine internals (backoff timers, mux completion, streaming hash state) DAEMON has no visibility into without CORE reporting them; forcing DAEMON to poll or reimplement that timing duplicates docs/04 §7 in two places and they will drift.

A pauseReason on the wire (TaskState split into paused_user / paused_auto / etc.). Rejected — it roughly doubles the enum for a fact only DAEMON's resume logic needs, and adding wire cardinality for internal bookkeeping is the kind of thing that becomes a compatibility problem the moment a client starts branching on it. The value DAEMON needs (CORE's reason) can travel on the existing error field instead — see the contract gap in open item 3 — without touching TaskState itself.

A contract gap this ADR surfaces, not just an open question

event.task.state.schema.json's own description scopes error to "whenever the new state is failed or retry_wait" — not paused. The one fixture (event.task.state.json) only exercises the failed case. So today, when CORE auto-pauses for auth_required or server_file_changed, DAEMON has no signal on the wire telling it why — §2/§3 of this ADR are unbuildable without one. This needs a PROTO follow-up (minor: widening an existing field's presence condition, per contracts/README.md rule 4 — no new field, no retype) to also populate error when state == "paused" and the pause was CORE-initiated. DAEMON is not asking for a way to tell CORE-paused from user-paused on the wire in general — error: null on a DAEMON-initiated pause is sufficient, since DAEMON already knows it just did that.

Open, for CORE and PROTO to confirm or amend

1. Does CORE's starved_tasks() already exclude retry_wait and auto-paused tasks, or does this ADR ask for a behavior change there (§4)?
2. Is pause() idempotent today, or does calling it on an already-paused task currently return an error CORE needs to relax?
3. PROTO: land the error-on-paused widening above before DAEMON writes the resume logic in §3 — otherwise DAEMON has no correctness-preserving way to implement it and would have to guess from timing, which is the exact failure mode ADR 0011 was written to rule out for a different pair of governors.
4. Naming: is "auto-pause" the term CORE already uses internally, or does CORE have an existing name for this that this ADR should adopt instead of introducing a new one?