sami/vdm
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

proto: answer CORE's freeze-blockers before 1.0.0 lands

Browse Source 
Three corrections into 1.0.0, all of which would be major bumps once the
contract has landed. It has not: main still carries 1.0.0-draft, so these are
corrections to an unpublished version rather than changes to a released one.
ADR 0010 records that and the reasoning behind each.

B1 — TaskError.code was a bare integer, and the integer space in the contract is
JSON-RPC's, which is a different thing; TaskError's own description said so while
typing its code as one. Freeze TaskErrorCode: a string enum mirroring vdm::Error
by name and in order, all 27 failure values, verified against
core/include/vdm/util/error.hpp mechanically. ErrorCode says why a call failed;
TaskErrorCode says why a download failed, and a download fails while every RPC
succeeds. Adds TaskError.cause so max_retries_exhausted names what kept failing.

B2 — TaskSummary.segments is now explicitly the effective count in use right now,
after the per-host cap and the non-resumable demotion to 1. DownloadSpec.segments
and download.update's patch say they are the requested value.

B3 — Segment.endByte's "minimum: 0" contradicted the description's own empty-range
encoding of startByte - 1, which is -1 for the first segment of every download.
Empty ranges are no longer representable and are not needed. The range stays
CLOSED and INCLUSIVE, matching the HTTP Range header the two fields are copied
into verbatim, and that is now stated in the schema, the README, an ADR, a fixture
assertion and a conformance check. CORE asked for half-open and gets a written
notice rather than a silent schema edit. Segment state spells 'downloading' as
CORE asked, not 'receiving'.

check_contract.py now enforces segment contiguity, coverage of exactly
[0, sizeBytes-1], downloadedBytes within the range size, and the entry count
matching TaskSummary.segments. The download.get fixture claimed 8 segments while
carrying 2; it now carries 8 contiguous ones covering the whole file.

