**`query` 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.
**The 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.
**Three 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.
**Results 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.
**Every 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.
**One 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.
**`kind` 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.
The 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.
**The 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.**
**`select` 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.
**It 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.
**Seven 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.
**`scope:` 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.
**`has:` 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.
**`depth: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.
**The 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.
**An 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.
**The 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.
The 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`](../../design/map-query-language.xml) — the
lore this contract is the short form of.