daemon: D4b — download.pause/resume/start/cancel and queue.start/stop drive the scheduler

download.pause/resume/start/cancel and queue.start/stop were stubs; now they call into
the scheduler and take effect immediately, not on the next 1s tick — pausing, resuming
or cancelling a live transfer can't wait, and per ADR 0013 §3 the governor never
touches a user-owned pause on its own.

New rpc::TaskActionPort interface (owned by rpc/, implemented by sched::Scheduler) is
what dispatcher.hpp depends on instead of sched/scheduler.hpp directly. Needed because
veloxd_sched already links veloxd_rpc (for EventHub); dispatcher.hpp pulling in
sched/scheduler.hpp directly would make it a real circular library dependency, breaking
anything that links veloxd_rpc alone (cli's tests, as it turned out — hit and fixed
during this change).

Scheduler::user_pause/user_resume/user_start/user_cancel + pause_queue follow tick()'s
existing to_pause pattern: call the engine (async, no synchronous effect) and transition
the store eagerly so download.get/list are correct the instant the RPC call returns.

Fixed a real bug surfaced while building this: transition() always overwrote
pause_reason to NULL when the engine's own delayed pause-ack callback (on_state to
paused, no error) arrived after whoever actually initiated the pause had already
written the real reason — now it preserves the stored reason when the callback supplies
none, instead of clobbering it. Covered by a regression check in sched_scheduler_test.

store/queues gets get() and set_state() (was list()-only) for queue.start/stop.

Verified against real veloxd + tools/testserver, not just unit tests: pausing a live
single-segment throttled transfer freezes downloadedBytes, resume continues it from
that point, cancel stops it; a bad taskId comes back in BulkTaskResult.failed with
-32010, not a crash; queue.stop(pauseRunning:true) pauses the queue's running task
immediately and queue.start resumes admission.

Known gap: download.start's contract "a task in 'queued' jumps its queue" (priority
bump) is not implemented — admission is still plain FIFO by created_at. Noted in
deferrals.md.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01GRDjHGgpYmMoPE2UFbe7pP

daemon/src/rpc/dispatcher.cpp

@@ -28,6 +28,29 @@ proto::HandlerResult<T> not_implemented(const char* method) {
         std::string("not implemented in this build: ") + method});
 }
 
