samiandClaude Sonnet 5
60363a7142
Minor bump on 1.0.0, per core/docs/buffer-sizing.md. B4 — bufferBytes bounds corrected in all four locations (DownloadSpec, TaskDetail, download.update's patch, Settings.connection.bufferBytes): was 4 KiB-8 MiB with no stated default, now 64 KiB-16 MiB with a 1 MiB default. 64 KiB because 4 KiB is smaller than one libcurl HTTP/2 write-callback delivery; 16 MiB because throughput from write size is flat past ~1-4 MiB and past 16 MiB there is stall-cover left to buy but no memory left to spend it on; 1 MiB default because it is the only candidate for which docs/04's 60 MB RSS target actually holds once buffers are counted per segment, not per download. Two new settings keys: connection.maxTotalBufferBytes (128 MiB default) and connection.maxActiveSegments (32 default). Without them CORE's clamp — reduce every live segment's buffer to fit the global cap — has no wire configuration surface, and "20 active downloads" has no meaning distinct from 160 live TLS connections. B2a — TaskDetail.effectiveBufferBytes: what a segment is actually using right now, after the clamp. Placed on TaskDetail next to bufferBytes, following the requested/effective pattern ADR 0010 already established for segments. The download.get fixture now demonstrates a real clamp (16 MiB requested, 4 MiB effective) rather than a case where the cap happens not to bind. docs/04-engine-design.md §4 and §8 updated in the same change per CORE's request and CLAUDE.md rule 5: the RSS target is now stated as conditional on maxActiveSegments = 32, and the old 4 MiB/64 MiB/256 MiB numbers are corrected to match the schema. ADR 0012 records the reasoning and explicitly keeps the 60 MB target over CORE's offered 120 MB alternative, with the arithmetic that makes 60 MB achievable with margin. Numbered 0012 rather than 0011: DAEMON is independently drafting ADR 0011 (admission control / segment budget split) in a peer session at time of writing, so 0011 was reserved to avoid a collision. Co-Authored-By: Claude Sonnet 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.