Skip to content

fix(handler,mcp): an MCP write tool writes one server line with its write_outcome, a handler that wrote nothing logs handler_status=0, and the work after a commit ends at a bound, not with the client - #482

Merged
GottZ merged 9 commits into
rootfrom
issue/453-mcp-write-outcome
Nov 21, 2026

Conversation

@GottZ

@GottZ GottZ commented Nov 21, 2026

Copy link
Copy Markdown
Owner

What this changes

The rest of #453: the open point of its last comment (write_outcome for the direct MCP store) and the five items found on the way.

  • A server line for every MCP write tool. Every call that reaches a tool without readOnlyHint (11 of the 17 tools) writes one INFO line mcp tool write when the tool returns: tool, block_id / blob_id / count, write_outcome (committed, rolled_back, unknown, or none for a call that wrote nothing), staged=true for a confirm_writes card, duration_ms, request_id, and client_gone=true when the client had left by then. No arguments, titles or content. Every tool is registered through addMCPTool, which wraps a tool without readOnlyHint; the tool cores note what they wrote (noteToolWrite, noteToolStatement, noteToolStaged, no-ops outside a call, so cores REST shares note for both).
  • write_outcome on the remaining write paths. The direct MCP store's server fault gets an ERROR line mcp: store error with write_outcome, as POST /api/store has. Added to MCP update, archive, guard_resolve, the staged store/update/archive/store_batch/blob cards, blob_store (REST and MCP), blob_link, the issue tools, the confirmed blob ops, REST guard-resolve with ids and ingest in block mode. statementOutcome states the outcome of a write without a commit label (one statement outside a transaction, or the issue writes' unlabeled bracket): rolled_back for a database error, a missing row or a statement that never left, unknown otherwise.
  • handler_status=0 when the handler wrote nothing. The request logger's record started at 200, so a 499 line of a route that wrote nothing (the MCP SDK after the client of a tools/call left, a /v1 route in the admission queue) read like a handler that answered 200. The record notes whether the handler wrote a status, a byte or a flush. The /v1 access line follows; its booking is unchanged.
  • The query pipeline marks an abandoned admission wait at the translation and the cross-encoder rerank: both stages are fail-open and logged their own WARN line, so the request's 499 stayed INFO without waited_for. They now mark the wait (markAbandonedWait, the same dispatcher wait fix(handler): follow-ups of the client-abort rule — a returned handler, waits the server could not serve, census gaps, the /v1 line and the work after a commit #462 marks).
  • The work a committed write still owes ends at a bound, not with the client. The batch store's afterwork (REST, MCP store_batch, the confirmed batch) ran on an unbounded WithoutCancel; it now runs under one followUpContext (10 s) for the whole batch. The topic map's and the root map's classification after their upsert ran on the caller's context — a client that left POST /api/digest after the upsert left the map with its insert type knowledge, visible to retrieval (executed); only that classification now runs detached, under 5 s each so the request stays within 10 s. The snapshot reloads after settings, secrets, backend, disable-profile, block-type and eject/gaming writes ran on the request context without a bound; they run on followUpContext. Work before the commit stays bound to the client. The handlers run this work synchronously, so the 15 s HTTP drain waits for it and the bound ends a step the database does not answer.
  • Pins. A census of the production tool set (every write tool writes its line, no read-only tool does), an AST census of every handler call of a block, blob or card write (its failure branch names write_outcome; eight existing calls listed as not yet covered), and a census of the writers that declare a body length (point below).

Why

Part of #453 — this PR closes it: the open point and the found-on-the-way items are built or, for the Content-Length case, pinned as unreachable with the place it would become reachable.

go-sdk v1.8.0 hides the request's cancellation from every tool handler but passes the context's values, and its stateless handler waits for the tool (executed). So a write tool runs to its end after its client left, and the only place that can tell "the client never saw this write's answer" is a line written when the tool returns, reading the request logger's record. Rejected: logging from a receiving middleware — it sees schema-refused calls too, but it cannot know which tools write (the SDK exposes no tool annotations to a middleware); a call the SDK refuses before the tool runs wrote nothing and needs no line. Rejected for handler_status: a separate field; no reader in the repository parses the field beyond the operations doc, and 0 reads as "no status written" without a new key.

