samiandClaude Sonnet 5
2d36e9fef0
The last contract gap blocking an M1 definition-of-done item: CORE's "401
handled" has no return path without it, and B2a's sibling F2 was accepted in
proto-answers-m1.md but never actually landed.
download.provideAuth {taskId, username, password, save?} -> {ok}, exactly as
proposed there. Privileged and Unix-socket-only: a credential-bearing method
must never be reachable from the browser, which is the other half of the
promise event.auth.required's own description already makes ("never back
through this event, never into a log"). It answers the challenge; it does not
itself resume the task -- the daemon retries with the credential attached and
the ordinary event.task.state reports the task leaving retry_wait, the same
as any other state change.
save only tells the daemon whether to persist the credential in the Secret
Service for next time, or use it for this attempt alone -- it never touches
SQLite or a log either way, in keeping with CLAUDE.md's secrets rule.
Three fixtures: the success path, -32010 for a task that no longer exists
(credentials submitted for it are simply discarded), and -32003 confirming
the extension has no path to this method under any transport.
mockd gets a real handler rather than falling through to the generic fixture
responder: it validates the taskId exists (so the -32010 fixture is
replayable) and actually transitions the task out of retry_wait.
Minor bump, 1.1.0 -> 1.2.0: additive method, no existing type touched.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
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
{
"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.