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:
2026-09-10 00:04:35 +04:00
co-authored by Claude Sonnet 5
parent 203d4a662f
commit 6db304a0ae
16 changed files with 179 additions and 40 deletions
+52 -9
View File
@@ -2,17 +2,60 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://velox.dev/schema/types/TaskError.schema.json",
"title": "TaskError",
"description": "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.",
"description": "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 \u2014 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.",
"type": "object",
"additionalProperties": false,
"required": ["code", "message", "retryable"],
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": { "$ref": "https://velox.dev/schema/types/TaskErrorCode.schema.json" },
"message": { "type": "string", "description": "Human-readable, safe to show a user. Never carries a credential, a token or a full local path outside the download roots." },
"httpStatus": { "type": ["integer", "null"], "minimum": 100, "maximum": 599, "description": "Set for the codes listed in TaskErrorCode's x-carriesHttpStatus, and null otherwise." },
"retryable": { "type": "boolean", "description": "Whether the scheduler will pick this task up again on its own. Carried per-occurrence rather than derived from the code, because 'probe_failed' is retryable or not depending on what the probe hit." },
"cause": { "oneOf": [{ "$ref": "https://velox.dev/schema/types/TaskErrorCode.schema.json" }, { "type": "null" }], "description": "The underlying failure, for codes that wrap one. max_retries_exhausted sets it to whatever the last attempt actually failed with, so a user learns the reason rather than just that Velox gave up." },
"attempt": { "type": ["integer", "null"], "minimum": 0, "description": "How many attempts have been made so far." },
"nextRetryAt":{ "type": ["string", "null"], "format": "date-time" }
"code": {
"$ref": "https://velox.dev/schema/types/TaskErrorCode.schema.json"
},
"message": {
"type": "string",
"description": "Human-readable, safe to show a user. Never carries a credential, a token or a full local path outside the download roots."
},
"httpStatus": {
"type": [
"integer",
"null"
],
"minimum": 100,
"maximum": 599,
"description": "Set for the codes listed in TaskErrorCode's x-carriesHttpStatus, and null otherwise."
},
"retryable": {
"type": "boolean",
"description": "Whether the scheduler will pick this task up again on its own. Carried per-occurrence rather than derived from the code, because 'probe_failed' is retryable or not depending on what the probe hit."
},
"cause": {
"oneOf": [
{
"$ref": "https://velox.dev/schema/types/TaskErrorCode.schema.json"
},
{
"type": "null"
}
],
"description": "The underlying failure, for codes that wrap one. max_retries_exhausted sets it to whatever the last attempt actually failed with, so a user learns the reason rather than just that Velox gave up."
},
"attempt": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "How many attempts have been made so far."
},
"nextRetryAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
@@ -132,7 +132,8 @@
{
"type": "null"
}
]
],
"description": "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."
}
}
}