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.

### 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. |
| `start` | int ≥ 0 | absolute byte offset, inclusive |
| `end` | int ≥ 0 | absolute byte offset, **exclusive** — range is `[start, end)` |
| `completed` | int ≥ 0 | bytes written in this range so far |
| `speedBps` | int ≥ 0 | current per-segment rate |
| `state` | enum | `connecting` \| `downloading` \| `stalled` \| `complete` \| `failed` |

Asks: (a) reconcile `i` vs `index` — one spelling in both the `Segment` type and the
`event.task.progress` payload; (b) confirm the half-open `[start, end)` convention in the
schema `description` so DAEMON and GUI don't off-by-one the last byte; (c) confirm the
segment `state` enum values.

---

## 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).