fix(agent,db,api,docs): a cap was reported as a count, and four more

[cevheri]

Round 16 of the backlog loop. Five settled entries close - B77, B78, B80, T6, T7 - plus two defects this round's own audit found and one its review round found. Every one of them is a figure or a sentence that claimed more than it measured.

What was wrong, and what it is now

B77 - the curated health reading reported a cap as a count. The projection carried slowQueryCount and activeSessionCount off lists that every provider caps. The audit measured it: 8 of the 8 providers that can return a slow-query row cap it (5 rows on MySQL, PostgreSQL, MSSQL, Oracle, MongoDB, Couchbase and ClickHouse, 10 on both of Trino's through one TRINO_HEALTH_LIMIT), every provider caps the session list, and none of those statements carries a slowness predicate at all - "slow" is the ordering. So the figure was the limit, permanently, on any server with that many digests.

The entry's premise turned out to be too kind. Where the source cannot be read the projection did not report 0 but 1, or 2: PostgreSQL without pg_stat_statements pushes [{ query: "pg_stat_statements extension not enabled" }], MongoDB with its profiler off does the same, and every SQLite database answers two synthetic integrity rows. No field name fixes a figure with no referent, so both counts are gone from the projection and from its declared fields. The slow-queries and sessions kinds carry those facts with their rows visible, which is the only form in which they mean anything - and the tool description the model receives, "one row of connection, size and cache figures", is now exact where it was incomplete.

The design that was considered and rejected: naming the cap beside the figure (slowQueriesSampled + slowQuerySampleLimit). It costs all 15 type-ids and buys the model a saturated constant plus a second number explaining that the first one is meaningless.

The same rule, one field over (not a backlog entry - found by this round's audit). MSSQL, Oracle and MongoDB initialised activeConnections to 0 and swallowed the read's failure into it, so a denied DMV, an unprivileged V$SESSION and a whole failed serverStatus reached the model as a measured zero connections - defeating the optionality HealthInfo.activeConnections exists for and which src/lib/db/types.ts mandates in words. All three now omit the key; a real 0 still reads as 0; both arms are pinned per provider. MongoDB's outer catch deliberately still resolves rather than rethrows - a rethrow would turn POST /api/db/health into a 5xx and the fleet row into error for a server that is up.

The same rule, one reading over (found by the review round). runCuratedRead sliced rows to the budget's ceiling and reported rows.length as rowCount, so a 500-row reading arrived at the model as "result, 200 row(s)" - while the docblock directly above promised "REFUSED rather than truncated ... a delivered result is a complete one". The budget's ceiling is not a request: it now refuses with the existing READING_OVER_BUDGET, the way the byte ceiling beside it always did. A limit the model asked for is a request and still delivers exactly it.

B80 - the engine refusal read the same paragraph twice. The route now carries a machine-readable refused: "engine-unsupported" marker, tied to AgentRunFailureReason with Extract<> on both sides so a rename cannot leave the wire value behind. String comparison against the posture paragraph was rejected: it makes prose the protocol. The error line says what happened to the request and points at the explanation with an aria-describedby that resolves, because "above" is not a claim a screen reader can check. With the card gone the line carries the server's full paragraph again - that arm has its own test.

T7 - three of four sentences were never rendered by a test. Four arms of a nested ternary are one line, so 100% line coverage was reached with three of the four decline sentences undriven. The selection is now an exhaustive switch with no default, one arm per line - and the test's own rows are typed, so a fifth reason fails typecheck in the test file whichever arm it is folded onto. The line gate alone does not catch a reason folded onto an existing arm; the review round proved that, and the docblock now says it rather than claiming otherwise.

T6 - a shared fixture answered what no server answers. defaultMockExecute used to answer a digest statement naming sql_text, a column that table does not have on any build - which is exactly how a health read asking for it survived every gate and two reviews. The repair had been prophylactic and unpinned. A rule list evaluated in recordCall, the one funnel every fixture in that file goes through, now records any statement no MySQL-family server would answer; a file-scope afterEach asserts the list is empty; two tests drive the guard itself. Reverting the shared fixture is red now. The guard's reach is stated honestly in its own docblock and in docs/providers/mysql.md: it inspects only statements a test actually sends, and one fixture's revert is still not caught.

B78 - a premise that no test named. A test now demonstrates the misattribution against the real tracker (a sibling charge landing inside the failing execution's span) and asserts maxConcurrentExecutions: 1 with that demonstration as its failure message. One assertion pins elapsedMs through the ledger WRITE rather than only the parse. The entry's own claim that "nothing fails if that constant is raised" was false and is corrected in the source comment, which had contradicted itself eleven lines apart.

How this was verified

Three fresh-context adversarial reviewers, each in its own worktree, ran mutations rather than reading reports. They confirmed the work and found nine things worth changing, all fixed here, including: an API_DOCS sentence that generalised over 400 shapes it had not checked (the connection resolver's 400 carries code and statusCode), a comment that put Trino in the wrong cap group, a MongoDB justification borrowed from a storage-engine claim to a network-layer field, and an MSSQL permission distinction that Microsoft's own documentation settles the other way - sys.dm_exec_sessions needs VIEW SERVER PERFORMANCE STATE on SQL Server 2022 and later, the same permission as the measured refusal, not a sibling.

Two of the reviewers' proposed fixes were measured and did not work: the sketched test for the refusal-code admit list kills neither of the two gates, because they are in series; the honest replacement is a hook-level test plus a docblock that stops claiming a guarantee the suite does not have.

In a real Chrome, against the bundled LibreDB sample with a local Ollama model: the error line reads "No run was opened. The notice above says why, and what still runs on this engine.", its aria-describedby resolves to the card, and the 406-character paragraph has exactly one visible copy where it had two (the second copy is the 1x1 sr-only safety claim, which is why the comment says "visible" rather than "once"). After Switch to Plan the card is gone and the line carries the full paragraph with the pointer cleared. Live on that route: three distinct 400 bodies - {error, refused} for the engine, {error, code, statusCode} from the resolver, {error} alone from mode validation - exactly as the corrected contract says.

Gates, all six run locally on the final tree: format clean; lint 0 errors; typecheck clean; knip clean; bun run test 13081 pass / 0 fail; bun run build clean; merged coverage 43694/43694 lines (100.00%).

Filed rather than fixed

Three new backlog entries, each with the number it would cost:

• D36 - a slow-query source nobody could read is still a row on three providers and silence on two others. The fix is HealthInfo.slowQueries becoming optional: 15 type-ids with their docs and tests, plus five pinned sentences.
• D37 - the identical fabricated zero survives in getOverview on the same three providers, and there a person sees it: the Overview panel renders a confident 0 connections. Two other providers' docs cite mssql.ts as the "0 means not published" precedent and move with it.
• D38 - two more surfaces read a capped list as a count: QueriesTab's Queries and Slow cards over a list capped at 10, and Trino's table-stats read slicing to 25 tables inside the provider, where nothing above it can see that rows were dropped.

Also noted and not touched, because it is pre-existing and outside this round: the 202 sample for POST /api/agent/runs in docs/API_DOCS.md omits autoExecute and thread, which the route does return.

No src/exports/ file changed, so build:lib and attw are unaffected, and there is no version bump, so the chart and operator gates do not apply.

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud