Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

fix(api): fields/docvalue_fields pierce an explicit _source includes filter (#932)

xerj-orgbf652dee840b
diff --git a/engine/crates/xerj-api/src/es_compat.rs b/engine/crates/xerj-api/src/es_compat.rs
index 712da8dc3..9b5fa2d03 100644
--- a/engine/crates/xerj-api/src/es_compat.rs
+++ b/engine/crates/xerj-api/src/es_compat.rs
@@ -6091,6 +6091,60 @@ fn value_bearing_field_names(body: &EsSearchBody, fields: &[String]) -> Vec<Stri
names
}
+/// #932: would an explicit `_source` includes/excludes projection DROP a name
+/// the request pulls a value out of (`fields` / `docvalue_fields`)?
+///
+/// Answered by running the production projection (`xerj_engine::filter_object`)
+/// over probe documents instead of re-deriving its wildcard/dotted semantics —
+/// whatever the projection does to a document that carries ONLY the named
+/// field is what it would do to the real one. Both spellings the fields
+/// builder resolves (`get_source_value_by_path`: the whole dotted path as a
+/// literal key, then the nested walk) are probed, and a name counts as covered
+/// only when BOTH survive — a parent include (`_source: ["a"]`) keeps the
+/// nested `{"a": {"b": …}}` spelling but not a literal `a.b` key, so "either"
+/// would still let a stored flat key be silently dropped. A name that itself
+/// carries a wildcard can select fields the includes list never names, so it
+/// always counts as dropped — the safe direction: piercing re-applies the
+/// caller's filter at emission, so an unnecessary pierce costs only the
+/// `_savings` note, while a missed one is the silent 200 of #932.
+fn source_filter_drops_a_name(
+ includes: &[String],
+ excludes: &[String],
+ value_bearing_names: &[String],
+) -> bool {
+ const PROBE: &str = "__xy_source_cover_probe__";
+ let survives = |doc: &Value, name: &str| -> bool {
+ let filtered = xerj_engine::filter_object(doc, includes, excludes);
+ // Literal spelling: the whole dotted name as one top-level key.
+ if filtered.get(name).and_then(Value::as_str) == Some(PROBE) {
+ return true;
+ }
+ // Nested spelling: walk the name's segments.
+ let mut cur = &filtered;
+ for seg in name.split('.') {
+ match cur.get(seg) {
+ Some(v) => cur = v,
+ None => return false,
+ }
+ }
+ cur.as_str() == Some(PROBE)
+ };
+ value_bearing_names.iter().any(|name| {
+ if name.contains('*') {
+ return true;
+ }
+ let mut flat = serde_json::Map::new();
+ flat.insert(name.clone(), Value::String(PROBE.to_string()));
+ let mut nested = Value::String(PROBE.to_string());
+ for seg in name.rsplit('.') {
+ let mut m = serde_json::Map::new();
+ m.insert(seg.to_string(), nested);
+ nested = Value::Object(m);
+ }
+ !(survives(&Value::Object(flat), name) && survives(&nested, name))
+ })
+}
+
/// Build a `SearchRequest` from the ES body, forwarding all relevant options.
fn build_search_request(
body: &EsSearchBody,
@@ -11211,11 +11265,10 @@ async fn search_impl(
// teaching the engine to treat `Default` as `Enabled(true)` would put
// companions back into every internal `SearchRequest::default()`.
let default_source_projection = body.source.is_none();
- let value_bearing_names = if default_source_projection {
- value_bearing_field_names(&body, &search_req.fields)
- } else {
- Vec::new()
- };
+ // Computed for BOTH projections (#932): for the default projection these
+ // names drive the companion pierce below; for an explicit narrowing
+ // filter they drive the explicit-filter pierce further down.
+ let value_bearing_names = value_bearing_field_names(&body, &search_req.fields);
// One schema read-lock per participating index, and only for a request that
// could actually consume the answer: a pierce (a companion named in
// `fields`/`docvalue_fields`) OR a collapse `inner_hits` block, whose members
@@ -11242,6 +11295,50 @@ async fn search_impl(
if pierce_default_source {
search_req.source = xerj_query::ast::SourceFilter::Enabled(true);
}
+
+ // ── #932: an EXPLICIT `_source` filter has the same blind spot ──
+ //
+ // A narrowing filter — `_source: ["title"]`, the object spelling, and
+ // the URL spellings (`?_source=`, `?_source_includes=`, all promoted
+ // into body.source above) — is applied by the ENGINE
+ // (`apply_source_filter`), which narrows `hit.source` before the
+ // response layer runs. `fields` and `docvalue_fields` resolve out of
+ // that same narrowed source, so `{"_source": ["title"], "fields":
+ // ["body"]}` legally omitted `fields.body`: a 200, no warning, nothing.
+ // The #310 pierce above cannot fire here — it is keyed on
+ // `default_source_projection`.
+ //
+ // Same fix, second path: when the caller's own includes/excludes drop a
+ // value-bearing name, ask the engine for the intact source
+ // (`Enabled(true)` — the shape `"_source": false` already uses for
+ // exactly this resolution) and re-apply the caller's filter at every
+ // `_source` emission site below. Unlike #310 this is not
+ // companion-gated: the field being dropped is the caller's own, text or
+ // keyword alike. A filter that already selects every named field does
+ // not pierce at all — its engine-side narrowing (and its `_savings`
+ // note) stays exactly as it was.
+ let pierce_explicit_source: Option<(Vec<String>, Vec<String>)> =
+ if !default_source_projection && !value_bearing_names.is_empty() {
+ match &search_req.source {
+ xerj_query::ast::SourceFilter::Includes(includes) => {
+ source_filter_drops_a_name(includes, &[], &value_bearing_names)
+ .then(|| (includes.clone(), Vec::new()))
+ }
+ xerj_query::ast::SourceFilter::Fields { includes, excludes } => {
+ source_filter_drops_a_name(includes, excludes, &value_bearing_names)
+ .then(|| (includes.clone(), excludes.clone()))
+ }
+ // `Enabled(true)` narrows nothing; `Enabled(false)` keeps the
+ // raw source on purpose (suppression is a response-time
+ // decision); `Default` never carries an explicit filter.
+ _ => None,
+ }
+ } else {
+ None
+ };
+ if pierce_explicit_source.is_some() {
+ search_req.source = xerj_query::ast::SourceFilter::Enabled(true);
+ }
let search_req = search_req;
// Execute search on each index and merge results.
@@ -12144,6 +12241,35 @@ async fn search_impl(
}
}
}
+ // #932 emission site 3: the same obligation for the caller's EXPLICIT
+ // filter — continuation pages are rendered by `scroll_page_response`,
+ // which carries no `fields` clause, so the snapshot must be re-narrowed
+ // before the context is stored. The collapse sentinels are preserved
+ // across the filtering exactly as the engine's own Includes/Fields
+ // branches do (take → filter → reattach, #651), so a scroll+collapse
+ // context keeps rendering inner_hits on pages 2..n.
+ if let Some((includes, excludes)) = &pierce_explicit_source {
+ for (_, h) in snap.iter_mut() {
+ let sentinels: Vec<(&str, Value)> =
+ ["__xy_collapse_group__", "__xy_collapse_spec__"]
+ .into_iter()
+ .filter_map(|k| {
+ h.source
+ .as_object()
+ .and_then(|o| o.get(k))
+ .map(|v| (k, v.clone()))
+ })
+ .collect();
+ h.source = xerj_engine::filter_object(&h.source, includes, excludes);
+ if !sentinels.is_empty() {
+ if let Some(obj) = h.source.as_object_mut() {
+ for (k, v) in sentinels {
+ obj.insert(k.to_string(), v);
+ }
+ }
+ }
+ }
+ }
Some(snap)
} else {
None
@@ -12364,6 +12490,19 @@ async fn search_impl(
obj.retain(|name, _| !companions.contains(name));
}
}
+ // #932 emission site 1: this request pierced the caller's
+ // own EXPLICIT `_source` filter so the `fields` builder below
+ // could resolve a name the filter drops. The pierce ends HERE
+ // — `fields` reads `h.source`, which is untouched, while the
+ // wire `_source` carries exactly what the engine-side filter
+ // would have produced (same `filter_object`, same input). The
+ // engine's Includes/Fields branches re-attach the collapse
+ // sentinels around their filtering; that dance is unnecessary
+ // here — the sentinels were already extracted above and
+ // stripped from `s`.
+ if let Some((includes, excludes)) = &pierce_explicit_source {
+ s = xerj_engine::filter_object(&s, includes, excludes);
+ }
// Non-synthetic mode: strip the internal copy-to
// tracking marker; keep the copied values in the source
// since stored-source clients expect them.
diff --git a/engine/crates/xerj-api/tests/fields_pierce_explicit_source_includes.rs b/engine/crates/xerj-api/tests/fields_pierce_explicit_source_includes.rs
new file mode 100644
index 000000000..5ce283f61
--- /dev/null
+++ b/engine/crates/xerj-api/tests/fields_pierce_explicit_source_includes.rs
@@ -0,0 +1,470 @@
+//! Issue #932 — a `fields` clause must resolve against the intact stored
+//! source even when an explicit `_source` includes list does not contain the
+//! requested field, and the wire `_source` must stay narrowed to that list.
+//!
+//! The engine applies an explicit `_source` includes/excludes projection to
+//! `hit.source` BEFORE the response layer runs, and `fields` /
+//! `docvalue_fields` resolve their values out of that same narrowed source —
+//! so `{"_source": ["title"], "fields": ["body"]}` legally omitted
+//! `fields.body`: HTTP 200, no warning, nothing. The identical clause works
+//! with no `_source` filter and with `_source: false` (which deliberately
+//! keeps the raw source for exactly this resolution). Elasticsearch treats
+//! the two clauses as independent: `fields` reads the stored `_source`,
+//! source filtering only selects "what fields of the source are returned".
+//!
+//! The fix is the #310 approach applied to the explicit-filter path: ask the
+//! engine for the intact source when the caller's own includes/excludes drop
+//! a value-bearing name, then re-apply the caller's filter at every `_source`
+//! emission site. Every assertion below is therefore paired — the POSITIVE
+//! half (the value comes back) is the fix; the NEGATIVE half (`_source`
+//! carries exactly the caller's projection, never the pierced field) is what
+//! keeps the pierce honest.
+
+use axum::body::Body;
+use axum::http::{Request, StatusCode};
+use serde_json::{json, Value};
+use tower::ServiceExt;
+use xerj_common::types::{FieldConfig, FieldType, Schema};
+
+/// Long bodies on purpose: the `_savings` note has a print floor (a saving
+/// smaller than [`SAVINGS_REPORT_FLOOR_RATIO`] times the block costs is not
+/// printed), and the last test uses the note's PRESENCE as its oracle for
+/// "this request did not pierce".
+const DOCS: [(&str, &str, &str, i64); 4] = [
+ (
+ "1",
+ "Trial results one",
+ "vitamin d supplementation improved bone density in the treatment group, \
+ with sustained gains observed across every follow-up visit and no \
+ attrition in the cohort assigned to the active arm of the study",
+ 11,
+ ),
+ (
+ "2",
+ "Trial results two",
+ "the placebo group showed no change over the study period, matching the \
+ pre-registered expectation for the control arm and confirming that the \
+ measured effect in the treated cohort is attributable to the invention",
+ 7,
+ ),
+ (
+ "3",
+ "Trial results three",
+ "secondary endpoints favoured the treatment group on every measure that \
+ the protocol designated as exploratory, and the direction of effect was \
+ consistent with the primary endpoint throughout the observation window",
+ 5,
+ ),
+ (
+ "4",
+ "Trial results four",
+ "no serious adverse events were recorded in either arm during the entire \
+ study, and the safety monitoring board recommended continuation without \
+ modification at each of its scheduled interim reviews",
+ 2,
+ ),
+];
+
+/// The seeded `body` value: the base sentence repeated, so the bytes an
+/// includes list omits clear the savings print floor.
+fn full_body(base: &str) -> String {
+ format!("{base} {base} {base}")
+}
+
+async fn seeded_app() -> (axum::Router, tempfile::TempDir) {
+ let dir = tempfile::tempdir().expect("tempdir");
+ let mut config = xerj_common::config::Config::default();
+ config.server.data_dir = dir.path().to_string_lossy().into_owned();
+ config.storage.wal_sync = xerj_common::config::WalSync::Async;
+ let metrics = xerj_common::metrics::Metrics::new().expect("metrics");
+ let engine = xerj_engine::Engine::new(config.clone()).expect("engine");
+ let state = xerj_api::state::AppState::new(config, engine, metrics);
+
+ let mut schema = Schema::empty();
+ schema
+ .add_field(FieldConfig::new("title", FieldType::Text))
+ .expect("title field");
+ schema
+ .add_field(FieldConfig::new("body", FieldType::Text))
+ .expect("body field");
+ schema
+ .add_field(FieldConfig::new("cat", FieldType::Keyword))
+ .expect("cat field");
+ schema
+ .add_field(FieldConfig::new("n", FieldType::Long))
+ .expect("n field");
+ state.engine.create_index("docs", schema).expect("create");
+ let idx = state.engine.get_index("docs").expect("get index");
+ for (id, title, body, n) in DOCS {
+ idx.index_document(
+ Some(id.into()),
+ json!({
+ "title": title,
+ "body": full_body(body),
+ "cat": format!("cat-{id}"),
+ "n": n
+ }),
+ )
+ .await
+ .expect("index document");
+ }
+ idx.refresh().await.expect("refresh");
+
+ (xerj_api::router::build_es_compat_router(state), dir)
+}
+
+async fn post(app: &axum::Router, path: &str, body: Value) -> (StatusCode, Value) {
+ let response = app
+ .clone()
+ .oneshot(
+ Request::post(path)
+ .header("content-type", "application/json")
+ .body(Body::from(body.to_string()))
+ .expect("request"),
+ )
+ .await
+ .expect("response");
+ let status = response.status();
+ let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
+ .await
+ .expect("body");
+ let value: Value = serde_json::from_slice(&bytes).unwrap_or(Value::Null);
+ (status, value)
+}
+
+fn hits(response: &Value) -> &Vec<Value> {
+ response["hits"]["hits"]
+ .as_array()
+ .unwrap_or_else(|| panic!("no hits.hits array: {response}"))
+}
+
+/// The issue's repro table, row by row. Rows 1-3 already worked on main and
+/// must keep working; rows 4-5 are the bug (`fields` silently dropped for a
+/// text AND a keyword field the includes list omits).
+#[tokio::test]
+async fn fields_survives_every_source_includes_combination() {
+ let (app, _dir) = seeded_app().await;
+
+ // Row 1: no `_source` filter — `fields.body` returned.
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({ "query": { "match_all": {} }, "size": 4, "fields": ["body"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["body"],
+ json!([full_body(DOCS[i].2)]),
+ "row 1 (no _source): fields.body: {hit}"
+ );
+ }
+
+ // Row 2: `_source: false` — same clause, still returned.
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({ "query": { "match_all": {} }, "size": 4, "_source": false, "fields": ["body"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["body"],
+ json!([full_body(DOCS[i].2)]),
+ "row 2 (_source false): fields.body: {hit}"
+ );
+ assert!(
+ hit.get("_source").is_none(),
+ "row 2: _source suppressed: {hit}"
+ );
+ }
+
+ // Row 3: includes list CONTAINS the requested field — works, and must
+ // keep working (a covered name does not pierce).
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({ "query": { "match_all": {} }, "size": 4, "_source": ["title"], "fields": ["title"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["title"],
+ json!([DOCS[i].1]),
+ "row 3 (covered name): fields.title: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "row 3: _source stays narrowed to the includes list: {hit}"
+ );
+ }
+
+ // Row 4: `_source: ["title"]`, `fields: ["body"]` — the bug. `fields.body`
+ // must come back AND `_source` must carry exactly the caller's projection.
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({ "query": { "match_all": {} }, "size": 4, "_source": ["title"], "fields": ["body"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["body"],
+ json!([full_body(DOCS[i].2)]),
+ "row 4 (#932): fields.body must pierce the explicit includes: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "row 4 (#932): _source must stay narrowed to title: {hit}"
+ );
+ }
+
+ // Row 5: same for a keyword field — not specific to text.
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({ "query": { "match_all": {} }, "size": 4, "_source": ["title"], "fields": ["cat"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["cat"],
+ json!([format!("cat-{}", DOCS[i].0)]),
+ "row 5 (#932): fields.cat (keyword) must pierce too: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "row 5 (#932): _source must stay narrowed to title: {hit}"
+ );
+ }
+}
+
+/// The object spelling and both URL spellings of the same request.
+#[tokio::test]
+async fn every_spelling_of_the_request_pierces() {
+ let (app, _dir) = seeded_app().await;
+
+ // `_source: {"includes": ["title"]}`.
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({
+ "query": { "match_all": {} }, "size": 4,
+ "_source": { "includes": ["title"] }, "fields": ["body"]
+ }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["body"],
+ json!([full_body(DOCS[i].2)]),
+ "object spelling: fields.body: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "object spelling: _source narrowed: {hit}"
+ );
+ }
+
+ // `?_source_includes=title` with a body `fields` clause.
+ let (status, resp) = post(
+ &app,
+ "/docs/_search?_source_includes=title",
+ json!({ "query": { "match_all": {} }, "size": 4, "fields": ["body"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["body"],
+ json!([full_body(DOCS[i].2)]),
+ "URL _source_includes spelling: fields.body: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "URL _source_includes spelling: _source narrowed: {hit}"
+ );
+ }
+
+ // `?_source=title` + `?fields=body`, both via URL.
+ let (status, resp) = post(
+ &app,
+ "/docs/_search?_source=title&fields=body",
+ json!({ "query": { "match_all": {} }, "size": 4 }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["body"],
+ json!([full_body(DOCS[i].2)]),
+ "URL _source= spelling: fields.body: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "URL _source= spelling: _source narrowed: {hit}"
+ );
+ }
+}
+
+/// `docvalue_fields` resolves out of the same narrowed source — the identical
+/// silent drop for a non-text field.
+#[tokio::test]
+async fn docvalue_fields_pierce_the_includes_list() {
+ let (app, _dir) = seeded_app().await;
+
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({
+ "query": { "match_all": {} }, "size": 4,
+ "_source": ["title"], "docvalue_fields": ["n"]
+ }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["n"],
+ json!([DOCS[i].3]),
+ "#932: docvalue_fields.n must pierce the includes: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "#932: _source must stay narrowed to title: {hit}"
+ );
+ }
+}
+
+/// An excludes-only filter (`_source: {"excludes": ["title"]}`) drops every
+/// OTHER field from nothing — `fields: ["title"]` names exactly the excluded
+/// field, the sharpest form of the bug.
+#[tokio::test]
+async fn an_excluded_field_name_still_resolves_through_fields() {
+ let (app, _dir) = seeded_app().await;
+
+ let (status, resp) = post(
+ &app,
+ "/docs/_search",
+ json!({
+ "query": { "match_all": {} }, "size": 4,
+ "_source": { "excludes": ["title"] }, "fields": ["title"]
+ }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{resp}");
+ for (i, hit) in hits(&resp).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["title"],
+ json!([DOCS[i].1]),
+ "#932: fields.title names the excluded field and must resolve: {hit}"
+ );
+ let src = hit["_source"].as_object().expect("_source object");
+ assert!(!src.contains_key("title"), "excludes still applies: {hit}");
+ assert!(src.contains_key("body"), "unexcluded fields stay: {hit}");
+ }
+}
+
+/// #932 emission site 3: a scroll opened by a piercing request must NOT leak
+/// the pierced field on the CONTINUATION pages — the scroll snapshot is
+/// re-narrowed before the context is stored.
+#[tokio::test]
+async fn scroll_continuation_stays_narrowed_after_a_pierce() {
+ let (app, _dir) = seeded_app().await;
+
+ let (status, page1) = post(
+ &app,
+ "/docs/_search?scroll=5m",
+ json!({
+ "query": { "match_all": {} }, "size": 2,
+ "_source": ["title"], "fields": ["body"]
+ }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{page1}");
+ for (i, hit) in hits(&page1).iter().enumerate() {
+ assert_eq!(
+ hit["fields"]["body"],
+ json!([full_body(DOCS[i].2)]),
+ "page 1 resolves fields.body through the pierce: {hit}"
+ );
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i].1 }),
+ "page 1 _source stays narrowed: {hit}"
+ );
+ }
+ let sid = page1["_scroll_id"].as_str().expect("scroll id").to_string();
+
+ let (status, page2) = post(
+ &app,
+ "/_search/scroll",
+ json!({ "scroll": "5m", "scroll_id": sid }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{page2}");
+ for (i, hit) in hits(&page2).iter().enumerate() {
+ assert_eq!(
+ hit["_source"],
+ json!({ "title": DOCS[i + 2].1 }),
+ "#932 site 3: continuation pages must not leak the pierced body: {hit}"
+ );
+ }
+}
+
+/// The pierce is an instrumentation trade, not a free fix: `Enabled(true)` is
+/// not a measured shape in the engine, so a PIERCED request loses its
+/// `_savings` note (the same trade #310's default-projection pierce makes) —
+/// while a filter that already covers every named field must NOT pierce, and
+/// so keeps the note it has always had. That asymmetry is the proof that the
+/// coverage check keeps unaffected requests on the un-pierced path.
+#[tokio::test]
+async fn a_covered_name_keeps_the_savings_note_a_pierced_one_trades_it() {
+ let (app, _dir) = seeded_app().await;
+
+ // Covered (`title` is in the includes list): no pierce, `_savings` intact.
+ let (status, covered) = post(
+ &app,
+ "/docs/_search",
+ json!({ "query": { "match_all": {} }, "size": 4, "_source": ["title"], "fields": ["title"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{covered}");
+ assert!(
+ covered["_savings"].is_object(),
+ "a covered name does not pierce; the default savings note stays: {covered}"
+ );
+
+ // Pierced (`body` is dropped by the includes list): the note is the cost.
+ let (status, pierced) = post(
+ &app,
+ "/docs/_search",
+ json!({ "query": { "match_all": {} }, "size": 4, "_source": ["title"], "fields": ["body"] }),
+ )
+ .await;
+ assert_eq!(status, StatusCode::OK, "{pierced}");
+ assert!(
+ pierced.get("_savings").is_none(),
+ "a pierced request asks the engine for the intact source — nothing was \
+ withheld, and no note may claim otherwise: {pierced}"
+ );
+ // …and the value the caller asked for is there.
+ assert_eq!(
+ pierced["hits"]["hits"][0]["fields"]["body"],
+ json!([full_body(DOCS[0].2)]),
+ "{pierced}"
+ );
+}