PROP-015 — MCP server and agent integration

2.2.1 Searching the map — the set-returning twin of explain

16query finds nodes; explain looks at one. Until 2026-08-06 the map could only be asked about a target already known by name, so «which of these exist?» was unanswerable — not in the host, not in any language stack, not in the engine. query is that question, and the two are deliberately separate verbs rather than one verb with a mode: a point lookup and a set filter render differently, cap differently, and fail differently.

17The filter level is a permanent level, not a first version to be replaced (owner ruling, 2026-08-06). An agent accustomed to grep reaches for filters; a query language demands a form it will not build without need. So the filters must work on their own and must never become a degenerate case of a grammar — in the library they are their own entry point, so a broken parser could not take them down with it.

18Three filters, combined with AND, under a hard ceiling: exact spec address, substring of a code symbol, element kind. None is required; those given narrow. The ceiling is not a convenience and cannot be removed — the answer is read by an agent with a bounded context, and an unbounded one is useless rather than generous. When it truncates it says so, with the total, in both renderings.

19Results are nodes, never edges. «Find me an edge» is not a question anyone asks; «find me what has, or lacks, an edge of this kind» is — so edges are a filter dimension for the query level above, and the result set stays spec units and code items.

20Every hit records where it came from, because a second producer is already designed: the code-quality engine's findings join these results at query time, by the owner's ruling that two engines must not merge their data. Nothing of that engine is built here; the result shape simply does not close the door — a discriminated field rather than a closed variant set, so a third source adds a value instead of breaking every reader.

21One library, two thin surfaces, per the omnichannel floor: the filtering lives in the host's trace crate, vibe query renders it for a person and the query tool renders it for an agent, and both call the same function. The MCP tool's description says when to reach for it instead of explain — that description is the surface's own, which is exactly what the agent-facing class owns and all it owns.

22kind filters over a measured vocabulary. The committed map carries nine code kinds, and a spec unit answers on its own kind rather than borrowing the code one; the two vocabularies are disjoint, so one filter serves both without ambiguity. Caveat worth carrying: every spec unit in this tree is legacy-unmarked, so a spec kind matches nothing here today. The path is open and exercised only by fixtures — stated because a filter that silently returns nothing is indistinguishable from one that is broken.

23The map is built fresh in memory per call, never read from the committed artefact — the same posture explain takes, for the same reason: a query answers for the tree as it is.

24The query language is designed and not built. Its shape is the filters plus graph traversal — depth, and «has no edge of kind X», which is what answers «which rules does nothing verify» — and it introduces a grammar that will need versioning. It stands on this level rather than replacing it. SUPERSEDED 2026-08-06 — it is built; the contract is §2.2.2 below.

2.2.2 The query language — traversal on top of the filters

25select is a third verb, for the same reason query and explain are two. explain looks at one target, query filters a set, and select walks the graph from a set. Three questions, three caps, three failure modes — a mode flag on one verb would make the result type depend on the argument, and every consumer would carry three readers.

26It stands on the filter level and cannot take it down with it. The three filter predicates are the ones §2.2.1 ships, reached rather than redefined; the parser lives in its own module behind its own entry point, so a broken grammar leaves query answering. That separation is the owner's ruling in ##MAP-QUERY-THE-SIMPLE-LEVEL-IS-PERMANENT made structural instead of promised.

27Seven predicates, whitespace separated, joined by AND, and no operators at all: uri:, symbol:, kind: (the filter level's own), scope: (prefix of a spec address), has: / lacks: (an edge verb), depth: (0..3). No disjunction, no parentheses, no precedence — each of those is a permanent versioning liability, and a predicate can be added without renumbering a language that has no operator layer to renumber.

28scope: is in the set because the level's own canonical question is unanswerable without it. Measured before the build: 5 742 of 5 825 spec units carry no verifies edge, and nothing that shipped could narrow that — kind is carried by 0 units in this tree and uri is exact, so composing the negative predicate with the filter level yields 5 742 or 1. A document prefix brings 67 of the corpus's 72 documents inside the ceiling; the five that do not are named in the design record rather than left to be rediscovered.

29has: and lacks: select seeds, and «touches» reads from each family's own side — incoming for a spec unit, outgoing for a code item. On a directed bipartite graph that is the only reading under which one predicate serves both families, and applying them after the walk instead would answer a question nobody asked.

30depth:N expands the seed set along edges, undirected, and the seeds stay in the answer. depth:0 is the default and the identity, so a query without it is exactly the seed selection — which is what keeps this level a strict superset of the one below rather than a different thing wearing its name. Every hit carries the hop count it was reached at, so a caller can tell what it asked for from what the walk brought with it.

31The depth bound is 3, and the number came from the graph. Exhaustively over all 1 205 edge-bearing nodes, 71.7 % reach more at depth 2 than at depth 1 and only 5.9 % reach more at depth 3; the largest connected component is 44 nodes. So depth is a precision control on this map rather than a safety one — and the result ceiling stays hard regardless, because it protects against a future map, not this one.

32An unknown predicate, an unknown verb, a repeated predicate, an out-of-range depth or an empty query is an ERROR that names the offending token and lists what was expected — never a silently ignored clause. Same law as the markup's typed fences, for the same reason: a grammar that ignores what it does not understand promises everything and checks nothing, and whoever trusted the promise is the one who finds out. An empty query is refused rather than read as «everything», because that answer already exists one verb away.

33The grammar carries a version and reports it in every answer rather than demanding it in every query. A query string stays free of ceremony; the structured answer states the version it was parsed under, so a consumer that cares can branch and one that does not is unaffected. Requiring a prefix would tax every caller forever to buy nothing until the first breaking change.

34The rejected shapes, the measurements above with their commands, and the correction of a sampled reading that was wrong about depth are in vibevm/vibespecs/design/map-query-language.xml — the lore this contract is the short form of.