Rendered from docs/verifications/0004-the-ingest-stubs-of-the-query-fixture-tree-prove-what-governs-a-path.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

The ingest stubs of the query fixture tree prove what governs a path

Approach

The query fixture tree at engine/crates/query/fixtures/ is one small corpus. Its documents are under query/, and its code is the two stub files src/ingest/mod.rs and src/ingest/rate_limit.rs. The stubs hold no code. They exist because a code_path anchor binds only when its pattern matches at least one entry on the tree.

Two documents govern the stubs, and the overlap is the case that HW-AC-0005 needs:

  • query/specs/ingest.md (SPEC-FIX-ingest) governs the pattern src/ingest/**.
  • query/decisions/edge-throttling.md (DR-FIX-0031) governs the list [src/ingest/rate_limit.rs, src/ingest/mod.rs].

So each stub matches two anchors, and the directory src/ingest matches the pattern only. src/nothing.rs is not on the tree, and no anchor matches it.

Two tests read this design:

  • the_fixture_tree_answers_the_recorded_reads in engine/crates/query/tests/reads.rs asks governing_docs_for_path about src/ingest/rate_limit.rs, src/ingest/mod.rs, src/ingest and src/nothing.rs. It records each answer in engine/crates/query/fixtures/query.reads, and it compares the report byte for byte.
  • the_related_and_governing_tools_read_every_spelling_of_a_path_as_explain_does in engine/crates/query/tests/mcp.rs asks the MCP tool about src/ingest/mod.rs in three more spellings, and about two paths outside the root.

The recorded report is what makes a missing governor visible. A change that dropped a list member from the answer moves the bytes of query.reads, and the test then fails.

What this does not cover

This document governs the two stubs only. The documents under query/ and the other files of the fixture tree serve many other reads in the same two test files, so this document is not their design.

The tests do not cover a governor reached through a symlink, or a path that a .. segment takes outside the root and back in. headwater explain on a code path gives the same governors from the command line, and this design does not test that route.

Comments in both test files cite HW-VER-0004, and either one binds the cited_in edge onto its file.