vdm/contracts/proto-answers-m1.md

PROTO → CORE — answers to core/docs/proto-requests-m1.md

Status: answered. Against contracts/ at 1.0.0 (lane/proto, not yet on main). Raised by CORE at 1.0.0-draft; every freeze-blocker is resolved below.

Read docs/adr/0010-task-error-taxonomy-and-segment-ranges.md for the reasoning on B1/B2/B3. This file is the index and the parts CORE has to act on.

---

Freeze-blockers — all three are in 1.0.0

B1 — a frozen wire enum for the task failure code · done, as a string enum

TaskError.code was a bare integer. It is now TaskErrorCode: a string enum with your 27 failure values, mirrored by name and in your order, verified against core/include/vdm/util/error.hpp mechanically rather than by eye. ok has no wire spelling — a TaskError only exists when something failed.

You were right that this was blocker #1, and right about the diagnosis: the draft typed code as the JSON-RPC integer while its own description said "distinct from the JSON-RPC Error". Those are two code spaces. ErrorCode says why a call failed; TaskErrorCode says why a download failed, and a download fails while every RPC succeeds.

Strings, not your grouped-integer fallback: the mapping is lossless with no numbering scheme maintained in two repos that cannot include each other's headers, and a log line reads "server_file_changed" instead of 407.

Two details you should design against:

• retryable stays a per-occurrence boolean, not a property of the code — because your own table has probe_failed as "maybe". Emit it per failure.
• cause is new on TaskError and carries a TaskErrorCode. It exists for max_retries_exhausted, which your header says has a cause: put the last underlying Error there so the user is told what actually kept failing.

httpStatus is expected for the codes in TaskErrorCode's x-carriesHttpStatus annotation, which matches the "carries httpStatus" column of your table.

B2 — the meaning of TaskSummary.segments · done, frozen as effective

"The EFFECTIVE connection count in use right now — not the number that was requested. What remains after the per-host connection cap and after the demotion to 1 for a non-resumable source."

The requested value stays in DownloadSpec.segments, which now says so on its own description, as does download.update's patch.segments. TaskDetail.segmentDetail carries exactly TaskSummary.segments entries, and conformance checks that.

B3 — Segment field names, and the range convention · done, but read this

(a) index vs i — settled as index, everywhere. There is no i spelling in the contract; event.task.progress's per-segment entries use index too. Nothing to reconcile, it was already consistent.

(c) the state enum — pending | connecting | downloading | stalled | complete | failed. Spelled downloading as you asked, matching TaskState; the draft's receiving is gone. pending is added for a range planned but not yet dialled — if the engine never reports that, ignore it.

(b) the range convention — this is the one that will bite you if you skim.

Ranges are CLOSED and INCLUSIVE: [startByte, endByte].

endByte is the index of the last byte, not one past it. The segment covers endByte - startByte + 1 bytes.

You asked for half-open [start, end). PROTO chose inclusive and did not adopt your convention — this notice is the point of this document, and it is deliberately before you build stage 6.

The reason: these two fields are copied verbatim into Range: bytes=<start>-<end>, and RFC 9110 byte ranges are inclusive. Inclusive means no arithmetic at all between the wire and the socket. Half-open means a -1 at every boundary between the contract and every HTTP request the engine makes — which is exactly where off-by-ones live.

Field names stayed startByte / endByte / downloadedBytes rather than your start / end / completed, partly so that code written against the half-open spelling does not silently compile against inclusive fields.

While fixing this we found a real contradiction in the draft: it encoded an empty segment as endByte == startByte - 1, which is -1 at offset 0 — and every download's first segment starts at 0, so the schema's own minimum: 0 rejected it. Empty ranges are no longer representable and are not needed. endByte >= startByte always holds; a zero-length download carries an empty segmentDetail; a segment that donates its remainder to a steal keeps the bytes it already wrote. If the engine has a state that genuinely needs an empty range, say so now — that is a schema change, not something to encode around.

tests/conformance/check_contract.py enforces contiguity, coverage of exactly [0, sizeBytes - 1], downloadedBytes <= endByte - startByte + 1, and the entry count. A fixture flipped to half-open fails it.

---

Not gating the freeze — the follow-up queue

Agreed with your ranking: these are minor under rule 4 and land as small PRs to contracts/ alone. They are not in 1.0.0. Ranked by when M1 needs them.

#	Item	Verdict	Shape
B2a	readable effective buffer size	accepted	effectiveBufferBytes on TaskSummary, next to the effective segment count, so the requested/effective split reads the same way for both. You are right about the additionalProperties: false trap — no daemon can tack it on, so it needs a schema PR either way.
F2	credential return path for 401/407	accepted as proposed	download.provideAuth {taskId, username, password, save?} → {ok}. Unix socket only, privileged: a credential-bearing method must never be reachable from the browser. Secrets go to the Secret Service; save only tells DAEMON whether to persist.
F1	"needs user decision" carrier	the simple option	state: paused + event.notify is the intended carrier for M1: CORE reports server_file_changed, DAEMON pauses and notifies, GUI offers restart. A dedicated event.task.decision + download.decide is a real design with a state machine attached, and it should not be invented in a hurry — raise it again in M3 if the notify path proves too thin. A string comparison on error.code covers the engine side either way, which is now a TaskErrorCode comparison rather than a magic number.
F3	checksum string format	already frozen, differently	download.add {checksum} is not a string. It is a Checksum object: {algorithm: "md5"|"sha1"|"sha256"|"sha512", value: "<hex>"}, with value patterned ^[0-9a-fA-F]{32,128}$. Parse your "<algo>:<hex>" form at the CLI or GUI edge, not on the wire. Note sha512 is accepted by the contract even though the appendix lists MD5/SHA-256 — reject it in the engine if you do not implement it, rather than the contract forbidding it.

Raise B2a and F2 as requests whenever you need them and PROTO will land them together; neither blocks anything you are building this week.

---

D1 — state-machine ownership

Your proposed split is right and PROTO does not dispute any of it: CORE owns probing → connecting → downloading ⇄ paused → retry_wait → assembling → verifying → complete | failed plus cancelled from anywhere; DAEMON owns new, queued and pause-for-schedule; paused is shared and both sides must be idempotent about it.

PROTO will not write that ADR alone. It is a three-way decision and the lane that owns neither half writing it down is how a decision gets recorded that DAEMON never agreed to. DAEMON should draft it, CORE and PROTO review. The contract's part is already frozen: TaskState has the twelve values, and the wire does not encode who drove a transition.

One thing that is PROTO's and worth stating: event.task.state carries previousState, so a client can render a transition without keeping its own state machine. Neither CORE nor DAEMON should assume a client tracks lifecycle — clients render what they are told.