+// Shared by download.pause/resume/start/cancel: apply `action` to every id in `task_ids`
+// and fold the per-task velox::daemon::rpc::TaskActionPort::Result into a
+// BulkTaskResult (ADR: "a bulk call never fails as a whole because one id was bad").
+proto::BulkTaskResult bulk_apply(
+    const std::vector<std::string>& task_ids,
+    const std::function<velox::daemon::rpc::TaskActionPort::Result(const std::string&)>&
+        action) {
+    proto::BulkTaskResult out;
+    for (const auto& id : task_ids) {
+        const auto r = action(id);
+        if (!r.found) {
+            out.failed.push_back({id, proto::ErrorCode::TaskNotFound, "no such task"});
+            continue;
+        }
+        proto::BulkTaskResultUpdatedItem item;
+        item.taskId = id;
+        item.changed = r.changed;
+        if (auto st = proto::parse_TaskState(r.state)) item.state = *st;
+        out.updated.push_back(std::move(item));
+    }
+    return out;
+}
+
 // A v4 UUID for a new task id.
 std::string new_task_id() {
     std::random_device rd;
@@ -237,8 +260,13 @@ VeloxDispatcher::on_download_addBatch(const proto::DownloadAddBatchParams&) {
     return not_implemented<proto::DownloadAddBatchResult>("download.addBatch");
 }
 proto::HandlerResult<proto::BulkTaskResult>
-VeloxDispatcher::on_download_cancel(const proto::DownloadCancelParams&) {
-    return not_implemented<proto::BulkTaskResult>("download.cancel");
+VeloxDispatcher::on_download_cancel(const proto::DownloadCancelParams& params) {
+    if (!actions_) return not_implemented<proto::BulkTaskResult>("download.cancel");
+    auto result = bulk_apply(params.taskIds, [this](const std::string& id) {
+        return actions_->user_cancel(id, /*discard_partial=*/false);
+    });
+    if (on_mutation_) on_mutation_();
+    return result;
 }
 proto::HandlerResult<proto::TaskDetail>
 VeloxDispatcher::on_download_get(const proto::DownloadGetParams& params) {
@@ -273,8 +301,12 @@ VeloxDispatcher::on_download_get(const proto::DownloadGetParams& params) {
     return d;
 }
 proto::HandlerResult<proto::BulkTaskResult>
-VeloxDispatcher::on_download_pause(const proto::DownloadPauseParams&) {
-    return not_implemented<proto::BulkTaskResult>("download.pause");
+VeloxDispatcher::on_download_pause(const proto::DownloadPauseParams& params) {
+    if (!actions_) return not_implemented<proto::BulkTaskResult>("download.pause");
+    auto result = bulk_apply(params.taskIds,
+                             [this](const std::string& id) { return actions_->user_pause(id); });
+    if (on_mutation_) on_mutation_();
+    return result;
 }
 proto::HandlerResult<proto::DownloadProbeResult>
 VeloxDispatcher::on_download_probe(const proto::DownloadProbeParams&) {
@@ -293,12 +325,20 @@ VeloxDispatcher::on_download_remove(const proto::DownloadRemoveParams&) {
     return not_implemented<proto::DownloadRemoveResult>("download.remove");
 }
 proto::HandlerResult<proto::BulkTaskResult>
-VeloxDispatcher::on_download_resume(const proto::DownloadResumeParams&) {
-    return not_implemented<proto::BulkTaskResult>("download.resume");
+VeloxDispatcher::on_download_resume(const proto::DownloadResumeParams& params) {
+    if (!actions_) return not_implemented<proto::BulkTaskResult>("download.resume");
+    auto result = bulk_apply(
+        params.taskIds, [this](const std::string& id) { return actions_->user_resume(id); });
+    if (on_mutation_) on_mutation_();
+    return result;
 }
 proto::HandlerResult<proto::BulkTaskResult>
-VeloxDispatcher::on_download_start(const proto::DownloadStartParams&) {
-    return not_implemented<proto::BulkTaskResult>("download.start");
+VeloxDispatcher::on_download_start(const proto::DownloadStartParams& params) {
+    if (!actions_) return not_implemented<proto::BulkTaskResult>("download.start");
+    auto result = bulk_apply(
+        params.taskIds, [this](const std::string& id) { return actions_->user_start(id); });
+    if (on_mutation_) on_mutation_();
+    return result;
 }
 proto::HandlerResult<proto::TaskSummary>
 VeloxDispatcher::on_download_update(const proto::DownloadUpdateParams&) {
@@ -346,12 +386,54 @@ VeloxDispatcher::on_queue_reorder(const proto::QueueReorderParams&) {
     return not_implemented<proto::QueueReorderResult>("queue.reorder");
 }
 proto::HandlerResult<proto::QueueStartResult>
-VeloxDispatcher::on_queue_start(const proto::QueueStartParams&) {
-    return not_implemented<proto::QueueStartResult>("queue.start");
+VeloxDispatcher::on_queue_start(const proto::QueueStartParams& params) {
+    store::Queues queues(db_);
+    auto exists = queues.get(params.queueId);
+    if (!exists)
+        return std::unexpected(proto::HandlerError{proto::ErrorCode::InternalError,
+                                                   "queue.start: " + exists.error().message});
+    if (!exists->has_value())
+        return std::unexpected(proto::HandlerError{
+            proto::ErrorCode::InvalidParams, "no such queue",
+            nlohmann::json{{"queueId", params.queueId}}});
+
+    (void)queues.set_state(params.queueId, "running");
+    // Nudged through the same deferred tick() as download.add (on_mutation_ posts onto the
+    // loop) — which tasks actually get admitted happens asynchronously (tick()'s to_start
+    // even probes before it starts one), so startedTaskIds is not knowable synchronously
+    // here; the GUI learns the real outcome from event.task.state as each one lands.
+    if (on_mutation_) on_mutation_();
+
+    auto after = queues.get(params.queueId);
+    proto::QueueStartResult r;
+    if (after && after->has_value()) r.queue = **after;
+    return r;
 }
 proto::HandlerResult<proto::QueueStopResult>
-VeloxDispatcher::on_queue_stop(const proto::QueueStopParams&) {
-    return not_implemented<proto::QueueStopResult>("queue.stop");
+VeloxDispatcher::on_queue_stop(const proto::QueueStopParams& params) {
+    store::Queues queues(db_);
+    auto exists = queues.get(params.queueId);
+    if (!exists)
+        return std::unexpected(proto::HandlerError{proto::ErrorCode::InternalError,
+                                                   "queue.stop: " + exists.error().message});
+    if (!exists->has_value())
+        return std::unexpected(proto::HandlerError{
+            proto::ErrorCode::InvalidParams, "no such queue",
+            nlohmann::json{{"queueId", params.queueId}}});
+
+    (void)queues.set_state(params.queueId, "stopped");
+
+    proto::QueueStopResult r;
+    // "the difference between 'stop the queue' and 'stop everything', which IDM
+    // conflates" (the schema's own words) — absent means the soft stop: only halt new
+    // admissions, let what's running finish.
+    if (params.pauseRunning.value_or(false) && actions_)
+        r.pausedTaskIds = actions_->pause_queue(params.queueId);
+    if (on_mutation_) on_mutation_();
+
+    auto after = queues.get(params.queueId);
+    if (after && after->has_value()) r.queue = **after;
+    return r;
 }
 proto::HandlerResult<proto::QueueUpsertResult>
 VeloxDispatcher::on_queue_upsert(const proto::QueueUpsertParams&) {

daemon/src/rpc/dispatcher.hpp

@@ -15,6 +15,7 @@
 #include <functional>
 
 #include "rpc/event_hub.hpp"
+#include "rpc/task_action_port.hpp"
 #include "store/sqlite.hpp"
 #include "velox_proto.hpp"
 
@@ -22,7 +23,15 @@ namespace velox::daemon::rpc {
 
 class VeloxDispatcher final : public velox::proto::Dispatcher {
 public:
-    VeloxDispatcher(velox::daemon::store::Db& db, EventHub& hub) : db_(db), hub_(hub) {}
+    // `actions` drives download.pause/resume/start/cancel and queue.start/stop
+    // immediately (D4b) — those cannot wait for the next tick(), unlike download.add's
+    // on_mutation nudge. Optional so existing tests that only exercise download.add/list/
+    // get keep building with no scheduler at hand; a null actions_ makes those methods
+    // answer "not implemented" instead of crashing. See rpc/task_action_port.hpp for why
+    // this is an interface owned by rpc/ rather than a direct sched::Scheduler* (avoids a
+    // veloxd_rpc <-> veloxd_sched circular library dependency).
+    VeloxDispatcher(velox::daemon::store::Db& db, EventHub& hub, TaskActionPort* actions = nullptr)
+        : db_(db), hub_(hub), actions_(actions) {}
 
     // Called after a handler mutates task state (download.add for now). main.cpp wires it
     // to nudge the scheduler; unset in tests.
@@ -109,6 +118,7 @@ public:
 private:
     velox::daemon::store::Db& db_;
     EventHub& hub_;
+    TaskActionPort* actions_;
     std::function<void()> on_mutation_;
 };
 

daemon/src/rpc/task_action_port.hpp

@@ -0,0 +1,44 @@
+#pragma once
+
+// The seam between the dispatcher and the scheduler for user-initiated task/queue actions
+// (download.pause/resume/start/cancel, queue.stop's pauseRunning) — owned by rpc/ so
+// dispatcher.hpp (part of veloxd_rpc) never has to include sched/scheduler.hpp, which
+// would make veloxd_rpc depend on veloxd_sched at compile time. veloxd_sched already
+// depends on veloxd_rpc (for EventHub); the other direction too would be a real circular
+// library dependency, not just an inconvenience — anything linking veloxd_rpc alone (e.g.
+// the CLI's tests) would fail to link over symbols it never calls.
+//
+// sched::Scheduler implements this directly (it already lives in a library that depends on
+// rpc/, so adding an rpc-defined base costs nothing new); main.cpp hands the dispatcher a
+// `TaskActionPort*` pointing at the same Scheduler it constructs.
+
+#include <string>
+#include <vector>
+
+namespace velox::daemon::rpc {
+
+class TaskActionPort {
+public:
+    virtual ~TaskActionPort() = default;
+
+    // Mirrors sched::Scheduler::UserActionResult: whether the task was found at all,
+    // whether it actually changed state (a task already in the target/a terminal state is
+    // reported found=true, changed=false — BulkTaskResult's own "not an error" contract),
+    // and its resulting/current state spelling either way.
+    struct Result {
+        bool found = false;
+        bool changed = false;
+        std::string state;
+    };
+
+    virtual Result user_pause(const std::string& wire_id) = 0;
+    virtual Result user_resume(const std::string& wire_id) = 0;
+    virtual Result user_start(const std::string& wire_id) = 0;
+    virtual Result user_cancel(const std::string& wire_id, bool discard_partial) = 0;
+
+    // queue.stop(pauseRunning=true): pause every currently-running task in `queue_id` now.
+    // Returns the wire ids actually paused.
+    virtual std::vector<std::string> pause_queue(const std::string& queue_id) = 0;
+};
+
+}  // namespace velox::daemon::rpc