samiandClaude Opus 5
2c8f5e5d7d
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
tests/conformance — one suite, three runners
This is a required check on every lane's PR. It is the mechanism that makes four parallel lanes safe: the C++ daemon and the TypeScript extension are proved compatible without either having run against the other.
./tests/conformance/run.sh # starts its own mockd
./tests/conformance/run.sh --uds /run/user/1000/velox/velox.sock --ws-port 52000
The runners
| Runner | Needs | Asserts |
|---|---|---|
check_contract.py |
python3, jsonschema | schemas parse and resolve; the documented surface matches the schema surface both ways; every method has a success fixture; every fixture validates; SettingKey and Settings agree; committed generated code is not stale |
cpp/ |
a C++23 compiler, nlohmann | every golden payload parses into the generated structs, serialises back stably, and goes through the real dispatch(); privileged methods are refused -32003 over the WebSocket |
ts/replay.ts |
node ≥ 20 | a live server answers every fixture over every transport the contract allows, and the reply passes the generated validator |
run.sh also runs one scenario that cannot be shown against a healthy server: with the
daemon answering slower than capture.offer's 750 ms deadline, the client must give up and
let Firefox take the download. That is the fail-open guarantee, and it is checked here.
What "passing" means
The runners check the contract, not the implementation's opinions. Results are compared by
shape and validated against the generated validators; error codes are compared exactly.
Byte-equality with a golden file is deliberately not asserted, because a live daemon
returns its own ids and its own clock — see contracts/fixtures/README.md.
Adding a method without a fixture fails check_contract.py. Regenerating and forgetting to
commit the output fails it too.
Request to lane PKG/QA
.github/ belongs to PKG/QA, so this suite is not wired into CI by lane PROTO. Please add
it as a required status check on every branch, roughly:
conformance:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '22' }
- run: sudo apt-get update && sudo apt-get install -y nlohmann-json3-dev
- run: pip install jsonschema referencing
- run: ./tests/conformance/run.sh
The suite needs: python3 with jsonschema, a C++23 compiler, nlohmann-json, and Node
≥ 20. It starts and stops its own mockd; nothing else needs to be running.