Fixes #211

An AI agent (Claude Opus 5) wrote this change. Split of verified (commands run, output observed) vs assumed (untested) is at the bottom.

The defect, reproduced at HEAD

The issue reports that internal docs list features that do not exist and omit ones that do. All four claims check out against the source at origin/main:

Rather than reproduce by eye, the drift was reproduced as a test. Wrapping the existing stale lists in the new markers and running the new guard at HEAD prints exactly the issue's two directions:

engine/README.md section `agg-types` has drifted from the source of truth.
  implemented but undocumented: ["adjacency_matrix", …, "bucket_script", …]   (62 names)
engine/README.md section `rejected-query-types` has drifted from the source of truth.
  implemented but undocumented: ["has_child", "has_parent"]

Root cause, and why the fix is not "edit the prose"

"What XERJ supports" was written in prose in six places and derived from the code in none. Every list was a literal someone had to remember to bump, and nothing failed when they forgot. Correcting the text alone re-creates the defect on the next commit — which is exactly how the current text got there.

So the lists are now derived, and the derivation is enforced:

• xerj_query::parser::SUPPORTED_QUERY_TYPES (50) and REJECTED_QUERY_TYPES (2). A unit test reads parse_query's dispatch arms out of the file's own source (include_str!, bounded by the match head and its catch-all arm) and fails if the constants and the arms differ in either direction. A second test proves the labels behaviourally in both directions: no supported name may answer unknown query type or refuse with a not supported message, and every rejected name must refuse with exactly that message. (The second half of the supported-side rule was missing until the fourth pass below — see the correction there.)
• xerj_engine::aggs::SUPPORTED_AGG_TYPES (62), pinned the same way.
• xerj_console_api::seed::BUILTIN_DASHBOARD_COUNT (14) — one place, pinned to seed_specs().
• engine/crates/xerj-engine/tests/docs_capability_lists.rs compares engine/README.md and landing/llms-full.txt against those constants, and the README crate map against the workspace members.

