docs(research): mock bridge has five dead handlers and one backend-less tested handler (#344)

[tucktuck101]

Summary

Answers #344 by extracting both command sets and diffing them. The mock bridge has drifted — six handlers stand in for commands that exist nowhere in the repository — but the drift is currently harmless, because an unmocked command throws rather than returning a default. The real finding is that nothing detects drift at all.

Related issue

Closes #344

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-opus-5[1m]
Session reference	N/A - the harness exposes no shareable run id
Initiating human	@tucktuck101

Objective

Add launchpad/Research/344-mock-bridge-drift.md comparing the commands the E2E mock bridge handles against the commands the Tauri backend registers, in both directions.

Impacted components

launchpad/Research/344-mock-bridge-drift.md

Approach and rejected alternatives

Diffed the two sets mechanically with comm, then chased each difference to a verdict rather than reporting the counts. That mattered: of the nine commands the mock handles without a backend counterpart, three are deliberate test-only helpers and six are dead residue, and a bare "9 mismatches" would have implied nine problems.

Then checked the mock's default: branch before drawing any conclusion about severity. That single line is what determines whether the 62-command gap is dangerous or benign, and it turns the answer from "the mock may be reporting false green" into "it cannot".

Rejected treating the 62 unmocked commands as a coverage gap to close. The mock is deliberately partial and the throw makes partiality safe; mocking commands no spec exercises would add surface for no assurance. That reasoning is in the document's recommendations section, marked as opinion.

Verification

Command run:

git rev-parse HEAD
grep -rhn "#\[tauri::command\]" desktop/src-tauri/src/ | wc -l
awk 'NR>=604 && /generate_handler!\[/,/\]\)/' desktop/src-tauri/src/lib.rs | ... | sort -u > /tmp/real_cmds.txt
grep -oE 'case "[a-zA-Z_0-9]+"' desktop/src/testing/e2eBridge.ts desktop/src/testing/e2eBridgeCustomHarnesses.ts | ... | sort -u > /tmp/mock_cmds.txt
comm -23 /tmp/mock_cmds.txt /tmp/real_cmds.txt    # mock handles, backend does not
comm -13 /tmp/mock_cmds.txt /tmp/real_cmds.txt    # backend has, mock does not
grep -rn "pub async fn <each>\|pub fn <each>" desktop/src-tauri/src/
grep -rln "pick_team_directory" desktop/
grep -n -A6 "default:" desktop/src/testing/e2eBridge.ts

Raw output:

$ git rev-parse HEAD
5d76799d6e44f2f76aa7bd78c5343d339af98f63

$ grep -rhn "#\[tauri::command\]" desktop/src-tauri/src/ | wc -l
     322
real registered (lib.rs generate_handler):      312
mock handled:                                   259

$ comm -23 /tmp/mock_cmds.txt /tmp/real_cmds.txt
clear_e2e_opened_external_urls
complete_identity_recovery_pairing
export_team_to_json
get_e2e_opened_external_urls
get_global_agent_config_set_call_count
install_team_from_directory
parse_team_file
pick_team_directory
sync_team_directory
count: 9

# the six, checked against the Rust backend
complete_identity_recovery_pairing: defined_in_rust=0  in_lib.rs=0
export_team_to_json:               defined_in_rust=0  in_lib.rs=0
install_team_from_directory:       defined_in_rust=0  in_lib.rs=0
parse_team_file:                   defined_in_rust=0  in_lib.rs=0
pick_team_directory:               defined_in_rust=0  in_lib.rs=0
sync_team_directory:               defined_in_rust=0  in_lib.rs=0

$ grep -rln "pick_team_directory" desktop/
desktop/src/testing/e2eBridge.ts

$ comm -13 /tmp/mock_cmds.txt /tmp/real_cmds.txt | wc -l
      62

# e2eBridge.ts:13423-13424 -- the fallback
      default:
        throw new Error(`Unsupported mocked Tauri command: ${command}`);

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

Return-shape fidelity was not examined at all, and it is the more dangerous question. This is a name-level comparison. A mocked command whose name matches but whose return value has drifted from the real Rust signature would pass every check here and could produce a false green. That applies to all ~250 commands the mock does handle and is unmeasured; establishing it means comparing each handler's returned shape against its Rust function's return type.

The second handler at native_websocket.rs:325 was not expanded. Its commands are not among the 312 counted from lib.rs, so a few of the "unmocked" 62 may be registered there and the real total is above 312.

The 259 figure comes from case "…" labels. If the bridge dispatches some commands another way — a lookup table, a prefix match — those are uncounted.

Whether the mock's partiality is documented anywhere was not established. No specs were run — #322 established this host cannot resolve pnpm.

That nothing detects drift is negative evidence — I found no such check, which is not the same as proving none exists.

Security implications

None added by the document. One observation: the six dead handlers name a removed team import/export flow (pick_team_directory, install_team_from_directory, export_team_to_json), so the mock retains a description of filesystem-touching commands the application no longer has. Unreachable, but misleading to read.

Escalations

1. The dangerous version of this question is still open. Name-level drift is now measured and benign; return-shape drift is unmeasured and is where a false green could actually originate. If prd: the cohort test suite — what we test that upstream doesn't #290 wants confidence in the 146 specs, that is the question worth funding, not this one.
2. My recommendations are marked as opinion in the document, per the claim rule — including the view that the 62 unmocked commands should be left alone and the six dead handlers deleted as tidying. Neither is a decision I should take.
3. enh: drive the real desktop app in a VM — automated native-layer E2E that files its own issues #292 remains the larger gap. Nothing here changes that no test drives the real application; this only establishes that the mock's command names are in reasonable shape.

[serina-mcfall]

Blocker — it is five dead handlers, not six, and "no test path reaches them" is false

complete_identity_recovery_pairing is driven by a registered, running spec:

$ git grep -n "complete_identity_recovery_pairing" -- 'desktop/tests/**' 'desktop/src/testing/**'
desktop/src/testing/e2eBridge.ts:13257:      case "complete_identity_recovery_pairing":
desktop/tests/e2e/identity-lost.spec.ts:280:      "complete_identity_recovery_pairing",

$ git grep -n "identity-lost" -- desktop/playwright.config.ts
desktop/playwright.config.ts:122:        "**/identity-lost.spec.ts",

$ git grep -rn "fn complete_identity_recovery_pairing" -- desktop/src-tauri/
(no match — the handler is mock-only)

Three things break together:

1. The count is wrong — in the PR title, the frontmatter description and the finding. Five, not six.
2. "They cannot mislead a test, because no test path reaches them" is false, and it is the sole support for "the drift is currently harmless." A registered spec invokes this command and then asserts a UI transition. A green spec exercising a command with no backend implementation at all is very close to the exact failure mode the note declares is not present.
3. Recommendation 2 — "I would delete the six dead handlers" — would break a registered spec if actioned as written.

On the harmlessness question specifically: it is measured for direction 2 and asserted for direction 1, and the direction-1 assertion is the one that does not hold. Your direction-2 argument is genuinely evidenced — an unmocked command throws with its own name in the message, so missing coverage cannot produce a false pass. That reasoning is good. It just does not transfer.

Medium — the single-grep generalisation is what produced the above

The note runs grep -rln "pick_team_directory" desktop/, gets one file back, and generalises "the only file in the repository that mentions them is e2eBridge.ts" to all six. Running the grep per name would have caught complete_identity_recovery_pairing. Worth naming in the note itself, because the method is reusable and the failure is the interesting part.

Medium — e2eBridgeCustomHarnesses.ts contributes nothing to the 259

259 commands are handled by e2eBridge.ts and e2eBridgeCustomHarnesses.ts, counted from their case "…" labels.

$ git show 5d76799d:desktop/src/testing/e2eBridgeCustomHarnesses.ts | grep -c 'case '
0

All 259 come from e2eBridge.ts alone. The figure is right; the attribution to a second file that contributes zero will send whoever re-runs the count into the wrong place.

What is right — every quantitative figure reproduced exactly

This is the most mechanically accurate part of the note, and it is worth saying so plainly:

Figure	Note	Recount
#[tauri::command] attributes	322	322
Registered at lib.rs:604	312	312
Mock handlers	259	259
Direction 1 (mock-only)	9	9
Direction 2 (backend-only)	62	62
e2eBridge.ts length	13,450	13,450
Playwright specs	146	146

The throwing fallback at e2eBridge.ts:13424 is real, and all six named handlers genuinely have no fn <name> anywhere under desktop/src-tauri/.

That accuracy is exactly what makes the one error hard to spot — the nine mock-only handlers were found correctly; it is the step from "mock-only" to "dead" that skipped a check. Everything else here stands.

---

Reviewed at head 16c0cf72d. The spec invocation and its registration were verified by me directly.

🤖 Review drafted by Claude Code (claude-opus-5) for @serina-mcfall.

[tucktuck101]

Review panel — two independent reviewers (Fable, gpt-5.6-sol xhigh), consolidated

Summary: The prior review's blocker (six→five, the falsified "no test path reaches them") is genuinely fixed and threaded through the whole note, and every figure the note derives by its own method reproduces exactly (Fable re-derived all of them: 322/312, 259 by the note's extraction, the 9 and 62 sets, 13,450 lines, 146 specs, identity-lost.spec.ts:280). But independent verification found two substantive problems the revision itself introduces or preserves, so this cannot merge as-is. Verdict: changes needed (posted as a comment — author is tucktuck101, so this panel cannot formally approve or request changes).

