fix(contracts): tolerate unknown keybinding commands on client decode

[bulgadev]

Problem

When a T3 Code server introduces new keybinding commands (e.g. filePicker.toggle, projectSearch.toggle), clients built against an older contracts build fail to decode the entire server.getConfig response because ResolvedKeybindingsConfig uses a closed union (KeybindingCommand) that rejects unknown values.

This manifested in the VS Code extension as:

T3 Code pairing failed: Could not connect to T3 Code: Expected "sidebar.toggle" | "terminal.toggle" | ... | "thread.jump.9", got "filePicker.toggle" at ["value"]["keybindings"][42]["command"]

The pairing itself succeeded (bearer token exchanged and stored), but the subsequent getConfig RPC failed during schema validation, blocking the connection.

Solution

Make the decode side of ResolvedKeybindingsConfig forward-compatible: rules whose command does not match the known union are silently dropped on decode, while known rules round-trip unchanged. Encoding is unaffected, so the server (which only ever emits known commands) and the strict authoring path (KeybindingRule / KeybindingsConfig) keep their exact behavior.

This is the same forward-compat pattern used elsewhere in the codebase (e.g. ProviderOptionSelections in model.ts tolerates legacy shapes via Schema.decodeTo + transformOrFail).

Scope

ResolvedKeybindingsConfig is consumed by all four wire schemas that carry resolved keybindings:

• server.getConfig (initial config fetch)
• subscribeServerConfig (config stream)
• serverUpsertKeybinding / serverRemoveKeybinding (mutation results)

All three clients (vscode, web, mobile) share the same RpcClient.make(WsRpcGroup) decode path, so this fix unblocks all of them simultaneously.

Changes

• packages/contracts/src/keybindings.ts: wrap ResolvedKeybindingsConfig with a decodeTo transform that filters unknown rules via Schema.decodeUnknownOption(ResolvedKeybindingRule) per element.
• packages/contracts/src/keybindings.test.ts: two new tests verifying unknown commands are dropped and all-unknown arrays decode as empty.

Verification

• pnpm --filter @t3tools/contracts test: 238 tests passed (19 files)
• pnpm exec vp check packages/contracts/src/keybindings.ts packages/contracts/src/keybindings.test.ts: 0 errors, 0 warnings
• ELECTRON_SKIP_BINARY_DOWNLOAD=1 pnpm exec vp run -r --cache --log labeled typecheck: exit 0

[patroza]

Thanks a lot for the contribution!

Requesting changes:

• decodeUnknownOption(ResolvedKeybindingRule) drops every invalid rule, not only rules with unknown commands. Malformed rules using known commands should continue to fail validation; only genuinely unknown command names should be skipped.
• The maximum-length check runs after filtering. A large input containing unknown or malformed rules can decode to an empty array and bypass the 256-rule limit. Please enforce the limit on the input array before filtering.

[omegent-app]

Thanks for this one too, @bulgadev — you were right about the bug, and it is fixed. Closing because
fork/dev already has it, arrived at independently.

ResolvedKeybindingsConfig now goes through a generic ForwardCompatibleArray helper:

export const ResolvedKeybindingsConfig = ForwardCompatibleArray(ResolvedKeybindingRule).check(
  Schema.isMaxLength(MAX_KEYBINDINGS_COUNT),
);

It decodes each element and keeps only the ones that decode, passing encode through untouched —
the same semantics as your filterKnownResolvedKeybindingRules, generalised so other contracts get
it for free. Merging yours on top would add a second, bespoke implementation of behaviour already in
place.

The test coverage that landed with it is also a superset of the two cases here:

• rules whose command this build does not know — your case
• rules with unknown when-node types
• malformed entries ("garbage", null)

One thing worth flagging, since it says something about how long this sat: your second assertion
would now fail. It expects filePicker.toggle to decode away as unknown, but that command shipped in
the meantime and is in the known set — so a payload containing it decodes to one rule, not zero. The
class of bug you found is exactly why that matters, and the generic fix covers it.

For context on why this went quiet rather than getting reviewed: it targeted fork/changes, which
has since been frozen. This repository moved to a stable, never-rebased fork/dev as the contributor
target — partly because PRs like yours were being silently invalidated by rebases underneath them.
Your other PR (#237) is merged as #351 with your authorship on the commit.

fork/dev is the branch to target from here. Thanks again. 🙏