A Content-Length answer the client received in full before its handler returned is logged 499 (behaviour test). No ctxd writer reaches it: only the camo proxy and the SPA's static files declare a body length, both write it as their last statement and flush nothing. The census fails for a new function that declares a length, flushes one or works on after writing it.

Behaviour changes (intended)

  • New INFO line mcp tool write per MCP write tool call; a new ERROR line mcp: store error for a server fault of the direct MCP store (before: no server line).
  • New write_outcome key on the failure lines listed above.
  • A 499 line whose handler wrote nothing says handler_status=0 (before: 200); on the /v1 access line too. Live requests keep their line byte for byte.
  • /api/query: a client that left while the translation or the cross-encoder rerank waited for its slot gives a 499 at WARN with waited_for=admission (before: INFO).
  • A client that leaves after a committed batch, digest or admin write no longer cuts its afterwork; a hanging afterwork step ends at its bound (10 s, the digest/root-map classification 5 s) with its own context deadline exceeded line; a live client waiting on a hanging settings, secrets or eject/gaming reload gets 500 after 10 s instead of waiting; on SIGTERM the scheduler's digest and root-map runs finish their classification (at most 5 s) instead of stopping.
  • mcpIssueError takes the call's context (MCP issue tools only).

Consumers of the changed contracts

Changed Callers and readers Covered by
mcp tool write line (new) operators; docs/operations.md TestMCPWriteLineStore, TestMCPWriteLineEveryWriteToolCommits, TestMCPEveryWriteToolWritesItsLine
addMCPTool (all 17 registrations) registerTools, registerStoreBatchTool, registerIssueTools, registerGuardTools, registerBlobTools TestMCPEveryWriteToolWritesItsLine, TestMCPEveryRegisteredToolIsBehindTheRecovery
write_outcome on failure lines operators; docs/operations.md TestWriteOutcomeFollowups, TestMCPWriteLineStore, TestWriteFailureLinesNameTheOutcome
handler_status value 0 docs/operations.md; .gotmp/release/deploy.sh counts levels only, no dashboard in the repo TestRequestLogHandlerStatusSaysWhatTheHandlerWrote, TestGatewayAccessLogClientGone*
waited_for=admission from query stages operators; deploy check counts WARN TestQueryAdmissionAbandon*
followUpContext at the batch afterwork and the reloads runStoreBatch (REST batch, MCP store_batch), executeConfirmedStoreBatch, reloadAfterMutation (backend, disable-profile, eject writes), reloadBlockTypes (manage and /api/types), SettingsHandler/SecretsHandler reload, gaming reload TestFollowupBound*
digest/rootmap classification after the upsert POST /api/digest, the scheduler's digest and root-map runs TestFollowupBoundDigest; existing digest/rootmap/events tests
mcpIssueError(ctx, …) the three MCP issue tools, issues_core_prosa_test.go TestMCPWriteLineEveryWriteToolCommits, prosa tests

Cost

  • The tool line sends no statement: 10 statements per direct store call with and without the line (integration measurement, same database, five alternating rounds). The wrapper and its JSON line: about 1.6 µs, 224 B, 6 allocations per write tool call (unit benchmark; the store call itself takes 5–17 ms on the test database). One log line per MCP write call.
  • handler_status: one atomic store per WriteHeader/Write/flush.
  • Afterwork bounds: one timer per batch, digest classification or reload; no statement added. A full batch of 100 items' afterwork took 0.3–0.5 s on the test database (bound 10 s).

