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
contracts/README.md
+40 -2
View File
@@ -5,8 +5,12 @@ Nobody else commits here. Everybody else *generates from* here.
> ## Status: **v1.0.0 — FROZEN** (2026-09-09)
>
> The surface below is complete and generated from: 38 methods, 9 events, 25 named types,
> 59 fixtures. See `docs/adr/0005-protocol-1.0.0-freeze.md` for the versioning rule.
> The surface below is complete and generated from: 38 methods, 9 events, 26 named types,
> 59 fixtures. See `docs/adr/0005-protocol-1.0.0-freeze.md` for the versioning rule and
> `docs/adr/0010-...` for the failure taxonomy and the segment range convention.
>
> Lane requests are answered in writing: `contracts/proto-answers-m1.md` responds to
> `core/docs/proto-requests-m1.md` point by point.
>
> **What each lane can rely on, starting now:**
>
@@ -140,6 +144,40 @@ methods marked `"privileged": true` in the schema are refused over the WebSocket
| `event.settings.changed` | `{keys[]}` |
| `event.grabber.progress` | `{jobId, found, crawled, done}` |
## Two error spaces, and why they are not the same
This trips people up, so it is stated once, loudly:
| | `ErrorCode` | `TaskErrorCode` |
|---|---|---|
| Says | why a **call** failed | why a **download** failed |
| Space | JSON-RPC integers (`-32xxx`) | strings (`"server_file_changed"`) |
| Lives in | the JSON-RPC envelope's `error` | `TaskError.code`, on a task |
| Example | `-32602` — your params were malformed | `checksum_mismatch` — the bytes arrived and were wrong |
**A download fails while every RPC involved succeeds.** That is the normal case. Never put
a `-32xxx` into a `TaskError`, and never invent a JSON-RPC code for a transfer failure.
`TaskErrorCode`'s 27 values mirror `vdm::Error` in `core/include/vdm/util/error.hpp` by
name, so DAEMON's projection from the engine taxonomy is lossless and a new engine failure
that has no wire spelling is a visible hole rather than a silent collapse to `internal`.
## Segment ranges are inclusive
`Segment.startByte` and `Segment.endByte` describe a **closed** range `[startByte,
endByte]`: `endByte` is the last byte, not one past it, and the segment covers
`endByte - startByte + 1` bytes. The two fields are copied verbatim into
`Range: bytes=<startByte>-<endByte>`, which RFC 9110 defines as inclusive, so there is no
arithmetic between the wire and the socket and nowhere for an off-by-one to hide.
Conformance enforces contiguity and full coverage; a fixture written half-open fails.
## Requested is not effective
`DownloadSpec.segments` is what a client **asked for**. `TaskSummary.segments` is what is
**in use right now**, after the per-host cap and after the demotion to 1 for a
non-resumable source. They are routinely different and the GUI must render the effective
one.
## Error codes
| Code | Meaning |