docs(worker): state why pinned requests drop the channel filter, and pin it

[TennyZhuang]

Hands-lane follow-up from Computer task #816, Raft task #proj-hands #208. Scoped by @Archer: comment + contract tests only.

Why

?version= (pinned) requests look a version up across channels — the SQL predicate ((?5 IS NULL AND ch.slug = ?2) OR ?5 IS NOT NULL) stops filtering by channel, and the CASE ordering prefers main.

That is deliberate, but nothing in the code said so. The shape reads like an oversight, and the obvious "fix" — re-adding a channel filter for pinned requests — would actually narrow a documented contract and break pinning a build that lives on another channel (e.g. a feature-channel build). This PR makes the intent legible so the next reader doesn't "correct" it.

What changed

Comment only, in handlePublicCliBinaryUpdateCheck. It records:

• pinned requests drop the channel filter by design — "pin this exact version" is a request about version identity;
• why that is safe: safety lives in the artifact identity comparison below, not in the channel filter — same version_name on multiple channels with divergent bytes fails closed with UPDATE_IDENTITY_CONFLICT, and version_name is unique per release;
• the guard's precondition explicitly: rows.length > 1. A single matching row is served as-is and is not identity-checked against other channels.

No SQL change. No behaviour change.

Tests

All three previously-unstated behaviours are now pinned:

• cross-channel lookup is the contract, not an accident — a pin naming main still resolves a version that exists only on alpha, and the response reports the channel the release actually lives on;
• divergent same-name bytes across channels fail closed with 409 (existing test, kept, now adjacent to the contract it belongs to);
• byte-identical duplicates across channels are served normally, not rejected as a conflict — this is what makes the divergence test meaningful;
• a single-row hit is served as-is, the guard being unable to run.

Honest note on teeth

Only the divergence arm is mutation-detectable:

• removing the identity guard → the divergence test reddens;
• narrowing the pinned lookup back to one channel → that plus the cross-channel arm redden.

The single-row arm is a behavioural pin only — the guard's precondition is inherent to the match count, so widening or narrowing it cannot be observed from that test. The test says so in a comment rather than implying a tooth it does not have. (I verified this: forcing rows.length >= 0 leaves the suite green.)

Verification

• Worker suite: 580 passed, 1 failed — the failure is the pre-existing spawnSync /usr/bin/sqlite3 ENOENT (feedback_closure_reason_migration), which worker-tests.yml documents as a machine fact unrelated to the commit.
• tsc --noEmit: 900 before, 900 after, empty delta — expected for a comment-and-test change.
• Reviewed-head note: this is based on 6acebaa (current main).

Overlap note for the lander

PR #522 (volta/hands-206-channel-alias-shadowing) is also based on 6acebaa and touches worker/src/routes/public_v2.ts — a different region (the channel lookup / alias resolution), but the same file. Whichever lands second should expect a trivial rebase. Both are independent, reviewed separately, and neither contains the other.

Not part of Computer PR #7764. Source only — no merge, deploy, or production action.