Verification

  • Red before / green after: the tool line, the census of write tools (11 write tools without a line on the base), the store fault line, write_outcome on MCP update/archive/guard_resolve/staged batch, REST guard-resolve with ids and ingest block mode, handler_status for a handler that wrote nothing (request line and /v1 line), the query stages' marking (TestQueryAdmissionAbandon*), the bounded batch afterwork, the digest/root-map classification after a client left (the map stayed knowledge, retrieval-visible) and every reload site (TestFollowupBound*: a client that left cut the reload, a hanging one ran the 15 s drain out), and the review fixes (TestMCPWriteLineReviewFixes, TestFollowupBoundGamingReloadsShareOneBound, two new TestStatementOutcome rows). The write-outcome census is red on the base (22 calls without an outcome, 8 after).
  • Mutants: 49, every one killed, none failed to build — 25 on the tool line, the write outcomes, handler_status, the Content-Length census and the review fixes; 7 on the query stages' marking; 17 on the bounded afterwork (each bound removed, moved back onto the request context, set per item instead of per batch, the digest constant raised to 10 s).
  • A fresh reviewer agent read the diff; one medium finding (the client's blob_link argument reached the tool line) and four low ones (a batch or guard_resolve that changed nothing said committed; a refused unlabeled commit or a failed connect read unknown; the eject/gaming reloads had two bounds summing past the drain; the REST issue writes missing from the doc's list) are fixed with tests.
  • go test -race and without, -count=5 on every new test; go test -tags=integration -p 1 on ./internal/handler/ (630 s, ok, final head), ./cmd/ctxd/ (ok), ./internal/store/ (729 s, ok, in the gates), ./internal/digest/, ./internal/rootmap/, ./internal/handler/v1door/ (ok) and ./internal/events/ (412 s, ok; the scheduler calls RunDigest and rootmap.Run).
  • bash go/gates.sh wave --final: rc 0 — build, vet, lint, doccheck, short (11 packages), census tests, race (9 packages, 0 races), integration (5 packages), python conformance, deadcode, deadcode testonly.

Not verified

  • HTTP/2 (ctxd serves HTTP/1.1 only).
  • The MCP tool line on the 2026-07-28 protocol with PropagateRequestCancellation (not set in ctxd): there a write tool would end with its client.
  • A client that leaves after the tool returned and before the SDK wrote the answer: only the request line (499) shows it; the tool line says no client_gone.

🤖 Generated with Claude Code

GottZ and others added 9 commits November 21, 2026 20:05
…er_status=0, not the record's start value 200

Part of #453.

The request logger's record started at 200, so a route that answered a
gone client with nothing (the MCP SDK when the client of a tools/call
left, a /v1 route in the admission queue) logged handler_status=200, the
same line as a handler that answered 200. The record now notes whether
the handler wrote a status, a byte or a flush; without one the 499 line
says handler_status=0. The /v1 access line follows the same rule; its
booking still counts the request as answered. Live requests keep their
line byte for byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ith its write_outcome, and the remaining MCP and batch write failures name theirs

Part of #453.

A /mcp POST's request line said 200 whatever the tool did, and the write
tools answered their outcome to the client only; the direct store tool
wrote no server line at all, even for a server fault. Every tool without
ReadOnlyHint is now registered through addMCPTool and writes one INFO line
"mcp tool write" per call that reaches it: tool, block_id / blob_id or the
item count, write_outcome (committed, rolled_back, unknown, or none for a
call that wrote nothing), staged=true for a confirm_writes card,
duration_ms, request_id, and client_gone=true when the client had left —
read from the request logger's record, since go-sdk hides the request's
cancellation from write tools and they run to their end. No arguments,
titles or content go into it.

The direct store's server fault gets an ERROR line with write_outcome, as
POST /api/store has. write_outcome is added to MCP update, archive,
guard_resolve, the staged store/update/archive/store_batch/blob cards,
blob_store, blob_link, the issue tools, the confirmed blob ops, REST
guard-resolve with ids and ingest in block mode; statementOutcome states
the outcome of a write without a commit label. A census rejects a new
block, blob or card write whose failure line names no outcome.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… after it, the case a delivered answer is logged 499

Part of #453.

A Content-Length answer the client read in full before its handler
returned is logged 499 when the client closes right after reading; the
request logger cannot know the body was delivered. No ctxd writer reaches
it: only the camo proxy and the SPA's static files declare a body length,
both write it last and flush nothing. A census over the handler and web
packages fails for a new function that declares a length, flushes one or
works on after writing it, and a behaviour test shows the verdict such a
writer would get. No production change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ore call with and without it — and about 1.6 µs

Part of #453.

An integration measurement runs the direct store call through the
production chain with the line and with the store tool registered bare,
alternating on one database, and fails when the line adds a statement; a
unit benchmark measures the wrapper and its JSON line alone (224 B, 6
allocations).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…encoder rerank waited for its admission slot is marked waited_for=admission

Part of #453.

