test(mcp): pin that a missing recordId refusal names the id the caller sent

[claude]

Fixes #17568

Summary

Test-only. No production code changes, and that is load-bearing.

The card's premise is stale: the diagnostic it asks for is already correct on main. What was missing is anything holding it there. So this PR delivers the regression pin the card's acceptance criterion describes, and the empty production diff is itself the proof that the accepted argument set did not move.

Premise check — measured, not reasoned

The card reports that update_record with id: instead of recordId: answers:

MCP error -32602: Input validation error: Invalid arguments for tool update_record:
Invalid input: expected string, received undefined at recordId

Measured on this tree (packages/mcp at 76c9fab3, the branch point) the same call answers:

MCP error -32602: Input validation error: Invalid arguments for tool update_record: Invalid input: expected string, received undefined at recordId
Unrecognized key(s) on this update_record call: `id`. Did you mean `id` → `recordId`? This argument used to be dropped silently and the call still succeeded, so a mis-guessed parameter name answered a differently filtered or differently ordered set with no way for the caller to tell.

Both facts are already named — the missing recordId and the unexpected id that was sent, plus the mapping between them. The card was observed against a released service; #16913 has since closed every tool's argument shape with strictToolInput and given the record-scoped tools the alias table RECORD_ID_ALIASES (id, record_id mapping to recordId). Its changeset (.changeset/mcp-refuse-undeclared-tool-arguments.md, still pending release) carries the row for this exact pair. So the fix landed as a side effect of that sweep, and no message change is owed.

Both of the negatives the card asks for also already hold: a call carrying recordId succeeds and reaches the bridge unchanged, and a call carrying neither key gets the ordinary missing-recordId refusal with no unexpected-key clause invented for it.

Why a pin is still the right deliverable

Nothing pinned any of this, and the green is the intersection of three independent mechanisms — any one of which can regress while every existing gate stays green:

1. zod reports both issues for a strict object — the unrecognized_keys for id and the invalid_type for the absent recordId. A schema that short-circuits on the first issue drops the half carrying the news.
2. the MCP SDK's validateToolInput() joins every issue into one message. A change rendering only the first issue restores the card's defect verbatim.
3. the alias table carries an id entry at all. It is one line, and it reads as decoration next to the tool it annotates.

The nearest sibling, mcp-http-tools.unknown-argument-keys.test.ts, does not cover this: every case there sends a complete set of valid arguments plus one probe key, so the unexpected-key half never has to coexist with a missing required key. The compound case is the one the card measured, and it was unguarded.

What is pinned — 10 cases

The named acceptance criterion, plus both negatives:

case	asserts
the card's repro (objectName + id + data)	refused; -32602 present; result.isError true with no protocol error; names recordId, quotes `id`, prescribes `recordId`; bridge untouched
negative 1a — recordId present	succeeds, and the bridge receives exactly ('crm_lead', id, {status:'qualified'}) — not merely "did not refuse"
negative 1b — id present	the bridge is never reached, so an alias cannot hide here
negative 2 — neither key	ordinary missing-key refusal, asserted to quote no key at all
record_id, the other induced spelling	same compound answer — shares no literal with the case above, so it reds if the seam is narrowed to a hard-coded id
get_record, delete_record	inherit the compound refusal
run_action (where recordId is optional)	names the sent id, and invents no missing-key complaint
create_record (declares no recordId)	quotes id, prescribes nothing — the control on the prescription channel
the stdio transport	the same refusal on a real StdioServerTransport

Two deliberate choices worth flagging to a reviewer:

• Every key assertion uses the backtick form. A bare toContain('id') is satisfied by the word Invalid in Invalid input — it passes against the exact defect this file exists to catch. The negative is likewise asserted as "quotes no key at all" rather than "lacks some particular sentence", so it cannot be satisfied by a reworded invented clause.
• Prose is not pinned, only named subjects — which keys the message names, and in which quoting position. The refusal pin's code + status half is asserted in this surface's own vocabulary: MCP answers a rejected tools/call as a tool error, so it is the protocol code -32602 plus isError: true with error absent, and HTTP 200 pinned so a later change cannot silently turn a tool error into a transport error.

Ablation — the pin fails, on the card's exact message