High

1. The revised headline's "backend-less tested handler" is a deliberate test seam, not drift creating a false green. (codex; consolidator verified) The mock handler at desktop/src/testing/e2eBridge.ts:13257 sets mock state and emits pairing-complete — the same event the real recovery task emits on completion (desktop/src-tauri/src/commands/pairing.rs, finish_recovery path), which IdentityRecoveryPairing.tsx:86 listens for. The spec invokes the command directly to simulate completion of an asynchronous native operation; production code never calls it. It belongs in the test-only-helper class, not in "drift is present in one direction." The current framing (344-mock-bridge-drift.md:12-22, :76-79) overstates the risk the note exists to measure.
2. The 259 mock-handler count is a regex artifact. (codex; consolidator verified: grep -o 'case "[^"]*"' | sort -u → 277, of which 18 are colon-named plugin commands) Four of the excluded labels are plugin:websocket|connect/send/disconnect/disconnect_all — exactly the four commands of the native_websocket.rs:325 handler the note's caveat says it never expanded. The websocket surface is mocked; the registered surface is an enumerable 316 (312 + 4), not an unknown. :26-34 and the :142-148 caveat need rederiving with prefix normalization (the 9/62 difference sets on the main handler are unaffected — both reviewers confirmed those reproduce).
3. One leftover sentence restates the claim the revision falsified. (Fable) 344-mock-bridge-drift.md:20-21: "Six handlers for commands that exist nowhere in the repository" — the note's own correction establishes complete_identity_recovery_pairing exists at identity-lost.spec.ts:280. One-line fix: "commands with no Rust implementation" (as :35-36 already phrases it).

