Skip to content

docs(specs): 102-schema-deferred plan - #1045

Closed
Dumbris wants to merge 37 commits into
mainfrom
102-schema-deferred-plan
Closed

Dumbris wants to merge 37 commits into
mainfrom
102-schema-deferred-plan

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 25, 2026

Copy link
Copy Markdown
Member

Speckit stage 2 for Spec 102 (schema-deferred direct mode, issue #971 accepted direction): implementation plan + Phase 0/1 artifacts (research.md, data-model.md, quickstart.md, one contract).

Key decisions recorded (D1-D8): dedicated direct_tool_response_mode key (default full, flag + env parity); outputSchema deferred with additive output_schema in describe_tool definitions; describe_tool batch cap stays 5; FR-007 convention via static direct-server instructions; FR-009 prose goes surface-neutral with a one-time enumerated regen of the two describe_tool-bearing goldens; FR-017 directCatalog snapshot (atomic swap, deterministic collision guard) shared by listing/signatures/describe/validation; catalog-backed direct describe resolver with listing-parity gates incl. the operation-permission tier; opt-in rollout, no default flip.

Golden handling is explicit: tools_list_prefeature, retrieve_full_default, pre099/, and code_execution_mode pass unregenerated; a new gate pins the direct surface's built-ins in both modes.

Plan only — no tasks.md, no implementation. Related #971

Plan for schema-deferred direct-mode enumeration (Spec 102): dedicated
direct_tool_response_mode config axis, FR-017 directCatalog snapshot design,
describe_tool on the direct surface with listing-parity visibility,
pre-dispatch validation reuse, frozen-golden handling, and file-touch list.
Phase 0/1 artifacts: research.md, data-model.md, quickstart.md, contract.

Related #971
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 25, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: 4a683c1
Status: ✅  Deploy successful!
Preview URL: https://eee59b2e.mcpproxy-docs.pages.dev
Branch Preview URL: https://102-schema-deferred-plan.mcpproxy-docs.pages.dev

View logs

@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

…findings

Self-review + cross-model review pass over the stage-2 plan artifacts.
Every item below was verified against this tree before recording.

Corrections to false/incomplete claims:
- R11 (new): the {"type":"object"} placeholder is NOT what mcp.NewTool
  produces. mcp-go v0.57.0's schema marshaller always writes properties:{}
  and required:[], which re-opens the arg-pruning hazard FR-004 exists to
  close. Deferred entries must use mcp.NewToolWithRawSchema with annotations
  copied on explicitly; mixing RawInputSchema onto a NewTool result is a hard
  marshal error, not a silent override. Verified empirically.
- R2: retracts "no golden pins describe_tool response bytes" — the
  describe_plain_corpus gate pins 18 response bodies byte-for-byte. Added as
  the FOURTH frozen gate with named describePlainDelta substitutions.
- R5: the surface-neutral prose rewrite covers FOUR retrieve_tools strings,
  not one — both parameter descriptions and the two shared remediation
  constants. tool_ids prose must also name the server__tool id form (FR-011).
- Test strategy: names TestDescribeTool_RegisteredInRetrieveToolsModeOnly's
  "direct routing mode" subtest, which asserts the v1 decision this feature
  reverses and will go red; and warns the new direct built-in gate must be
  standalone, since DeltaIsEnumerated demands a pre099 baseline per surface.
- toolsListAllowedDelta needs no edit: describe_tool is already enumerated
  there from spec 099.

Missed interactions now closed:
- D10: parity must hold on BOTH sides. The direct listing filters still
  resolve via ParseDirectToolName's first-__ split, so a server named a__b
  is judged as server a by the listing and as the real pair by a
  catalog-backed describe — describable-but-unlisted, the exact FR-011
  disclosure. Filters now resolve through the catalog. Also gated: the
  preflight did_you_mean corpus (server-level filtered only, no permission
  tier) and the definition-mode case-correction hint.
- D11: FR-007 instructions ignored the operator-configurable instructions
  config key, which today reaches only the default server. Direct-server
  instructions are now resolveInstructions(cfg) + the deferral legend.
- D12: upstream.Manager is concrete and lists only connected clients, so the
  unit matrix had no seam. buildDirectModeTools splits into pure
  buildDirectCatalog + renderDirectTools.
- Pre-dispatch validation placement pinned, including the started+completed
  activity pair the 085 path emits (issue #969 blind-spot property).
- FR-014 guard: publish an empty catalog on DiscoverTools failure so a flip
  during an upstream outage is not lost.

Related #971
…02 gates need

The token gates were specified as "measure via the spec-083 profiler pipeline"
with no implementation surface. bench/arms/ is a registry of encoding arms
(baseline, compact_sig, toon, tron, tscg) that all render retrieve_tools result
sets; none renders a direct tools/list, so the deferred measurement needs a new
registered arm plus its testdata render golden. Added bench/arms/ to the
file-touch list and the package count.

Related #971
… the FR-007 instructions precedence in the summary

Related #971
…return path; instructions hot-reload caveat stated

buildDirectModeTools returns nil early when DiscoverTools fails
(mcp_routing.go:81-85), so "append describe_tool inside tool-set construction"
must mean every return path or the built-in vanishes on the first upstream
hiccup. Also records that instructions are constructor-time on both server
instances, so D11 does not promise hot-reload it cannot deliver.

Related #971
…ture actually runnable

The merge-base capture as written cannot run: the D12 pure seam does not exist
at origin/main and DiscoverTools only returns tools from connected clients, so
there is no way to render a deterministic direct listing there from a fixture
slice. Replaced with a live stdio-fixture capture (the preflight_e2e_test.go /
testdata/preflight_fixture_server.js harness, which runs unchanged at the
merge-base) plus a same-tree differential fallback, with the trade-off stated.

Related #971
@github-actions

github-actions Bot commented Aug 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: 102-schema-deferred-plan

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (25 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (21 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 33043150949 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

Dumbris added 20 commits August 25, 2026 07:27
…tually is

The contract example showed create_issue(owner*:str, ...) while
toolsig.Signature.Sig is the parenthesised parameter list only and carries no
tool name (internal/toolsig/signature.go:18). Made the name prefix normative and
recorded that Signature.Desc is deliberately unused here, since deferred entries
keep the full description rather than the 085 first-sentence prefix.

Related #971
…rral legend

R4 and the contract carried two different draft legend texts. R4 now points at
the contract as the single source so the pinned bytes have one origin.

Related #971
Mirrors effectiveToolResponseMode (profile_resolver.go:57) so the renderer, the
catalog's recorded serializationMode, and the FR-014 rebuild guard cannot resolve
the mode by three different paths. Notes it takes no detail override, since
tools/list has no parameters.

Related #971
…nition annotations)

buildFullToolEntry does not read annotations from the entry passed in: it calls
p.lookupToolAnnotations (mcp.go:6344), which reads the StateView snapshot, and
derives call_with from that, defaulting to ToolVariantRead on nil. A
catalog-backed describe that synthesizes a ToolMetadata would therefore still
resolve annotations out-of-band — so the listed pending/changed destructive tool
SC-007 targets would describe with no annotations and call_with:"read". That is
a wrong safety hint, not just a missing field. The definition-assembly seam now
takes a catalog-supplied annotations override on the direct surface only, leaving
the retrieve_tools path byte-identical for the frozen goldens.

Related #971
…the direct check-mode corpus

preflight.Scope is a server-name set, so the evaluator structurally cannot
express the per-tool gate the direct listing applies — which is why did_you_mean
leaks names the listing hides. The fix is concrete rather than aspirational:
preflight.EvalContext.Index is an interface (preflight_glue.go:103 supplies
preflightIndexReader), so the direct surface passes a catalog-backed reader and
both id resolution and the suggestion corpus share one authority. Suppression
demoted to fallback. Added preflight_glue.go to the file-touch list.

Related #971
…tution row with D9-D12

D4/D5 rows and the Principle IV assessment still described the pre-hardening
scope. Also records that all four direct routes share one p.directServer
instance (GetMCPServerForMode), so a single SetTools covers the aliases.

Related #971
…ndings

Round 2 (opencode / gpt-5.6-sol). Every finding was re-verified against this
tree before the fix.

BLOCKER — catalog/registry publication skew (new R13, D13). The atomic.Pointer
makes the catalog swap atomic but NOT the catalog-plus-mcp-go-registry pair:
RefreshDirectModeTools publishes the catalog and then calls SetTools
(mcp_routing.go:666-673), and mcp-go owns its own registry read, so no lock of
ours can span both. Handler-to-schema atomicity does hold (closure capture); the
filters and describe resolver are what skew. Closed by rule rather than denied:
catalog published first, filters DENY on catalog miss (built-ins matched by an
explicit name set — the previous fall-through wording would have let a stale
entry skip the permission-tier gate during the window), describe additionally
requires directServer.GetTool(name) != nil, plus a generation counter and an
interleaving test.

MAJOR — check-mode ids (D14). preflight.Evaluate accepts colon ids only
(splitToolID, evaluator.go:500-510) and normalizeDescribeCheckIDs forwards ids
verbatim, so every server__tool id under check:true would answer not_found no
matter what the id gate does. The adapter now canonicalizes before Evaluate and
restores the caller's original id and ordering in both response and activity.

MINOR — server-level vs tool-level states. DiscoverTools drops disabled and
quarantined SERVERS before projection (upstream/manager.go:1128-1138), so the
"non-agent listings retain quarantined/disabled" claim was too broad: only
pending / changed / tool-level-disabled reach the listing.

MINOR — TestRetrieveToolsFullMode_GoldenByteIdentity pins TWO goldens
(retrieve_full_default and retrieve_full_stats, mcp_entry_builder_test.go:116).
Both are now listed as must-pass-unregenerated.

Related #971
…empty one in the deny-on-miss rule

Deny-on-miss would otherwise blank the listing before the first publication and
break every hand-constructed test proxy that calls the direct filters directly.
A nil pointer keeps today's ParseDirectToolName behavior; an empty published
generation is real and denies.

Related #971
…icity claim

R9 buys handler-to-schema atomicity only; a reader stopping there would carry
away the over-broad claim R13 corrects.

Related #971
…indings

BLOCKER — D13 did not cover a same-name update. GetTool(name) != nil is
satisfied by the old entry while the resolver uses the new catalog, so a schema
edit or a flipped collision winner could be described one generation ahead of
the registry. Generation stamping is not available (mcp.Tool's only free-form
field marshals to _meta, which FR-015 freezes; mcp-go snapshots its tool map
before our filters run), so the plan now promises a stated safety property
instead of atomicity: SetTools first then publish, permission tier derived from
the registered entry's OWN annotations (generation-correct by construction,
closing the read-to-destructive over-permit), and the residual same-name
staleness enumerated with tests for all four interleavings.

MAJOR — the direct server registers nothing at init (mcp_routing.go:651-653,
"built lazily... servers.changed will trigger a refresh"). Composing the
built-in into rebuild construction alone leaves FR-009 false until the first
refresh, worst with zero upstreams, and leaves the catalog nil so the first
unrelated reload churns every client. Added D15/R14: an initial direct rebuild
in initRoutingModeServers, and the built-in gate now asserts over
p.directServer.ListTools() rather than the builder's return value.

MAJOR — D11 imported resolveInstructions' defaultInstructions, whose DISCOVERY
line says "Use 'retrieve_tools'" and whose CALLING line names call_tool_*, none
of which exist on the direct surface. D16: operator text when set, otherwise a
direct-specific default.

MAJOR — the check-mode column used definition mode's vocabulary. Check mode
answers status:"unavailable" plus a preflight.Reason (tool_pending_approval,
tool_changed, tool_blocked_by_user, tool_denied_by_config, ...). The adapter now
projects those through untouched, with a byte-compatibility test.

Related #971
… chosen ordering

The table still marked catalog-first as chosen after the round-3 fix reversed it.
Rewritten with the same-name row added and the reasoning for SetTools-first made
explicit: removal becomes window-free, addition fails closed.

Related #971
…t publish

Today buildDirectModeTools calls setDirectToolPermissions mid-build, before
RefreshDirectModeTools reaches SetTools — the exact ordering R13 rule 1
reverses. Made the constraint explicit so the split in D12 does not carry the
old publication point along with it.

Related #971
…ocument

Round 4 (opencode). Both findings were my own round-3 fixes not carried through.

D13 rule 3 (tier from the registered entry's own annotations) had not reached
data-model.md, which still routed the listing filters at the catalog's
requiredPermission and still asserted "installed by one SetTools call
(atomicity)" — the claim R13 retracted. The catalog now backs the (server,tool)
split and the describe resolver only; the invariant is restated as R13's safety
property.

D16 had not reached plan.md, whose FR-007 summary and D11 row still mandated
resolveInstructions — the function D16 exists to avoid. Named the single helper
resolveDirectInstructions and dropped upstream_servers from the direct default:
management tools are registered by the code-exec and call-tool builders only
(mcp_routing.go:398, :507), so naming it would repeat the defect.

Also records the init state transition (D15) in the data model.

Related #971
…wing in Complexity Tracking

R13 replaces the spec's literal "rebuilt atomically, so no window exposes one
without the other" with a proven safety property, because the two publications
straddle mcp-go's registry and cannot be made one transaction without forking it
or taking the direct listing off SetTools. A plan that quietly weakens a spec
MUST is exactly what review should catch, so the narrowing is now an explicit
Complexity Tracking row flagged for the maintainer's assent at the tasks stage,
not a silent reinterpretation buried in research.

Related #971
…-5 finding)

Round 5 showed D13 still had a hole: name-only GetTool membership cannot detect
that the registered entry and the catalog entry describe different ORIGINS. A
flipped collision winner could get scope-checked against server A while its
handler dispatches to server B, and the describe path still took its tier from
the catalog, so a read-scoped token could obtain a destructive tool's definition
during the window.

Two mechanisms close it, both verified against the tree:
- Colliding display names are now WITHHELD outright rather than first-writer-wins.
  The spec sanctions this (resolve deterministically OR report it), and it is
  strictly safer than today, which is undefined rather than merely
  non-deterministic: buildDirectModeTools appends both and SetTools collapses
  them last-writer-wins over a map seeded by a map iteration of m.clients.
- A name can still change origin without ever colliding (A removed and B added in
  one reconcile). Closed by a description discriminator: filters and the describe
  resolver compare the catalog entry's rendered description against the registered
  mcp.Tool.Description and fail closed on a mismatch. One string comparison, no
  wire change, and it subsumes the same-name schema-change case.

The describe path also takes its tier from the GetTool result's annotations now,
not the catalog. Residual narrows from served-stale to briefly-withheld —
availability, not correctness. Interleaving tests go from four cases to five.

Related #971
…or claim (round-6 finding)

The round-5 draft claimed the description discriminator "subsumes" the same-name
schema-change case. It does not: the direct description is
fmt.Sprintf("[%s] %s", ServerName, Description) (mcp_routing.go:95), so a
schema-only edit leaves it byte-identical, and in deferred mode the appended
signature is lossy by design so a nested-property change can render the same ~.
No field on the registered mcp.Tool encodes the schema in BOTH modes either --
deferred advertises the same {"type":"object"} placeholder for every tool -- and
Tool.Meta is wire-visible, so a hash stamp is closed off by FR-015.

The identity and origin hazards stay fully closed. The schema-only case is now
recorded as an explicit residual rather than claimed fixed, with its blast radius
argued rather than asserted: dispatch is never wrong (the handler validates
against the schema it captured), so an agent acting on a stale definition is
rejected by the pre-dispatch validator with the CORRECT schema embedded and
succeeds on one retry -- the US3/SC-003 self-healing path this feature ships. It
gets its own Complexity Tracking row flagged for maintainer assent, and a sixth
interleaving test that asserts the residual behaves as documented.

Also fixes two stale contradictions the same review surfaced: data-model.md still
labelled byDisplayName first-writer-wins, and R12's signature sketch still had
the builder publishing the catalog.

Related #971
…alog entry (round-7 finding)

The R13 rule 5 discriminator compared "the catalog entry's rendered description"
against the registered mcp.Tool.Description, but the catalog stored only the raw
upstream description -- so the comparison implied a re-render. In deferred mode
that suffix comes from toolsig.Cache, which mutates independently of any direct
rebuild: Warm adds entries at index time and RetainHashes evicts them
(internal/toolsig/cache.go:79, :108). A miss at registration followed by a hit at
filter time, or the reverse, would flip the recomputed string with no generation
change at all, manufacturing a false mismatch that leaves a still-registered tool
unlisted and undescribable until the next rebuild. That is a persistent SC-007
violation -- strictly worse than the microsecond window the discriminator exists
to police.

renderDirectTools now records each entry's exact renderedDescription on the
catalog before publication, and the discriminator compares two immutable
snapshots. Two no-rebuild interleaving tests added: cache miss->warm and
hit->eviction must both leave the tool listed and describable.

Related #971
…e count reads straight

Six cases had accumulated as five-plus-two-plus-a-sixth. Regrouped into
closed-by-design, closed-by-withholding, and the documented residual, with the
two no-rebuild cache cases called out separately as what they are: proof the
discriminator reads the stored value.

Related #971
…on API and the annotation defaults (round-8 findings)

Cross-model review round 8 (two scoped opencode passes) returned five MAJORs and
four MINORs; all nine verified genuine against the tree, none rejected.

D13 rule 3 was wrong twice over. It told the filters and the describe resolver to
derive the permission tier from the REGISTERED entry's annotations via
contracts.DeriveCallWith "exactly as dispatch does". DeriveCallWith takes
*config.ToolAnnotations, while the registered entry carries mcp.ToolAnnotation --
and mcp.NewTool seeds destructive=true on every tool, with each
With...HintAnnotation overwriting only its own field. A read-only upstream tool
therefore registers readOnlyHint=true AND the untouched destructiveHint=true, and
DeriveCallWith gives destructive top priority: the rule would have classified
nearly the whole catalog destructive, hiding it from every read- and write-scoped
token while dispatch still admitted the call as read. The tier now comes from the
catalog entry's upstream-derived requiredPermission -- identical to today's
behavior and to dispatch's -- used behind the rule-5 discriminator. That makes an
annotations-only change a third stated residual, bounded exactly like the
schema-only one: the handler re-derives the tier from its own captured
annotations, so no call is ever mis-authorized, only a listing can be stale.

R13 rule 1 forbids the builder from publishing, but R12 still specified
buildDirectModeTools as returning []ServerTool alone -- leaving the catalog it
built unreachable and RefreshDirectModeTools with nothing to publish. It now
returns (tools, catalog), non-nil on every path including the DiscoverTools error
return.

NewToolWithRawSchema leaves every annotation hint nil where NewTool seeds four
defaults, so copying only the upstream hints would have made full and deferred
modes marshal different annotations for the same tool (FR-004/FR-008). The
deferred renderer now seeds mcp-go's defaults first.

D15 publishes an empty catalog at init and FR-014 guards the reload, which
together retire the nil-catalog unconditional rebuild -- an accidental self-heal
for a dropped first servers.changed. SubscribeEvents is hoisted out of the
listener goroutine into the constructor, ahead of StartBackgroundInitialization.

Also: spec.md FR-017 gains a note pointing at the plan's three narrowings so the
two documents stop contradicting each other (requirement text unchanged);
rule-count drift fixed (five, not three/four) and two mislabelled rule-4
references corrected; the skew matrix is seven interleavings plus two no-rebuild
cache cases, with the annotations-only case added; generation is given its two
concrete uses and a data-model row instead of being vestigial; quickstart no
longer promises a signature on every entry, which contradicted FR-005.

Related #971
…iduals field by field (round-9 findings)

Cross-model review round 9 re-reviewed the round-8 fixes and confirmed all nine,
then found five more. All verified genuine, none rejected.

The residual inventory was incomplete and the narrowing was under-declared. R13
now walks directCatalogEntry field by field and proves exactly three fields can
move while leaving the rendered description byte-identical: paramsJSON,
outputSchemaJSON and annotations. outputSchemaJSON was the one nobody had named,
and it does not fit under the existing schema residual: nothing validates against
an output schema, so the invalid_params self-healing retry that bounds the input
case does not apply. Stated separately, with what actually bounds it -- output
schemas are advisory shape metadata MCP permits to be absent entirely, so a stale
one costs an agent one mis-shaped parse and is corrected at the next publish.

The spec.md FR-017 note declared only the FR-017 deviation, while the
annotations-only residual also relaxes FR-011 and SC-005 (a read-scoped token can
briefly list a tool that just became destructive) and the two schema residuals
relax SC-007. The note now names all of them, and repeats that call-time
authorization is never stale -- the handler re-derives the tier from its own
capture, so the call is refused even while the listing is not.

Also: the contract still told implementers to copy annotations onto the
raw-schema tool "explicitly", which is precisely the instruction round 8 found
broken -- it now carries the seed-defaults-then-override rule. The publisher
count was ambiguous (D12 said two builder call sites, D15 implied a second
independent publisher); pinned to ONE publisher, RefreshDirectModeTools, which
the initial rebuild calls rather than duplicating. Quickstart no longer claims
the placeholder schema on every entry -- describe_tool keeps its real one.

Related #971
…nto source and derived fields (round-10 finding)

Round 10 confirmed the four other round-9 fixes and found the fifth over-claimed.
R13's field walk concluded "nothing else on the entry can skew silently" after
enumerating only the source fields; it skipped requiredPermission, which is a real
directCatalogEntry field that moves without moving the rendered description. No
new authorization hole -- requiredPermission is derived from annotations, whose
residual already covers the behavior -- but the proof as written was invalid, and
an invalid proof is worse than none when it is the thing licensing three declared
residuals.

The walk is now a two-part table. Source fields carry the visibility verdict:
identity and description are visible by construction; paramsJSON is not reliably
visible (never rendered in full mode, and a semantically-equal edit renders the
identical Sig in deferred mode); outputSchemaJSON and annotations are never
rendered at all. Derived fields are shown to add no independent axis: hash covers
server, tool, description and both schemas but not annotations
(hash.ToolHashWithOutputSchema), and requiredPermission is a pure function of
annotations. Three independent source classes, which is exactly what the skew
tests drive.

Round 10 also confirmed the single-publisher pin is safe at construction time
(DiscoverTools snapshots the manager under a read lock and skips disconnected
clients) and judged the design converged, with no decision worth cutting.

Related #971
…n precise (round-11 findings)

Round 11 found two precision defects in the round-10 proof. Both are about the
proof, not the behavior -- the three residuals and their bounds are unchanged --
but a partition that licenses three declared narrowings has to be exactly right.

The walk said renderedDescription is "a function of exactly two things",
description and the signature. It is not: full mode renders
fmt.Sprintf("[%s] %s", serverName, description) and deferred appends toolName
plus the Sig, so serverName, toolName, the serialization mode and the cache-hit
state are all inputs. Spelled out verbatim now, which also makes clear why the
origin flip is description-visible and why a mode flip is.

The walk's scope was also left implicit -- it covered directCatalogEntry while
the review criterion was the whole catalog. The catalog-level fields are now
accounted for explicitly: entries/byDisplayName/byCanonical are membership,
already covered by the add/remove/origin-flip/collision cases and by rules 2 and
4; serializationMode is visible (a flip adds or removes the whole suffix, which is
what FR-014 rebuilds on); generation is never rendered.

Second: the derived-field table said each "moves iff" its source moves. Only one
direction is needed and only one is true. requiredPermission reads solely
destructiveHint and readOnlyHint, so a title or idempotent edit moves annotations
without moving the tier; and the hash canonicalizes schemas, so a representational
schema edit moves neither hash nor cached signature. Restated as "cannot move
unless a source moves", with the converse explicitly disclaimed -- and the second
case turned to use: it is what makes the input-schema-only skew case constructible
in a test, so the test bullet now pins a canonicalization-equal edit.

Related #971
…ipe (round-12 finding)

Round 11's tightening introduced a test that cannot exist. It told the
input-schema skew case to use a "canonicalization-equal edit so the hash and
cached signature genuinely do not move", while the same bullet requires dispatch
to reject the stale-schema call and one retry to succeed. Those cannot both hold:
hash parses and re-marshals the schema before hashing, so a canonicalization-equal
edit is the same schema, the validator has nothing to reject, and the self-healing
assertion is vacuous. This one changes what an engineer builds, not just how the
paragraph reads.

The recipe is now normative and matches the mechanism: the edit must be
semantically different but signature-identical -- confined to nested properties
the 085 grammar collapses to a ~ marker -- AND the new hash must be warmed into
the signature cache before the rebuild renders, or Peek misses, the suffix
vanishes, and the change becomes visible after all. The hash row in R13's derived
table now says the same thing from the other direction: a representational edit is
not a schema change, a semantic one always moves the hash, and that is precisely
why the warm step is part of the case.

Related #971
Five defects, each verified against the code or a running core rather than read
off the plan.

- **The FR-010 built-ins gate would not measure what it claims.** It asserts over
  p.directServer.ListTools(), described as "what the server actually serves".
  ListTools() is mcp-go's registration map (server/server.go:1032);
  handleListTools serves filteredTools(ctx) (:1767), which applies every
  WithToolFilter - and directServer is the one routing-mode server that carries
  filters (filterDirectModeToolsForAuth, filterDirectToolsForAgentCallability,
  added to directOpts and to no other server, mcp_routing.go:615-618). Left as
  written the gate reproduces the D15/R14 mistake one level up: green while an
  over-broad filter empties the real listing. Now: assert the registry AND drive
  a real tools/list through the direct server, with any divergence a failure.
- **The same gate could not be byte-exact.** ListTools() returns a map and Go
  randomizes map iteration, so a golden serialized straight from it is flaky.
  Sort by tool name before serializing.
- **The frozen-gate list was missing its tightest member.**
  TestDescribeTool_DefinitionTokenBudget (mcp_describe_tool_test.go:382) holds
  describe_tool's definition to 250 tokens and it currently measures ~243. FR-009
  exists to name both id forms in the description and in tool_ids - precisely the
  edit that spends single-digit headroom. Added as gate 5 with its handling.
- **The quickstart's verification command cannot run.** Its bare tools/list POST
  to /mcp/all answers "Invalid session ID" (reproduced against a live core):
  /mcp/all is Streamable HTTP and needs initialize, the Mcp-Session-Id header and
  notifications/initialized first, and its replies are SSE frames that must have
  the "data: " prefix stripped before jq. Replaced with the working three-step
  form.
- **spec.md overstated what the direct listing retains.** It said a non-agent
  session's listing keeps tools that are "pending, changed, quarantined or
  disabled". Server-level quarantine and disable never reach the projection at
  all - DiscoverTools skips those clients ("Skipping quarantined client for tool
  discovery", internal/upstream/manager.go), confirmed live on a quarantined
  server. Only tool-level states are retained.

CLAUDE.md's Recent Changes line said "Added Go 1.24 module toolchain"; go.mod
says go 1.25.5.
83 tasks across 8 phases, organized by user story so US1+US2 (both P1) form the
shippable increment and US3/US4 land independently after it.

Phase 0 is blocking and is not busywork. plan.md's Complexity Tracking records
three narrowings of normative spec MUSTs - FR-017's atomicity delivered as a
safety property rather than a transaction, a schema-only change describable one
generation stale, and an annotations-only change listed one generation stale -
each ending "needs the maintainer's assent at the tasks stage". That stage is
now, so T001-T003 make the assent an explicit gate and require the outcome to be
written back into spec.md rather than left in the plan's appendix. T004 folds the
D1/D2/D3 resolutions back into spec.md, which still carries [NEEDS CLARIFICATION]
markers for questions the plan treats as decided.

Phase 2 (the directCatalog) is the other hard gate: US1 renders from it, US2
resolves through it, US3 validates against it, US4 rebuilds it. D13 rule 1 is
encoded structurally - the builder returns the catalog, the publisher swaps it
after SetTools, and T017 fails if a swap happens inside the builder.

Two plan corrections while writing the tasks:

- The describe_tool prose rewrite is FIVE retrieve_tools-specific strings, not
  four. The plan said "four" while enumerating five (tool description :64,
  tool_ids :71, filters :82, describeNotFoundRemediation :50, and the inline
  malformed-id remediation :195). Verified against mcp_describe_tool.go; the
  count now matches the enumeration in all three places it appears.
- research.md is D1-D16 / R1-R14, not D1-D8 / R1-R10, and tasks.md is no longer
  "NOT created by this plan".

Related #971
Cross-model review (opencode/gpt-5.6) of tasks.md against plan.md. Three P1s,
all of them ordering defects that would have surfaced as a blocked agent rather
than a failing test.

**Phase 2 depended on Phase 4 — through its own prerequisite.** T024 asserts a
freshly initialized proxy already lists describe_tool, but the registration sat
in Phase 4 (T037), so the foundational phase could not go green until the phase
built on top of it had landed. The registration is a one-line append with no
resolver behind it, so it moves to Phase 2 as T019b; the describe handler work
stays in Phase 4.

**No task changed makeDirectModeHandler's signature.** T020 updated call sites
for a change nothing performed, and Phase 5's validation task consumed a captured
catalog entry that nothing had captured. Added T019a. The closure capture is what
makes R9's "a dispatch can never validate against a definition other than the one
its own registration advertised" true, so it belongs in the foundational phase.

**Phase 6 silently needed Phase 5.** T070's input-schema residual asserts the
stale-schema case self-heals on one retry and T072 asserts no call succeeds
against the wrong schema — both are pre-dispatch-validation behaviour, while the
dependency section claimed US4 needed only the Phase 2 rebuild path.

Also:

- Phase 0 no longer blocks everything. The three approvals concern publication
  skew, stale schemas and stale annotations; none of them affects the config axis
  or toolsig.Peek. Only T004 gates Phase 1; T001-T003 gate their named dependents.
- T014 bundled "neither is describable" into a Phase 2 collision test, where no
  resolver exists yet. Split: catalog assertions stay, describe lands as T046a.
- T058 wrote a failing output_schema test AFTER T047 implemented it - a test that
  cannot fail first does not satisfy the constitution's test-first gate. Split to
  T046b, before its implementation.
- T063/T064 split validation from its activity emission. Landing the first alone
  would reject calls that appear nowhere in the availability funnel - exactly the
  blind spot issue #969 established this handler must not have. Now one task.
- Phase 3 claims a >=70% reduction in its independent test and had no task
  measuring it; the gate sat in Polish, outside the MVP that depends on it. Added
  T035a, and the MVP now names it.
- [P] means "different file" by this document's own definition, and was on four
  groups that share one test file each (T028-T030, T042-T058, T059-T062,
  T067/T069). Removed there; the batching advice stays, since batchable and
  parallel are not the same thing.

88 tasks, up from 83.
…MUST

T001/T002/T003, decided by the maintainer.

FR-017's third bullet claimed the advertised entry and its handler are "rebuilt
atomically, so no window exposes one without the other". That was not
deliverable: the entry lives in mcp-go's registry and the catalog in ours, and
mcp-go reads its own tool map under its own lock before our filters run, so the
two publications cannot be one transaction without forking it. The bullet now
states what IS delivered — no request observes a state less restrictive than both
generations, and no request gets a definition for a name the registry is not
serving — and keeps literal the half that is literal: a handler validates against
the definition its own registration captured, because it closes over it.

The other two narrowings are accepted in the same amendment: a schema-only change
may be described one generation stale (T002), and an annotations-only change may
be listed one generation stale (T003).

Each is accepted because of a compensating mechanism this feature ships, and the
amendment says which: the input-schema case self-heals through the pre-dispatch
validator (one retry succeeds); the annotations case cannot mis-authorize,
because call-time authorization re-derives the tier from the handler's own
captured annotations and never from the catalog; the output-schema case has no
self-healing path and is accepted on its merits, since output schemas are
advisory metadata MCP permits to be absent.

Moved from the plan's appendix into the requirement text. A narrowing recorded
only in an implementation note is one a reader discovers after trusting the MUST.
@Dumbris
Dumbris enabled auto-merge (squash) August 27, 2026 05:44
@Dumbris

Dumbris commented Aug 28, 2026

Copy link
Copy Markdown
Member Author

Superseded by #1063, which is now merged into main.

This PR's branch (102-schema-deferred-plan) was an ancestor of feat/102-schema-deferred-impl, so every spec artifact here — spec.md, plan.md, tasks.md, research.md, data-model.md, contracts/ — landed with the implementation. Verified against origin/main after the merge; the branch is now strictly behind.

It is being closed rather than merged for two reasons: it had become conflicting with main, and #1063 was squash-merged, so GitHub cannot detect the inclusion automatically and would have left this open indefinitely.

Nothing is lost. Closing as superseded.

@Dumbris Dumbris closed this Aug 28, 2026
auto-merge was automatically disabled August 28, 2026 19:24

Pull request was closed

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