proto: widen error-on-paused for ADR 0013's auto-pause signal (1.3.0)
DAEMON's docs/adr/0013-task-state-machine-ownership.md needs a wire signal
for the difference between a paused task the daemon entered unilaterally
(auth_required, server_file_changed, disk_full) and one that was requested
(user, schedule, queue stop, admission reconcile) -- without it, DAEMON's §3
resume rule ("resume only when the reason matches the event that justifies
resuming") has nothing correctness-preserving to key on, and would have to
guess from timing. CORE has already accepted the ADR; this was the sole
remaining blocker per DAEMON's own status line on it.
No retype, no new field -- error was already TaskError | null on both
event.task.state and TaskSummary, exactly as DAEMON characterized the ask.
Only the *description* of when it is populated widens: previously "failed or
retry_wait", now also "paused, when the daemon entered it on its own
initiative". A deliberate pause still carries error: null. TaskError's own
top-level description gets the same widening, since it previously also said
"failed or retry_wait" and would otherwise contradict the field that embeds
it.
New fixture (event.task.state.auto-paused.json) exercises the case directly:
an auth_required pause with error populated, contrasted in its own
description against download.pause.json's error: null for a requested pause.
The existing event.task.state.json fixture's first assertion was stale
("error is present exactly when failed or retry_wait") and is corrected.
Minor bump, 1.2.0 -> 1.3.0: a description widening on an already-nullable,
already-optional field changes no JSON Schema shape, but it is a real
behavioral commitment change worth a version bump so downstream regenerates
and notices, per the same reasoning ADR 0010 applied to TaskErrorCode.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_cpp.py
|
||||
// Contract: v1.2.0
|
||||
// Contract: v1.3.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_cpp.py
|
||||
@@ -27,7 +27,7 @@
|
||||
// docs/adr/0009-generated-protocol-library.md.
|
||||
namespace velox::proto {
|
||||
|
||||
inline constexpr std::string_view kProtocolVersion = "1.2.0";
|
||||
inline constexpr std::string_view kProtocolVersion = "1.3.0";
|
||||
|
||||
/// Why a payload could not be turned into a typed value. `path` is a JSON Pointer
|
||||
/// into the offending document, so a conformance failure names the exact field.
|
||||
@@ -750,9 +750,13 @@ struct Settings {
|
||||
std::optional<std::int64_t> connection_maxActiveSegments{};
|
||||
};
|
||||
|
||||
/// Why a task is in the failed or retry_wait state. Distinct from the JSON-RPC Error, which
|
||||
/// describes a failed call rather than a failed download — the two live in different code
|
||||
/// spaces on purpose, and `code` here is a TaskErrorCode string, never a JSON-RPC integer.
|
||||
/// Why a task is in the failed, retry_wait, or (when the daemon paused it on its own initiative
|
||||
/// rather than the user) paused state. Distinct from the JSON-RPC Error, which describes a
|
||||
/// failed call rather than a failed download — the two live in different code spaces on
|
||||
/// purpose, and `code` here is a TaskErrorCode string, never a JSON-RPC integer. A pause the
|
||||
/// user or the scheduler requested carries no error: this field only explains a paused state
|
||||
/// the daemon entered unilaterally (auth_required, server_file_changed, disk_full and the
|
||||
/// like), never a deliberate one.
|
||||
struct TaskError {
|
||||
TaskErrorCode code{};
|
||||
/// Human-readable, safe to show a user. Never carries a credential, a token or a full local
|
||||
@@ -808,6 +812,9 @@ struct TaskSummary {
|
||||
std::string createdAt{};
|
||||
std::optional<std::string> lastTryAt{};
|
||||
std::optional<std::string> completedAt{};
|
||||
/// Set when state is failed or retry_wait, and also when state is paused and the daemon entered
|
||||
/// that state on its own initiative rather than at a user's or scheduler's request. null on
|
||||
/// every other state, including a deliberate pause.
|
||||
std::optional<TaskError> error{};
|
||||
};
|
||||
|
||||
@@ -1394,6 +1401,12 @@ struct TaskStateEvent {
|
||||
TaskState state{};
|
||||
std::optional<TaskState> previousState{};
|
||||
std::optional<TaskSummary> summary{};
|
||||
/// Set when the new state is failed or retry_wait, and also when it is paused and the daemon
|
||||
/// entered that state on its own initiative — auth_required, server_file_changed, disk_full and
|
||||
/// the like — rather than because of a user action, a schedule window closing, or an
|
||||
/// admission-control decision. null on every other transition, including every
|
||||
/// deliberately-requested pause. A client must not assume a paused task has no error just
|
||||
/// because it usually doesn't; check this field rather than the state name alone.
|
||||
std::optional<TaskError> error{};
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user