contracts/proto-answers-m1.md answers every item in core/docs/proto-requests-m1.md,
including the ones not being landed now: B2a and F2 accepted as follow-ups, F1
answered with the notify path for M1, F3 already frozen as a Checksum object
rather than a string, and D1 left for DAEMON to draft as the three-way ADR it is.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
This commit is contained in:
sami
2026-09-09 20:01:47 +04:00
co-authored by Claude Opus 5
parent 53421d6cb8
commit 2c8f5e5d7d
19 changed files with 1306 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
extension/src/shared/protocol/types.ts
+119 -9
View File
@@ -207,6 +207,12 @@ export interface DownloadSpec {
categoryId?: string | null;
/** Required when startMode is 'queue'. */
queueId?: string | null;
/**
* The REQUESTED connection count. An upper bound, not a promise: the daemon lowers it to
* the per-host cap, and to 1 when the source turns out not to be resumable. What is
* actually in use comes back as TaskSummary.segments. null means use
* connection.maxSegmentsPerDownload.
*/
segments?: number | null;
bufferBytes?: number | null;
startMode?: StartMode;
@@ -374,11 +380,15 @@ export interface Rule {
action: RuleAction;
}
export type SegmentState = "pending" | "connecting" | "receiving" | "stalled" | "complete" | "failed";
/**
* 'downloading' is spelled as in TaskState, not 'receiving'. 'pending' is a range that has
* been planned but not yet dialled.
*/
export type SegmentState = "pending" | "connecting" | "downloading" | "stalled" | "complete" | "failed";
export const SEGMENT_STATE_VALUES = [
"pending",
"connecting",
"receiving",
"downloading",
"stalled",
"complete",
"failed",
@@ -386,17 +396,42 @@ export const SEGMENT_STATE_VALUES = [
/**
* One byte range being fetched by one connection. This is the deepest the contract ever
* exposes the engine: the GUI draws a bar per segment and never learns what a segment
* steal is.
* exposes the engine: the GUI draws a bar per segment and is never told what a segment
* steal is. RANGE CONVENTION — READ THIS BEFORE IMPLEMENTING. The range is CLOSED and
* INCLUSIVE on both ends: [startByte, endByte]. The segment covers endByte - startByte + 1
* bytes, and endByte is the index of the LAST byte in the range, not one past it. This
* deliberately matches the HTTP Range header the engine actually sends ('Range:
* bytes=<startByte>-<endByte>' is a byte-for-byte copy of these two fields, and RFC 9110
* ranges are inclusive), so no arithmetic happens between the wire and the socket and
* there is nowhere for an off-by-one to hide. CORE asked for half-open [start, end); PROTO
* chose inclusive for that reason and this note exists so nobody discovers the difference
* at integration. A segment always covers at least one byte: endByte >= startByte always
* holds. An empty range is not representable and is not needed — a zero-length download
* carries an empty segmentDetail array, and a segment that has donated its remainder to a
* steal keeps the bytes it already wrote.
*/
export interface Segment {
/**
* Position in TaskDetail.segmentDetail. Spelled 'index' here and in event.task.progress;
* there is no 'i' spelling anywhere in the contract.
*/
index: number;
/** Absolute offset of the first byte of the range. Inclusive. */
startByte: number;
/** Inclusive. Equal to startByte - 1 for an empty segment. */
/**
* Absolute offset of the LAST byte of the range. Inclusive — this is not one-past-the-end.
* Always >= startByte.
*/
endByte: number;
/** Bytes written for this range so far, out of endByte - startByte + 1. */
downloadedBytes: number;
speedBps?: number;
/**
* 'downloading' is spelled as in TaskState, not 'receiving'. 'pending' is a range that has
* been planned but not yet dialled.
*/
state: SegmentState;
/** The status this segment's request got. 206 on a healthy ranged fetch. */
httpStatus?: number | null;
}
@@ -541,15 +576,73 @@ export interface Settings {
"sounds.onError"?: string;
}
/**
* Why a download failed. This is the WIRE failure taxonomy and it is deliberately NOT the
* JSON-RPC ErrorCode space: ErrorCode says why a *call* failed, TaskErrorCode says why a
* *download* failed. A task can fail while every RPC involved succeeded. The values mirror
* vdm::Error in core/include/vdm/util/error.hpp one-for-one, by name, so DAEMON's
* projection from the engine taxonomy onto the wire is lossless and the GUI can tell 'the
* file on the server changed' from 'the checksum did not match'. CORE's 'ok' has no wire
* spelling: a TaskError only exists when there is a failure. Adding a value here is a
* minor bump; renaming or removing one is major, and would desynchronise the engine.
*/
export type TaskErrorCode = "canceled" | "resolve_failed" | "connect_failed" | "tls_failed" | "connection_reset" | "timeout" | "too_many_redirects" | "http_client_error" | "http_server_error" | "auth_required" | "forbidden" | "not_found" | "range_not_satisfiable" | "gone" | "server_file_changed" | "content_length_mismatch" | "checksum_mismatch" | "disk_full" | "io_error" | "path_rejected" | "permission_denied" | "meta_corrupt" | "meta_version_unsupported" | "probe_failed" | "unsupported_url_scheme" | "max_retries_exhausted" | "internal";
export const TASK_ERROR_CODE_VALUES = [
"canceled",
"resolve_failed",
"connect_failed",
"tls_failed",
"connection_reset",
"timeout",
"too_many_redirects",
"http_client_error",
"http_server_error",
"auth_required",
"forbidden",
"not_found",
"range_not_satisfiable",
"gone",
"server_file_changed",
"content_length_mismatch",
"checksum_mismatch",
"disk_full",
"io_error",
"path_rejected",
"permission_denied",
"meta_corrupt",
"meta_version_unsupported",
"probe_failed",
"unsupported_url_scheme",
"max_retries_exhausted",
"internal",
] as const satisfies readonly TaskErrorCode[];
/**
* 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.
* 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.
*/
export interface TaskError {
code: number;
code: TaskErrorCode;
/**
* Human-readable, safe to show a user. Never carries a credential, a token or a full local
* path outside the download roots.
*/
message: string;
/** Set for the codes listed in TaskErrorCode's x-carriesHttpStatus, and null otherwise. */
httpStatus?: number | null;
/**
* 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.
*/
retryable: boolean;
/**
* 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.
*/
cause?: TaskErrorCode | null;
/** How many attempts have been made so far. */
attempt?: number | null;
nextRetryAt?: string | null;
@@ -577,7 +670,15 @@ export interface TaskSummary {
/** null when the size or the speed is unknown. */
etaSeconds?: number | null;
resumable: boolean;
/** Connection count. Per-segment detail lives in TaskDetail. */
/**
* The EFFECTIVE connection count in use right now — not the number that was requested. It
* is what remains after the per-host connection cap has been applied and after the
* demotion to 1 for a non-resumable source, so a task the user asked for 16 connections on
* legitimately reports 4, or 1. The GUI displays this value and must not assume it equals
* what download.add asked for. The requested value lives in DownloadSpec.segments and is
* not echoed back on this type. TaskDetail.segmentDetail always has exactly this many
* entries.
*/
segments: number;
categoryId?: string | null;
queueId?: string | null;
@@ -597,6 +698,11 @@ export interface TaskSummary {
*/
export interface TaskDetail {
summary: TaskSummary;
/**
* Exactly TaskSummary.segments entries, in index order, covering [0, sizeBytes) with no
* gaps and no overlaps. Empty for a zero-length download, and empty before the task has
* been segmented.
*/
segmentDetail: Segment[];
headers?: Headers | null;
referrer?: string | null;
@@ -883,7 +989,11 @@ export interface DownloadUpdateParamsPatch {
categoryId?: string | null;
queueId?: string | null;
description?: string | null;
/** Takes effect on the next start; a running task is not re-segmented underneath the user. */
/**
* The REQUESTED connection count, subject to the same per-host cap and non-resumable
* demotion as DownloadSpec.segments. Takes effect on the next start; a running task is not
* re-segmented underneath the user.
*/
segments?: number | null;
bufferBytes?: number | null;
checksum?: Checksum | null;
extension/src/shared/protocol/validate.ts
+9 -3
View File
@@ -135,6 +135,7 @@ import type {
TaskAddedEvent,
TaskDetail,
TaskError,
TaskErrorCode,
TaskFilter,
TaskProgressEvent,
TaskProgressEventTasksItem,
@@ -175,6 +176,7 @@ import {
SETTINGS_PROXY_MODE_VALUES,
SETTINGS_SAVE_TO_FILE_EXISTS_POLICY_VALUES,
START_MODE_VALUES,
TASK_ERROR_CODE_VALUES,
TASK_SORT_DIRECTION_VALUES,
TASK_SORT_FIELD_VALUES,
TASK_STATE_VALUES,
@@ -698,7 +700,7 @@ export function validateSegment(v: unknown, path = ''): Validated<Segment> {
if (!r.ok) return r;
r = req(v, "state", path, validateSegmentState, out);
if (!r.ok) return r;
r = opt(v, "httpStatus", path, vInteger, out);
r = opt(v, "httpStatus", path, vLimited(vInteger, { minimum: 100, maximum: 599 }), out);
if (!r.ok) return r;
return { ok: true, value: out as unknown as Segment };
}
@@ -890,14 +892,16 @@ export function validateTaskError(v: unknown, path = ''): Validated<TaskError> {
if (!isPlainObject(v)) return fail(path, 'expected an object');
const out: Record<string, unknown> = {};
let r: Validated<null>;
r = req(v, "code", path, vInteger, out);
r = req(v, "code", path, validateTaskErrorCode, out);
if (!r.ok) return r;
r = req(v, "message", path, vString, out);
if (!r.ok) return r;
r = opt(v, "httpStatus", path, vInteger, out);
r = opt(v, "httpStatus", path, vLimited(vInteger, { minimum: 100, maximum: 599 }), out);
if (!r.ok) return r;
r = req(v, "retryable", path, vBoolean, out);
if (!r.ok) return r;
r = opt(v, "cause", path, validateTaskErrorCode, out);
if (!r.ok) return r;
r = opt(v, "attempt", path, vLimited(vInteger, { minimum: 0 }), out);
if (!r.ok) return r;
r = opt(v, "nextRetryAt", path, vString, out);
@@ -905,6 +909,8 @@ export function validateTaskError(v: unknown, path = ''): Validated<TaskError> {
return { ok: true, value: out as unknown as TaskError };
}
export const validateTaskErrorCode: Validator<TaskErrorCode> = vEnum(TASK_ERROR_CODE_VALUES, 'TaskErrorCode');
/** Validate an untrusted value as TaskFilter. */
export function validateTaskFilter(v: unknown, path = ''): Validated<TaskFilter> {
if (!isPlainObject(v)) return fail(path, 'expected an object');