vdm/core/docs/proto-requests-m1.md

CORE → PROTO — requests before the VERSION freeze

Status: open. Raised by lane CORE against contracts/ at 1.0.0-draft. This is a request list, not a decision record. PROTO owns every item here. Once PROTO answers D1, that one becomes a three-way ADR (docs/adr/) per contracts/README.md rule 4.

Ranking is by contracts/README.md rule 4, not by intuition: new method or new optional field = minor, can land anytime; rename / remove / retype / default change = major + ADR.

---

Freeze-blockers — get these into 1.0.0 (major if we guess wrong)

B1. A frozen wire enum for TaskSummary.error.code

TaskSummary.error.code is currently a bare integer. CORE cannot import a protocol header (layering rule — core/ never sees JSON/RPC), so CORE has its own failure taxonomy regardless of what PROTO picks; DAEMON owns the projection from one to the other. The ask is not "who owns the enum" — it is: freeze a wire enum with enough cardinality that DAEMON's mapping from the CORE taxonomy below is lossless.

If the wire enum is coarser than this table, DAEMON has to collapse distinct engine failures into one code and the GUI can't tell "server file changed" from "checksum mismatch". Retyping error.code later is a major bump.

CORE failure taxonomy (this is vdm::Error in core/include/vdm/util/error.hpp):

CORE Error	Meaning	retryable	carries httpStatus
canceled	user/daemon cancelled	no	no
resolve_failed	DNS resolution failed	yes	no
connect_failed	TCP connect failed	yes	no
tls_failed	TLS handshake / cert rejected	no	no
connection_reset	peer reset mid-transfer	yes	no
timeout	connect or idle/stall timeout	yes	no
too_many_redirects	redirect limit hit	no	no
http_client_error	4xx not otherwise classified	no	yes
http_server_error	5xx	yes	yes
auth_required	401 / 407 — task pauses, not terminal	no	yes
forbidden	403 after the referrer-retry (docs/04 §7)	no	yes
not_found	404	no	yes
range_not_satisfiable	416 — triggers re-probe/re-split	yes	yes
gone	410 / expired signed URL, no mirror left	no	yes
server_file_changed	200 where 206 expected, or If-Range / ETag drift (docs/04 §5)	no	yes
content_length_mismatch	bytes received ≠ declared length	yes	no
checksum_mismatch	post-download hash ≠ expected	no	no
disk_full	ENOSPC	no	no
io_error	pwrite / fallocate / fdatasync failed	no	no
path_rejected	outside allowed roots or not writable	no	no
permission_denied	EACCES on the destination	no	no
meta_corrupt	.veloxpart.meta failed CRC / bad magic	no	no
meta_version_unsupported	meta file from a newer engine	no	no
probe_failed	probe could not determine file info	maybe	yes
unsupported_url_scheme	not http/https	no	no
max_retries_exhausted	backoff loop gave up (data names the last underlying Error)	no	maybe
internal	invariant violation / bug	no	no

Concretely: a string enum on error.code mirroring these names is simplest to keep lossless; if it stays an integer, please reserve grouped ranges (e.g. 1xx network, 2xx http, 3xx local-io, 4xx metadata, 5xx internal) with room to grow inside each.

B2. Freeze the meaning of TaskSummary.segments — major, retype-of-meaning

docs/04 §4/§3 require the effective value (after the per-host cap and the non-resumable→1 demotion) to reach the UI. TaskSummary.segments currently has no stated meaning. Please freeze it as "effective segment count in use right now", not the requested value. This is the only genuinely freeze-blocking half of the buffer/segment story — pinning a field's meaning after 1.0.0 is a major bump under rule 4. It stands alone; do not defer it together with B2a below.

B2a. A readable effective buffer size — minor, but note the trap

Split out from B2 on purpose so PROTO can't use the cheap half to defer the major half.

bufferBytes is write-only: accepted by download.add and download.update.patch, readable on no type. docs/04 §4 says the clamped / "silently reduced to fit" value is "reported back to the UI", so CORE will expose an effective value and PROTO needs a frozen field to carry it. Adding an optional field is minor under rule 4 — except that TaskSummary is additionalProperties: false, so a daemon cannot tack it on as an extension; it has to be in the schema or it's dropped by every conformance replay. Name and placement are PROTO's call (effectiveBufferBytes on TaskSummary / TaskDetail, or a dedicated readback). Land it whenever — it just can't be improvised later.

Fold in two more, all discovered via B4 (buffer-sizing.md):

• maxTotalBufferBytes is absent from the contract entirely. CORE implements the clamp against it; the Options dialog can neither show nor set it. Add Settings.schema.json connection.maxTotalBufferBytes (recommended default 134217728 = 128 MiB).
• maxActiveSegments is new — the global concurrent-segment cap that actually bounds "20 active downloads" for the RSS budget. Add Settings.schema.json connection.maxActiveSegments (recommended default 32). DAEMON's scheduler reads it.

B3. Freeze Segment.schema.json field names

Segment is already on PROTO's type list (contracts/README.md) and TaskDetail "includes segments[]", so this is mostly field-name matching — but do it before freeze or each fix is a rename = major.