Reverting update_record's inputSchema to the pre-#16913 raw shape (zod's .strip then deletes id before the parse reports the absent recordId) reconstructs the defect. Run from the committed state; the mutation was proved on disk before the run (injected marker count 1, deleted anchor count 0, blob hash moved) and restored to a byte-identical blob afterwards (bf6d34d5b15f02a8e12a292653aa7b4918075a99 both before and after, clean git diff HEAD, zero marker residue):

× the reported `id` call is refused naming BOTH the missing `recordId` and the `id` it received
× `record_id` — the other induced spelling — is answered the same way
× names both facts on a real StdioServerTransport
Tests  3 failed | 7 passed (10)

AssertionError: expected '...' to contain '`id`'
Received: "MCP error -32602: Input validation error: Invalid arguments for tool update_record: Invalid input: expected string, received undefined at recordId"

That Received: line is the card's reported refusal, byte for byte. The 7 that stayed green are the negatives and the un-ablated sibling tools, which is the correct result.

Reach — measured per tool, never swept

update_record, get_record, delete_record all name both facts. run_action declares recordId optional, so nothing is missing and only the key mistake is named — the asymmetry is why reach is pinned per tool rather than asserted as a rule. create_record declares no recordId at all and correctly prescribes nothing. Both transports verified; the stdio half is asserted on the wire because this package has already shipped one outage in which the two transports served different surfaces while every per-surface pin stayed green.

Scope

The ruling on this card refused adding id as an alias for recordId (consumer-side tolerance that permanently widens a published MCP surface and teaches the caller nothing) and refused renaming recordId (a breaking change to a published tool parameter). Neither was needed and neither was done. The card's separately recorded second shape — all three parameters undefined — is out of scope and untouched, per the card's own instruction not to merge it with the above.

Gates

Derived from the final diff with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, each run with output redirected and $? captured before any pipe, then reconciled with --ran:

• 51 derived, 48 green, 3 NOT MEASURED, 0 unrun. The three are check:dual-build-cjs-loads, check:lean-entry-closure and check:type-check-debt, each of which exited 3 printing PREREQUISITE NOT MET — they read built output across the whole workspace and need a full pnpm build, which is CI's run, not a finding in either direction.
• check-keyed-text-bounds.mjs green; read by hit line rather than exit code, its population is *.object.ts declarations (112 files / 148 keyed text columns judged, 148 bounded) and it names no path in this diff. Moot twice over here, since no message text changes.
• pnpm lint — the full union, not a narrowing: eslint . --no-inline-config --format json over 6620 files, 0 errors / 0 warnings, this file included and clean, measured at 9e33b0e0.
• pnpm --filter @objectstack/mcp test — 30 files / 323 tests pass. pnpm --filter @objectstack/mcp typecheck green, including check:test-typecheck (existing ledger held; this file adds no entry and no error).
• Coverage confirmed rather than assumed: tsc --project tsconfig.test.json --listFiles lists this file, so its assertions are compiled rather than phantom, and vitest list collects its 10 cases.

skip-changeset, measured

@objectstack/mcp publishes files: ["dist", "README.md", "CHANGELOG.md"], and tsup builds entry: ['src/index.ts'] only. After a real build of the package, with a positive control to prove the channel answers:

• positive control — wireBridgeTools, a genuinely published symbol: 4 hits in dist/index.js
• an existing test-only symbol (zzUndeclaredProbeKey, from the sibling test): 0 files in dist/
• this file's own symbols: 0 files in dist/
• test files emitted into dist/: 0

Nothing published moves, from any released package, so the label genuinely applies rather than being claimed.

Acceptance notes

• The refusal renders as Did you mean \id` → `recordId`?, which leads with the caller's own spelling; the zod default sentence naming only recordId` also still comes first in the joined message. Both facts are present and the retry loop is broken, so this is not a defect under this card — noted, not filed, and deliberately not pinned, since the prose is not the contract.
• The card's second shape (take v3, all three parameters undefined) is consistent with a client sending empty arguments and is not the same failure as guessing a parameter name; no change is recommended and none is made.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 1c4270fa7a2ffb8b15211d151d71f9dbb89ccc83 → packageMentionDocs.