MCP refusals get their status word: every validation bail answers the {status:"invalid"} envelope on both SKUs, and the PostgreSQL refusals that wore error go HTTP 500 → 400 (Closes #3739)

[erikdarlingdata]

Closes #3739 — the ruling #3719 asked for (Q11 residue of #3653), made and landed.

This is a WIRE CHANGE. Roughly four hundred validation bails on both SKUs — every if (error != null) return error; after a ServerResolver miss or a McpHelpers validator — answered with the validator's bare sentence, the one outcome on the wire that was not JSON. They now answer with the same envelope every other outcome uses: {"status":"invalid","message":"<the same sentence>","hints":{"parameter":"<what to fix>"}}. The frozen Dashboard twin links PerformanceMonitor.Common and its 46 validator call sites change with it.

The lie

#3719 collapsed every caught exception onto McpHelpers.FormatError and the payload contract said "errors one shape" — but a REFUSAL is not an error, and the refusals never got a shape at all. A client that keys on status, which is what the instructions teach it to do, was handed prose for a bad hours_back and JSON for everything else, with nothing in the prose to say whether the tool failed, refused, or found nothing.

Nine PostgreSQL refusals (the issue counted seven; two more — get_pg_plans' query_id and get_pg_wait_trend's queryid — split the "error" literal across a line break and evaded the grep) took the worse path: they hand-built McpHelpers.Status("error", …), and since #3719 the web surface reads that word as a server fault. A bad limit on /api/read/get_pg_deadlocks answered HTTP 500. Before #3719 it answered 200 (the {-sniff passed it through). Neither was the 400 a client-correctable refusal deserves. #3719 stated the consequence, pinned the present behaviour (ClassifyToolResponse_TheErrorEnvelope_IsServerError), and said the word was a ruling it would not make.

The ruling

The word is invalid, widened. It was already the write tools' word for a body that would not parse — Outcome("invalid", …) across the mute-rule, alert-settings, custom-alert and custom-view verbs, and DarlingWebEndpoints.MuteRuleEnvelopeStatus already mapped it to HTTP 400 on the write surface — and "a body that will not parse" is one instance of "the request as given cannot be served: a parameter the tool cannot honor, a missing required parameter, an unresolvable server name". So the read surface says the same word for the same kind of thing. refused / rejected were considered and NOT added: a sixth word beside a fifth that already means this would be a divergence, not a distinction.

HTTP: a refusal is 400, on both surfaces, by one rule. ClassifyToolResponse gains a Refusal kind, tested after the error envelope and BEFORE the {-sniff (which would answer 200 over it); ToHttpResult maps it to Results.Text(envelope, "application/json", 400) — the envelope itself as the body, not the {"error": sentence} wrap — which is exactly the shape MuteRuleToolResult has always given invalid. MuteRuleEnvelopeStatus reaches its 400 through the same classifier arm now (its parsed "invalid" case survives as belt-and-braces for an envelope serialized some other way; not_found still reaches its 404). The nine PostgreSQL refusals go 500 → 400. The ~400 bare sentences already answered 400 (the final arm, by the accident of being unshaped); shaping them does not move their code, only their body. #3719 pinned the present mapping so this would change it knowingly. This is that change.

The fix — a twin of FormatError, built in the producers

McpHelpers.Refusal(parameter, sentence) → Status("invalid", sentence, new { parameter }), beside InvalidEnvelopePrefix ({"status":"invalid",) and IsRefusalEnvelope — the same prefix test IsErrorEnvelope is, so the two consumers that split 500 from 400 tell them apart with two prefix tests. ErrorMessageOf unwraps either envelope.

Why the hint is the PARAMETER and not the operation. The brief's twin signature named the operation, as FormatError does. The producers of a refusal are the shared validators and the server resolvers, which are called from four hundred tools and know nothing about which one — what every one of them knows is the parameter it refused, and that is the thing the caller has to change. A failure's useful question is "which read broke"; a refusal's is "which knob". So hints.parameter it is, on every refusal.

The producers, not the sites. Every validator in McpHelpers (ValidateHoursBack, ValidateTop, ValidateDaysBack, ValidateUncappedWindow, ResolveAsOf, ParseSummaryDate, ValidateChoice, ValidateMinMs; ValidateWindow passes theirs through), both SKUs' ServerResolver miss, the web dispatch's MissingParam / UnparseableParam, the fleet-sweep ValidateSpan / ValidateWatchState, and the handful of tools that refuse a parameter of their own inline (analyze_plan_xml's "No plan XML provided." and compare_analysis' baseline rule on both SKUs, mute_analysis_finding's hand-serialized {status:"invalid"} on both SKUs, get_sweep_reports' sweep_id, get_top_queries_by_cpu's group_by, and the nine PostgreSQL sites). The if (error != null) return error; idiom at every call site passes the envelope through untouched. The SENTENCES are byte-for-byte unchanged inside message, so every log grep and every pinned fragment survives — read back through ErrorMessageOf.

Darling's resolver, specifically. ResolveOrError wraps MissSentence (the local listing plus the #2339 peer disclosure, unchanged) in the envelope. ResolveOrErrorWithFleetSentinelAsync appends its disclosure to the SENTENCE and rebuilds the envelope, rather than appending text to JSON. The registry-read FAULT ("Could not read the servers registry from the Postgres store: …") deliberately stays a bare sentence: it is a store fault, not the caller's request, wearing invalid would tell them to fix a call that was fine, and this seam has no tool name for FormatError's hints.operation. It maps to the web's bare-string 400 arm exactly as before — stated here rather than hidden; the right shape for it is a separate question.

The consumers this would otherwise have broken

• DarlingTriageEndpoint: the resolution note and the per-section error are TEXT the card renders — both read through ErrorMessageOf now (the section arm already did; it just learned the second envelope).
• DarlingCliCommands (remove-server's miss on stderr) and remove_servers' not_found outcome — both consumed the resolver's miss as text; both unwrap.
• DarlingFleetSweepEndpoints — its own {"error": sentence} contract (The analysis family cannot be anchored at a past window, and it is the one an incident starts with #2506) is kept; SweepError unwraps, so a web client reading .error is not handed JSON inside a string.
• wwwroot/js/util.js classifyResponse — the non-2xx arm reads message off a {status, message} body when there is no .error (the refusal is now the 400 body on /api/read/*), so readErrorStrip's "window too wide" degrade keeps its sentence; the 2xx arm treats invalid like error (belt-and-braces for an unmapped body). The two hunks MCP errors take one wire shape: FormatError returns the {status:"error"} envelope on both SKUs (Partial #3653, Q11) #3719 touched, taught the word.

The census

McpPayloadContractCensusTests gains the arm, walker-driven rather than a hand-list of 400 sites:

• EveryRefusal_ReturnsThroughTheSharedShape_AndTheBareSentenceRosterIsExact — every guarded pass-through (if (x != null) return x;, 463 across both SKUs: 196 resolver, 218 validator, 49 gates and the health-parser family's carried result) is walked back to the LAST assignment of x and its producer must be shared; every return "…" in a tool body must be in the exact roster BareSentenceReturns (three MISS sentences — list_servers on an empty registry on both SKUs, and analyze_query_store_plan's vanished-connection sentence — One payload said NoData and No Data, eight spellings of four severity words were two bands and six other vocabularies, and the page cut had five names: the daily summary speaks one band token on both SKUs, six inferred cuts become observed truncated + *_returned, and the census classifies every cut key and severity literal by what it is (partial #3653) #3703's lane, not refusals); every hand-built Status("invalid" / new { status = "invalid" } fails. Floors on all three counts so the idiom regex cannot go dark.
• TheFailureWord_HasOneProducer_OnBothSkus — Status("error" appears in no tool source and exactly once in McpHelpers.cs, inside FormatError. This is the pin that makes the nine-refusals shape unrepeatable.
• TheOneRefusalShape_IsTheEnvelope_ExecutedThroughRefusal_AndEveryValidatorBuildsIt — the shape executed (parses; status / message / hints.parameter; byte-equal to Status(…)), the recognizer on the producer and the write tools' bytes and not on its neighbours, and every shared validator driven past its bound hands back exactly Refusal(its parameter, its sentence).
• Two witnessed discriminators (the idiom matcher, the producer walk).

Red-first, all executed here: one PostgreSQL site reverted to Status("error", limitError) → TheFailureWord_… names DarlingMcpPgDeadlockTools.cs: GetPgDeadlocks; analyze_plan_xml reverted to the bare sentence → the roster fails naming DarlingMcpPlanTools.cs analyze_plan_xml: "No plan XML provided.".

DarlingWebEndpointsTests: ClassifyToolResponse_TheInvalidEnvelope_IsARefusal against the real producers (Refusal, four validators, the Darling resolver's miss, the write tools' bytes) and its neighbours (invalid_count, {"invalid":true}); TheErrorEnvelope_IsServerError stays, its third case re-documented as the reason the census forbids the shape; the mute-rule table gains Refusal's bytes and a spaced envelope; the bare-string theory keeps its rows as the floor under what the producers no longer emit, plus the two sentences that still can. McpPageContractTests (Lite) gains EveryRefusal_IsTheInvalidEnvelope_OnLite — the resolver's miss, four validators through real tools, analyze_plan_xml, and a miss neighbour — the half that RUNS on Lite. McpMissMessageParityPinTests.SharedMissFragments pins the new instructions paragraph byte-for-byte on both SKUs (the two SKU-specific tails #3719 left unpinned now say the same true thing and are shared). Forty-odd sentence pins in twenty-two test files across both projects read through ErrorMessageOf (the JSON serializer escapes ' and +, so a raw StartsWith/Contains on the envelope would have gone red or vacuous).

What is NOT changed

• The four miss words and their sentences (One payload said NoData and No Data, eight spellings of four severity words were two bands and six other vocabularies, and the page cut had five names: the daily summary speaks one band token on both SKUs, six inferred cuts become observed truncated + *_returned, and the census classifies every cut key and severity literal by what it is (partial #3653) #3703's lane) — untouched; the three bare miss sentences are rostered for that lane, not shaped here.
• The write tools' Outcome("invalid", …) — same word, same bytes, MCP write tools report what happened: every server you add lands in a counter, a partial name cannot delete the wrong server, an omitted field is never a clear, and a mute that matched nothing says so (#3541 A14) #3615's contract; they carry no hints.parameter and are not made to.
• The resolver's store-fault sentence (above).
• deprecated/Dashboard/** source — frozen; builds clean; its own ServerResolver is separate and still a sentence.
• No schema, no migration.

Descriptions

Both instructions files: the #3719 paragraph's SKU-specific trailing sentence on validation refusals is replaced by one shared paragraph teaching the sixth status word, with the example envelope byte-for-byte, and "six status words, then: four kinds of nothing, one failure, one refusal". Lite's ## Error Handling names the envelope and re-labels "Could not resolve server" as invalid's message.

Tests — executed here vs CI-first

Executed on this Mac: the real Darling.Tests in-process (WindowsDesktop stripped), 19 classes / 516 tests including McpPayloadContractCensusTests, DarlingWebEndpointsTests, DarlingPeerDisclosureTests, RepoFileAdoptionTests, StragglerCommandTimeoutTests, LiveCleanupConversionRatchetTests, MeasurementContractCensusTests, McpPageContractTests, DocCommentHygieneTests, FleetIdentifierScrubTests — 1 red, the harness-csproj artifact in TheDerivedProjectListCoversEveryProjectInTheTree; Lite harness (McpMissMessageParityPinTests, McpPageContractTests, AsOfWindowAnchorTests, DailySummaryRangeToolTests, MeasurementContractCensusTests: 109 tests, 6 reds all the Mac PresentationFramework artifact on Lite's wait-stats read). CI-first: every live-PostgreSQL pin touched (McpFilterSemanticsLivePostgresTests, DarlingMcp*ToolsTests' unknown-server rows, DarlingDailySummaryRangeTests, AnalysisAsOfAnchorTests) and the Dashboard.Tests run. Builds: Common, Darling.Service, PerformanceMonitorLite, Darling.Tests, Lite.Tests, deprecated/Dashboard — 0 warnings on the touched projects.

Closes #3739