proto: freeze the wire contract at 1.0.0

Schemas for the whole v1 surface: 38 methods, 9 events, 25 named types and the
JSON-RPC envelope, with x-privileged / x-transports / x-deadlineMs / x-errors
annotations that both generators emit as data rather than prose.

Four generators over one IR (contracts/codegen/schema_ir.py), so the C++ structs,
the TypeScript types and the OpenRPC document cannot disagree about what the
contract says:

  gen_cpp.py             -> core/generated/velox_proto.{hpp,cpp}
  gen_ts.py              -> extension/src/shared/protocol/
  gen_openrpc.py         -> contracts/openrpc.json
  gen_cpp_conformance.py -> tests/conformance/cpp/fixture_dispatcher.hpp

Inbound parsing never throws: parse<T>() returns std::expected<T, ParseError> and
nlohmann's throwing ADL from_json is deliberately not emitted. Schema constraints
(minimum, maxLength, pattern, ...) become real runtime checks in both languages —
the daemon does not trust the extension and the extension does not trust the
daemon.

59 golden fixtures: a success case per method, 12 error cases, 9 events. Replayed
by tests/conformance/ against both the generated C++ and a live server over both
transports. tools/mockd serves the same fixtures with unhappy-path flags so the
GUI and EXT lanes never wait for veloxd.

run.sh also proves capture.offer fails open: with a daemon answering slower than
750 ms the client gives up and lets Firefox take the download.

core/generated/ is libveloxproto, a separate target from libveloxcore, which
still never sees JSON — see docs/adr/0009.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV

contracts/fixtures/README.md

@@ -0,0 +1,83 @@
+# contracts/fixtures — golden request/response pairs
+
+Every method has at least one success fixture. A method with no fixture is not done.
+
+These files are replayed by `tests/conformance/` against **both** the generated C++ and a
+live server, which is what lets four lanes build in parallel and still be compatible: green
+fixtures mean the C++ daemon and the TypeScript extension agree, without either having ever
+run against the other. `tools/mockd` also answers from them, so the GUI and extension are
+developed against the same bytes conformance asserts.
+
+## Layout
+
+```
+fixtures/
+├── *.json          one success fixture per method
+├── errors/         error cases: auth, transport, not-found, bad path, timeout
+└── events/         one fixture per server-to-client notification
+```
+
+## Shape
+
+```jsonc
+{
+  "name": "download.add — start an ISO now, into the Programs category",
+  "description": "Why this case is worth pinning.",
+  "transport": "uds",          // optional: replay only on this transport
+  "requires": "...",           // optional: a condition a plain server cannot produce
+  "kind": "timeout",           // optional: the correct behaviour is *no reply*
+  "request":  { "jsonrpc": "2.0", "id": 11, "method": "download.add", "params": { } },
+  "response": { "jsonrpc": "2.0", "id": 11, "result": { } },
+  "assertions": [ "things a runner or a reviewer should check" ]
+}
+```
+
+An event fixture carries `notification` instead of `request`/`response`.
+
+`assertions` are prose, for the human writing the implementation. The runners check the
+machine-checkable parts: schema validity, error codes, shape, and the timeout.
+
+## Placeholders
+
+Some values cannot be pinned in a golden file. These stand in for them, and the runners
+treat them as "any value of the right shape":
+
+| Placeholder | Means |
+|---|---|
+| `$uuid` | any UUID |
+| `$isoDate` | any RFC 3339 date-time |
+| `$opaque` | a credential-shaped string (a token) |
+| `$any` | any value |
+| `$taskId`, `$taskId2` | a task the runner creates during setup, and binds before replaying |
+
+`$taskId` exists so a fixture never depends on a task id that only happens to exist in a
+seeded mock. The same fixture then runs against an empty `veloxd` and a populated `mockd`.
+
+## Values are matched by shape, not by equality
+
+A live daemon returns its own task ids and its own clock. Demanding byte-identical results
+would only teach the suite to lie, so the runners assert:
+
+* the payload passes the **generated validator** — this is the real cross-language check;
+* the **key structure** matches the golden file, with no extra and no missing fields;
+* **error codes** match exactly.
+
+A `null` where the golden shows a value is accepted: the validator has already ruled on
+whether null is legal there, and a golden file shows one plausible value, not the only one.
+
+## `requires`: fixtures a mock cannot produce
+
+Most error fixtures are *intrinsic* — a path outside the allowed roots, an out-of-range
+parameter, an unknown task id — and any correct server produces them from the request
+alone. Those are replayed everywhere.
+
+Four are environmental: a 403 from an origin server, a full disk, a pairing lockout, a
+wedged daemon. They carry `requires`, are skipped by default, and are exercised where the
+condition can actually be arranged — `run.sh` starts a deliberately slow `mockd` to prove
+`capture.offer` fails open, and lane PKG/QA's `tools/testserver` covers the hostile-server
+cases in `tests/integration/`.
+
+`errors/capture.offer.timeout.json` is the most important file in this directory. Its
+correct response is *no response*: past 750 ms the extension must abandon the offer and let
+Firefox download normally. A download manager that eats downloads when its daemon is down
+is worse than no download manager.