Both stages are fail-open: they log their own WARN line and the pipeline
goes on, so the request later failed on the ended context with an error
that is no abandoned wait, and its 499 line stayed INFO without
waited_for. The two WARN sites now mark the abandoned admission wait
(dispatch.AbandonedWait, the dispatcher wait #462 marks) on the request
record, so the 499 line and the line of a later failing step say WARN with
waited_for=admission. The stage lines are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ds at a bound inside the shutdown drain, not with the client

Part of #453.

The batch store's afterwork (REST, MCP store_batch, the confirmed batch) ran on
an unbounded WithoutCancel; it now runs under one followUpContext for the
whole batch (100 items measured 0.3-0.5 s). The topic map's and the root
map's classification after their upsert ran on the caller's context: a
client that left POST /api/digest after the upsert left the map with its
insert type knowledge, visible to retrieval. Only that classification
now runs detached, under 5 s each so the digest request stays within 10
s. The snapshot reloads after settings, secrets, backend, disable-
profile, block-type and eject/gaming writes ran on the request context and
without a bound; they run on followUpContext. Work before the commit stays
bound to the client; a hanging step now ends at its bound, so the 15 s
HTTP drain no longer runs out on it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… write, handler_status=0, the query stages' waited_for and the bounded afterwork

Part of #453.

The section on requests the client gave up on says which lines an MCP
write produces and how to read write_outcome and client_gone there, which
write paths name their outcome and which do not yet, that a 499 whose
handler wrote nothing says handler_status=0, that the translation and the
cross-encoder rerank mark an abandoned admission wait, and how the work a
committed write still owes is bounded inside the shutdown drain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…all that changed nothing says none, a refused commit or a failed connect reads rolled_back, and the gaming reloads share one bound

Part of #453.

blob_link noted the client's id argument before the database matched it,
so an argument that is no id reached the INFO line; it now names the
blob the UPDATE returned. guard_resolve with every id skipped, a batch
whose items all matched (direct and confirmed) noted committed although
nothing was written; they say none. statementOutcome reads
pgx.ErrTxCommitRollback and pgconn.ConnectError as rolled_back. The
eject/gaming toggle ran its backend and settings reloads under two 10 s
bounds, past the 15 s drain; they share one. The cost measurement runs a
fixed number of calls after a warm-up. Docs: the REST issue writes are
listed among the paths without write_outcome, and api.md names
handler_status=0; the census states its limits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… spelling of the argument

Part of #453.

An upper-case id matches the blob; the line carries the id the database
returned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@GottZ
GottZ requested a balanced review from Copilot November 21, 2026 21:35

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@coderabbitai

coderabbitai Bot commented Nov 21, 2026

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 32 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 56a67cde-8ac2-4fb6-91e6-b2304637c112
Commits

Reviewing files that changed from the base of the PR and between db0ba90 and 0f31fed.

Files selected for processing: 36

  • docs/api.md
  • docs/operations.md
  • go/internal/digest/digest.go
  • go/internal/handler/admission_abandon_query_integration_test.go
  • go/internal/handler/backends_manage.go
  • go/internal/handler/blob_core.go
  • go/internal/handler/blocktype_manage.go
  • go/internal/handler/confirm_core.go
  • go/internal/handler/content_length_census_test.go
  • go/internal/handler/context_gaming.go
  • go/internal/handler/context_manage.go
  • go/internal/handler/followup_bound_integration_test.go
  • go/internal/handler/gateway_access.go
  • go/internal/handler/gateway_access_usage_test.go
  • go/internal/handler/ingest.go
  • go/internal/handler/issues_core_prosa_test.go
  • go/internal/handler/mcp.go
  • go/internal/handler/mcp_archive.go
  • go/internal/handler/mcp_blob.go
  • go/internal/handler/mcp_confirm.go
  • go/internal/handler/mcp_guard.go
  • go/internal/handler/mcp_issues.go
  • go/internal/handler/mcp_store_batch.go
  • go/internal/handler/mcp_update.go
  • go/internal/handler/mcp_write_line.go
  • go/internal/handler/mcp_write_line_bench_integration_test.go
  • go/internal/handler/mcp_write_line_integration_test.go
  • go/internal/handler/mcp_write_line_test.go
  • go/internal/handler/middleware.go
  • go/internal/handler/query.go
  • go/internal/handler/request_log_handler_status_test.go
  • go/internal/handler/sealbox.go
  • go/internal/handler/settings.go
  • go/internal/handler/store_batch.go
  • go/internal/handler/write_outcome_census_test.go
  • go/internal/rootmap/run.go
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@GottZ
GottZ merged commit 707468e into root Nov 21, 2026
30 checks passed
@GottZ
GottZ deleted the issue/453-mcp-write-outcome branch November 21, 2026 21:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants