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.