Medium

4. The deliverable-of-record still carries the retracted analysis. (both reviewers) task: find out whether the desktop E2E mock bridge has drifted from the real Tauri command surface #344's DoD is a comment on the issue, and the standing comment there still says six dead handlers, "no path reaches them," "delete the six." The PR body likewise. Post a correcting follow-up on task: find out whether the desktop E2E mock bridge has drifted from the real Tauri command surface #344 and refresh the body before this closes the issue.
5. The ticket's "two lists and their difference" enumeration is still not met (codex): neither the registered set nor the mock set is listed anywhere, and Direction 2 gives five examples of 62. Given task: find out whether the desktop E2E mock bridge has drifted from the real Tauri command surface #344's explicit DoD, include the full lists (or an appendix / linked gist-style block in the note).
6. "The mock is deliberately partial, covering what the 146 specs exercise" is stated as fact but is an inference (codex) — intent was never established and no specs were run (:105-106, :145). Phrase as inference.

What looks good

• The 5+1 correction is not a patch-over: it's threaded through finding, direction-1 analysis, recommendations, and confidence, and the note candidly documents its own earlier methodological error — the most valuable part for future notes.
• The five team-flow handlers genuinely have no caller outside the mock (both reviewers re-verified independently), and the throwing-fallback behaviour is accurately described with exact line cites.
• The "Not checked" section correctly identifies return-shape fidelity as the unmeasured dangerous case.

Panel: fable + gpt-5.6-sol (codex, xhigh), independent reviews consolidated by the lane; the consolidator re-verified the deciding findings (277-label count, pairing-event seam) directly against the repo. Author is tucktuck101, so this is a comment, not a formal review — needs an external reviewer once addressed. Posted under Jeff's standing authorization.

[serina-mcfall]

Re-review — the blocker is addressed. Three Highs filed as issues; no blocker remains.

Agent-authored under @serina-mcfall's instruction. I do not approve; this records what I verified.

Blocker (six dead handlers is five, and "no test path reaches them" is false) — fixed, and threaded properly. The finding, the direction-1 analysis, the recommendation and the confidence section all carry the correction, and :68-69 documents the methodological error that produced it — checking one name and generalising to six. That candour is the most reusable part of the revision.

Medium (e2eBridgeCustomHarnesses.ts contributed zero labels) — fixed. :33 now says so explicitly.

Three Highs, filed rather than blocked

I verified each of these myself at origin/launchpad rather than adopting them from the panel comment above:

• #513 — :20 still says "Six handlers for commands that exist nowhere in the repository", which is the exact wording the note's own correction falsified. :54 already has the accurate phrasing.
• #514 — the 259 mock-handler count is a de-duplication artifact. grep -o 'case "[^"]*"' | sort -u gives 277, of which 18 are colon-namespaced (plugin:websocket|connect and friends); 277 − 18 = 259 exactly. Four of the dropped labels are the websocket commands the note's own caveat calls unexpanded — that surface is mocked, and enumerable.
• #515 — complete_identity_recovery_pairing is a test seam, not drift. The mock at e2eBridge.ts:13259 emits pairing-complete, the same event the real backend emits at pairing.rs:439/:546 and that IdentityRecoveryPairing.tsx:86 listens for. The spec invokes it to stand in for an async native callback; production never calls it.

None of the three is a blocker under this repo's rubric: the note's central claim — nothing detects mock/backend mismatch — survives all of them, and the five genuinely dead handlers are correctly identified. #515 is the one I would most want fixed before this is cited, because it changes what the note says the risk is.

Nothing else new. Every figure the note derives by its own stated method reproduces: 322/312, the 9 and 62 difference sets, 13,450 lines, 146 specs, and identity-lost.spec.ts:280.

---

Reviewed at head b3f947592; counts run at origin/launchpad. The 277-label recount and the pairing-event wiring were both checked by me directly, not taken on report.

🤖 Review drafted by Claude Code (claude-opus-5) for @serina-mcfall.