Repository navigation
design(mcpx): honour upstream ttlMs and cacheScope — the pool catalogue cache gets a freshness deadline and a scope #1601
Description
Summary
mcpx's server half honours the 2026-07-28 caching contract; its client half never did. The client drops ttlMs/cacheScope on the floor, the pool's catalogue cache has a timestamp and no expiry, and the on-disk schema cache persists private catalogues and re-serves them after a restart as if they were public and eternally fresh. This design gives the pool cache a freshness deadline and a scope, era-scoped the way the spec is.
Design doc: files/designs/code-mcpx-client-cache-hints.md in the keep-the-four-repos-healthy goal workspace (full audit, alternatives, risks, open questions).
Current state (verified on main 33a4e67, 2026-10-28)
- Server side landed:
internal/mcpserver/server.gostampsttlMs+cacheScopeon complete cacheable results for modern peers (scope table ~L690-706; envelope ~L730-740; values fromprotoMessages.listMaxAge/readMaxAgesettings). - Client side missing: list result types in
internal/mcpclient/client.go(toolsListResult~L183,resourcesListResult~L204,resourceTemplatesListResult~L209,promptsListResult~L1117) carry no hint fields;ListTools/ListResources/ListPromptsreturn bare slices. - Pool:
Pool.Schemas(internal/pool/pool.go~L815) serves the cache forever onceschemaAtis set; onlyInvalidate()(list_changed, viainternal/daemon/hooks.go) or manual refresh re-reads. - Disk:
Registry.loadCache/SaveCache(internal/daemon/registry.go~L249-285) persist and re-seed every catalogue with no TTL applied toFetchedAtand no scope check. - The conformance register says it nine times (
internal/conformance/coverage_stateful.go:113-121, client gaps under mcpx client: cannot reach a conformant 2026-07-28 server dezren39/darwin-nix#200): "the client ignores ttlMs and cacheScope; the pool keeps upstream lists until list_changed or restart" — pluscaching-notification-invalidates(CI: nix flake check intermittently dies with 'No space left on device' in id-test/id-ci #257) unverified.
Proposal (decisions recorded in the design doc)
- Freshness is era-scoped. Modern upstream: hints rule — absent/zero/negative
ttlMs= immediately stale; positive = hard deadline. Legacy upstream: unchanged (cache until list_changed / refresh / restart) — the TTL rules exist only in 2026-07-28, and legacy's invalidation channel is its notifications. - Aggregated hints. A list's TTL is the minimum across its pages; its scope is
privateif any page says so. The pool cache expires at the earliest of its three lists' deadlines. - Private never persists.
SaveCacheskips private catalogues; public disk entries carry deadline + scope (cacheVersion bump) and seed expired if their deadline passed. - Stale on error only. A failed refetch of an expired entry serves the stale entry and records the error; a failed first fetch behaves exactly as today.
Phases (each independently landable; filed as sub-issues)
- Client hints + pool TTL (modern era) — hint fields/aggregation in
internal/mcpclient(incl. templatesnextCursor→*string+ paging), hint-returning list variants with existing signatures kept as wrappers; pool deadline +Schemas()expiry; fivecaching-*gaps retired. - Scope, disk persistence, stale-on-error — scope plumbing, private-never-persisted, expired-on-load seeding, stale-on-refetch-failure;
caching-private-no-cross-authretired. Gated on Phase 1. - Truth-up + notification verification + origin note — the missing list_changed-invalidates-cache test;
docs/compare/register/pagination-caching.mdPG-08..PG-13 rewritten as-built; remaining gaps retired with reasons; roadmap row updated; evidence comment on mcpx client: cannot reach a conformant 2026-07-28 server dezren39/darwin-nix#200 (comment, not close — that umbrella tracks other rows). Gated on Phases 1–2.
Open questions stay in the design doc (resources/read client caching, discover/era TTL, a legacy default TTL knob, per-kind deadlines, background revalidation) — they are questions, not issues.
Related
- Origin: mcpx client: cannot reach a conformant 2026-07-28 server dezren39/darwin-nix#200 (its summary names this remainder: "
ttlMson upstream lists is ignored") - Roadmap:
planning/roadmaps/mcpx.md→ Next → "Legacy client robustness" (nix#203, nix#200, nix#201) - Register:
pkgs/mcpx/docs/compare/register/pagination-caching.mdPG-08..PG-13 - Neighbouring designs (distinct): design(mcpx): a supervisor that owns each stdio child's pipes — replace the takeover handoff for stdio #1384, design(mcpx): resume upstream HTTP sessions after a cold restart — persist the resumable session state #1414, design(mcpx): JSON Schema validation of tool input and output — one validator at the client choke point #1481, design(mcpx): what a stdio server's identity is — a script's identity includes its directory #1531, design(mcpx): tasks, finished — one task store for MCP and /v1, and a client that can call task-required tools #1554
Acceptance criteria
- The design decisions in the linked design doc are implemented by the three phase issues (mcpx: Phase 1 of #1601 — surface ttlMs/cacheScope in mcpclient and expire the pool catalogue cache (modern era) #1602, mcpx: Phase 2 of #1601 — cacheScope at the disk boundary: private never persists, expired seeds expired, stale on refetch error #1603, mcpx: Phase 3 of #1601 — register truth-up, list_changed invalidation test, and nix#200 evidence #1604): the mcpclient list types carry
ttlMs/cacheScope, aggregated hints (minimum TTL across pages,privateif any page is private) drive pool cache expiry, and legacy-era upstreams keep the unchanged cache-until-list_changed behaviour. Registry.SaveCachenever persists aprivatecatalogue; public disk entries carry deadline + scope (cacheVersion bumped) and seed expired once their deadline has passed.- The conformance register's client-caching gaps (coverage_stateful.go, under mcpx client: cannot reach a conformant 2026-07-28 server dezren39/darwin-nix#200) are updated to match the landed behaviour, and the stale-on-refetch-error behaviour is covered by a test.
Metadata
Metadata
Assignees
Labels
Package/app: mcpx (pkgs/ or apps/ in this repo)Large: multi-day or open-ended; expect staged check-insMeta-issue grouping multiple items (org Project Type=Epic)A design proposal (design-architect): multi-step, phased, decision-bearingIntake review done: acceptance criteria, links, and normalized labels addedOrdinary priority (the default)Filed by the repo design architect job
Activity
developing-today commentedon Oct 28, 2026
CODE-627
dezren39 commentedon Oct 28, 2026
🤖 Agent note · filed
dezren39 commentedon Oct 28, 2026
Intake review
Related: phase issues #1602 (Phase 1, PR #1608 in CI), #1603 (Phase 2), #1604 (Phase 3) carry the implementation; dezren39/darwin-nix#200 holds the conformance-register evidence. No merged PR resolves this design issue (checked this run).
Notes: the server half already landed on main; this epic closes when its three phases merge and the register is truthed up. Labels were already complete (kind/design, source/design-architect, priority/normal, effort/l, app/mcpx) — this pass adds only the standard acceptance section and
meta/enriched.Risks: era-scoping is the sharp edge — applying modern TTL rules to a legacy upstream would thrash the catalogue cache; the phase issues carry that boundary.
Suggested approach: let the phases land in order (#1602 → #1603 → #1604); close this epic from the #1604 completion note with the register diff linked.
🤖 Agent note · filed
1 remaining item
feat(mcpx): enforce cacheScope at the disk boundary (#1603)
feat(mcpx): enforce cacheScope at the disk boundary (#1603)
mcpx: Phase 3 of #1601 — list_changed invalidation test, register tru…
dezren39 commentedon Oct 29, 2026
Phase 3 landed — the pagination-caching slice is complete (PR #2181)
#1604was the last phase of this design. Merged as PR #2181 (318ca58a17f944d47759a75c094e4ab090e83f47, 2026-10-29), closing #1604.daemon.TestListChangedInvalidatesPoolCache— a modernlist_changednotification (tools, resources, prompts) empties the pool catalogue cache (timestamp + deadline forgotten), so the next read re-lists instead of serving the stale catalogue. This retires thecaching-notification-invalidatesgap, which was the last unverified one.caching-may-refetch-early-serve-stale(a MAY mcpx does not take — refresh is synchronous on read, the decision recorded here),caching-page-refetchandcaching-key-method-params(not applicable by construction — one aggregated catalogue per configured server;resources/readis not pool-cached). Reasons live inoverrides/stateful.jsonand the register, and flow into the regeneratedrequirements.json.docs/compare/register/pagination-caching.mdPG-08..PG-13 now describe the post-Phase-1-2 as-built state with code evidence instead of the pre-fix "none of the six carry them" text.planning/roadmaps/mcpx.mdnames the caching slice as landed.With Phases 1 (#1602 / PR #1608), 2 (#1603 / PR #1705) and 3 (#1604 / PR #2181) merged, the ttlMs/cacheScope freshness-deadline slice of this design is delivered. Remaining items in the body are the ones explicitly deferred (e.g.
resources/readresult caching, discover TTL, a legacy default TTL) and remain open design questions, not implementation gaps in the conformance register.dezren39 commentedon Oct 29, 2026
Program tending — all sub-issues closed, proposing closure
Program-tender check (2026-10-29): all 3 sub-issues of this design epic are now closed — #1602 (closed 2026-10-28T11:26Z), #1603 (2026-10-28T22:03Z), #1604 (2026-10-29T08:45Z) — and the Phase 3 landed comment above already records the slice as complete (PR #2181).
Proposing this epic be closed as complete, so the epic list only carries designs with work still owed.
dezren39 commentedon Nov 1, 2026
🤖 Agent note · picked up
dezren39 commentedon Nov 1, 2026
🤖 Agent note · triage verdict — ALREADY DONE; closing with evidence (task 2613)
pkgs/mcpx/internal/mcpclient/client.go:235-265—CacheHintsaggregates across pages exactly as designed:TTLMsis the minimum declaredttlMs;Privateis true when any page declaredcacheScope "private"; list result types carryttlMs/cacheScopefields.pkgs/mcpx/internal/pool/pool.go:202-211, 1010-1014—schemaDeadline("when a modern upstream's ttlMs hints say the cached catalogue goes stale; zero means never expires — legacy upstreams") gates the cachedSchemas()path.pkgs/mcpx/internal/daemon/registry.go:137-156, 415-426+SaveCache— entries carryDeadline+Scope; "SaveCache never writes a private entry and loadCache never seeds one" (write side skipsprivatepools with the mcpx: Phase 2 of #1601 — cacheScope at the disk boundary: private never persists, expired seeds expired, stale on refetch error #1603 comment; load side refusesScope == "private"even from a foreign cache file);cacheVersionis shape-derived.