The checked regions are <!-- generated:… --> blocks that may hold only backticked type names plus plain-text family labels. A backticked qualifier (`knn (HNSW-served)`) is a hard failure, not a silently mis-parsed entry, and a missing marker fails loudly instead of skipping the file — the guard must not itself become an accepted-and-ignored input (#204).

Prose corrected against the source

• engine/README.md — 23 query types → 50, plus the 2 rejected ones and why. 15 aggregations → 62. The old table also called cardinality approximate, contradicting aggs.rs; run_cardinality collects a HashSet and returns distinct.len(), so exact is the correct word. Crate map: 11 of 16 crates → all 16 (xerj-autoindex, the flagship feature, was one of the five missing).
• landing/llms-full.txt §6 — the same two lists, in the file AI agents actually read.
• ROADMAP.md — removes "26 publicly-documented query types", "~14 additional", "~49 dispatched / roughly 38 run", "15 aggregations plus ~15 more", and the note "(The README under-lists these — a docs gap, not a defect.)". Also removes a claim that is simply false at HEAD: nested does not "return 0 hits" — the inner query is evaluated per nested element in index.rs, and test_nested_query passes. What is genuinely missing is narrower and now stated as such: score_mode is parsed then ignored and inner_hits is not parsed at all, an accepted-and-ignored pair filed under Tracking: accepted-and-ignored is the dominant bug class, six instances found in one review #204. A stale parser.rs:330 citation is replaced by a name.
• aggs.rs module docs — a nine-row "supported aggregation types" table replaced by a pointer to the constant.
• xerj-console-api, demo/playbooks/CONSOLE_UX_REWORK.md — the 13/14 disagreements.

Honest scope

The lists are an acceptance claim, not a fidelity claim, and both docs now say so: a listed type parses, plans and executes; that is not a promise that every parameter matches Elasticsearch. Per-type gaps stay in ROADMAP.md; the ES-YAML suite remains the measured answer. weighted_avg is deliberately not in SUPPORTED_AGG_TYPES — it still returns a buried error instead of a 400, which is tracked, not fixed here.

Out of scope on purpose: the settings count (#207, has its own issue), and honouring-or-rejecting nested.score_mode / inner_hits (a behaviour change needing an owner decision).

engine/CLAUDE.md — the file the issue names — is gitignored and cannot appear in this diff. It was corrected in place on the working machine: the two stale lists now point at the constants, and four further drifts were removed (an example commit body carrying a Co-Authored-By: Claude trailer that the repo's own rule forbids; cargo build --release with no -p listed as an approved command; "tests NOT yet run against a live XERJ instance", true in April 2026; and a conformance-suite table whose file counts were wrong in every row — measured 200 files, not 182).

Gate

Run locally in this worktree:

• cargo fmt --all -- --check — clean
• cargo clippy -p xerj-query -p xerj-engine -p xerj-console-api --all-targets -- -D warnings — clean
• cargo test -p xerj-query — 173 + 9 passed, 0 failed
• cargo test -p xerj-console-api — passed, 0 failed
• cargo test -p xerj-engine — all binaries pass except two pre-existing, non-related conditions on a machine at load average 43: several painless wall-clock-budget tests flake under contention (all 66 pass with --test-threads=1), and painless_script_limits::call_depth_limit_survives_the_multi_thread_block_in_place_path overflows its stack in a debug build. That last one was re-run on a stashed tree at origin/main and fails identically there — it is not from this change.
• New tests: docs_capability_lists 6/6, parser::tests::dispatch_table_matches_capability_manifest, parser::tests::manifest_labels_match_observed_behaviour, aggs::capability_manifest_tests::dispatch_table_matches_capability_manifest, seed::tests::seeds_every_registry_dashboard.

No engine behaviour changes, so the ES-YAML conformance gate is untouched by construction — the only non-doc code added is pub const arrays and #[cfg(test)] code.

Verified vs assumed

Verified (ran the command, read the output): every test result above; the drift output quoted at the top; bucket_script executing; nested filtering; run_cardinality being exact; 50/2/62 counts extracted from the constants; the crate-map guard failing when a row is deleted; the stack-overflow reproducing at origin/main.

Assumed (not run): that the ES-YAML conformance suite is unaffected — argued from the diff containing no runtime code path, not measured. That CI's runner does not hit the debug-build stack overflow, since main is currently green with that test present.

Reference-coding: attempted xc.py xerj-search "registry that enumerates all supported query types or aggregation types by name"; the retrieval server on :9200 was down at the time and the task forbids starting it. Skipping is defensible here anyway — the mandate exempts work confined to this repository's own code, and the only non-trivial addition scrapes this repo's dispatch tables. How tantivy or Elasticsearch registers its own query types is not evidence for how XERJ's docs should be pinned to XERJ's parser.

Second pass — the docs site had the same defect (commit 2)

A second agent re-derived the four claims independently before touching
anything, then audited what the first pass had not covered. The first
pass's own claims hold up:

What it missed is that "the docs" is bigger than this repository's markdown.

Query types the docs published that do not exist

landing/docs/queries.html shipped cards for boosted and
semantic_search. Neither string occurs anywhere under engine/crates
(grep -rn '"boosted"' engine/crates → nothing). The parser has boosting and
semantic; both published names would answer unknown query type.
semantic_search was also an entry in the docs-site search index, which is
duplicated verbatim into all 44 pages — so the site's own search box offered a
query type XERJ has never had. Fixed in all 44.

The page also listed 34 of 50 dispatched types and never mentioned the two that
are recognised-and-rejected, so has_child read as merely absent rather than
deliberately refused. It now carries all 50 plus a Recognised and rejected
section.

Aggregations: 15 of 62, pipeline family invisible

landing/docs/aggregations.html is the page an evaluator reads to answer "does
XERJ do pipeline aggregations?" — and the answer it gave was no, by omission.
It now lists all 62 under Metric / Bucket / Pipeline.

Two implementation claims the source contradicts

• cardinality — advertised "Exact · bitmap-backed". run_cardinality
  (aggs.rs:6450) collects a HashSet<String> of every distinct value. Exact,
  yes; bitmap-backed, no — and memory grows with cardinality, the opposite of
  what the phrase implies.
• percentiles — advertised "t-digest · bounded memory". run_percentiles
  (aggs.rs:7451) sorts all values into a Vec<f64> and interpolates. The
  source comment names t-digest as the ES option name, not the algorithm.
  Memory is O(N).

The page intro promised bounded memory on that basis; it is replaced by the
rule that is actually in fast_aggs.rs (FAST_AGG_MIN_DOCS = 10_000), and the
unmeasured "sub-second SIEM top-N over millions of events" phrasing goes with
it.

21 pages pointed at crates that do not exist

Every docs section ends with Source · engine/crates/…. Twenty-one named
pre-rename crates — logs, api, common, server, storage, cluster,
fts, compress — plus an otlp crate that never existed (OTLP ingest is
xerj-api/src/native.rs) and an api/src/middleware/auth.rs that is
xerj-api/src/auth.rs. Every replacement path was checked to exist on disk
before it was written.

Enforcement, so it cannot come back

• docs_capability_lists.rs gained an HTML extractor — one name per
  <div class="item"> card, card descriptions deliberately not scanned, so
  a name mentioned in prose cannot pass as a capability. Both pages joined the
  checked set and are compared for equality with the constants: a phantom
  name and a missing family each fail.
• A card whose text is not a bare type name panics instead of being absorbed,
  matching the markdown extractor's rule — the guard must not itself accept and
  ignore (Tracking: accepted-and-ignored is the dominant bug class, six instances found in one review #204).
• every_source_pointer_in_the_docs_site_resolves walks every page under
  landing/ and fails on any engine/crates/<path> not on disk.
• seeds_every_registry_dashboard now does what its name says. It compared two
  Rust values to each other; the registry is JavaScript, and that is the
  actual definition of a built-in dashboard. It now reads the all array out of
  xerj-ux/src/dashboards/registry.js, resolves each symbol to its module,
  takes that module's own id, and compares the id sets both ways — closing the
  cross-language half of the drift that produced three different counts.

Watched fail, then pass (each defect re-introduced on the fixed tree, test
run, output read, then reverted):

landing/docs/queries.html      documented but not implemented: ["boosted", "semantic_search"]
landing/docs/aggregations.html implemented but undocumented: [15 pipeline names]
docs site cites source paths that do not exist:
  landing/docs/analyzers.html → engine/crates/fts/src/analyzer.rs
seed_specs() has drifted from xerj-ux/src/dashboards/registry.js
  seeded but not in the registry: ["settings"]

Gate (second pass, re-run after rebase onto origin/main)

cargo fmt --all -- --check clean · cargo clippy -p xerj-console-api -p xerj-engine -p xerj-query --all-targets -- -D warnings clean ·
xerj-console-api 43/43 · xerj-query 173 + 9 · xerj-engine --lib 428/428 ·
docs_capability_lists 9/9. No runtime code changed in this commit — the edits
are HTML, one integration test, and a #[cfg(test)] module.

Still deliberately out of scope

The settings count (38 / 56 / 60) is #207's, and is untouched here to avoid
colliding with that issue's fix. nested.score_mode / inner_hits and the
type query (accepted, and degraded to match_all) are accepted-and-ignored
inputs that need an owner's call on honour-or-reject; they are described
honestly on the page rather than silently fixed.

Reference-coding: skipped, legitimately. The retrieval server on
localhost:9200 was down for this session (curl /_cluster/health → exit 7)
and the task forbids starting it — but the mandate also exempts work confined
to this repository, and this change is documentation plus a test that scrapes
this repo's own dispatch tables and HTML. How tantivy or Lucene documents its
own query registry is not evidence for what XERJ's pages should say.

Correction, and a third pass — the phantom was still on the site (commit 3)

The second commit's message overstates what it fixed, and this is the
correction. aa3ac3c0 says of semantic_search: "Neither string appears
anywhere in engine/crates … Both would answer unknown query type … Fixed in
all 44." It was fixed in the 44 embedded search-index blobs only. The two
places a human actually reads still shipped the phantom, on files this PR had
already edited:

Re-verified against a live instance — release binary, scratch data dir, ES
port, not the shared retrieval server:

{"query":{"semantic_search":{…}}}                        -> 400 unknown query type `semantic_search`
{"query":{"semantic":{"field":"embedding","text":"…"}}}  -> 400 `query` must be a non-empty string
{"query":{"semantic":{"field":"summary","query":"…","k":10}}} -> 200, correct doc first (_score 0.8247)

Fixed

1. vector-search.html semantic example — rewritten to
   {"query":{"semantic":{"field":…,"query":…,"k":10}}} (parse_semantic,
   parser.rs:2557, requires field + query; k defaults to 10), with the
   one-line semantic_text mapping that makes it runnable. Both snippets were
   executed verbatim against a live instance before being published.
2. vector-search.html hybrid example — a second broken body on the same
   page, not previously flagged. It was published at the top level of the
   search body (parse_request only reads query → 400 Unknown key for a START_OBJECT in [hybrid]) with bare clauses in queries (parse_hybrid
   requires each entry to wrap its clause in query → hybrid.queries[0] missing query). Corrected and re-run. The knn block above it is
   left alone: top-level knn really is handled (es_compat.rs:6991) and
   returns hits.
3. migration-from-es.html — semantic_search → semantic, the count
   corrected and pinned, the two recognised-and-rejected types explained, and
   the pipeline family named with a link to /docs/aggregations.html.
4. engine/README.md self-contradiction — "100% ES API compatible —
   drop-in replacement" and "all ES query types" sat 140 lines above this PR's
   own "Recognised and deliberately rejected with a 400 … Any other query type
   answers unknown query type", and are refuted by
   demo/playbooks/ES_COMPATIBILITY.md:65 (40 supported / 9 partial / 9
   unsupported of 58 ES catalog types). Replaced with "Broad ES 8.x wire
   compatibility", pointing at the measured coverage document.
5. "All xerj aggregations are exact" — a claim this PR itself added —
   run_sampler (aggs.rs:9640) sorts matched docs by _score and truncates
   to shard_size (default 200), so every sub-agg under sampler /
   random_sampler / diversified_sampler runs over a sample;
   random_sampler shares that impl and the string probability does not
   occur in aggs.rs. Narrowed to what is true — no probabilistic sketch in
   the metric path — with the sampling family named as the deliberate
   exception in engine/README.md, landing/llms-full.txt and
   landing/docs/aggregations.html. ROADMAP.md was missed on that pass
   and kept the strongest form of the claim on a line this PR adds; it is
   corrected in the fourth pass below.
6. Two more stale counts the guard could not see: landing/pricing
   (twice) and landing/demo both said "38 query types". The parser
   dispatches 50.

The guard now reads the whole published surface

The marked-region checks only saw three files that had opted in; the docs site
is 60+ pages of prose and samples. Three new checks read
landing/**/*.html, landing/llms*.txt, engine/README.md and ROADMAP.md:

• no_published_surface_names_a_phantom_query_type — a source-derived
  denylist of names the docs have published but the parser has never
  dispatched (boosted, semantic_search), matched on token boundaries so the
  real MCP tool xerj_semantic_search is not a hit. A companion test,
  the_phantom_list_only_holds_names_the_parser_really_lacks, fails the moment
  the parser grows one of those names — the denylist cannot outlive its reason.
• every_query_clause_in_a_published_sample_is_a_real_query_type —
  anything directly under "query": { … } must be in SUPPORTED ∪ REJECTED.
  That is the one position in an ES body where a key's meaning is unambiguous,
  so it needs no denylist. It asserts it is reading something — the guarded
  floor is checked > 20. (The figure "73 clauses across 11 distinct names"
  originally written here was measured at the third pass and is stale: the
  count at this head is 77, re-measured in the fifth pass by forcing the
  floor to fail and reading the number back. The test asserts the floor, not
  an exact count, which is why the drift was invisible — a published number
  pinned to nothing, the same defect this PR exists to remove, this time in
  the PR body rather than the docs.)
• published_capability_counts_match_the_constants — a published number
  drifts exactly like a published list (32 / 38 / 50 for the same quantity), so
  counts live in <!-- generated:query-type-count --> regions pinned to the
  constants' .len(). Every occurrence in a file listed in COUNT_DOCS
  is checked, not just the first — and COUNT_DOCS was three HTML pages on
  this pass, missing ROADMAP.md, which the fourth pass below adds.

Watched fail, then pass (each defect re-introduced on the fixed tree, test
run, output read, then reverted):

landing/docs/playbooks/vector-search.html:181 names `semantic_search`
landing/docs/playbooks/vector-search.html:180 uses `semantic_search` in query position
landing/docs/migration-from-es.html publishes 32 for `query-type-count`; the source has 50
landing/pricing/index.html:138 publishes 38 for `query-type-count`; the source has 50

The last line is the proof that the second marked count in a file is checked.

Gate (third pass)

cargo fmt --all -- --check clean · cargo clippy -p xerj-engine --all-targets -- -D warnings clean · docs_capability_lists 13/13 · xerj-engine --lib
428/428 · every other engine test binary passes.

Two conditions did not pass locally, and neither contains a line from this
change — the only Rust edited here is tests/docs_capability_lists.rs, and
both live in separate test binaries built from unmodified source:
painless_script_limits overflows its stack in a debug build (already recorded
on this PR as reproducing at origin/main), and
query_string_default_field::field_less_query_string_cross_product_respects_the_request_deadline
is a 150 ms wall-clock-budget test that ran past its 3 s allowance on a box at
load average 320 (32 cores). Both passed in CI's Build + Test on this
branch head before this commit; CI re-runs on the push.

Reference-coding

Retrieved this time — the server was up, where the previous pass recorded it
down. xc.py xerj-search "registerQuery SearchModule QueryBuilder named writeable registry query type names" returns
elasticsearch/server/src/main/java/org/elasticsearch/search/SearchModule.java
as the top hit: the analogous pattern, one registration site where the wire
name and the builder are declared together so the registry is the single source
of truth. APPROACH-ONLY (AGPL-3.0 / SSPL-1.0 / Elastic-2.0) — nothing
copied, and it confirms rather than changes the design already in this PR. An
earlier query for a capability manifest returned ESQL datasource plumbing;
irrelevant, and recorded as such rather than forced in.

Fourth pass — the three findings the merge gate left open (commit 4)

The merge gate re-measured this branch at d470eecf and kept three findings
open. All three were real. They are fixed here, each with the defect
re-introduced on the fixed tree first so the guard was watched failing.

1. ROADMAP.md published a false claim — one this PR itself added

ROADMAP.md:14 said, on a + line introduced by this PR:

All aggregations are exact (no HLL, no sampling).

That is false at HEAD, and the same PR's other files already said so:

Three of those sampling aggregations are inside the very count the sentence
covered, so the release would have shipped ROADMAP.md telling a reader that a
random_sampler job is exact while engine/README.md told them the same job
silently truncates to 200 documents. The sentence is replaced by an
Exactness, precisely paragraph that states what is true (no probabilistic
sketch in the metric path — cardinality is a true distinct count, terms
doc_count is precise) and then names both exceptions: the sampling family
with its shard_size default and its ignored probability, and hdr
percentiles.

hdr is the second exception and was missing everywhere, not just in
ROADMAP.md. engine/README.md and landing/llms-full.txt said the sampling
family was the deliberate exception; both now say there are two.
landing/docs/aggregations.html already described the hdr switch on the
percentiles card and needed no change.

2. ROADMAP.md's own counts were pinned to nothing

grep -c 'generated:' ROADMAP.md returned 0, and COUNT_DOCS listed three
HTML pages only. So this PR published 50 query types and 62 aggregation types in ROADMAP.md as hand-typed literals — recreating, inside its own fix,
the drift #211 exists to stop. Adding query type 51 would have left ROADMAP
saying 50 with every test green.

Fixed: ROADMAP.md joins COUNT_DOCS, and its three numbers now live in
<!-- generated:query-type-count -->, <!-- generated:rejected-query-type-count -->
and <!-- generated:agg-type-count --> regions. HTML comments are invisible in
rendered markdown, so the marker mechanism ports unchanged. The hand-copied
15-name pipeline list is deleted rather than marked — it was a second
unguarded copy — and replaced by a pointer to the machine-checked list. The
prose repeats of the numbers ("those 50 are the dispatch surface", "not among
the 62") are reworded so no unmarked literal remains. The floor on how many
marked counts must be found rises from 5 to 9, so a page dropping its markers
still fails.

Watched fail, then pass — 50 → 51 and 62 → 61 on the fixed tree:

ROADMAP.md:12 publishes 51 for `query-type-count`; the source has 50

3. manifest_labels_match_observed_behaviour could not see a mislabelled type

The gate reproduced this by measurement and it reproduced here identically.
Moving "has_child" from REJECTED_QUERY_TYPES into SUPPORTED_QUERY_TYPES
left both manifest tests green, because a recognised-and-refused type never
produces ParseError::UnknownQueryType — and the docs guard would then have
required has_child to be published as a supported capability. That is the
#211 defect, undetected by the test written to detect it.

Fixed at parser.rs:5679: the supported-side loop now also asserts the parse
error does not contain not supported — the phrase REJECTED_QUERY_TYPES is
required to carry is the phrase SUPPORTED_QUERY_TYPES is forbidden to carry.

Watched fail, then pass — has_child relabelled supported on the fixed
tree:

`has_child` is listed as supported but refuses with a not-supported message:
parse error: parent-child join queries (has_child/has_parent) are not supported; …
  A recognised-and-refused type belongs in REJECTED_QUERY_TYPES, or the docs
  will advertise a query that 400s.

Reverted, both tests pass again (2 passed; 0 failed).

Known gaps, stated plainly

These are not fixed, and no sentence in this PR should be read as claiming
otherwise:

• The count guard is opt-in. It checks every occurrence in every file
  listed in COUNT_DOCS — now four files — and nothing else. A new page that
  publishes "XERJ supports N query types" without a marker is unguarded, and no
  test will notice. There is no repo-wide scanner for numbers in capability
  sentences.
• Aggregation names outside a marked region are unguarded. Query types
  have a phantom denylist (no_published_surface_names_a_phantom_query_type)
  and a query-position check; aggregations have neither. The three exemplar
  names left in ROADMAP.md (bucket_script, derivative, moving_fn) are
  true today and checked by nobody.
• The labels test proves acceptance, not fidelity. It sends {"<type>": {}}
  and reads the error. A type that accepts that body and then does nothing
  useful still reads as supported — type is mapped to match_all and nested
  ignores score_mode/inner_hits, both documented under Partial in
  ROADMAP.md and both counted among the 50.
• weighted_avg still returns HTTP 200 with a buried error instead of a 400
  (tracked in ROADMAP.md), and the settings count (38/56/60) remains Public claims contradicted by the source: cargo-audit and fuzzing are documented but not in CI #207's.

Gate (fourth pass)

Run in this worktree, CARGO_TARGET_DIR=/home/claude/.cargo-shared-target/shard-2:

• cargo fmt --all -- --check — clean
• cargo clippy -p xerj-query -p xerj-engine --all-targets -- -D warnings — clean
• cargo test -p xerj-query — 173 + 9 passed, 0 failed
• cargo test -p xerj-engine --lib — 428 passed, 0 failed
• cargo test -p xerj-engine --test docs_capability_lists — 13 passed, 0 failed
• cargo test -p xerj-engine — 681 passed, 0 failed across every test binary,
  then aborts in painless_script_limits on
  call_depth_limit_survives_the_multi_thread_block_in_place_path, which
  overflows its stack in a debug build. Already recorded on this PR as
  reproducing on a stashed tree at origin/main; it contains no line from this
  change. The eight test binaries that sort after it were run individually and
  all pass (perf_benchmark, product_experience,
  query_string_default_field, rc4_w2_storage_hardening,
  search_bounded_under_ghosts, search_context_ttl,
  shard_router_write_path, tombstone_only_segment_search).

The ES-YAML conformance suite is not re-run for this pass and does not need to
be: the fourth commit touches ROADMAP.md, engine/README.md,
landing/llms-full.txt, one #[cfg(test)] block in parser.rs and one
integration-test file. No runtime code path is edited.

Reference-coding: skipped, and the reason is the same one the mandate names
as an exemption — every edit here is either this repository's own prose or a
test that scrapes this repository's own constants. How another engine documents
its query registry is not evidence for what XERJ's ROADMAP.md should say
about run_sampler's shard_size.

Fifth pass — re-measured the gate's three findings, and found the #204 bug class inside the guard itself (commit 5)

The gate's three findings, re-measured rather than re-read

The fourth pass claims all three are fixed. Each was re-verified here by
re-introducing the defect on the fixed tree and reading the failure, not by
trusting the commit message:

The replacement wording in ROADMAP.md was also checked against the source
rather than against the previous commit: aggs.rs:2934 dispatches sampler
and random_sampler to run_sampler; run_sampler sorts by _score and
.take(shard_size) with unwrap_or(200); grep -c probability aggs.rs is
0; the hdr branch (aggs.rs:7458-7520) really does replicate a
DoubleHistogram auto-ranging conversion, so "quantized" is the right word;
run_cardinality collects a HashSet and returns distinct.len(). The
nested rewrite checks out too — index.rs:29116 is
arr.iter().any(|elem| doc_matches_query(&inner, elem)), score_mode is
parsed at parser.rs:3139 and dropped by the QueryNode::Nested { path, query, .. }
destructure at index.rs:26757, and inner_hits does not occur in parser.rs
at all.

What that review turned up: the guard was swallowing unreadable pages

Five sites in tests/docs_capability_lists.rs discarded a read failure, so a
page that could not be read was scanned as an empty string — and an empty
string passes every check below it by finding nothing:

every_source_pointer_in_the_docs_site_resolves
  html_files:  let Ok(entries) = read_dir(dir) else { return };  +  entries.flatten()
  page body:   read_to_string(page).unwrap_or_default()
doc_surfaces  (feeds both site-wide checks)
  walk:        the same read_dir / flatten pair
no_published_surface_names_a_phantom_query_type
every_query_clause_in_a_published_sample_is_a_real_query_type
  file body:   read_to_string(&file).unwrap_or_default()

The failure mode is a confident wrong answer: "no phantom query type on this
page", for a page that was never read. The pages.len() > 20 and
files.len() > 20 floors do not cover the directory half either — one
subdirectory becoming unreadable drops its pages while sixty others keep the
total above the floor.

Both are hard failures now (read_dir_or_panic / read_surface_or_panic),
each naming the offending path. This matters beyond tidiness: this PR's own
prose claims twice that the guard "must not itself become an accepted-and-ignored
input (#204)", and until this commit that was true of the marker and card
extractors but not of the three site-wide walkers added in the second and third
passes.

Watched fail, then pass — a non-UTF-8 landing/docs/__gate_probe.html:

test every_query_clause_in_a_published_sample_is_a_real_query_type ... FAILED
test no_published_surface_names_a_phantom_query_type ... FAILED
test every_source_pointer_in_the_docs_site_resolves ... FAILED
cannot read published surface .../landing/docs/__gate_probe.html: stream did not
contain valid UTF-8 — an unreadable page must fail this test; treating it as
empty would silently pass every check

Removed, and docs_capability_lists is 13/13 again. The rest of the new test
code was scanned for the same pattern (let _ =, if let Ok(..) with no else,
.ok(), unwrap_or_default, flatten()) in seed.rs and parser.rs; there
are no other instances.

Known gaps, restated — nothing here is claimed to be fixed

Unchanged from the fourth pass, and still true:

• The count guard is opt-in. Only the four files in COUNT_DOCS are
  checked, and only markers whose section name is in COUNT_SECTIONS. A new
  page publishing "XERJ supports N query types" without a marker — or with a
  mistyped marker name — is unguarded, and no test will notice.
• Aggregation names outside a marked region are unguarded. Query types
  have a phantom denylist and a query-position check; aggregations have
  neither. The three exemplar names left in ROADMAP.md (bucket_script,
  derivative, moving_fn) are true today and checked by nobody.
• The labels test proves acceptance, not fidelity. type is mapped to
  match_all and nested ignores score_mode / inner_hits; both are
  counted among the 50 and both are documented under Partial in ROADMAP.md.
• weighted_avg still returns HTTP 200 with a buried error instead of a 400,
  and the settings count (38 / 56 / 60) remains Public claims contradicted by the source: cargo-audit and fuzzing are documented but not in CI #207's.
• ROADMAP.md:11's ES-YAML figure ("1,365 / 1,368") is not touched by this
  PR and was not re-measured here. It disagrees with the "1,360 / 1,363"
  figure further down the same file. Correcting it needs a conformance run and
  belongs to whoever owns that number; it is called out rather than quietly
  left.

Gate (fifth pass)

Run in this worktree, CARGO_TARGET_DIR=/home/claude/.cargo-shared-target/shard-2:

• cargo fmt --all -- --check — clean
• cargo clippy -p xerj-query -p xerj-engine -p xerj-console-api --all-targets -- -D warnings — clean
• cargo test -p xerj-query — 173 + 9 passed, 0 failed
• cargo test -p xerj-console-api — 108 passed, 0 failed
• cargo test -p xerj-engine --no-fail-fast — 710 passed, 0 failed across
  every test binary. --no-fail-fast is the change from the fourth pass: the
  eight binaries that sort after painless_script_limits were run as part of
  the same invocation rather than individually.
• cargo test -p xerj-engine --test docs_capability_lists — 13 passed, 0 failed

One condition still does not pass locally: painless_script_limits::… aborts
with fatal runtime error: stack overflow in a debug build. This pass stopped
asserting that from memory and measured it — git checkout origin/main -- engine/
in this worktree and re-running that one binary aborts identically, so it
is not from this branch. It also passes in CI's Build + Test on this branch
head.

The ES-YAML conformance suite was not re-run and does not need to be: the only
non-test change anywhere on this branch is three pub const arrays
(SUPPORTED_QUERY_TYPES, REJECTED_QUERY_TYPES, SUPPORTED_AGG_TYPES) plus
BUILTIN_DASHBOARD_COUNT; everything else is #[cfg(test)] code, one
integration-test file, doc comments, markdown and HTML. CI's own ES-compat YAML
conformance check is green on this branch.

Merge-forward check: the branch is 31 commits behind origin/main. A trial
git merge --no-commit origin/main in this worktree merges cleanly, and
docs_capability_lists (13/13) and both parser manifest tests stay green on
the merged tree — so main's drift has not invalidated any published list or
count. The merge was aborted; the branch is not rebased.

Reference-coding: skipped, under the mandate's own exemption — every edit
in this pass is either this repository's prose or a test that reads this
repository's own constants and pages. How another engine documents its query
registry is not evidence about read_to_string(..).unwrap_or_default() in
XERJ's guard.