2026-05-28

Broker dead-code cleanup — session cache removed, issuer-machinery claim corrected

Started the follow-up cleanup slice the 2026-05-27 journal flagged under "Still dormant (follow-up cleanup)." Before deleting anything, mapped the full reference graph for every candidate. The mapping surfaced a material error in yesterday's dormant list.

Correction to the 2026-05-27 "dormant" list

Yesterday's entry said of the issuer/issuance//tokens/Sweeper machinery: "All of this is now unreachable from the live code paths." That is wrong for most of it. Verified live references:

Issuer.List ← GET /tokens (server.go:464, route at server.go:265)
Issuer.Revoke ← DELETE /tokens/{label} (server.go:484, route 266)
Issuer.RotateLabel ← POST /tokens/{label}/rotate (server.go:511, route 267)
mintForWorld / appendIssuance ← reachable via RotateLabel
readIssuances / revokeIssuance / lookupWorld ← reachable via the three routes AND the Sweeper (main.go:189 → sweeper.go:155,212)

So the per-user issuance subsystem is registered, reachable, and user-facing. What is actually true: nothing populates the issuances Secret anymore — the only writer was Issuer.Mint, which now has zero callers — so the /tokens API operates on a permanently-empty dataset. Vestigial, not dead. Retiring it is a product decision (removing a live HTTP surface + a Sweeper refactor to drop its *Issuer dependency), not a dead-code sweep. Left for an explicit go/no-go.

What WAS genuinely dead, and got removed

sessionCache / mcp_session.go. The open-reads + per-world-write-token rework left it constructed-but-never-read: the only production reference was newSessionCache(...) assigned to the mcpGateway.sessionCache field at mcp_gateway.go:74, and nothing ever dereferenced the field. Dispatch goes through worldWriteTokens.Provision, never GetOrMint/Invalidate.

Removed:

mcp_session.go (whole file: sessionCache, session, cachedWorldToken, mintFunc, mintOutcome, errInvalidEmail, LRU/idle eviction, singleflight).
mcp_session_test.go (whole file).
mcpGateway.sessionCache field + the newSessionCache(...) wiring in newMCPGateway.
golang.org/x/sync dependency (singleflight was its only consumer) — dropped by go mod tidy from tools/go.mod + go.sum.

canonicalEmail is NOT in this file (it lives in mcp_auth.go, used by live write paths) — left untouched. Fixed three stale comments that described the old singleflight+sessionCache token-reuse behavior (one in mcp_tools_write.go handleMarkAppend doc, two in mcp_tools_write_test.go's merge-dispatch test) to describe the per-world write-token reuse that actually happens now.

Still orphaned by this change (noted, not yet removed)

cfg.Server.MCP.SessionMaxIdle + MaxSessions (config.go) — validated and defaulted but no longer consumed by any code after the session cache is gone. They no-op now. Folding them into the larger /tokens-retirement decision rather than touching the chart/config surface in this minimal diff. FirstMint* knobs stay live (the write dispatch retry loop still uses them).

Verification

go build ./..., go test -race ./... (broker module), and pre-commit.sh (fmt + vet + lint across all four modules) all green. Pure dead-code removal — no behavior change on any live path.