CORE will emit per segment:

CORE field	Type	Note
index	int ≥ 0	event.task.progress currently says i. Pick one name for both.
startByte	int ≥ 0	absolute byte offset, inclusive
endByte	int	absolute byte offset, inclusive — range is [startByte, endByte] (see below)
completed	int ≥ 0	bytes written in this range so far
speedBps	int ≥ 0	current per-segment rate
state	enum	connecting | downloading | stalled | complete | failed

Resolved by PROTO at freeze: endByte is inclusive (matches HTTP Range semantics — Range: bytes=start-end is inclusive — and removes an off-by-one at the curl boundary). CORE designs stage 6 (segmenter/stealer) against inclusive. The earlier [start, end) ask is withdrawn.

Still open: (a) reconcile i vs index; (b) confirm the segment state enum values; (c) empty-segment representation — see B3a.

B3a. Zero-length segment must be representable — PROTO is fixing; CORE's requirement

With endByte inclusive and minimum: 0, a zero-length segment (endByte = startByte - 1) at offset 0 is endByte = -1, which the schema forbids. The one case CORE actually needs: a whole-file zero-length download (Content-Length: 0) — one segment, length 0. It is a valid HTTP response and the daemon/GUI must be able to hold it.

CORE will not produce empty segments mid-download: the min_segment_bytes floor (1 MiB, docs/04 §3) means the segmenter never splits below 1 MiB and the stealer only takes a half-range if it is ≥ that floor. So B3a is purely about the degenerate whole-file case.

Preference: encode segments as startByte + length (+ completed) rather than an inclusive endByte with a startByte - 1 sentinel — length: 0 is then the natural representation and there is no negative value to allow. If endByte inclusive stays, then a 0-byte task needs an explicit encoding (an empty/length field, or permitting endByte = startByte - 1 with minimum: -1) — any of those work for CORE as long as total length 0 round-trips. Flag back if the chosen fix needs anything else from CORE.

B4. bufferBytes range is wrong in the frozen schema — see buffer-sizing.md

contracts/ froze bufferBytes at 4 KiB – 8 MiB in four schema files (DownloadSpec, TaskDetail, download.update patch, and Settings.schema.json connection.bufferBytes); docs/04 §4 says 64 KiB – 64 MiB default 4 MiB; the RSS DoD (docs/04 §8 line 125) holds with neither. CORE's recommendation — 64 KiB – 16 MiB, default 1 MiB, plus a new maxActiveSegments (32) global concurrent-segment cap and maxTotalBufferBytes lowered to 128 MiB and added to the contract, with line 125 kept at 60 MB "given maxActiveSegments = 32" (or explicitly raised to 120 MB) — and the per-segment RSS arithmetic are in core/docs/buffer-sizing.md. PROTO to land the four schema edits + docs/04 §4 + §8 + ADR together.

---

Do not hold the freeze for these

All minor under rule 4 (new methods / new events / a pattern on an existing optional string). contracts/README.md rule 5 wants contract changes "cheap and frequent" — raise these now, land them as small follow-up PRs, but do not gate 1.0.0 on them. Each is needed within M1.

F1. A "needs user decision" carrier — new event + method, minor

docs/04 §5 mandates a "File on server has changed — restart download?" prompt, and §7 has 416/stale-metadata. The event surface has only event.notify + task states. Either:

• confirm state: paused + an event.notify {level:"warn", …} is the intended carrier (CORE reports server_file_changed, DAEMON pauses + notifies, GUI offers restart), or
• add event.task.decision {taskId, kind, options[]} + download.decide {taskId, choice}.

CORE needs to know which, but a string comparison on error.code covers the engine side either way, so this doesn't block freeze.

F2. A credential return path for 401/407 — new method, minor, M1-needed

event.auth.required exists; there is no method to hand credentials back to a paused task. session logins / Secret Service is M3, but "401 handled" is in CORE's M1 DoD. Requesting download.provideAuth {taskId, username, password, save?} → {ok}. Secrets go to the Secret Service, never SQLite/logs (CLAUDE.md §4) — save just tells DAEMON whether to persist.

F3. checksum string format — pattern on an existing optional field, borderline

download.add {checksum?} has no shape. CORE's verifier will accept "<algo>:<hex>" with algo ∈ {md5, sha1, sha256} (appendix lists MD5/SHA-256). Adding a pattern to an existing optional string is close to free; PROTO's call whether it's worth a fixture now or a doc note.

---

Three-way ADR material (after PROTO answers)

D1. State-machine ownership split — CORE / DAEMON / PROTO

docs/04 §1 hands CORE the lifecycle, but queued and every scheduler transition are DAEMON's. Proposed split, to be recorded as an ADR once all three agree:

• CORE owns: probing → connecting → downloading ⇄ paused → retry_wait → assembling → verifying → complete | failed, plus cancelled from any state.
• DAEMON owns: new, queued, and pause-for-schedule (enters CORE's paused).
• Shared: paused is reachable from either side; both must be idempotent about it.

This needs an ADR regardless of the answer (contracts/README.md rule 4: the lifecycle enum is a frozen type and any change to who drives it is a documented decision).