[USP][QA] Gate the Dart/WASM boundary and fix subscribe signature drift

[DevenDucommun]

Purpose

Protect the production Dart-to-JavaScript-to-WASM boundary on the usp branch. Canonical program tracking: https://github.com/linksys/qa-usp-automation/issues/10

Verified defect

The real usp_client.d.ts exports subscribe(subscription_id, path, notification_type), while lib/core/usp/web/usp_client_wasm.dart and the current Playwright mock expose only subscribe(subscriptionId). The mock agrees with the wrapper while both disagree with the real artifact.

Acceptance criteria

• Decide whether the Dart binding is used: either fix wrapper, mock, and callers to the real 3-argument contract, or remove the dead binding
• Vendor usp_client.d.ts beside the JS/WASM assets
• Record the source usp_framework commit SHA and hashes for JS, WASM, and .d.ts
• Add a boundary checker that compares Dart external bindings with the .d.ts surface, including method arity and compatible types
• Report intentionally unbound TypeScript methods explicitly
• Include a deliberate arity mismatch fixture proving the check fails
• Run the check for pull requests and pushes targeting the usp branch
• Regenerate or verify vendored artifacts in CI instead of relying only on manual copies

Related: https://github.com/linksys/qa-usp-automation/issues/12

---

Investigation (2026-07-17): the drifted binding is dead code

Verified on the usp branch. The app's subscriptions run through the hand-written UspClient (lib/core/usp/services/usp_client.dart) via client.subscribe<T>(...), which is SSE-backed (createNotifySubscription + an SSE delegate), as the generated providers in lib/generated/*.g.dart use. The hand-written UspClient delegates to the Wasm wrapper UspClientWeb for transport (get/set/add/delete/operate), but its subscription path is SSE, not the wrapper's subscribe.

The Wasm wrapper's UspClientWeb.subscribe(String subscriptionId) (lib/core/usp/web/usp_client_wasm.dart:133) has no external caller. Nothing invokes it. So the 1-arg vs 3-arg drift against the real .d.ts sits in unused code.

This resolves the "decide whether the Dart binding is used" item: it is not used. The fix is a UI-team API call, either:

• Remove the dead subscribe/unsubscribe from UspClientWeb (plus the stub, the JS externals, and the Playwright mock). Cleanest. The boundary checker then lists .d.ts subscribe/unsubscribe as intentionally unbound.
• Or correct them to the 3-arg .d.ts contract if the binding is meant to be wired up later.

QA-owned deliverable is unchanged: the boundary checker (parse the vendored .d.ts, assert every Dart external binding matches arity and types, report intentionally-unbound methods, include a deliberate-mismatch fixture that proves the check fails, run on usp PRs/pushes).

[DevenDucommun]

Implementation is open in PR #1156: #1156

The Dart/Wasm boundary job and existing Quality & Logic job are green. The PR removes the unused drifted subscribe/unsubscribe bindings, vendors the complete artifact set, and pins reviewed producer head bec64cd221272601eeb5512cffb4fda9d7a8714e.

The checker now recursively discovers callable USP externals, rejects unrecognized declarations, requires the expected JS classes, enforces a 40-decision floor, handles intervening annotations and function-typed parameters, and includes nine positive/negative tests. Consumer CI verifies local hashes and records the upstream reference; producer PR #44 owns the enforceable source-to-package rebuild proof.

Merge #44 first, then refresh this reference to the resulting mainline commit before merging #1156. No ownership change was made.

[AustinChangLinksys]

Scope check: is the vendored .d.ts actually a consumer contract on the Dart runtime path?

Flagging a gap between the framing and what PrivacyGUI actually consumes at runtime. The per-symbol facts in this ticket check out (verified on usp): usp_client.d.ts subscribe is 3-arg, the Wasm wrapper UspClientWeb.subscribe is 1-arg at lib/core/usp/web/usp_client_wasm.dart:133, that wrapper method has no caller (dead code — the app subscribes via the hand-written UspClient SSE path at usp_client.dart:862, and all 8 .subscribe( call sites route through SseManager/UspBridgeClient, never UspClientWeb). No dispute there.

But the framing — "make the vendored TypeScript declaration the checked consumer contract" — doesn't match how this code runs:

PrivacyGUI does not consume .d.ts anywhere on the Dart runtime path. Evidence on usp:

• Repo-wide search for any reference to .d.ts returns exactly one hit: web/usp_client.js:1 /* @ts-self-types="./usp_client.d.ts" */ — that is the .js file's own TS self-declaration comment, not PrivacyGUI consuming it.
• No Dart code imports/references .d.ts; no build step, pubspec.yaml, or web/index.html reads it. The real runtime entry is web/index.html → usp_init.js + flutter_bootstrap.js.
• The actual runtime contract is Dart @JS() library usp_client; + dart:js_interop external bindings resolving directly against the .js runtime symbols (usp_client_wasm.dart:1-6). TypeScript types are never on this path.

Why this matters for what the gate protects:

The .d.ts is wasm-pack's auto-generated type description of the .js. Comparing "Dart binding arity vs .d.ts" therefore only indirectly catches drift, and only under the assumption that .d.ts faithfully mirrors the shipped .js. It structurally cannot catch the exact class of bug this PR also fixes — the missing-websocket-feature build, where .d.ts describes UspWsClient/buildWebSocketConnect but the shipped .js has no such symbol. A .d.ts-vs-binding arity check passes clean in that scenario; the app still explodes at runtime on firmware upload.

So the genuinely protective parts of #1156 are the "verify required production exports exist in the shipped .js" + artifact hash checks, not the .d.ts arity comparison. Those are what would have caught the websocket regression.

Suggestion: keep the gate (the export-existence + hash verification is real value), but restate its contract as "Dart externals vs the shipped .js runtime surface, cross-referenced with the .d.ts as the upstream-intent description" — rather than ".d.ts is the consumer contract." The distinction is what tells a reviewer the gate's true protection boundary.

Verified read-only on branch usp (HEAD 5beff305); no code or PR state changed.