2026-05-20 — Universe Onboarding PR5

Cold-started PR5 from /plans/universe-onboarding-pr5.md. Both open design questions confirmed:

1. GET vs POST for /me/install: GET. Parent-plan-locked, matches OAuth /me-style endpoints. Mint side-effect documented in meInstall's doc comment so future readers don't expect REST-idempotent semantics.
2. Empty authorized worlds → 200 vs 403: 200 + worlds: []. The user IS authenticated; absence of installable worlds is authz-config emptiness, not auth failure. The plugin layer needs the distinction so it can surface "no worlds authorized for your identity" vs an auth-retry.

Changes

• tools/demarkus-broker/internal/broker/issuer.go — MintFiltered(ctx, claims, keep) added. Body of Mint's authorization+iteration moved here; Mint is now a back-compat wrapper MintFiltered(ctx, claims, nil). keep runs AFTER authorizedWorlds so the predicate input is "worlds this identity is already permitted to use." All-filtered-out returns ErrNotAuthorized (same sentinel as "zero authorized worlds in the first place") so the HTTP layer maps both branches to one response shape.
• tools/demarkus-broker/internal/broker/issuer_test.go — six new tests around MintFiltered: nil-predicate ≡ Mint regression guard, predicate skip + Secret assertion, reject-all → ErrNotAuthorized + no-Secret-touch, partial-failure passthrough, ErrNotAuthorized-short-circuits-before-predicate (panic predicate proves the contract), predicate-sees-authorized-worlds-only.
• tools/demarkus-broker/internal/broker/install.go (new) — meInstall handler, installResponse/installWorld structs, toInstallWorlds joiner, lookupPublicURL. PublicURL filter passed to MintFiltered as func(w *WorldConfig) bool { return w.PublicURL != "" } so worlds without a PublicURL get no issuance record. Cache-Control + Pragma headers set BEFORE writeJSON so they actually land on the wire. Partial-mint shape matches /auth/callback's partialFailure field for consumer consistency.
• tools/demarkus-broker/internal/broker/install_test.go (new) — 12 tests covering happy path (1 world), multi-world ordering (declaration order pinned), PublicURL-less filtered out + no Secret churn, no-bearer 401, bad-bearer 401, empty-worlds → 200+[], all-worlds-filtered → 200+[], unverified email → 403, partial mint → 200 + partialFailure flag, hard failure → 500, Cache-Control/Pragma headers, broker-signed bearer accepted (regression guard against PR4's compositeVerifier dispatch).
• tools/demarkus-broker/internal/broker/server.go — mux.Handle("GET /me/install", authedSubject(s.meInstall)) registered in Routes(). Same composition as /tokens routes (requireAuth → subjectRateLimit).
• tools/demarkus-broker/main.go — package-doc Current-scope comment updated to mention /me/install.
• deploy/helm/demarkus-broker/README.md — new "Endpoint surface" section with a table of every broker route + auth/rate-limit/notes. /me/install subsection documents the response shape, the PublicURL-filter rule, the 200-empty empty-worlds policy, the partial-failure shape, and the broker-signed/IdP-signed bearer-accept story.

Design decisions that landed differently from the plan

• MintFiltered's keep runs AFTER AllowConfig, not before. Plan diagrammed it "after authorizedWorlds and before per-world mint." Tightened in implementation: the predicate must NEVER run on an unauthorized caller (the new TestMintFilteredRejectsUnauthorizedBeforePredicate test pins this with a panic() predicate that fires loudly if the contract regresses). Reasoning: a buggy predicate could otherwise be coaxed into running against fabricated WorldConfig pointers if the unauthorized-short-circuit moved.
• toInstallWorlds tolerates empty PublicURL lookup misses. A world that vanishes from cfg.Worlds between MintFiltered's iteration and the response-build (operator hot-reload mid-request) would land in the response with publicURL: "". Two options: (a) drop the row, (b) surface it with empty URL. Picked (b) — config-time race is a logging-and-metrics story; dropping a row would also need a partial-failure flag set, doubling the failure-mode surface for an edge case that doesn't happen in production wiring (cfg is loaded once, never mutated). The consumer (tools/demarkus-join, PR6) treats empty publicURL as "skip this row" so the user sees "X out of Y worlds installed."
• fakeVerifier already had a verifyFn hook from PR4. Was tempted to add a new helper for "verifier that errors on VerifyIDToken"; reused the existing hook instead. Pattern worth remembering for next time: the test-double surface already has the lever; check first.

Verification

• go test -race -count=1 ./internal/broker/ → green (~6s; +18 new tests: 6 MintFiltered + 12 meInstall)
• helm unittest . (broker chart) → 72/72 pass, unchanged from PR4 baseline (no chart changes — README is the only doc surface that moved)
• bash pre-commit.sh → format, vet, lint clean across protocol/server/client/tools

Scope estimate vs actual

Tests came in roughly 2× the estimate — the partial-failure + Cache-Control + broker-signed-bearer matrix is denser than the plan accounted for, and the install_test.go file isolates fixtures (installTestConfig, installTestConfigTwoWorlds) that the plan assumed would be shared with issuer_test.go. Worth it: every test covers a distinct invariant that would be expensive to debug in PR6/PR7 if it regressed silently.

Next

PR5 ready to open. Fritz handles the commits (per /patterns.md "Fritz handles all commits himself"). Branch is feat-tools-broker-me-install. After review + merge:

• PR6 (tools/demarkus-join binary) consumes the JSON shape PR5 emits. Wire contract: {name, publicURL, label, accessToken, expiresAt} per world; PR5 pins this in install_test.go so a future field-rename ripples through tests.
• PR7 (plugin slash commands + kind Stage 5) drives PR6.
• PR8 (docs) is the operator-facing universe-onboarding write-up.

Touch points worth remembering for PR6

• The plugin layer must NOT treat worlds: [] as an auth error. The broker returns 200; the plugin surfaces "no worlds authorized for this identity."
• A partialFailure: "one_or_more_worlds_failed" field is informational, not fatal — install the worlds that did come through and tell the user some are missing.
• accessToken is a one-time disclosure. Once it lands in tools/demarkus-join, write it to the world client config and discard the in-memory copy; the broker can't reissue it (raw material is unrecoverable).
• Cache-Control + Pragma headers are set by the broker, but the consumer should also avoid logging the response body — bearer tokens leak via accidental error-path stack traces.

Broker MCP Gateway — kickoff (Pre-Flight 0 + 1)

Same-day pivot from PR5 (#141 shipped) into the gateway plan. Plan v3 read top-to-bottom; only Open Question 1 is settled, #2-#8 carry forward with their documented leans.

Pre-Flight 0 — hoist client/internal/fetch + merge to public

Branch feat-client-hoist-fetch-public. Mechanical relocation:

• client/internal/fetch/fetch.go → client/fetch/fetch.go
• client/internal/merge/{merge,diff3,merge_test,diff3_test}.go → client/merge/...
• Import paths updated in 9 consumers (broader than the plan's "3 cmd dirs" — also demarkus-agent, fedcrawl, graphstore). The grep before the move caught this; worth noting in the plan-vs-reality column.

Verification:

• go test -race -count=1 ./... inside client/ → green; same package list as baseline plus client/fetch (no test files) and client/merge (tests survive the move intact).
• bash pre-commit.sh → format/vet/lint clean across protocol/server/client/tools.
• git status shows 5 renames + 9 modified imports. Git's rename detection caught all 5 as zero-diff renames.

Why this matters for the gateway: tools/demarkus-broker lives in a separate Go module under monorepo replace directives. Go's internal-package rule would have blocked the broker from importing client/internal/fetch and client/internal/merge directly. The hoist is the unlock — broker's per-tool handlers in Slice 2/3/6 can now call fetch.Client and merge.Candidate without copy-paste.

Branch waiting on Fritz for commit + PR review (per /patterns.md "Fritz handles all commits himself").

Pre-Flight 1 — Streamable HTTP support in mcp-go v0.44.0

Decision: Streamable HTTP, via mcp-go's server.NewStreamableHTTPServer. No transport swap or in-house implementation needed.

Evidence: ~/go/pkg/mod/github.com/mark3labs/mcp-go@v0.44.0/server/streamable_http.go exports StreamableHTTPServer as a first-class production type (not just a test helper). It implements http.Handler — drop-in for whatever HTTP mux the broker's MCP listener uses, and the default URL path is /mcp, exactly the shape Slice 1 calls for. Three usage modes are documented (.Start(":8080"), http.Handle("/path", handler), or ServeHTTP directly). Targets the 2025-03-26 transport spec.

One caveat from the package doc: "The current implementation does not support Stream Resumability." Irrelevant here — the plan's Out-of-Scope already excludes long-lived subscriptions and server-initiated events; tool calls are JSON-RPC request/response. Polling is the model.

Slice 1 shape this implies:

• mcpGateway wraps server.NewStreamableHTTPServer(s.mcpServer) and mounts it on a fresh http.ServeMux separate from the existing management API.
• gatewayAuth middleware composes around the StreamableHTTPServer (standard http.Handler chain): id_token verification + per-subject rate-limit happen before the handler ever sees the request body.
• OAuth metadata endpoints (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server) register on the same mux, plain mux.HandleFunc.

Stdio-mode client/cmd/demarkus-mcp keeps using ServeStdio — unchanged. Two transports, one tool surface, eventually.

Next

Branch out of Pre-Flight 0 once merged, cut feat-tools-broker-mcp-gateway-foundation for Slice 1.