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.

182 KB
Raw Blame
//! Bulk operation handler.
//!
//! Parses ES-compatible NDJSON bulk format and executes operations against
//! the engine with per-item error isolation.
//!
//! Performance: index/create operations are batched per-index and submitted
//! via `index_batch_turbo()` for maximum throughput (50K+ docs/sec).

use std::collections::HashMap;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::engine::Engine;
use crate::index::IndexResponse;
use crate::{EngineError, Result};

#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum SemanticLifecyclePoint {
    Grouped,
    Parsed,
    Prepared,
    EmbeddingInside,
    EmbeddingItemInside,
    BeforePublication,
    PublicationInside,
    AfterPublication,
}

#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum SemanticLifecycleFault {
    None,
    Embedding,
    Publication,
}

#[cfg(test)]
pub(crate) type SemanticLifecycleHook = std::sync::Arc<
    dyn Fn(&str, SemanticLifecyclePoint) -> SemanticLifecycleFault + Send + Sync + 'static,
>;

#[cfg(test)]
tokio::task_local! {
    static SEMANTIC_LIFECYCLE_HOOK: (String, SemanticLifecycleHook);
    static DISABLED_SEMANTIC_COUNTERS: std::sync::Arc<DisabledSemanticCounters>;
}

#[cfg(test)]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
struct DisabledSemanticInstrumentation {
    schema_reads: usize,
    guard_vectors: usize,
    sizing_walks: usize,
}

#[cfg(test)]
#[derive(Default)]
struct DisabledSemanticCounters {
    schema_reads: std::sync::atomic::AtomicUsize,
    guard_vectors: std::sync::atomic::AtomicUsize,
    sizing_walks: std::sync::atomic::AtomicUsize,
}

#[cfg(test)]
impl DisabledSemanticCounters {
    fn snapshot(&self) -> DisabledSemanticInstrumentation {
        use std::sync::atomic::Ordering;
        DisabledSemanticInstrumentation {
            schema_reads: self.schema_reads.load(Ordering::Relaxed),
            guard_vectors: self.guard_vectors.load(Ordering::Relaxed),
            sizing_walks: self.sizing_walks.load(Ordering::Relaxed),
        }
    }
}

#[cfg(test)]
fn count_disabled_semantic_access(
    select: fn(&DisabledSemanticCounters) -> &std::sync::atomic::AtomicUsize,
) {
    use std::sync::atomic::Ordering;
    let _ = DISABLED_SEMANTIC_COUNTERS.try_with(|counters| {
        select(counters).fetch_add(1, Ordering::Relaxed);
    });
}

#[cfg(test)]
pub(crate) fn semantic_lifecycle_hook(
    target: &str,
    point: SemanticLifecyclePoint,
) -> SemanticLifecycleFault {
    SEMANTIC_LIFECYCLE_HOOK
        .try_with(|(hook_target, hook)| {
            if hook_target == "*" || hook_target == target {
                hook(target, point)
            } else {
                SemanticLifecycleFault::None
            }
        })
        .unwrap_or(SemanticLifecycleFault::None)
}

#[cfg(test)]
pub(crate) async fn with_semantic_lifecycle_hook<F: std::future::Future>(
    target: impl Into<String>,
    hook: SemanticLifecycleHook,
    future: F,
) -> F::Output {
    SEMANTIC_LIFECYCLE_HOOK
        .scope((target.into(), hook), future)
        .await
}

#[cfg(test)]
fn semantic_lifecycle_hook_installed(target: &str) -> bool {
    SEMANTIC_LIFECYCLE_HOOK
        .try_with(|(hook_target, _)| hook_target == "*" || hook_target == target)
        .unwrap_or(false)
}

#[cfg(not(test))]
fn semantic_lifecycle_hook_installed(_target: &str) -> bool {
    false
}

#[cfg(test)]
thread_local! {
    /// Test-only count of explicit-id batch publications (#2427).
    static EXPLICIT_ID_BATCHES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}

/// Publish semantically prepared sources as one batch (#2427). A failed
/// preparation fails only its own item; an empty id gets a generated one.
async fn publish_prepared_batch(
    idx: &crate::index::Index,
    index_name: &str,
    prepared: Vec<(usize, String, Result<Value>)>,
    items: &mut [Option<BulkItemResult>],
) -> bool {
    let mut errors = false;
    let mut docs = Vec::with_capacity(prepared.len());
    for (item_idx, id, prepared) in prepared {
        let failure = match prepared {
            Ok(source) => {
                let id = if id.is_empty() {
                    uuid::Uuid::new_v4().to_string()
                } else {
                    id
                };
                match serde_json::to_vec(&source) {
                    Ok(bytes) => {
                        docs.push((item_idx, id, std::sync::Arc::<[u8]>::from(bytes)));
                        continue;
                    }
                    Err(e) => (id, 500, e.to_string()),
                }
            }
            Err(e) => (id, engine_error_http_status(&e), e.to_string()),
        };
        let (id, status, error) = failure;
        items[item_idx] = Some(BulkItemResult {
            action: "index".into(),
            index: index_name.to_string(),
            id,
            status,
            result: None,
            error: Some(error),
            get_source: None,
        });
        errors = true;
    }
    errors | publish_explicit_id_batch(idx, index_name, docs, items).await
}

/// Publish `index` actions that carry an `_id` as one batch and fill their
/// item slots in request order. Returns whether any item failed (#2427).
async fn publish_explicit_id_batch(
    idx: &crate::index::Index,
    index_name: &str,
    docs: Vec<(usize, String, std::sync::Arc<[u8]>)>,
    items: &mut [Option<BulkItemResult>],
) -> bool {
    if docs.is_empty() {
        return false;
    }
    #[cfg(test)]
    EXPLICIT_ID_BATCHES.with(|count| count.set(count.get() + 1));
    let mut errors = false;
    let mut slots = Vec::with_capacity(docs.len());
    let batch = docs
        .into_iter()
        .map(|(item_idx, id, bytes)| {
            slots.push((item_idx, id.clone()));
            (id, bytes)
        })
        .collect();
    match idx.index_batch_explicit_ids_raw(batch).await {
        Ok(results) => {
            for ((item_idx, id), result) in slots.into_iter().zip(results) {
                items[item_idx] = Some(match result {
                    Ok(resp) => BulkItemResult {
                        action: "index".into(),
                        index: index_name.to_string(),
                        id: resp.id,
                        // 201 for a new doc, 200 for an overwrite (ES).
                        status: if resp.result == "updated" { 200 } else { 201 },
                        result: Some(resp.result),
                        error: None,
                        get_source: None,
                    },
                    Err(e) => {
                        errors = true;
                        BulkItemResult {
                            action: "index".into(),
                            index: index_name.to_string(),
                            id,
                            status: engine_error_http_status(&e),
                            result: None,
                            error: Some(e.to_string()),
                            get_source: None,
                        }
                    }
                });
            }
        }
        Err(e) => {
            // Whole-batch failure (write block, breaker, back-pressure):
            // every item gets the same status, as on the auto-id batch.
            let status = engine_error_http_status(&e);
            for (item_idx, id) in slots {
                items[item_idx] = Some(BulkItemResult {
                    action: "index".into(),
                    index: index_name.to_string(),
                    id,
                    status,
                    result: None,
                    error: Some(e.to_string()),
                    get_source: None,
                });
            }
            errors = true;
        }
    }
    errors
}

// ── Types ─────────────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BulkResult {
    pub took_ms: u64,
    pub errors: bool,
    pub items: Vec<BulkItemResult>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct BulkItemResult {
    pub action: String,
    pub index: String,
    pub id: String,
    pub status: u16,
    pub result: Option<String>,
    pub error: Option<String>,
    /// Post-execution source to echo under `items[N].<action>.get` in
    /// the HTTP response. Populated only when the action metadata
    /// carried `_source: true` / `_source: {...}` and the action
    /// succeeded. None for all other cases.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub get_source: Option<Value>,
}

fn malformed_document_reason(
    document_id: Option<&str>,
    item_index: usize,
    error: &serde_json::Error,
) -> String {
    let document_id = document_id.unwrap_or("<auto-generated>");
    format!(
        "invalid document JSON for document ID {document_id:?} at bulk item position {}: \
         parser error: {error}; parser location: line {}, column {}. \
         Fix: replace this source line with exactly one complete UTF-8 JSON object. \
         Related help: xerj index --help and https://xerj.org/llms.txt",
        item_index + 1,
        error.line(),
        error.column(),
    )
}

/// Per-item 400 reason for a document carrying an unpaired UTF-16 surrogate.
/// Mirrors the shape of [`malformed_document_reason`] so the HTTP response
/// reads the same way, and names the fix the issue reporter already adopted.
fn lone_surrogate_document_reason(
    document_id: Option<&str>,
    item_index: usize,
    detail: &str,
) -> String {
    let document_id = document_id.unwrap_or("<auto-generated>");
    format!(
        "invalid document JSON for document ID {document_id:?} at bulk item position {}: \
         parser error: {detail}; a JSON string escape (\\uXXXX) encoded an unpaired UTF-16 \
         surrogate — half of an astral code point (e.g. an emoji cut in two by a fixed-width \
         chunker). Fix: replace the unpaired surrogate with U+FFFD, or re-encode the field as \
         valid UTF-8, before indexing. \
         Related help: xerj index --help and https://xerj.org/llms.txt",
        item_index + 1,
    )
}

/// Scan a structurally-valid JSON document for an unpaired UTF-16 surrogate in
/// a `\uXXXX` string escape, returning a short reason when one is found.
///
/// Why this exists: the `index` turbo path validates each source line with
/// `serde_json::IgnoredAny`, which walks the JSON *without decoding* string
/// contents, so it ACCEPTS an escape such as `"a\ud83db"`. The auto-id docs
/// are then grouped and parsed as one batch into `serde_json::Value`s
/// (`index_batch_turbo_raw` → `parse_validated_raw_batch`), and that parse
/// DOES decode escapes and rejects the unpaired surrogate — but it fails the
/// whole batch with a single error, so one bad chunk sank all 127 of its
/// neighbours (issue #1304). ES reports such a document per-item and indexes
/// the rest; this check restores that contract by catching the one gap
/// between `IgnoredAny` acceptance and `Value` rejection here, per-item,
/// before the document can enter a batch.
///
/// It runs only after `IgnoredAny` has already accepted the bytes, so every
/// string is terminated and every `\u` is followed by four hex digits; the
/// scan therefore only has to check surrogate *pairing*. Equivalence with
/// serde_json's own accept/reject decision is pinned by a unit test. Unpaired
/// surrogates are the sole semantic string check `Value` makes that
/// `IgnoredAny` skips (nesting depth is already capped identically upstream
/// in `validate_raw_json_nesting`), so this closes the gap completely.
fn lone_surrogate_escape_reason(bytes: &[u8]) -> Option<&'static str> {
    // Decode four ASCII hex digits at `i` into a u16. The structural pass
    // guarantees they are present and valid; `None` here would mean that
    // invariant broke, in which case we defer to the downstream parser.
    fn hex4(bytes: &[u8], i: usize) -> Option<u16> {
        let mut value: u16 = 0;
        for offset in 0..4 {
            let digit = *bytes.get(i + offset)?;
            let nibble = match digit {
                b'0'..=b'9' => digit - b'0',
                b'a'..=b'f' => digit - b'a' + 10,
                b'A'..=b'F' => digit - b'A' + 10,
                _ => return None,
            };
            value = (value << 4) | nibble as u16;
        }
        Some(value)
    }

    // Fast path: a `\uXXXX` escape requires a backslash, so a document with
    // no backslash at all cannot carry an unpaired surrogate. `contains` is a
    // single memchr pass, which keeps the common ingest doc (no escapes) off
    // the byte-by-byte state machine below and preserves the turbo win.
    if !bytes.contains(&b'\\') {
        return None;
    }

    let mut i = 0;
    let mut in_string = false;
    while i < bytes.len() {
        let byte = bytes[i];
        if !in_string {
            if byte == b'"' {
                in_string = true;
            }
            i += 1;
            continue;
        }
        match byte {
            b'"' => {
                in_string = false;
                i += 1;
            }
            b'\\' => {
                // The byte after a backslash is the escape kind. An escaped
                // backslash (`\\`) consumes both bytes here, so a following
                // `u` is a literal `u`, never the start of a `\u` escape.
                match bytes.get(i + 1).copied() {
                    Some(b'u') => {
                        // `None` can only mean the structural invariant broke;
                        // fall through to the downstream parser via `?`.
                        let code_unit = hex4(bytes, i + 2)?;
                        if (0xDC00..=0xDFFF).contains(&code_unit) {
                            // A low surrogate with no preceding high surrogate.
                            return Some("lone trailing surrogate in hex escape");
                        }
                        if (0xD800..=0xDBFF).contains(&code_unit) {
                            // A high surrogate must be followed immediately by
                            // a `\u` escape encoding a low surrogate.
                            let paired = bytes.get(i + 6) == Some(&b'\\')
                                && bytes.get(i + 7) == Some(&b'u')
                                && hex4(bytes, i + 8)
                                    .is_some_and(|low| (0xDC00..=0xDFFF).contains(&low));
                            if !paired {
                                return Some("lone leading surrogate in hex escape");
                            }
                            // Consume the whole valid pair: `\uXXXX\uYYYY`.
                            i += 12;
                            continue;
                        }
                        // A well-formed non-surrogate `\uXXXX` escape.
                        i += 6;
                    }
                    Some(_) => i += 2, // `\"`, `\\`, `\n`, `\t`, …
                    None => i += 1,
                }
            }
            _ => i += 1,
        }
    }
    None
}

/// The one place a bulk item's per-item `status` is derived from an engine
/// error. Every `Err` arm in this module routes through here.
///
/// It defers to `XerjError::http_status()` (409 version conflict, 404 not
/// found, 403 index blocked, 400 bad mapping/query, 429 exhausted …) and only
/// overrides one case: the disk flood-stage block reports itself as
/// `read_only_allow_delete`, which ES answers **429**, not the 403 the other
/// blocks get (`IndexMetadata.INDEX_READ_ONLY_ALLOW_DELETE_BLOCK` carries
/// `RestStatus.TOO_MANY_REQUESTS`; approach only, no ES code reproduced).
///
/// Three call sites used to inline their own `match` instead, and each listed
/// only the errors its author had in mind — so a genuine write block fell
/// through `_ => 500` and a blocked bulk looked like a server fault.
fn engine_error_http_status(error: &EngineError) -> u16 {
    match error {
        EngineError::Common(xerj_common::XerjError::IndexBlocked { block_type, .. })
            if block_type.contains("read_only_allow_delete") =>
        {
            429
        }
        EngineError::Common(error) => error.http_status(),
        _ => 500,
    }
}

// ── Bulk processor ────────────────────────────────────────────────────────────

/// A parsed bulk action before execution.
struct ParsedAction {
    action_type: String,
    target_index: String,
    doc_id: Option<String>,
    doc_body: Option<Value>,
    /// Original NDJSON bytes for the doc line — forwarded verbatim to
    /// the WAL so we never re-serialize the parsed `Value`.  Empty for
    /// delete actions.
    doc_bytes: std::sync::Arc<[u8]>,
    /// Original position in the output items vec.
    item_index: usize,
    /// `require_alias` flag: Some(true)  → require target to be an alias;
    ///                      Some(false) → explicitly opt out of URL default;
    ///                      None        → inherit URL-level default.
    require_alias: Option<bool>,
    /// Per-item ingest pipeline name (if set via action metadata).
    pipeline: Option<String>,
    /// Optimistic concurrency: expected `_seq_no` / `_primary_term`
    /// from the action metadata. When set, the engine routes via
    /// `index_document_with_version` so a mismatch produces a 409
    /// `version_conflict_engine_exception` per-item error.
    if_seq_no: Option<u64>,
    if_primary_term: Option<u64>,
    /// Per-item `_routing` from action metadata — stored on the doc
    /// as `_routing` so `exists: _routing` and `fields: [_routing]`
    /// resolve.
    routing: Option<String>,
    /// Per-item `dynamic_templates` spec from the action metadata.
    /// ES bulk allows callers to request a specific dynamic template
    /// per field: `{"index":{"dynamic_templates":{"foo":"tmpl_name"}}}`.
    /// Validation against the index's declared `dynamic_templates`
    /// happens in execute_bulk_action — unknown template names
    /// produce a per-item 400 `document_parsing_exception`.
    dynamic_templates: Option<std::collections::BTreeMap<String, String>>,
    /// Per-item `_source` from action metadata (update-only). When
    /// set, the response echoes the post-update source under
    /// `items[N].update.get._source` (ES `?_source=true` shorthand
    /// on bulk updates).
    source_req: Option<Value>,
}

/// Process a bulk NDJSON body.
///
/// `default_index` is used when the action line does not specify `_index`.
///
/// All `index` and `create` operations are batched per-index and submitted
/// via `index_batch_turbo()` for 10–20x higher throughput than one-at-a-time.
/// `update` and `delete` operations are still executed individually.
pub async fn process_bulk(engine: &Engine, default_index: Option<&str>, body: &str) -> BulkResult {
    process_bulk_with_opts(engine, default_index, body, BulkOpts::default()).await
}

fn release_raw_owner(
    owners: &mut std::collections::HashMap<usize, (usize, crate::ingest_memory::Retained<'static>)>,
    source: std::sync::Arc<[u8]>,
) {
    let owner = std::sync::Arc::as_ptr(&source) as *const () as usize;
    // The logical owner must outlive every Arc clone. Dropping the ledger
    // token first would publish a false zero while this clone still retains
    // the backing allocation.
    drop(source);
    release_raw_owner_by_id(owners, owner);
}

fn release_raw_owner_by_id(
    owners: &mut std::collections::HashMap<usize, (usize, crate::ingest_memory::Retained<'static>)>,
    owner: usize,
) {
    if let Some((remaining, _)) = owners.get_mut(&owner) {
        *remaining -= 1;
        if *remaining == 0 {
            owners.remove(&owner);
        }
    }
}

#[derive(Clone, Default)]
pub struct BulkOpts {
    pub require_alias: Option<bool>,
    /// URL-level default `_source` / `_source_includes` / `_source_excludes`
    /// shape (see search body filter). Applied to every update action
    /// that doesn't provide its own `_source` in the action meta.
    pub default_source_req: Option<Value>,
    /// URL-level `?pipeline=` — the ingest pipeline for every `index` /
    /// `create` action that does not name one in its own action metadata.
    /// `_none` disables the target index's `index.default_pipeline`.
    ///
    /// Issue #204: this used to be dropped on the floor, so
    /// `POST /_bulk?pipeline=redact` answered `201` per item and stored the
    /// UNREDACTED document, while the single-document form of the same write
    /// ran the pipeline. Same for `index.default_pipeline`, which `_bulk` never
    /// consulted at all.
    pub default_pipeline: Option<String>,
}

/// The action named by the first key of a bulk action line, without parsing
/// the line. Anything unrecognised reads as `index`, the renderer's default.
fn action_line_kind(line: &str) -> &'static str {
    let rest = line.trim_start_matches([' ', '\t']);
    let Some(rest) = rest.strip_prefix('{') else {
        return "index";
    };
    let rest = rest.trim_start_matches([' ', '\t']);
    let Some(rest) = rest.strip_prefix('"') else {
        return "index";
    };
    match rest.split('"').next() {
        Some("create") => "create",
        Some("update") => "update",
        Some("delete") => "delete",
        _ => "index",
    }
}

/// One refusal item per paired action, in body order (#2427). Used when the
/// whole request is refused before its parse: a single summary item would
/// not match the body's action count, and the autoindex client (like any
/// client re-offering 429 items by position) could not map it back.
fn refuse_every_action(
    pairs: &[(usize, &str, Option<&str>, usize)],
    default_index: Option<&str>,
    error: &EngineError,
) -> Vec<BulkItemResult> {
    let status = engine_error_http_status(error);
    let reason = error.to_string();
    pairs
        .iter()
        .map(|(_, action_line, _, _)| BulkItemResult {
            action: action_line_kind(action_line).to_string(),
            index: default_index.unwrap_or("").to_string(),
            id: String::new(),
            status,
            result: None,
            error: Some(reason.clone()),
            get_source: None,
        })
        .collect()
}

pub async fn process_bulk_with_opts(
    engine: &Engine,
    default_index: Option<&str>,
    body: &str,
    opts: BulkOpts,
) -> BulkResult {
    use rayon::prelude::*;

    let started = std::time::Instant::now();

    // ── F8: bulk DoS protections ──────────────────────────────────────────
    //
    // 1. Acquire a global bulk-concurrency permit. Caps the number of
    //    concurrent `_bulk` requests in the parse phase to
    //    `max_concurrent_bulks` (default 8), preventing N concurrent bulks
    //    from each materializing ~300 B/action of parse-phase heap before the
    //    memtable admission check fires.
    // 2. Enforce `max_actions_per_bulk` (default 50 000). An unbounded bulk
    //    body of one-byte lines produces ~50 M lines → ~25 M action pairs ×
    //    ~300 B ≈ 7.5 GiB of heap per request. The cap rejects oversized
    //    bulks with a single 413-style error item before allocating the
    //    parse-phase Vecs.
    let _bulk_permit = match crate::governor::global() {
        Some(g) => match g.acquire_bulk().await {
            Ok(p) => Some(p),
            Err(e) => {
                return BulkResult {
                    took_ms: started.elapsed().as_millis() as u64,
                    errors: true,
                    items: vec![BulkItemResult {
                        action: "bulk".to_string(),
                        index: default_index.unwrap_or("").to_string(),
                        id: String::new(),
                        status: 503,
                        result: None,
                        error: Some(e.to_string()),
                        get_source: None,
                    }],
                };
            }
        },
        None => None,
    };

    let t_lines = std::time::Instant::now();
    let lines: Vec<&str> = body.lines().filter(|l| !l.trim().is_empty()).collect();
    let lines_ms = t_lines.elapsed().as_millis() as u64;

    // Pre-allocate output slots — filled in after execution.
    let mut items: Vec<Option<BulkItemResult>> = Vec::new();
    let mut errors = false;

    // F8: enforce `max_actions_per_bulk`. Each action is an action+doc line
    // pair (or a single delete line), so the action count is at most
    // `lines.len()`. Reject before building `pairs` / `parse_results` /
    // `parsed` (the ~300 B/action amplifiers).
    let max_actions = engine.config().limits.max_actions_per_bulk;
    if max_actions > 0 && lines.len() > max_actions * 2 {
        return BulkResult {
            took_ms: started.elapsed().as_millis() as u64,
            errors: true,
            items: vec![BulkItemResult {
                action: "bulk".to_string(),
                index: default_index.unwrap_or("").to_string(),
                id: String::new(),
                status: 413,
                result: None,
                error: Some(format!(
                    "bulk request contains {} lines (~{} actions); exceeds max_actions_per_bulk of {}",
                    lines.len(),
                    lines.len() / 2,
                    max_actions,
                )),
                get_source: None,
            }],
        };
    }

    // M5.3 — PARALLEL NDJSON PARSE.
    //
    // Pre-M5.3 the bulk parser walked lines serially, calling
    // `serde_json::from_str::<Value>` on every action + doc line.
    // For a 5 000-doc bulk = 10 000 parses × ~5 µs = ~50 ms of
    // single-threaded work per batch — the single largest CPU cost
    // in the bulk ingest path at single-client saturation.
    //
    // We pair action+doc lines into tuples (an action line is
    // always followed by a doc line for index/create/update; delete
    // has no doc line), then rayon-parallel-parse the tuples.  The
    // parse is a pure function so no cross-pair state is shared —
    // rayon shards the work across up to `num_cpus()` cores.
    //
    // The parse output is a `Vec<Result<ParsedAction, ErrItem>>`
    // that preserves the original order, so downstream code that
    // matches on item_index remains correct.

    // Step 1: pair action + doc lines so we can parse each pair in
    // parallel.  The delete action has no doc line, so we track the
    // optional body-line index.
    // A delete action has NO body line; index/create/update each have
    // exactly one.  The action type is the first key of the action object
    // (`{"delete":{...}}`), so we can identify a delete from its action
    // line alone — no full parse needed.  This loop USED to optimistically
    // consume the next line as the body for EVERY action and rely on a
    // "push it back" fixup that was never actually implemented (see the
    // delete branch below).  The result: a delete followed by another
    // action (e.g. two consecutive deletes) silently swallowed that next
    // action line — ~50% of consecutive deletes were lost.  Detect the
    // delete up front so its body line is never consumed.
    fn action_line_is_delete(line: &str) -> bool {
        let b = line.as_bytes();
        let mut p = 0usize;
        while p < b.len() && (b[p] == b' ' || b[p] == b'\t') {
            p += 1;
        }
        if p >= b.len() || b[p] != b'{' {
            return false;
        }
        p += 1;
        while p < b.len() && (b[p] == b' ' || b[p] == b'\t') {
            p += 1;
        }
        if p >= b.len() || b[p] != b'"' {
            return false;
        }
        p += 1;
        let start = p;
        while p < b.len() && b[p] != b'"' {
            p += 1;
        }
        p < b.len() && &b[start..p] == b"delete"
    }
    let mut pairs: Vec<(usize, &str, Option<&str>, usize)> = Vec::new();
    let mut i = 0;
    while i < lines.len() {
        let action_line = lines[i];
        let item_index = items.len();
        items.push(None);
        let (doc_line, advance) = if !action_line_is_delete(action_line) && i + 1 < lines.len() {
            (Some(lines[i + 1]), 2)
        } else {
            (None, 1)
        };
        pairs.push((i, action_line, doc_line, item_index));
        i += advance;
    }

    // #2427: memory admission for the whole request BEFORE the parse.
    // The write paths below check the breaker only after the parse has built
    // a document copy (and, for update/create, a parsed `Value`) per action,
    // so a bulk admitted on a stale sample, or while a latch was engaged,
    // allocated all of that first. `lines` and `pairs` borrow the body and
    // cost a few words per action. Refuse here with one 429 per action (the
    // client re-offers 429 items by position, so the count must match the
    // body), or count the body against live RSS until the parse ends.
    let parse_reservation = match crate::governor::global() {
        Some(g) => match g.admit_bulk_parse(body.len() as u64) {
            Ok(reservation) => Some(reservation),
            Err(e) => {
                // The refusal frees nothing by itself; ask for the drain on
                // this 429 like `Index::governor_write_gate` (#2321).
                crate::engine::request_memory_pressure_drain();
                return BulkResult {
                    took_ms: started.elapsed().as_millis() as u64,
                    errors: true,
                    items: refuse_every_action(&pairs, default_index, &EngineError::Common(e)),
                };
            }
        },
        None => None,
    };

    // Step 2: parallel parse.  Each tuple yields either a
    // `ParsedAction` or an `ErrItem`.  The order of the output
    // vector matches the input order so `item_index` still
    // addresses the right slot.
    enum ParseOutcome {
        Ok(ParsedAction),
        Err(BulkItemResult, usize),
    }

    let t_parse = std::time::Instant::now();
    // Dedicated ingest pool: keeps bulk-parse bursts off the global rayon
    // pool that the search path fans out on (see `crate::ingest_pool`).
    let parse_results: Vec<ParseOutcome> = crate::ingest_pool().install(|| {
        pairs
            .par_iter()
            .map(|(_line_idx, action_line, doc_line, item_index)| {
                // M5.12 — FAST-PATH manual parse of the action line.
                //
                // Pre-M5.12 the action line hit `serde_json::from_str::<Value>`
                // which allocates a Map<String,Value> for every one of 5000
                // action lines per batch = ~5 us × 5000 = 25 ms of pure
                // allocation per bulk batch.
                //
                // We handle the three common shapes inline and fall back to
                // full serde_json parse only on a cache miss:
                //   {"index":{}}
                //   {"index":{"_id":"..."}}
                //   {"index":{"_index":"..."}}
                //   {"index":{"_index":"...","_id":"..."}}
                //   (same for "create", "update", "delete")
                let bytes = action_line.as_bytes();
                // Any require_alias mention forces full parse (bool extraction is
                // not handled in the fast path); uncommon enough to not matter.
                let has_require_alias = bytes.windows(14).any(|w| w == b"require_alias\"");
                let has_pipeline = bytes.windows(9).any(|w| w == b"pipeline\"");
                let has_if_seq_no = bytes.windows(11).any(|w| w == b"\"if_seq_no\"");
                let has_routing = bytes.windows(9).any(|w| w == b"\"routing\"");
                let has_source = bytes.windows(9).any(|w| w == b"\"_source\"");
                let has_dynamic_templates =
                    bytes.windows(19).any(|w| w == b"\"dynamic_templates\"");
                let mut require_alias_per_item: Option<bool> = None;
                let mut pipeline_per_item: Option<String> = None;
                let mut if_seq_no_per_item: Option<u64> = None;
                let mut if_primary_term_per_item: Option<u64> = None;
                let mut routing_per_item: Option<String> = None;
                let mut source_req_per_item: Option<Value> = None;
                let mut dynamic_templates_per_item: Option<
                    std::collections::BTreeMap<String, String>,
                > = None;
                let (action_type, target_index, doc_id) = 'fast: {
                    if has_require_alias
                        || has_pipeline
                        || has_if_seq_no
                        || has_routing
                        || has_source
                        || has_dynamic_templates
                    {
                        break 'fast (None, None, None);
                    }
                    // Parse state: skip whitespace, expect `{`, "action": "index" etc.
                    let mut p = 0usize;
                    while p < bytes.len() && (bytes[p] == b' ' || bytes[p] == b'\t') {
                        p += 1;
                    }
                    if p >= bytes.len() || bytes[p] != b'{' {
                        break 'fast (None, None, None);
                    }
                    p += 1;
                    while p < bytes.len() && (bytes[p] == b' ' || bytes[p] == b'\t') {
                        p += 1;
                    }
                    if p >= bytes.len() || bytes[p] != b'"' {
                        break 'fast (None, None, None);
                    }
                    p += 1;
                    // Find closing quote of action name.
                    let key_start = p;
                    while p < bytes.len() && bytes[p] != b'"' {
                        p += 1;
                    }
                    if p >= bytes.len() {
                        break 'fast (None, None, None);
                    }
                    let key = &bytes[key_start..p];
                    let action_ty: &'static str = match key {
                        b"index" => "index",
                        b"create" => "create",
                        b"update" => "update",
                        b"delete" => "delete",
                        _ => break 'fast (None, None, None),
                    };
                    p += 1;
                    while p < bytes.len() && (bytes[p] == b' ' || bytes[p] == b':') {
                        p += 1;
                    }
                    if p >= bytes.len() || bytes[p] != b'{' {
                        break 'fast (None, None, None);
                    }
                    // Extract optional _index and _id inside the inner object.
                    // Both are bare-quoted strings with no embedded quotes in
                    // the canonical bulk format produced by ES clients. The
                    // inner object itself may contain nested objects (e.g.
                    // `dynamic_templates:{...}`), so we track brace depth —
                    // a naive "first `}`" scan would truncate the inner slice
                    // at the first nested `}` and hide fields like `op_type`.
                    let inner_end = {
                        let mut j = p + 1;
                        let mut depth: i32 = 1;
                        let mut in_str = false;
                        while j < bytes.len() {
                            let c = bytes[j];
                            if in_str {
                                if c == b'\\' {
                                    j += 2;
                                    continue;
                                }
                                if c == b'"' {
                                    in_str = false;
                                }
                            } else {
                                match c {
                                    b'"' => in_str = true,
                                    b'{' => depth += 1,
                                    b'}' => {
                                        depth -= 1;
                                        if depth == 0 {
                                            break;
                                        }
                                    }
                                    _ => {}
                                }
                            }
                            j += 1;
                        }
                        if j >= bytes.len() {
                            break 'fast (None, None, None);
                        }
                        j
                    };
                    let inner = &bytes[p + 1..inner_end];
                    // #954: a backslash inside the action object can only be
                    // part of a string escape in valid JSON, and find_field
                    // below scans for the next raw '"' without unescaping —
                    // `{"_id":"a\"b"}` would yield `a\` and desync the rest of
                    // the line, collapsing distinct ids. Any escaped content
                    // (_id, _index, op_type alike) opts out of the fast path;
                    // the serde_json fallback below parses it correctly.
                    if inner.contains(&b'\\') {
                        break 'fast (None, None, None);
                    }
                    let find_field = |needle: &[u8]| -> Option<String> {
                        // Look for `"_key":"value"` (quoted) or `"_key":NUM`
                        // (numeric, e.g. `_id:1`) inside `inner`. ES bulk
                        // accepts both shapes — numeric ids are stringified at
                        // the coordinator. An empty quoted value is preserved
                        // as `Some(String::new())` so the caller can tell
                        // "key absent" from "key present, empty".
                        let mut i = 0;
                        while i + needle.len() <= inner.len() {
                            if &inner[i..i + needle.len()] == needle {
                                let mut j = i + needle.len();
                                while j < inner.len() && inner[j] != b':' {
                                    j += 1;
                                }
                                j += 1;
                                while j < inner.len() && inner[j] == b' ' {
                                    j += 1;
                                }
                                if j >= inner.len() {
                                    return None;
                                }
                                if inner[j] == b'"' {
                                    j += 1;
                                    let v_start = j;
                                    while j < inner.len() && inner[j] != b'"' {
                                        j += 1;
                                    }
                                    return Some(
                                        std::str::from_utf8(&inner[v_start..j]).ok()?.to_string(),
                                    );
                                }
                                // Unquoted numeric id (e.g. `"_id":1`).
                                let v_start = j;
                                while j < inner.len()
                                    && (inner[j].is_ascii_digit()
                                        || inner[j] == b'-'
                                        || inner[j] == b'.')
                                {
                                    j += 1;
                                }
                                if v_start == j {
                                    return None;
                                }
                                return Some(
                                    std::str::from_utf8(&inner[v_start..j]).ok()?.to_string(),
                                );
                            }
                            i += 1;
                        }
                        None
                    };
                    let idx_name = find_field(br#""_index""#);
                    let id = find_field(br#""_id""#);
                    // ES allows `{"index": {"op_type": "create", ...}}` as a shorthand
                    // for a `create` action; promote it so downstream treats it as create.
                    let op_type = find_field(br#""op_type""#);
                    let final_ty: &'static str =
                        if action_ty == "index" && op_type.as_deref() == Some("create") {
                            "create"
                        } else {
                            action_ty
                        };
                    (Some(final_ty), idx_name, id)
                };

                let (action_type, target_index, doc_id) = if let Some(ty) = action_type {
                    (ty, target_index, doc_id)
                } else {
                    // Fallback: serde_json for non-canonical action lines.
                    // simd_json would need a mutable buffer (action_line is &str
                    // borrowed from the request body), forcing a per-action
                    // to_vec(). For the small action JSONs typical here (a few
                    // hundred bytes), serde_json's borrow-only path beats
                    // simd_json + allocation on the wall clock.
                    let action_val: Value = match serde_json::from_slice(action_line.as_bytes()) {
                        Ok(v) => v,
                        Err(e) => {
                            return ParseOutcome::Err(
                                BulkItemResult {
                                    action: "unknown".into(),
                                    index: default_index.unwrap_or("_unknown").to_string(),
                                    id: String::new(),
                                    status: 400,
                                    result: None,
                                    error: Some(format!("failed to parse action line: {e}")),
                                    get_source: None,
                                },
                                *item_index,
                            );
                        }
                    };
                    let (a, meta) = if let Some(obj) = action_val.get("index") {
                        ("index", obj)
                    } else if let Some(obj) = action_val.get("create") {
                        ("create", obj)
                    } else if let Some(obj) = action_val.get("update") {
                        ("update", obj)
                    } else if let Some(obj) = action_val.get("delete") {
                        ("delete", obj)
                    } else {
                        return ParseOutcome::Err(
                            BulkItemResult {
                                action: "unknown".into(),
                                index: default_index.unwrap_or("_unknown").to_string(),
                                id: String::new(),
                                status: 400,
                                result: None,
                                error: Some("unknown action type".to_string()),
                                get_source: None,
                            },
                            *item_index,
                        );
                    };
                    let op_type_str = meta.get("op_type").and_then(Value::as_str);
                    let final_a: &'static str = if a == "index" && op_type_str == Some("create") {
                        "create"
                    } else {
                        a
                    };
                    require_alias_per_item = meta.get("require_alias").and_then(Value::as_bool);
                    pipeline_per_item = meta
                        .get("pipeline")
                        .and_then(Value::as_str)
                        .map(str::to_owned);
                    // Wire → internal seq translation: ES numbers seq_no
                    // from 0 on the wire, the internal WAL counter from 1.
                    // The CAS compare (index_document_with_version) runs on
                    // internal seqs, so a `_seq_no` captured from any read
                    // or write response round-trips through bulk CAS.
                    if_seq_no_per_item = meta
                        .get("if_seq_no")
                        .and_then(Value::as_u64)
                        .map(|s| s.saturating_add(1));
                    if_primary_term_per_item = meta.get("if_primary_term").and_then(Value::as_u64);
                    routing_per_item = meta
                        .get("routing")
                        .and_then(Value::as_str)
                        .map(str::to_owned);
                    source_req_per_item = meta.get("_source").cloned();
                    dynamic_templates_per_item = meta
                        .get("dynamic_templates")
                        .and_then(Value::as_object)
                        .map(|o| {
                            o.iter()
                                .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
                                .collect()
                        });
                    // ES bulk accepts `_id` as either a string or a number;
                    // numeric ids are stringified at the coordinating node.
                    let id_from_meta = meta.get("_id").and_then(|v| match v {
                        Value::String(s) => Some(s.clone()),
                        Value::Number(n) => Some(n.to_string()),
                        Value::Bool(b) => Some(b.to_string()),
                        _ => None,
                    });
                    (
                        final_a,
                        meta.get("_index")
                            .and_then(Value::as_str)
                            .map(str::to_owned),
                        id_from_meta,
                    )
                };

                let target_index = target_index
                    .or_else(|| default_index.map(str::to_owned))
                    .unwrap_or_else(|| "_unknown".to_string());

                // ES rejects an explicit empty `_id` with an
                // illegal_argument_exception per-item error. `_id` missing
                // entirely still auto-generates; only the present-but-empty
                // case is wrong.
                if let Some(s) = doc_id.as_deref() {
                    if s.is_empty() {
                        return ParseOutcome::Err(
                            BulkItemResult {
                                action: action_type.to_string(),
                                index: target_index,
                                id: String::new(),
                                status: 400,
                                result: None,
                                error: Some("if _id is specified it must not be empty".to_string()),
                                get_source: None,
                            },
                            *item_index,
                        );
                    }
                }

                let (doc_body, doc_bytes) = if action_type != "delete" {
                    let dl = match doc_line {
                        Some(dl) => dl,
                        None => {
                            return ParseOutcome::Err(
                                BulkItemResult {
                                    action: action_type.to_string(),
                                    index: target_index,
                                    id: doc_id.unwrap_or_default(),
                                    status: 400,
                                    result: None,
                                    error: Some("missing document body".to_string()),
                                    get_source: None,
                                },
                                *item_index,
                            );
                        }
                    };
                    // One document over the fixed ceiling is refused before
                    // `IgnoredAny`, `Value`, or tokenization. `Token` owns a
                    // `String` per word, and `panic = "abort"` dies on that
                    // allocation before the RSS governor samples (#1122).
                    // 413, not 429:
                    // the item is settled. Neighbours in the same bulk still
                    // index. A lone 413 is not the whole-request action-count
                    // refusal (`is_whole_request_too_large` requires more than
                    // one sent action).
                    if xerj_common::document_limit::indexed_document_too_large(dl.len()) {
                        return ParseOutcome::Err(
                            BulkItemResult {
                                action: action_type.to_string(),
                                index: target_index,
                                id: doc_id.unwrap_or_default(),
                                status: 413,
                                result: None,
                                error: Some(xerj_common::document_limit::indexed_document_refusal(
                                    dl.len(),
                                )),
                                get_source: None,
                            },
                            *item_index,
                        );
                    }
                    // M5.11 — SKIP the doc-body JSON parse for `index`
                    // actions.  The turbo-raw ingest path accepts the raw
                    // NDJSON bytes and defers the parse to drain-for-flush
                    // on a background thread, taking ~5 µs/doc off the HTTP
                    // worker's critical path.  `update` and `create`
                    // actions still need the parsed Value because they
                    // take different code paths below — but `index` is
                    // the dominant one on ingest benchmarks.
                    //
                    // The bytes are still VALIDATED here (syntax + top-level
                    // object) via `IgnoredAny`, which walks the JSON without
                    // building a Value tree — no per-key String allocations,
                    // so the turbo win (skipping the tree build) is kept.
                    // Without this, a malformed doc line was deferred to the
                    // background parse whose `.unwrap_or({})` stored the doc
                    // as EMPTY `{}` while the response said 201/errors:false
                    // — silent data loss. ES rejects the item with a 400
                    // `document_parsing_exception` instead; mirror that.
                    if action_type == "index" {
                        if let Err(e) =
                            serde_json::from_slice::<serde::de::IgnoredAny>(dl.as_bytes())
                        {
                            return ParseOutcome::Err(
                                BulkItemResult {
                                    action: action_type.to_string(),
                                    index: target_index,
                                    id: doc_id.clone().unwrap_or_default(),
                                    status: 400,
                                    result: None,
                                    error: Some(malformed_document_reason(
                                        doc_id.as_deref(),
                                        *item_index,
                                        &e,
                                    )),
                                    get_source: None,
                                },
                                *item_index,
                            );
                        }
                        // ES requires the doc body to be a JSON object;
                        // a bare array / scalar is rejected per-item
                        // (ES 8.13: `not_x_content_exception`; we report
                        // the same condition as a 400 parse error).
                        let is_object = dl
                            .as_bytes()
                            .iter()
                            .find(|b| !b" \t\r\n".contains(b))
                            .map(|b| *b == b'{')
                            .unwrap_or(false);
                        if !is_object {
                            return ParseOutcome::Err(
                                BulkItemResult {
                                    action: action_type.to_string(),
                                    index: target_index,
                                    id: doc_id.unwrap_or_default(),
                                    status: 400,
                                    result: None,
                                    error: Some(
                                        "failed to parse: invalid document JSON: \
                                         document body must be a JSON object"
                                            .to_string(),
                                    ),
                                    get_source: None,
                                },
                                *item_index,
                            );
                        }
                        // `IgnoredAny` above does not decode string escapes,
                        // so an unpaired UTF-16 surrogate (`"a\ud83db"`) slips
                        // through here but is rejected by the batch `Value`
                        // parse on the turbo-raw ingest path — failing every
                        // other document grouped with it (issue #1304). Reject
                        // it per-item now so ES's bulk contract holds: the one
                        // bad document errors and its neighbours still index.
                        if let Some(detail) = lone_surrogate_escape_reason(dl.as_bytes()) {
                            return ParseOutcome::Err(
                                BulkItemResult {
                                    action: action_type.to_string(),
                                    index: target_index,
                                    id: doc_id.clone().unwrap_or_default(),
                                    status: 400,
                                    result: None,
                                    error: Some(lone_surrogate_document_reason(
                                        doc_id.as_deref(),
                                        *item_index,
                                        detail,
                                    )),
                                    get_source: None,
                                },
                                *item_index,
                            );
                        }
                        let bytes: std::sync::Arc<[u8]> = std::sync::Arc::from(dl.as_bytes());
                        (None, bytes)
                    } else {
                        // See action_line fallback above for why serde_json beats
                        // simd_json + to_vec() on small bulk doc lines.
                        match serde_json::from_slice::<Value>(dl.as_bytes()) {
                            Ok(v) => {
                                let bytes: std::sync::Arc<[u8]> =
                                    std::sync::Arc::from(dl.as_bytes());
                                (Some(v), bytes)
                            }
                            Err(e) => {
                                return ParseOutcome::Err(
                                    BulkItemResult {
                                        action: action_type.to_string(),
                                        index: target_index,
                                        id: doc_id.clone().unwrap_or_default(),
                                        status: 400,
                                        result: None,
                                        error: Some(malformed_document_reason(
                                            doc_id.as_deref(),
                                            *item_index,
                                            &e,
                                        )),
                                        get_source: None,
                                    },
                                    *item_index,
                                );
                            }
                        }
                    }
                } else {
                    // Delete action — we may have optimistically consumed
                    // a line during pair building that actually belongs to
                    // the NEXT action.  Signal the caller to pop it back
                    // into the input stream.
                    let skip_back = if doc_line.is_some() { 1usize } else { 0usize };
                    let action = ParsedAction {
                        action_type: action_type.to_string(),
                        target_index,
                        doc_id,
                        doc_body: None,
                        doc_bytes: std::sync::Arc::from(&[][..]),
                        item_index: *item_index,
                        require_alias: require_alias_per_item,
                        pipeline: pipeline_per_item.clone(),
                        if_seq_no: if_seq_no_per_item,
                        if_primary_term: if_primary_term_per_item,
                        routing: routing_per_item.clone(),
                        source_req: source_req_per_item.clone(),
                        dynamic_templates: dynamic_templates_per_item.clone(),
                    };
                    if skip_back > 0 {
                        // We need to signal that the "body" we consumed
                        // was actually a new action line — but with a
                        // parallel parse this is hard because lines are
                        // not in order.  For now, fall back to the
                        // serial path for delete-heavy batches.
                        // In practice nginx log ingest has ZERO deletes,
                        // so this branch is cold.
                        return ParseOutcome::Ok(action);
                    }
                    return ParseOutcome::Ok(action);
                };

                // For update actions, the request may put `_source` on the
                // doc body rather than the action meta
                // (`{_source: true, doc: {...}}`). Honor that too.
                let source_req_final = source_req_per_item.or_else(|| {
                    if action_type == "update" {
                        doc_body.as_ref().and_then(|b| b.get("_source").cloned())
                    } else {
                        None
                    }
                });

                ParseOutcome::Ok(ParsedAction {
                    action_type: action_type.to_string(),
                    target_index,
                    doc_id,
                    doc_body,
                    doc_bytes,
                    item_index: *item_index,
                    require_alias: require_alias_per_item,
                    pipeline: pipeline_per_item,
                    if_seq_no: if_seq_no_per_item,
                    if_primary_term: if_primary_term_per_item,
                    routing: routing_per_item,
                    source_req: source_req_final,
                    dynamic_templates: dynamic_templates_per_item,
                })
            })
            .collect()
    });

    let parse_ms = t_parse.elapsed().as_millis() as u64;
    // The parse buffers now exist and are visible to the RSS sampler; each
    // write path takes its own analyze reservation for the token spike.
    drop(parse_reservation);
    let t_group = std::time::Instant::now();
    let mut parsed: Vec<ParsedAction> = Vec::with_capacity(parse_results.len());
    for outcome in parse_results {
        match outcome {
            ParseOutcome::Ok(a) => parsed.push(a),
            ParseOutcome::Err(err_item, item_idx) => {
                items[item_idx] = Some(err_item);
                errors = true;
            }
        }
    }

    // ── Effective ingest pipeline per item ──────────────────────────────────
    //
    // Elasticsearch resolves the pipeline for a bulk `index`/`create` action in
    // this order, and so does xerj now:
    //
    //   1. the action's own `"pipeline"` metadata key
    //   2. the request's `?pipeline=` query parameter
    //   3. the target index's `index.default_pipeline` setting
    //
    // and `_none` at either of the first two levels disables the setting.
    //
    // Issue #204: only step 1 existed here. `POST /_bulk?pipeline=redact` and
    // an index carrying `index.default_pipeline` both answered `201` per item
    // and stored the document UNTRANSFORMED — no error, no log line — while
    // `PUT /{index}/_doc/{id}?pipeline=redact` ran the pipeline and refused
    // when it could not. One instruction, two answers, and the silent one was
    // the high-volume path.
    //
    // Resolving here, before the existence check below and before the
    // turbo-path partition (which diverts any action carrying a pipeline),
    // means the rest of this function needs no further change: an unknown or
    // unrunnable name fails the item exactly as an explicit one always did.
    for action in parsed.iter_mut() {
        if !matches!(action.action_type.as_str(), "index" | "create") {
            // `update` and `delete` never carry a source body through a
            // pipeline, in ES or here.
            continue;
        }
        let explicit = action
            .pipeline
            .as_deref()
            .or(opts.default_pipeline.as_deref());
        action.pipeline = match explicit {
            Some("_none") => None,
            Some(p) => Some(p.to_string()),
            None => engine.default_pipeline_for(&action.target_index),
        };
    }

    // ── Per-item validation: pipeline existence ─────────────────────────────
    //
    // The effective pipeline resolved above must name a registered ingest
    // pipeline; otherwise ES fails the item with
    // `illegal_argument_exception: pipeline with id [...] does not exist`.
    parsed.retain(|action| {
        if let Some(pid) = action.pipeline.as_deref() {
            if !engine.pipelines.contains_key(pid) {
                items[action.item_index] = Some(BulkItemResult {
                    action: action.action_type.clone(),
                    index: action.target_index.clone(),
                    id: action.doc_id.clone().unwrap_or_default(),
                    status: 400,
                    result: None,
                    error: Some(format!("pipeline with id [{pid}] does not exist")),
                    get_source: None,
                });
                errors = true;
                return false;
            }
        }
        true
    });

    // ── Per-item validation: require_alias + ambiguous-alias write target ─────
    //
    // ES rejects an item when `require_alias=true` (per-item or URL-default)
    // and the target is not a registered alias. It also rejects writes to an
    // alias that has more than one backing index unless one is designated as
    // the write index via `is_write_index:true` in the alias metadata.
    let url_require_alias = opts.require_alias.unwrap_or(false);
    let default_source_req = opts.default_source_req.clone();
    parsed.retain_mut(|action| {
        let eff_require_alias = action.require_alias.unwrap_or(url_require_alias);
        let target = action.target_index.clone();
        let is_alias = engine.aliases.contains_key(&target);
        if eff_require_alias && !is_alias {
            items[action.item_index] = Some(BulkItemResult {
                action: action.action_type.clone(),
                index: target.clone(),
                id: action.doc_id.clone().unwrap_or_default(),
                status: 404,
                result: None,
                error: Some(format!(
                    "no such index [{target}] and [require_alias] request flag is [true] and [{target}] is not an alias"
                )),
                get_source: None,
            });
            errors = true;
            return false;
        }
        if is_alias {
            // One write-target definition for every write path: a single
            // backing index or exactly one `is_write_index:true`. The old code
            // only checked that SOME write index existed and then left the
            // target as the alias, so `get_or_create_index` wrote to the FIRST
            // backing index and ignored the designation.
            match engine.write_target(&target) {
                Ok(Some(concrete)) => action.target_index = concrete,
                Ok(None) => {}
                Err(reason) => {
                    items[action.item_index] = Some(BulkItemResult {
                        action: action.action_type.clone(),
                        index: target.clone(),
                        id: action.doc_id.clone().unwrap_or_default(),
                        status: 400,
                        result: None,
                        error: Some(reason),
                        get_source: None,
                    });
                    errors = true;
                    return false;
                }
            }
        }
        true
    });

    // ── Turbo path: batch pure `index` ops per index ─────────────────────────
    //
    // `index` actions always overwrite — safe to batch via index_batch_turbo().
    // `create` actions must fail with 409 if the doc already exists, so they
    // are executed individually below (along with update/delete).
    //
    // Group `index`-only ops by target index.  **CONSUMES** `parsed` — the
    // previous version borrowed and then cloned `action.doc_body` (a full
    // `serde_json::Value` deep-clone) into the batch, which on a 60-field
    // nginx doc was ~60 allocations per document * 55 k docs/s = 3.3 M
    // allocs/s of pure waste.  Now we drain `parsed` by value and move the
    // Value straight into the batch.
    // M5.11 — index actions carry only `(item_index, doc_id, doc_bytes)`.
    // The parsed `Value` is never built for index actions on this path.
    let mut index_batches: HashMap<String, Vec<(usize, String, std::sync::Arc<[u8]>)>> =
        HashMap::new();
    // AUTO-ID plain-index actions (no explicit `_id`).  These are
    // guaranteed new — they can NEVER overwrite — so every one is a
    // "created"/201.  That makes them safe to push through the single
    // `index_batch_turbo_raw` batch call, whose response is hardcoded
    // to "created".  Explicit-id index actions stay in `index_batches`
    // and run the per-doc loop because they may overwrite and so need
    // created-vs-updated / 201-vs-200 semantics turbo can't express.
    let mut auto_id_batches: HashMap<String, Vec<(usize, String, std::sync::Arc<[u8]>)>> =
        HashMap::new();
    let mut semantic_index_batches: HashMap<
        String,
        Vec<(usize, Option<String>, std::sync::Arc<[u8]>)>,
    > = HashMap::new();
    let mut non_index_actions: Vec<ParsedAction> = Vec::new();

    // Precompute which target indices declare any strict-format date
    // fields — those need per-doc date-format validation before the
    // doc is accepted. Actions targeting those indices go through the
    // slow path so the validation loop below can see them.
    let mut index_needs_date_validation: HashMap<String, bool> = HashMap::new();
    let index_has_strict_date = |target: &str, cache: &mut HashMap<String, bool>| -> bool {
        if let Some(b) = cache.get(target) {
            return *b;
        }
        let has = engine
            .index_mappings
            .get(target)
            .map(|m| {
                let props = m.get("properties").cloned().or_else(|| {
                    m.get("mappings")
                        .and_then(|mm| mm.get("properties"))
                        .cloned()
                });
                mapping_has_strict_date(&props.unwrap_or(Value::Null))
            })
            .unwrap_or(false);
        cache.insert(target.to_string(), has);
        has
    };

    // Same gate for dynamic-templates with `copy_to`: the ingest
    // loop below materialises the copy into the doc body so the
    // stored source reflects it. The turbo path skips doc parsing,
    // so route those actions through the slow path.
    let mut index_needs_dynamic_copy: HashMap<String, bool> = HashMap::new();
    let index_has_dynamic_copy = |target: &str, cache: &mut HashMap<String, bool>| -> bool {
        if let Some(b) = cache.get(target) {
            return *b;
        }
        let has = engine
            .index_mappings
            .get(target)
            .map(|m| {
                let tmpls = m
                    .get("mappings")
                    .and_then(|mm| mm.get("dynamic_templates"))
                    .or_else(|| m.get("dynamic_templates"));
                tmpls
                    .and_then(Value::as_array)
                    .map(|arr| {
                        arr.iter().any(|v| {
                            v.as_object()
                                .and_then(|o| o.iter().next())
                                .map(|(_, body)| {
                                    body.get("mapping")
                                        .and_then(|mm| mm.get("copy_to"))
                                        .is_some()
                                })
                                .unwrap_or(false)
                        })
                    })
                    .unwrap_or(false)
            })
            .unwrap_or(false);
        cache.insert(target.to_string(), has);
        has
    };

    // Same gate for `semantic_text` fields: those auto-embed on ingest,
    // which only the per-doc path does. The turbo auto-id batch path
    // stores raw bytes and never embeds, so auto-id bulk docs into a
    // semantic_text index would land unvectorised and `semantic`/`knn`
    // search would silently return nothing. Route them through the slow
    // path so `apply_semantic_embeddings` runs.
    let mut index_needs_embedding: HashMap<String, bool> = HashMap::new();
    let index_has_embedding = |target: &str, cache: &mut HashMap<String, bool>| -> bool {
        if let Some(b) = cache.get(target) {
            return *b;
        }
        let has = engine
            .index_mappings
            .get(target)
            .map(|m| {
                let props = m.get("properties").cloned().or_else(|| {
                    m.get("mappings")
                        .and_then(|mm| mm.get("properties"))
                        .cloned()
                });
                mapping_has_semantic_text(&props.unwrap_or(Value::Null))
            })
            .unwrap_or(false)
            // The index does not exist yet. A matching template's
            // `semantic_text` is applied by the auto-create this batch is
            // about to do; classifying from the absent mapping sent the
            // first write down the turbo path, which never embeds (#2281).
            || engine.absent_index_template_has_semantic_text(target);
        cache.insert(target.to_string(), has);
        has
    };

    // Same gate for numeric / boolean field types (issue #781). Unlike the
    // three above this does NOT divert to the slow path — that would cost
    // every mapped-numeric index the turbo batch — it coerces the raw doc
    // bytes in place right here and lets the action stay on turbo. The gate
    // exists so an index with no numeric or boolean field never pays for the
    // parse at all.
    //
    // The cache carries the PROPERTIES MAP, not just the boolean gate:
    // `mapping_properties(...).cloned()` deep-copies the whole properties
    // blob, and reading it per action would put an O(mapping) copy on the HTTP
    // worker for every document in the batch — the cost M5.11 took off this
    // path. Behind an `Arc` the per-action price is a refcount bump, and both
    // enforcement sites (partition loop and per-item loop) share the one
    // cache. `None` means "this index needs no check" — an unmapped index, or
    // one whose mapping declares no numeric/boolean field.
    type CoerceProps = Option<std::sync::Arc<serde_json::Map<String, Value>>>;
    let mut index_type_check_props: HashMap<String, CoerceProps> = HashMap::new();
    let typed_numeric_props =
        |target: &str, cache: &mut HashMap<String, CoerceProps>| -> CoerceProps {
            if let Some(p) = cache.get(target) {
                return p.clone();
            }
            let props: CoerceProps = engine.index_mappings.get(target).and_then(|m| {
                if !xerj_common::field_coercion::mapping_has_enforced_types(&m) {
                    return None;
                }
                xerj_common::field_coercion::mapping_properties(&m)
                    .cloned()
                    .map(std::sync::Arc::new)
            });
            cache.insert(target.to_string(), props.clone());
            props
        };

    // A bulk body is an ordered log: ES applies its items in request order,
    // so `delete 1` followed by `index 1` leaves the doc present, and
    // `index 1 {v:1}`, `delete 1`, `index 1 {v:2}` leaves `{v:2}`. The
    // partition below runs its groups as phases (semantic, then turbo
    // index, then everything else), which reorders items across groups.
    // That is harmless while each `(index, _id)` lives in one group, but a
    // key that a non-turbo action (delete / update / create / CAS / routed
    // index) also touches would see its plain `index` items jump ahead and
    // the later delete win — the doc is gone and every item said success.
    // Collect those keys up front and keep all of their items on the
    // sequential path, which executes in request order.
    let sequential_keys: std::collections::HashSet<(String, String)> = parsed
        .iter()
        .filter(|a| {
            a.action_type != "index"
                || a.if_seq_no.is_some()
                || a.if_primary_term.is_some()
                || a.routing.is_some()
                || a.dynamic_templates.is_some()
                || a.pipeline.is_some()
        })
        .filter_map(|a| {
            a.doc_id
                .as_ref()
                .map(|id| (a.target_index.clone(), id.clone()))
        })
        .collect();

    for mut action in parsed {
        // ── Numeric / boolean type enforcement (issue #781) ──────────────
        //
        // A field mapped `integer` used to keep whatever arrived — `1.9`,
        // `9999999999`, `"abc"`, even an object — so `range {gte: 1.5}`
        // matched a doc that ES stores as `1` and `term {i: 1}` missed it.
        // Values ES coerces are coerced here (`1.9` → `1`, `"5"` → `5`,
        // `"true"` → `true`); values ES refuses become a per-item 400
        // `document_parsing_exception`, like the date-format check below.
        //
        // Runs at partition time so it covers the turbo batch path as well
        // as the per-item loop. Actions carrying a pipeline are skipped: ES
        // runs the pipeline before parsing the document, so those are
        // checked after their pipeline in the per-item loop instead.
        // `update` merges into a doc that was already validated on write.
        if matches!(action.action_type.as_str(), "index" | "create") && action.pipeline.is_none() {
            let props = typed_numeric_props(&action.target_index, &mut index_type_check_props);
            if let Some(props) = props {
                // `index` actions defer the JSON parse to the turbo path, so
                // the body may not be built yet — parse it here, and only
                // pay the re-serialize when a value actually changed.
                let parsed_body = match action.doc_body.take() {
                    Some(Value::Object(o)) => Some(o),
                    Some(other) => {
                        action.doc_body = Some(other);
                        None
                    }
                    None => match serde_json::from_slice::<Value>(&action.doc_bytes) {
                        Ok(Value::Object(o)) => Some(o),
                        _ => None,
                    },
                };
                if let Some(mut body) = parsed_body {
                    match xerj_common::field_coercion::coerce_document(&mut body, &props) {
                        Ok(changed) => {
                            // Serialize from the map itself, not a clone of
                            // it — `preserve_order` is on workspace-wide, so
                            // the caller's `_source` key order survives.
                            if changed {
                                if let Ok(bytes) = serde_json::to_vec(&body) {
                                    action.doc_bytes = std::sync::Arc::from(bytes.as_slice());
                                }
                            }
                            action.doc_body = Some(Value::Object(body));
                        }
                        Err(bad) => {
                            items[action.item_index] = Some(BulkItemResult {
                                action: action.action_type.clone(),
                                index: action.target_index.clone(),
                                id: action.doc_id.clone().unwrap_or_default(),
                                status: 400,
                                result: None,
                                error: Some(bad.reason(&action.doc_id.clone().unwrap_or_default())),
                                get_source: None,
                            });
                            errors = true;
                            continue;
                        }
                    }
                }
            }
        }
        // `index` with no `if_seq_no` / `routing` goes through the
        // turbo batch path. Actions that carry CAS or routing metadata
        // must be executed individually so we can honor them — route
        // them through the non-index path. Also divert when the index
        // has date fields with a strict `format`, so the per-item
        // validation loop can reject malformed values like ES does.
        let has_strict_date =
            index_has_strict_date(&action.target_index, &mut index_needs_date_validation);
        let has_dynamic_copy =
            index_has_dynamic_copy(&action.target_index, &mut index_needs_dynamic_copy);
        let has_embedding = index_has_embedding(&action.target_index, &mut index_needs_embedding);
        let has_plain_metadata = action.action_type == "index"
            && action.if_seq_no.is_none()
            && action.if_primary_term.is_none()
            && action.routing.is_none()
            && action.dynamic_templates.is_none()
            && action.pipeline.is_none()
            && !has_strict_date
            && !has_dynamic_copy
            && (sequential_keys.is_empty()
                || !action.doc_id.as_ref().is_some_and(|id| {
                    sequential_keys.contains(&(action.target_index.clone(), id.clone()))
                }));
        let is_plain_index = has_plain_metadata && !has_embedding;
        if is_plain_index {
            match action.doc_id {
                None => {
                    // Auto-id: brand-new doc, always "created"/201. Route the
                    // whole group through ONE `index_batch_turbo_raw` call.
                    let id = uuid::Uuid::new_v4().to_string();
                    auto_id_batches
                        .entry(action.target_index)
                        .or_default()
                        .push((action.item_index, id, action.doc_bytes));
                }
                Some(id) => {
                    // Explicit id: may overwrite → keep the per-doc path so
                    // created/updated + 201/200 is resolved correctly.
                    index_batches.entry(action.target_index).or_default().push((
                        action.item_index,
                        id,
                        action.doc_bytes,
                    ));
                }
            }
        } else if has_plain_metadata && has_embedding {
            semantic_index_batches
                .entry(action.target_index)
                .or_default()
                .push((action.item_index, action.doc_id, action.doc_bytes));
        } else {
            non_index_actions.push(action);
        }
    }
    let parsed = non_index_actions;

    let group_ms = t_group.elapsed().as_millis() as u64;
    let t_exec = std::time::Instant::now();

    // ── semantic_text index actions: cross-document embedding windows ────
    //
    // Parse and prepare a target-index group together so the embedder sees
    // useful multi-document windows. The normal per-document index method is
    // still used after preparation; it observes the supplied companion vector
    // and therefore preserves WAL, overwrite status, response ordering, and
    // item-level errors.
    let mut semantic_raw_memory = crate::ingest_memory::enabled().then(
        std::collections::HashMap::<usize, (usize, crate::ingest_memory::Retained<'static>)>::new,
    );
    if let Some(raw_memory) = semantic_raw_memory.as_mut() {
        for batch in semantic_index_batches.values() {
            for (_, _, source) in batch {
                let owner = std::sync::Arc::as_ptr(source) as *const () as usize;
                raw_memory
                    .entry(owner)
                    .and_modify(|(remaining, _)| *remaining += 1)
                    .or_insert_with(|| {
                        (
                            1usize,
                            crate::ingest_memory::Retained::new(
                                crate::ingest_memory::Category::RawSource,
                                source.len(),
                            ),
                        )
                    });
            }
        }
    }
    for (index_name, batch) in semantic_index_batches {
        #[cfg(test)]
        let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::Grouped);
        let idx = match engine.get_or_create_index(&index_name) {
            Ok(i) => i,
            Err(e) => {
                for (item_idx, id, source) in batch {
                    if let Some(raw_memory) = semantic_raw_memory.as_mut() {
                        release_raw_owner(raw_memory, source);
                    } else {
                        drop(source);
                    }
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id: id.unwrap_or_default(),
                        status: 500,
                        result: None,
                        error: Some(e.to_string()),
                        get_source: None,
                    });
                    errors = true;
                }
                continue;
            }
        };
        let vector_fields = if crate::ingest_memory::enabled() {
            #[cfg(test)]
            count_disabled_semantic_access(|counters| &counters.schema_reads);
            idx.semantic_vector_fields().await
        } else {
            std::collections::HashSet::new()
        };

        let mut valid_meta = Vec::with_capacity(batch.len());
        let mut valid_sources = Vec::with_capacity(batch.len());
        let mut valid_memory = crate::ingest_memory::enabled().then(|| {
            #[cfg(test)]
            count_disabled_semantic_access(|counters| &counters.guard_vectors);
            Vec::with_capacity(batch.len())
        });
        for (item_idx, id, bytes) in batch {
            let parsed = serde_json::from_slice::<Value>(&bytes);
            match parsed {
                Ok(source) => {
                    if let Some(valid_memory) = valid_memory.as_mut() {
                        #[cfg(test)]
                        count_disabled_semantic_access(|counters| &counters.sizing_walks);
                        let parsed_document = crate::ingest_memory::Retained::new(
                            crate::ingest_memory::Category::ParsedSource,
                            crate::ingest_memory::estimated_json_heap_excluding(
                                &source,
                                &vector_fields,
                            ),
                        );
                        let parsed_vector = crate::ingest_memory::Retained::new(
                            crate::ingest_memory::Category::ParsedVector,
                            crate::ingest_memory::vector_value_capacity(&source, &vector_fields),
                        );
                        valid_memory.push((parsed_document, parsed_vector));
                    }
                    if let Some(raw_memory) = semantic_raw_memory.as_mut() {
                        release_raw_owner(raw_memory, bytes);
                    } else {
                        drop(bytes);
                    }
                    valid_meta.push((item_idx, id));
                    valid_sources.push(source);
                }
                Err(e) => {
                    if let Some(raw_memory) = semantic_raw_memory.as_mut() {
                        release_raw_owner(raw_memory, bytes);
                    } else {
                        drop(bytes);
                    }
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id: id.unwrap_or_default(),
                        status: 400,
                        result: None,
                        error: Some(format!("failed to parse: invalid document JSON: {e}")),
                        get_source: None,
                    });
                    errors = true;
                }
            }
        }
        #[cfg(test)]
        let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::Parsed);

        // Backend-owned chunk strings, tokenizer tensors, and inference
        // scratch are not yet logically attributed. Their effect remains
        // visible only as allocator/RSS physical delta; it is not zero.
        let prepared = idx.apply_semantic_embeddings_batch(valid_sources).await;
        #[cfg(test)]
        let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::Prepared);
        // #2427: without ingest-memory tracing nothing is accounted per
        // document, so publish the prepared group as one batch instead of
        // one `index_document_prepared` call per document. The tracing mode
        // (and its lifecycle tests) keeps the sequential path so each
        // prepared document's ownership is still released as it publishes.
        if valid_memory.is_none() && !semantic_lifecycle_hook_installed(&index_name) {
            let docs = valid_meta
                .into_iter()
                .zip(prepared)
                .map(|((item_idx, id), prepared)| (item_idx, id.unwrap_or_default(), prepared))
                .collect();
            errors |= publish_prepared_batch(&idx, &index_name, docs, &mut items).await;
            continue;
        }
        let mut valid_memory = valid_memory.map(Vec::into_iter);
        for ((item_idx, id), prepared_source) in valid_meta.into_iter().zip(prepared) {
            let memory = valid_memory.as_mut().and_then(Iterator::next);
            let (source, prepared_memory) = match prepared_source {
                Ok(source) => {
                    let prepared_memory = if let Some((parsed_document, parsed_vector)) = memory {
                        #[cfg(test)]
                        count_disabled_semantic_access(|counters| &counters.sizing_walks);
                        let prepared_document_bytes =
                            crate::ingest_memory::estimated_json_heap_excluding(
                                &source,
                                &vector_fields,
                            );
                        let prepared_vector_bytes =
                            crate::ingest_memory::vector_value_capacity(&source, &vector_fields);
                        Some(crate::ingest_memory::Retained::replace_pair(
                            parsed_document,
                            parsed_vector,
                            (
                                crate::ingest_memory::Category::PreparedDocument,
                                prepared_document_bytes,
                            ),
                            (
                                crate::ingest_memory::Category::PreparedVector,
                                prepared_vector_bytes,
                            ),
                        ))
                    } else {
                        None
                    };
                    (source, prepared_memory)
                }
                Err(e) => {
                    drop(memory);
                    let status = engine_error_http_status(&e);
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id: id.unwrap_or_default(),
                        status,
                        result: None,
                        error: Some(e.to_string()),
                        get_source: None,
                    });
                    errors = true;
                    continue;
                }
            };
            let error_id = id.clone().unwrap_or_default();
            #[cfg(test)]
            let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::BeforePublication);
            let publication = idx.index_document_prepared(id, source).await;
            drop(prepared_memory);
            #[cfg(test)]
            let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::AfterPublication);
            match publication {
                Ok(resp) => {
                    let status = if resp.result == "updated" { 200 } else { 201 };
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id: resp.id,
                        status,
                        result: Some(resp.result),
                        error: None,
                        get_source: None,
                    });
                }
                Err(e) => {
                    let status = engine_error_http_status(&e);
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id: error_id,
                        status,
                        result: None,
                        error: Some(e.to_string()),
                        get_source: None,
                    });
                    errors = true;
                }
            }
        }
    }

    // ── Auto-id index actions: ONE turbo batch per target index ──────────
    //
    // `index_batch_turbo_raw` appends the whole group with a single WAL
    // batch + one parsed FTS-memtable insert per doc (the now-correct,
    // single-representation path).  It returns one `IndexResponse` per
    // input doc IN ORDER, so we map them straight back onto the item
    // slots — all 201/"created" since auto-id docs can't overwrite.
    for (index_name, batch) in auto_id_batches {
        let idx = match engine.get_or_create_index(&index_name) {
            Ok(i) => i,
            Err(e) => {
                for (item_idx, id, _) in batch {
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id,
                        status: 500,
                        result: None,
                        error: Some(e.to_string()),
                        get_source: None,
                    });
                    errors = true;
                }
                continue;
            }
        };

        // Keep item indices parallel to the docs we hand to turbo so we
        // can re-associate responses (turbo preserves input order).
        let item_indices: Vec<usize> = batch.iter().map(|(i, _, _)| *i).collect();
        let turbo_docs: Vec<(String, std::sync::Arc<[u8]>)> = batch
            .into_iter()
            .map(|(_, id, bytes)| (id, bytes))
            .collect();

        match idx.index_batch_turbo_raw(turbo_docs).await {
            Ok(responses) => {
                for (k, resp) in responses.into_iter().enumerate() {
                    let item_idx = item_indices[k];
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id: resp.id,
                        status: 201,
                        result: Some("created".into()),
                        error: None,
                        get_source: None,
                    });
                }
            }
            Err(e) => {
                // Whole-batch failure (e.g. ResourceExhausted → 429):
                // mark every item in the batch with the same status.
                let status = engine_error_http_status(&e);
                for item_idx in item_indices {
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id: String::new(),
                        status,
                        result: None,
                        error: Some(e.to_string()),
                        get_source: None,
                    });
                }
                errors = true;
            }
        }
    }

    // Execute turbo batches (index-only).
    for (index_name, batch) in index_batches {
        let idx = match engine.get_or_create_index(&index_name) {
            Ok(i) => i,
            Err(e) => {
                for (item_idx, id, _) in batch {
                    items[item_idx] = Some(BulkItemResult {
                        action: "index".into(),
                        index: index_name.clone(),
                        id,
                        status: 500,
                        result: None,
                        error: Some(e.to_string()),
                        get_source: None,
                    });
                    errors = true;
                }
                continue;
            }
        };

        // #2427: publish the whole explicit-id group as one batch. The
        // per-document `index_document` loop this replaces held the WAL lock,
        // copied the source into the storage memtable, and opened a
        // publication bracket once per document; eight concurrent bulks
        // used about two cores. `index_batch_explicit_ids_raw` keeps the
        // per-doc answers (`created`/`updated`, `_version`, date errors).
        //
        // An index created from a native schema can carry embedding fields
        // without a `semantic_text` mapping, so the partition above calls it
        // plain. `index_document` embedded those documents itself; prepare
        // them here in one shared pass before the batch publication.
        if !idx.semantic_vector_fields().await.is_empty() {
            let mut meta = Vec::with_capacity(batch.len());
            let mut sources = Vec::with_capacity(batch.len());
            for (item_idx, doc_id, doc_bytes) in batch {
                match serde_json::from_slice::<Value>(&doc_bytes) {
                    Ok(source) => {
                        meta.push((item_idx, doc_id));
                        sources.push(source);
                    }
                    Err(e) => {
                        items[item_idx] = Some(BulkItemResult {
                            action: "index".into(),
                            index: index_name.clone(),
                            id: doc_id,
                            status: 400,
                            result: None,
                            error: Some(format!("failed to parse: invalid document JSON: {e}")),
                            get_source: None,
                        });
                        errors = true;
                    }
                }
            }
            let prepared = idx.apply_semantic_embeddings_batch(sources).await;
            let docs = meta
                .into_iter()
                .zip(prepared)
                .map(|((item_idx, id), prepared)| (item_idx, id, prepared))
                .collect();
            errors |= publish_prepared_batch(&idx, &index_name, docs, &mut items).await;
            continue;
        }
        let docs = batch
            .into_iter()
            .map(|(item_idx, doc_id, doc_bytes)| {
                let doc_id = if doc_id.is_empty() {
                    uuid::Uuid::new_v4().to_string()
                } else {
                    doc_id
                };
                (item_idx, doc_id, doc_bytes)
            })
            .collect();
        errors |= publish_explicit_id_batch(&idx, &index_name, docs, &mut items).await;
    }

    // Execute non-index ops individually (create, update, delete).
    // `create` / `update` / `delete` — executed individually.  `parsed` here
    // has already been filtered to non-`index` actions by the turbo-batch
    // partition above, so the match arms no longer need an `"index" => {}`
    // no-op branch.  We consume `parsed` by value to avoid per-action
    // deep-clones of `doc_id` (String) and `doc_body` (Value tree).
    for action in parsed {
        let ParsedAction {
            action_type,
            target_index,
            doc_id,
            doc_body,
            doc_bytes,
            item_index: item_idx,
            require_alias: _,
            pipeline,
            if_seq_no,
            if_primary_term,
            routing,
            source_req,
            dynamic_templates,
        } = action;
        let error_id = doc_id.clone().unwrap_or_default();
        let target_index_for_get = target_index.clone();
        let doc_id_for_get = doc_id.clone();
        // Ensure we have the doc body parsed before validating — our
        // dynamic-templates check needs `doc_body.contains_key(field)`
        // to tell "spec applies to this doc" from "spec references a
        // field not even present". The turbo-index partition skipped
        // parsing; do it here if needed.
        let mut doc_body = doc_body.or_else(|| {
            if action_type == "index" && !doc_bytes.is_empty() {
                // doc_bytes is Arc<[u8]> — mutating it would invalidate
                // sibling clones, so simd_json (which mutates in-place)
                // forced a per-doc to_vec(). serde_json takes &[u8]
                // immutably and avoids the allocation entirely.
                serde_json::from_slice::<Value>(&doc_bytes).ok()
            } else {
                None
            }
        });
        // ── Ingest pipeline execution ───────────────────────────────────
        //
        // ES runs the item's ingest pipeline BEFORE field mapping,
        // `copy_to`, and date / dynamic-template validation, so we apply
        // it here — right after the doc body is parsed. Only `index` /
        // `create` carry a source body through a pipeline (`update` /
        // `delete` never do). Unknown pipeline names were already rejected
        // as per-item 400s in the pre-partition validation pass above, so a
        // lookup miss here is defensive only — mirror the same error.
        if let Some(pid) = pipeline.as_deref() {
            if matches!(action_type.as_str(), "index" | "create") {
                let input = doc_body
                    .clone()
                    .unwrap_or_else(|| Value::Object(serde_json::Map::new()));
                match engine.process_through_pipeline(pid, vec![input]) {
                    Ok(mut results) if !results.is_empty() => {
                        let (p_action, transformed) = results.remove(0);
                        if matches!(p_action, xerj_wasm::pipeline::ProcessAction::Drop) {
                            // Pipeline dropped the doc: ES reports a
                            // successful no-op and does not index it.
                            items[item_idx] = Some(BulkItemResult {
                                action: action_type.to_string(),
                                index: target_index.clone(),
                                id: error_id.clone(),
                                status: 200,
                                result: Some("noop".into()),
                                error: None,
                                get_source: None,
                            });
                            continue;
                        }
                        doc_body = Some(transformed);
                    }
                    // No output for this document. `process_through_pipeline`
                    // zips one action per input, so this is an internal
                    // invariant break — but it must not fall through to
                    // indexing the ORIGINAL body, which is the silent
                    // pass-through issue #204 is about. Fail the item.
                    Ok(_) => {
                        items[item_idx] = Some(BulkItemResult {
                            action: action_type.to_string(),
                            index: target_index.clone(),
                            id: error_id.clone(),
                            status: 400,
                            result: None,
                            error: Some(format!("pipeline with id [{pid}] returned no document")),
                            get_source: None,
                        });
                        errors = true;
                        continue;
                    }
                    Err(e) => {
                        // A genuinely absent pipeline keeps ES's exact wording
                        // (the conformance suite asserts it). A pipeline that
                        // IS registered but carries a processor this build
                        // cannot run reports that instead — issue #204: telling
                        // an operator a pipeline "does not exist" when
                        // `GET /_ingest/pipeline` plainly returns it sends them
                        // hunting for the wrong problem.
                        let reason = match &e {
                            xerj_wasm::WasmError::PipelineNotRunnable { .. } => e.to_string(),
                            _ => format!("pipeline with id [{pid}] does not exist"),
                        };
                        items[item_idx] = Some(BulkItemResult {
                            action: action_type.to_string(),
                            index: target_index.clone(),
                            id: error_id.clone(),
                            status: 400,
                            result: None,
                            error: Some(reason),
                            get_source: None,
                        });
                        errors = true;
                        continue;
                    }
                }
            }
        }
        // Apply dynamic-template `copy_to` at ingest. When a doc
        // field name matches a dynamic template's `match` pattern
        // (or equals the template name) and the template's mapping
        // carries `copy_to`, ES silently copies the value into the
        // target field. Our search-time `apply_copy_to` only walks
        // the declared schema — it doesn't see dynamic templates —
        // so we materialise the copy into the doc body before it's
        // stored. This fixes the copy_to cluster in
        // `20_synthetic_source.yml` without requiring full dynamic
        // mapping persistence.
        if matches!(action_type.as_str(), "index" | "create") {
            if let Some(body) = doc_body.as_mut().and_then(|v| v.as_object_mut()) {
                let mapping = engine.index_mappings.get(&target_index).map(|v| v.clone());
                apply_dynamic_template_copy_to(body, mapping.as_ref(), dynamic_templates.as_ref());
            }
        }
        // Dynamic-templates validation: if the action specifies any
        // per-field `dynamic_templates: {field: tmpl_name}`, the
        // referenced template must exist in the target index's
        // mapping. Unknown names produce a per-item 400
        // `document_parsing_exception` in ES.
        if let Some(dt_map) = &dynamic_templates {
            if !dt_map.is_empty() {
                let mapping = engine.index_mappings.get(&target_index).map(|v| v.clone());
                // Collect per-template (name, match_pattern) so we can
                // test whether the field name would match ANY declared
                // template's pattern. ES accepts a dynamic_templates
                // spec on a field when either (a) the named template
                // exists, or (b) the field already has a concrete
                // mapping, or (c) the field matches some template's
                // `match` pattern (ES would silently apply that
                // template instead).
                let templates: Vec<(String, Option<String>)> = mapping
                    .as_ref()
                    .and_then(|m| {
                        m.get("mappings")
                            .and_then(|mm| mm.get("dynamic_templates"))
                            .or_else(|| m.get("dynamic_templates"))
                    })
                    .and_then(Value::as_array)
                    .map(|arr| {
                        arr.iter()
                            .filter_map(|v| {
                                v.as_object().and_then(|o| {
                                    let (name, spec) = o.iter().next()?;
                                    let pattern =
                                        spec.get("match").and_then(Value::as_str).map(String::from);
                                    Some((name.clone(), pattern))
                                })
                            })
                            .collect()
                    })
                    .unwrap_or_default();
                let declared_names: std::collections::HashSet<String> =
                    templates.iter().map(|(n, _)| n.clone()).collect();
                let declared_fields: std::collections::HashSet<String> = mapping
                    .as_ref()
                    .and_then(|m| {
                        m.get("mappings")
                            .and_then(|mm| mm.get("properties"))
                            .or_else(|| m.get("properties"))
                    })
                    .and_then(Value::as_object)
                    .map(|o| o.keys().cloned().collect())
                    .unwrap_or_default();
                let field_matches_any_template = |field: &str| -> bool {
                    templates.iter().any(|(name, pattern)| {
                        if let Some(pat) = pattern {
                            // Simple `*`-glob matching.
                            let p_bytes = pat.as_bytes();
                            let f_bytes = field.as_bytes();
                            simple_glob_matches(p_bytes, f_bytes)
                        } else {
                            // No pattern — the template default is a
                            // name-matching rule: field must equal the
                            // template's name.
                            field == name.as_str()
                        }
                    })
                };
                let mut first_bad: Option<(String, String)> = None;
                for (field, tmpl) in dt_map {
                    let present_in_doc = doc_body
                        .as_ref()
                        .map(|db| {
                            db.as_object()
                                .map(|o| o.contains_key(field))
                                .unwrap_or(false)
                        })
                        .unwrap_or(true);
                    if declared_fields.contains(field) {
                        continue;
                    }
                    if !present_in_doc {
                        continue;
                    }
                    if declared_names.contains(tmpl) {
                        continue;
                    }
                    // Fall back: the field might be implicitly mapped by
                    // a pattern-matching template (e.g. `match: "my*"`).
                    if field_matches_any_template(field) {
                        continue;
                    }
                    first_bad = Some((field.clone(), tmpl.clone()));
                    break;
                }
                // Type-compatibility pass: when the caller's
                // `dynamic_templates: {foo: string}` maps a scalar
                // type (keyword/text/long/…) but the doc carries
                // dotted keys `foo.*` that would implicitly make
                // `foo` an object, ES rejects with
                // `failed to parse field [foo] of type [TYPE]`.
                if first_bad.is_none() {
                    if let Some(body) = doc_body.as_ref().and_then(Value::as_object) {
                        // Look up each referenced template's mapping
                        // spec so we can inspect its `type`.
                        let tmpl_specs: std::collections::HashMap<String, Value> = mapping
                            .as_ref()
                            .and_then(|m| {
                                m.get("mappings")
                                    .and_then(|mm| mm.get("dynamic_templates"))
                                    .or_else(|| m.get("dynamic_templates"))
                            })
                            .and_then(Value::as_array)
                            .map(|arr| {
                                arr.iter()
                                    .filter_map(|v| {
                                        v.as_object().and_then(|o| {
                                            let (name, spec) = o.iter().next()?;
                                            let mapping_spec =
                                                spec.get("mapping").cloned().unwrap_or(Value::Null);
                                            Some((name.clone(), mapping_spec))
                                        })
                                    })
                                    .collect()
                            })
                            .unwrap_or_default();
                        let mut first_type_clash: Option<(String, String, String)> = None;
                        for (field, tmpl) in dt_map {
                            let Some(spec) = tmpl_specs.get(tmpl) else {
                                continue;
                            };
                            let ftype = spec.get("type").and_then(Value::as_str).unwrap_or("");
                            // Scalar-like types that can't hold an object.
                            let scalar = matches!(
                                ftype,
                                "keyword"
                                    | "text"
                                    | "match_only_text"
                                    | "long"
                                    | "integer"
                                    | "short"
                                    | "byte"
                                    | "double"
                                    | "float"
                                    | "boolean"
                                    | "date"
                                    | "date_nanos"
                                    | "ip"
                                    | "binary"
                                    | "half_float"
                                    | "scaled_float"
                                    | "unsigned_long"
                                    | "geo_point"
                            );
                            if !scalar {
                                continue;
                            }
                            let prefix = format!("{}.", field);
                            let has_dotted = body.keys().any(|k| k.starts_with(&prefix));
                            if !has_dotted {
                                continue;
                            }
                            // Build a preview of the "object-shaped"
                            // value ES would render (e.g. `{bar=hello world}`).
                            let mut parts: Vec<String> = Vec::new();
                            for (k, v) in body.iter() {
                                if !k.starts_with(&prefix) {
                                    continue;
                                }
                                let sub_key = &k[prefix.len()..];
                                let rendered = match v {
                                    Value::String(s) => s.clone(),
                                    other => other.to_string(),
                                };
                                parts.push(format!("{}={}", sub_key, rendered));
                            }
                            let preview = format!("{{{}}}", parts.join(", "));
                            first_type_clash = Some((field.clone(), ftype.to_string(), preview));
                            break;
                        }
                        if let Some((field, ftype, preview)) = first_type_clash {
                            let reason = format!(
                                "failed to parse field [{}] of type [{}] in document with id '{}'. Preview of field's value: '{}'",
                                field, ftype,
                                doc_id.clone().unwrap_or_default(),
                                preview
                            );
                            items[item_idx] = Some(BulkItemResult {
                                action: action_type.to_string(),
                                index: target_index.clone(),
                                id: error_id.clone(),
                                status: 400,
                                result: None,
                                error: Some(reason),
                                get_source: None,
                            });
                            errors = true;
                            continue;
                        }
                    }
                }
                if let Some((field, tmpl)) = first_bad {
                    let reason = format!(
                        "Can't find dynamic template for dynamic template name [{}] of field [{}]",
                        tmpl, field
                    );
                    items[item_idx] = Some(BulkItemResult {
                        action: action_type.to_string(),
                        index: target_index.clone(),
                        id: error_id,
                        status: 400,
                        result: None,
                        error: Some(reason),
                        get_source: None,
                    });
                    errors = true;
                    continue;
                }
            }
        }
        // Date-format validation: if any field is declared as
        // `type: date` with an explicit `format` (no `ignore_malformed`
        // override), values that don't parse against the format are
        // rejected at ingest as ES does — `document_parsing_exception`
        // at the bulk item level. We only apply this for `index` /
        // `create`; updates operate on already-stored docs.
        if matches!(action_type.as_str(), "index" | "create") {
            if let Some(body) = doc_body.as_ref().and_then(Value::as_object) {
                let mapping_props = engine.index_mappings.get(&target_index).and_then(|m| {
                    m.get("properties")
                        .or_else(|| m.get("mappings").and_then(|mm| mm.get("properties")))
                        .cloned()
                });
                if let Some(props) = mapping_props {
                    if let Some(bad) = find_bad_date_field(body, &props) {
                        let reason = format!(
                            "failed to parse field [{}] of type [date] in document with id '{}'",
                            bad.0,
                            doc_id.clone().unwrap_or_default(),
                        );
                        items[item_idx] = Some(BulkItemResult {
                            action: action_type.to_string(),
                            index: target_index.clone(),
                            id: error_id.clone(),
                            status: 400,
                            result: None,
                            error: Some(reason),
                            get_source: None,
                        });
                        errors = true;
                        continue;
                    }
                }
            }
        }
        // Numeric / boolean type enforcement (issue #781). A field mapped
        // `integer` used to keep whatever arrived — `1.9`, `9999999999`,
        // `"abc"`, even an object — so the same query over the same declared
        // -integer field returned different hits than ES. Values ES coerces
        // are coerced here (`1.9` → `1`, `"5"` → `5`, `"true"` → `true`) and
        // values ES refuses become a per-item 400 `document_parsing_exception`,
        // exactly like the date-format check above. `index` / `create` only:
        // an `update` merges into a doc that was already validated on write.
        //
        // The rules live in `xerj_common::field_coercion`, shared with the
        // single-document `_doc` / `_create` handlers in `xerj-api`, so the
        // two write paths cannot drift apart.
        if matches!(action_type.as_str(), "index" | "create") {
            let mapping_props = typed_numeric_props(&target_index, &mut index_type_check_props);
            if let Some(props) = mapping_props {
                if let Some(body) = doc_body.as_mut().and_then(Value::as_object_mut) {
                    if let Err(bad) = xerj_common::field_coercion::coerce_document(body, &props) {
                        items[item_idx] = Some(BulkItemResult {
                            action: action_type.to_string(),
                            index: target_index.clone(),
                            id: error_id.clone(),
                            status: 400,
                            result: None,
                            error: Some(bad.reason(&doc_id.clone().unwrap_or_default())),
                            get_source: None,
                        });
                        errors = true;
                        continue;
                    }
                }
            }
        }
        // doc_body already lazy-parsed above (for dynamic-templates
        // validation). Nothing else to do here.
        let result = execute_bulk_action(
            engine,
            &action_type,
            &target_index,
            doc_id,
            doc_body,
            if_seq_no,
            if_primary_term,
            routing,
        )
        .await;

        match result {
            Ok(resp) => {
                // ES bulk semantics: 201 on first create, 200 on
                // overwrite (update). Delete → 200. Engine reports the
                // fact via `resp.result` ("created" vs "updated").
                let status: u16 = match action_type.as_str() {
                    "delete" => 200,
                    _ if resp.result == "updated" || resp.result == "noop" => 200,
                    _ => 201,
                };
                // Bulk update supports echoing the post-update source
                // via `items[N].update.get._source`. Source spec comes
                // from (priority): action metadata → doc-body `_source`
                // → URL-level default (?_source=true).
                let effective_source_req =
                    source_req.clone().or_else(|| default_source_req.clone());
                let get_source: Option<Value> =
                    if action_type == "update" && effective_source_req.is_some() {
                        match doc_id_for_get.as_deref() {
                            Some(id) => match engine.get_index(&target_index_for_get) {
                                Ok(idx) => {
                                    let fetched = idx.get_document(id).await.ok().flatten();
                                    fetched.map(|src| {
                                        apply_bulk_source_filter(
                                            &src,
                                            effective_source_req.as_ref().unwrap(),
                                        )
                                    })
                                }
                                Err(_) => None,
                            },
                            None => None,
                        }
                    } else {
                        None
                    };
                items[item_idx] = Some(BulkItemResult {
                    action: action_type.clone(),
                    index: target_index,
                    id: resp.id,
                    status,
                    result: Some(resp.result),
                    error: None,
                    get_source,
                });
            }
            Err(e) => {
                errors = true;
                // Map engine-level errors to the correct HTTP status so
                // per-item error objects carry the status ES clients key
                // off of. VersionConflict → 409, NotFound → 404.
                let status = engine_error_http_status(&e);
                items[item_idx] = Some(BulkItemResult {
                    action: action_type,
                    index: target_index,
                    id: error_id,
                    status,
                    result: None,
                    error: Some(e.to_string()),
                    get_source: None,
                });
            }
        }
    }

    // Flatten — any slot still None is a parse error that already set its slot.
    let final_items: Vec<BulkItemResult> = items.into_iter().flatten().collect();

    let exec_ms = t_exec.elapsed().as_millis() as u64;
    let took_ms = started.elapsed().as_millis() as u64;
    // THROWAWAY prof (XERJ_PROF): whole-request bulk attribution.
    if std::env::var_os("XERJ_PROF").is_some() {
        eprintln!(
            "XERJ_PROF bulk total_ms={} lines_ms={} parse_ms={} group_ms={} exec_ms={} n_lines={}",
            took_ms,
            lines_ms,
            parse_ms,
            group_ms,
            exec_ms,
            lines.len()
        );
    }
    if took_ms >= 50 {
        tracing::debug!(
            total_ms = took_ms,
            lines_ms,
            parse_ms,
            group_ms,
            exec_ms,
            n_lines = lines.len(),
            "process_bulk timings"
        );
    }
    BulkResult {
        took_ms,
        errors,
        items: final_items,
    }
}

/// Apply a bulk-action `_source` request to a fetched document.
///
/// Accepts the same shapes the search body does:
/// - `true` / `false` — include everything / return `Value::Null`
/// - `"field"` — single include
/// - `["f1", "f2"]` — include list
/// - `{"includes": [...], "excludes": [...]}` — full filter
fn apply_bulk_source_filter(src: &Value, spec: &Value) -> Value {
    let obj = match src.as_object() {
        Some(o) => o.clone(),
        None => return src.clone(),
    };
    let (includes, excludes): (Vec<String>, Vec<String>) = match spec {
        Value::Bool(true) => return Value::Object(obj),
        Value::Bool(false) => return Value::Null,
        Value::String(s) => (vec![s.clone()], Vec::new()),
        Value::Array(arr) => (
            arr.iter()
                .filter_map(|v| v.as_str().map(String::from))
                .collect(),
            Vec::new(),
        ),
        Value::Object(o) => {
            let pull = |k: &str| -> Vec<String> {
                match o.get(k) {
                    Some(Value::Array(a)) => a
                        .iter()
                        .filter_map(|x| x.as_str().map(String::from))
                        .collect(),
                    Some(Value::String(s)) => vec![s.clone()],
                    _ => Vec::new(),
                }
            };
            (pull("includes"), pull("excludes"))
        }
        _ => return Value::Object(obj),
    };
    let mut out = serde_json::Map::new();
    for (k, v) in obj {
        let keep = includes.is_empty() || includes.iter().any(|inc| inc == &k);
        let drop = excludes.iter().any(|exc| exc == &k);
        if keep && !drop {
            out.insert(k, v);
        }
    }
    Value::Object(out)
}

/// Apply dynamic-template `copy_to` directives to a doc body at
/// ingest. For each field in the doc that isn't already in the
/// declared mapping, check every dynamic template in order; if the
/// field name matches a template's `match` pattern (or equals the
/// template's name when no pattern is declared) AND the template's
/// mapping specifies `copy_to`, splice the field's value into the
/// target field (supporting dotted target paths and array append
/// semantics). When the per-item action metadata pins a specific
/// template via `dynamic_templates: {field: tmpl_name}`, that
/// template takes priority.
pub fn apply_dynamic_template_copy_to_public(
    body: &mut serde_json::Map<String, Value>,
    mapping: Option<&Value>,
) {
    apply_dynamic_template_copy_to(body, mapping, None);
}

fn apply_dynamic_template_copy_to(
    body: &mut serde_json::Map<String, Value>,
    mapping: Option<&Value>,
    per_item: Option<&std::collections::BTreeMap<String, String>>,
) {
    let Some(mapping) = mapping else { return };
    let templates_v = mapping
        .get("mappings")
        .and_then(|m| m.get("dynamic_templates"))
        .or_else(|| mapping.get("dynamic_templates"));
    let Some(templates_arr) = templates_v.and_then(Value::as_array) else {
        return;
    };
    if templates_arr.is_empty() {
        return;
    }
    let declared_props: std::collections::HashSet<String> = mapping
        .get("mappings")
        .and_then(|m| m.get("properties"))
        .or_else(|| mapping.get("properties"))
        .and_then(Value::as_object)
        .map(|o| o.keys().cloned().collect())
        .unwrap_or_default();

    // Pre-extract (name, pattern, copy_to) triples, ordered.
    let specs: Vec<(String, Option<String>, Option<String>)> = templates_arr
        .iter()
        .filter_map(|v| {
            let (name, body) = v.as_object().and_then(|o| o.iter().next())?;
            let pattern = body.get("match").and_then(Value::as_str).map(String::from);
            let copy_to =
                body.get("mapping")
                    .and_then(|m| m.get("copy_to"))
                    .and_then(|c| match c {
                        Value::String(s) => Some(s.clone()),
                        Value::Array(a) => a.first().and_then(Value::as_str).map(String::from),
                        _ => None,
                    });
            Some((name.clone(), pattern, copy_to))
        })
        .collect();

    let field_names: Vec<String> = body.keys().cloned().collect();
    let mut touched_targets: Vec<String> = Vec::new();
    let mut pristine: serde_json::Map<String, Value> = serde_json::Map::new();
    for field in field_names {
        if declared_props.contains(&field) {
            continue;
        }
        // Priority 1: per-item `dynamic_templates: {field: name}`.
        let forced = per_item.and_then(|m| m.get(&field).cloned());
        let mut chosen: Option<String> = None;
        if let Some(name) = forced {
            if let Some((_, _, copy_to)) = specs.iter().find(|(n, _, _)| n == &name) {
                chosen = copy_to.clone();
            }
        }
        // Priority 2: first matching template in declaration order.
        if chosen.is_none() {
            for (name, pattern, copy_to) in &specs {
                let matches = if let Some(pat) = pattern {
                    simple_glob_matches(pat.as_bytes(), field.as_bytes())
                } else {
                    field == name.as_str()
                };
                if matches {
                    chosen = copy_to.clone();
                    break;
                }
            }
        }
        let Some(target_path) = chosen else { continue };
        let Some(val) = body.get(&field).cloned() else {
            continue;
        };
        // Snapshot the target's pristine value before mutation so
        // the synthetic-source emit path can restore the explicit-
        // only source shape. Matches apply_copy_to's convention.
        if !touched_targets.iter().any(|t| t == &target_path) {
            let pristine_val = path_get(body, &target_path).cloned().unwrap_or(Value::Null);
            pristine.insert(target_path.clone(), pristine_val);
            touched_targets.push(target_path.clone());
        }
        // Append value into target path (splat arrays like
        // apply_copy_to does). Keyword-ish target types expect
        // strings; the synthetic_source + fields fetch path handles
        // stringification downstream, so we preserve the original
        // value shape here.
        match val {
            Value::Array(arr) => {
                for v in arr {
                    append_copy_to_path(body, &target_path, v);
                }
            }
            other => append_copy_to_path(body, &target_path, other),
        }
    }
    if !touched_targets.is_empty() {
        // Merge with any existing pristine snapshot (apply_copy_to
        // from the declared-schema path may have already written
        // one; keep both sets of restore entries).
        if let Some(Value::Object(existing)) = body.get("__xy_copy_to_pristine__").cloned() {
            for (k, v) in existing {
                pristine.entry(k).or_insert(v);
            }
        }
        body.insert(
            "__xy_copy_to_pristine__".to_string(),
            Value::Object(pristine),
        );
    }
}

fn path_get<'a>(root: &'a serde_json::Map<String, Value>, path: &str) -> Option<&'a Value> {
    let segs: Vec<&str> = path.split('.').collect();
    if segs.is_empty() {
        return None;
    }
    let mut cur: &Value = root.get(segs[0])?;
    for seg in &segs[1..] {
        cur = cur.as_object()?.get(*seg)?;
    }
    Some(cur)
}

fn append_copy_to_path(target: &mut serde_json::Map<String, Value>, path: &str, val: Value) {
    let segs: Vec<&str> = path.split('.').collect();
    if segs.is_empty() {
        return;
    }
    let last = segs.len() - 1;
    let mut cur: &mut serde_json::Map<String, Value> = target;
    for (i, seg) in segs.iter().enumerate() {
        if i == last {
            let entry = cur.entry((*seg).to_string()).or_insert(Value::Null);
            match entry {
                Value::Null => {
                    *entry = val;
                    return;
                }
                Value::Array(arr) => {
                    arr.push(val);
                    return;
                }
                existing => {
                    let prev = existing.clone();
                    *existing = Value::Array(vec![prev, val]);
                    return;
                }
            }
        }
        let entry = cur
            .entry((*seg).to_string())
            .or_insert_with(|| Value::Object(serde_json::Map::new()));
        if !entry.is_object() {
            let old = entry.take();
            let mut m = serde_json::Map::new();
            m.insert("__xy_scalar__".to_string(), old);
            *entry = Value::Object(m);
        }
        cur = entry.as_object_mut().unwrap();
    }
}

/// Does this mapping-properties tree contain at least one
/// `type: date`/`type: date_nanos` field that has an explicit
/// `format` set AND does not opt into `ignore_malformed`? When true,
/// ingest must parse-validate date values on this index.
fn mapping_has_strict_date(props: &Value) -> bool {
    let Some(obj) = props.as_object() else {
        return false;
    };
    for (_, spec) in obj {
        let ftype = spec.get("type").and_then(Value::as_str).unwrap_or("");
        if (ftype == "date" || ftype == "date_nanos")
            && spec.get("format").and_then(Value::as_str).is_some()
            && !spec
                .get("ignore_malformed")
                .and_then(Value::as_bool)
                .unwrap_or(false)
        {
            return true;
        }
        if let Some(sub) = spec.get("properties") {
            if mapping_has_strict_date(sub) {
                return true;
            }
        }
    }
    false
}

/// True when any field in the mapping is a `semantic_text` field. Such
/// fields auto-embed their text into a companion `<field>_vector` at
/// ingest, which only happens on the per-doc `index_document` path
/// (`Index::apply_semantic_embeddings`). The turbo auto-id batch path
/// stores the raw NDJSON bytes and never parses/embeds them, so an index
/// with a `semantic_text` field MUST be routed through the per-doc path —
/// otherwise auto-id bulk docs land with an empty vector column and
/// `semantic`/`knn` search silently returns nothing.
fn mapping_has_semantic_text(props: &Value) -> bool {
    let Some(obj) = props.as_object() else {
        return false;
    };
    for (_, spec) in obj {
        if spec.get("type").and_then(Value::as_str) == Some("semantic_text") {
            return true;
        }
        if let Some(sub) = spec.get("properties") {
            if mapping_has_semantic_text(sub) {
                return true;
            }
        }
    }
    false
}

/// Walk a doc body against the index's mapping properties to find
/// the first field that is declared as `type: date` with a `format`
/// set, `ignore_malformed` off, and a value that doesn't parse
/// against the declared format. Returns `(field_name, bad_value)`
/// or `None` when everything checks out. ES `date_optional_time` and
/// `strict_date_optional_time*` formats cover ISO-8601; `epoch_*`
/// require purely numeric strings / numbers.
fn find_bad_date_field(
    doc: &serde_json::Map<String, Value>,
    props: &Value,
) -> Option<(String, Value)> {
    let props_obj = props.as_object()?;
    for (fname, spec) in props_obj {
        let Some(val) = doc.get(fname) else { continue };
        let ftype = spec.get("type").and_then(Value::as_str).unwrap_or("");
        if ftype != "date" && ftype != "date_nanos" {
            continue;
        }
        let fmt = spec.get("format").and_then(Value::as_str).unwrap_or("");
        if fmt.is_empty() {
            continue;
        }
        let ignore_mal = spec
            .get("ignore_malformed")
            .and_then(Value::as_bool)
            .unwrap_or(false);
        if ignore_mal {
            continue;
        }
        // Pick the single value to validate — arrays recurse over
        // each element, using the first failure we find.
        let candidates: Vec<&Value> = match val {
            Value::Array(arr) => arr.iter().collect(),
            other => vec![other],
        };
        for cand in candidates {
            if !date_value_parses(cand, fmt) {
                return Some((fname.clone(), cand.clone()));
            }
        }
    }
    None
}

/// Does `val` parse against the ES date `fmt`?
///
/// This is the `ignore_malformed: false` path — a `false` here rejects the
/// whole document with `document_parsing_exception`. It delegates to
/// [`xerj_query::dates::date_value_valid_with_format`], which is also what
/// the `ignore_malformed: true` path calls, so the two cannot disagree.
///
/// They used to, and in the wrong direction: this function hand-rolled its
/// own rules and ended with a blanket `true` for "named or custom patterns",
/// so under a declared format like `dd/MM/yyyy` the value `"literally
/// anything"` was accepted here while the *lenient* path dropped it. Setting
/// `ignore_malformed: false` — asking for stricter handling — made the engine
/// accept strictly more. Keep this a delegation.
fn date_value_parses(val: &Value, fmt: &str) -> bool {
    xerj_query::dates::date_value_valid_with_format(val, fmt)
}

/// `*`-glob match (single wildcard segment, no `**`, no character
/// classes). Used to test a field name against a dynamic-template
/// `match` pattern.
fn simple_glob_matches(pat: &[u8], txt: &[u8]) -> bool {
    let (mut p, mut t) = (0usize, 0usize);
    let (mut star, mut star_t) = (None::<usize>, 0usize);
    while t < txt.len() {
        if p < pat.len() && (pat[p] == b'?' || pat[p] == txt[t]) {
            p += 1;
            t += 1;
        } else if p < pat.len() && pat[p] == b'*' {
            star = Some(p);
            star_t = t;
            p += 1;
        } else if let Some(sp) = star {
            p = sp + 1;
            star_t += 1;
            t = star_t;
        } else {
            return false;
        }
    }
    while p < pat.len() && pat[p] == b'*' {
        p += 1;
    }
    p == pat.len()
}

// Per-item bulk execution needs all 8 pieces of action metadata (target,
// id, body, CAS pair, routing); grouping them into a struct would just
// reshuffle the same fields, so allow the arg count here.
#[allow(clippy::too_many_arguments)]
async fn execute_bulk_action(
    engine: &Engine,
    action_type: &str,
    index: &str,
    doc_id: Option<String>,
    body: Option<Value>,
    if_seq_no: Option<u64>,
    if_primary_term: Option<u64>,
    routing: Option<String>,
) -> Result<IndexResponse> {
    // Inject `_routing` into the source body so `exists: _routing` and
    // `fields: [_routing]` resolve through the stored doc.
    let inject_routing = |body: Option<Value>| -> Option<Value> {
        match routing.as_deref() {
            Some(r) => {
                let mut v = body.unwrap_or(Value::Object(serde_json::Map::new()));
                if let Some(obj) = v.as_object_mut() {
                    obj.insert("_routing".to_string(), Value::String(r.to_string()));
                }
                Some(v)
            }
            None => body,
        }
    };
    match action_type {
        "index" => {
            // index: create or overwrite. Honors `if_seq_no` for
            // optimistic concurrency — a mismatch bubbles up as a
            // VersionConflict engine error which the caller maps to a
            // 409 per-item error.
            let idx = engine.get_or_create_index(index)?;
            let source = inject_routing(body).unwrap_or(Value::Object(serde_json::Map::new()));
            if if_seq_no.is_some() || if_primary_term.is_some() {
                idx.index_document_with_version(doc_id, source, if_seq_no, if_primary_term)
                    .await
            } else {
                idx.index_document(doc_id, source).await
            }
        }
        "create" => {
            // create: fail with 409 if document already exists.
            let idx = engine.get_or_create_index(index)?;
            let source = inject_routing(body).unwrap_or(Value::Object(serde_json::Map::new()));
            let id = doc_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
            idx.create_document(id, source).await
        }
        "update" => {
            // Partial update: merge `doc` fields into the existing document.
            let idx = engine.get_or_create_index(index)?;
            let id = doc_id.ok_or_else(|| {
                crate::EngineError::Common(xerj_common::XerjError::invalid_query(
                    "update action requires _id",
                ))
            })?;

            let body_val = body.unwrap_or(Value::Object(serde_json::Map::new()));
            let partial = body_val.get("doc").cloned();
            let upsert = body_val.get("upsert").cloned();
            let doc_as_upsert = body_val
                .get("doc_as_upsert")
                .and_then(Value::as_bool)
                .unwrap_or(false);

            match idx
                .update_document_with_upsert(&id, partial, upsert, doc_as_upsert)
                .await?
            {
                Some(resp) => Ok(resp),
                None => Err(crate::EngineError::Common(
                    xerj_common::XerjError::document_not_found(&id, index),
                )),
            }
        }
        "delete" => {
            let idx = engine.get_index(index)?;
            let id = doc_id.ok_or_else(|| {
                crate::EngineError::Common(xerj_common::XerjError::invalid_query(
                    "delete action requires _id",
                ))
            })?;
            idx.delete_document(&id).await?;
            Ok(IndexResponse {
                id,
                seq_no: 0,
                version: 0,
                result: "deleted".to_string(),
            })
        }
        other => Err(crate::EngineError::Common(
            xerj_common::XerjError::invalid_query(format!("unknown bulk action: {other}")),
        )),
    }
}

#[cfg(test)]
mod semantic_lifecycle_tests {
    use super::*;
    use crate::ingest_memory::{Category, Ledger, Measurement};
    use serde_json::json;
    use std::sync::{Arc, Mutex};
    use tempfile::TempDir;
    use xerj_common::config::Config;
    use xerj_common::types::{EmbeddingConfig, FieldConfig, FieldType, Schema};

    fn semantic_engine(name: &str) -> (TempDir, Engine) {
        semantic_engine_with_targets(name, &[("content", "content_vector")])
    }

    fn semantic_engine_with_targets(name: &str, targets: &[(&str, &str)]) -> (TempDir, Engine) {
        let dir = TempDir::new().unwrap();
        let mut config = Config::default();
        config.server.data_dir = dir.path().to_string_lossy().into_owned();
        let engine = Engine::new(config).unwrap();
        let mut schema = Schema::empty();
        for (field, target) in targets {
            let mut config = FieldConfig::new(*field, FieldType::Text);
            config.options.dimensions = Some(16);
            config.embedding = Some(EmbeddingConfig {
                endpoint: None,
                model: None,
                target_field: Some((*target).into()),
            });
            schema.fields.push(config);
        }
        engine.create_index(name, schema).unwrap();
        let properties = targets
            .iter()
            .map(|(field, _)| ((*field).to_string(), json!({"type": "semantic_text"})))
            .collect::<serde_json::Map<_, _>>();
        engine
            .put_index_mapping(name, json!({"properties": properties}))
            .unwrap();
        (dir, engine)
    }

    fn current(ledger: &Ledger, category: Category) -> u64 {
        ledger.gauge(category, Measurement::Estimated).current
    }

    fn all_semantic_current(ledger: &Ledger) -> u64 {
        [
            Category::RawSource,
            Category::ParsedSource,
            Category::ParsedVector,
            Category::PreparedDocument,
            Category::PreparedVector,
        ]
        .into_iter()
        .map(|category| current(ledger, category))
        .sum()
    }

    #[test]
    fn raw_owner_token_outlives_every_arc_occurrence() {
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        let source: Arc<[u8]> = Arc::from(&b"{\"content\":\"retained\"}"[..]);
        let owner = Arc::as_ptr(&source) as *const () as usize;
        let mut owners = std::collections::HashMap::from([(
            owner,
            (
                2,
                crate::ingest_memory::Retained::for_ledger(
                    ledger,
                    Category::RawSource,
                    source.len(),
                ),
            ),
        )]);
        let second = Arc::clone(&source);

        release_raw_owner(&mut owners, second);
        assert_eq!(Arc::strong_count(&source), 1);
        assert_eq!(owners.get(&owner).map(|entry| entry.0), Some(1));
        assert_eq!(current(ledger, Category::RawSource), source.len() as u64);

        release_raw_owner(&mut owners, source);
        assert!(owners.is_empty());
        assert_eq!(current(ledger, Category::RawSource), 0);
    }

    async fn run_case(
        name: &str,
        fault: SemanticLifecycleFault,
    ) -> (
        BulkResult,
        &'static Ledger,
        Vec<(SemanticLifecyclePoint, [u64; 5])>,
    ) {
        let (_dir, engine) = semantic_engine_with_targets(
            name,
            &[("content", "content_vector"), ("summary", "summary_vector")],
        );
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        // Zero-capacity rendezvous channels make every hook a genuine phase
        // barrier: the ingest task cannot advance until the observer has read
        // the live gauges and explicitly released it.
        let expected = if fault == SemanticLifecycleFault::Embedding {
            4
        } else {
            8
        };
        let (observation_tx, observation_rx) = std::sync::mpsc::sync_channel(0);
        let (resume_tx, resume_rx) = std::sync::mpsc::sync_channel(0);
        let resume_rx = Arc::new(Mutex::new(resume_rx));
        let observer = std::thread::spawn(move || {
            let mut points = Vec::with_capacity(expected);
            for _ in 0..expected {
                points.push(observation_rx.recv().unwrap());
                resume_tx.send(()).unwrap();
            }
            points
        });
        let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
            observation_tx
                .send((
                    point,
                    [
                        current(ledger, Category::RawSource),
                        current(ledger, Category::ParsedSource),
                        current(ledger, Category::ParsedVector),
                        current(ledger, Category::PreparedDocument),
                        current(ledger, Category::PreparedVector),
                    ],
                ))
                .unwrap();
            resume_rx.lock().unwrap().recv().unwrap();
            match (fault, point) {
                (SemanticLifecycleFault::Embedding, SemanticLifecyclePoint::EmbeddingInside) => {
                    fault
                }
                (
                    SemanticLifecycleFault::Publication,
                    SemanticLifecyclePoint::PublicationInside,
                ) => fault,
                _ => SemanticLifecycleFault::None,
            }
        });
        let body = format!(
            "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"one\"}}}}\n\
             {{\"content\":\"caller supplied vector\",\
             \"content_vector\":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,\
             0.9,1.0,1.1,1.2,1.3,1.4,1.5,1.6],\
             \"summary\":\"a genuine semantic lifecycle embedding job\"}}\n"
        );
        let result = crate::ingest_memory::with_test_ledger(
            ledger,
            with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
        )
        .await;
        let points = observer.join().unwrap();
        (result, ledger, points)
    }

    #[tokio::test]
    async fn semantic_lifecycle_success_balances_isolated_ledger() {
        let (result, ledger, points) =
            run_case("semantic-lifecycle-success", SemanticLifecycleFault::None).await;
        assert!(!result.errors, "{:?}", result.items);
        let phase_points: Vec<_> = points.iter().map(|(point, _)| *point).collect();
        assert_eq!(
            phase_points,
            [
                SemanticLifecyclePoint::Grouped,
                SemanticLifecyclePoint::Parsed,
                SemanticLifecyclePoint::EmbeddingInside,
                SemanticLifecyclePoint::EmbeddingItemInside,
                SemanticLifecyclePoint::Prepared,
                SemanticLifecyclePoint::BeforePublication,
                SemanticLifecyclePoint::PublicationInside,
                SemanticLifecyclePoint::AfterPublication,
            ]
        );
        let at = |point| points.iter().find(|(p, _)| *p == point).unwrap().1;
        assert!(at(SemanticLifecyclePoint::Grouped)[0] > 0);
        assert_eq!(at(SemanticLifecyclePoint::Parsed)[0], 0);
        assert!(at(SemanticLifecyclePoint::Parsed)[1] > 0);
        assert!(at(SemanticLifecyclePoint::EmbeddingInside)[1] > 0);
        assert!(
            at(SemanticLifecyclePoint::EmbeddingInside)[2] > 0,
            "caller-supplied vector ownership must remain live while embedding is blocked"
        );
        assert_eq!(at(SemanticLifecyclePoint::BeforePublication)[1], 0);
        assert!(at(SemanticLifecyclePoint::BeforePublication)[3] > 0);
        assert!(at(SemanticLifecyclePoint::BeforePublication)[4] > 0);
        assert_eq!(at(SemanticLifecyclePoint::AfterPublication), [0; 5]);
        assert!(current(ledger, Category::RawSource) == 0);
        assert!(
            ledger
                .gauge(Category::RawSource, Measurement::SerializedSize)
                .peak
                > 0
        );
        assert!(
            ledger
                .gauge(Category::ParsedSource, Measurement::Estimated)
                .peak
                > 0
        );
        assert!(
            ledger
                .gauge(Category::PreparedDocument, Measurement::Estimated)
                .peak
                > 0
        );
        assert!(
            ledger
                .gauge(Category::PreparedVector, Measurement::ExactCapacity)
                .peak
                > 0
        );
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
        assert_eq!(all_semantic_current(&crate::ingest_memory::LEDGER), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_embedding_error_releases_parsed_ownership() {
        let (result, ledger, points) = run_case(
            "semantic-lifecycle-embed-error",
            SemanticLifecycleFault::Embedding,
        )
        .await;
        assert!(result.errors);
        assert_eq!(result.items[0].status, 400);
        let phase_points: Vec<_> = points.iter().map(|(point, _)| *point).collect();
        assert_eq!(
            phase_points,
            [
                SemanticLifecyclePoint::Grouped,
                SemanticLifecyclePoint::Parsed,
                SemanticLifecyclePoint::EmbeddingInside,
                SemanticLifecyclePoint::Prepared,
            ]
        );
        let inside = points
            .iter()
            .find(|(point, _)| *point == SemanticLifecyclePoint::EmbeddingInside)
            .unwrap()
            .1;
        assert!(inside[1] > 0);
        assert!(
            inside[2] > 0,
            "caller-supplied vector ownership must remain live while embedding is blocked"
        );
        assert!(
            ledger
                .gauge(Category::ParsedSource, Measurement::Estimated)
                .peak
                > 0
        );
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_publication_error_releases_prepared_ownership() {
        let (result, ledger, points) = run_case(
            "semantic-lifecycle-publication-error",
            SemanticLifecycleFault::Publication,
        )
        .await;
        assert!(result.errors);
        assert_eq!(result.items[0].status, 400);
        let phase_points: Vec<_> = points.iter().map(|(point, _)| *point).collect();
        assert_eq!(
            phase_points,
            [
                SemanticLifecyclePoint::Grouped,
                SemanticLifecyclePoint::Parsed,
                SemanticLifecyclePoint::EmbeddingInside,
                SemanticLifecyclePoint::EmbeddingItemInside,
                SemanticLifecyclePoint::Prepared,
                SemanticLifecyclePoint::BeforePublication,
                SemanticLifecyclePoint::PublicationInside,
                SemanticLifecyclePoint::AfterPublication,
            ]
        );
        let inside = points
            .iter()
            .find(|(point, _)| *point == SemanticLifecyclePoint::PublicationInside)
            .unwrap()
            .1;
        assert!(inside[3] > 0);
        assert!(inside[4] > 0);
        assert!(
            ledger
                .gauge(Category::PreparedDocument, Measurement::Estimated)
                .peak
                > 0
        );
        assert!(
            ledger
                .gauge(Category::PreparedVector, Measurement::ExactCapacity)
                .peak
                > 0
        );
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_hook_scope_is_panic_safe_and_target_specific() {
        let (_dir, engine) = semantic_engine("semantic-lifecycle-panic");
        let engine = Arc::new(engine);
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        let hook: SemanticLifecycleHook = Arc::new(|_, point| {
            if point == SemanticLifecyclePoint::Grouped {
                panic!("deliberate lifecycle hook panic");
            }
            SemanticLifecycleFault::None
        });
        let body = concat!(
            "{\"index\":{\"_index\":\"semantic-lifecycle-panic\",\"_id\":\"one\"}}\n",
            "{\"content\":\"panic cleanup\"}\n",
        );
        let panic_engine = Arc::clone(&engine);
        let task = tokio::spawn(async move {
            crate::ingest_memory::with_test_ledger(
                ledger,
                with_semantic_lifecycle_hook(
                    "semantic-lifecycle-panic",
                    hook,
                    process_bulk(&panic_engine, None, body),
                ),
            )
            .await
        });
        assert!(task.await.unwrap_err().is_panic());
        assert_eq!(all_semantic_current(ledger), 0);

        let other_ledger = Box::leak(Box::new(Ledger::new()));
        let rejecting_hook: SemanticLifecycleHook =
            Arc::new(|_, _| SemanticLifecycleFault::Publication);
        let result = crate::ingest_memory::with_test_ledger(
            other_ledger,
            with_semantic_lifecycle_hook(
                "different-target",
                rejecting_hook,
                process_bulk(&engine, None, body),
            ),
        )
        .await;
        assert!(
            !result.errors,
            "target-specific hook leaked onto another target"
        );
        assert_eq!(all_semantic_current(other_ledger), 0);
        assert_eq!(all_semantic_current(&crate::ingest_memory::LEDGER), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_declines_after_each_sequential_publication() {
        let name = "semantic-lifecycle-sequential";
        let (_dir, engine) = semantic_engine(name);
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        let observations = Arc::new(Mutex::new(Vec::<(SemanticLifecyclePoint, u64, u64)>::new()));
        let captured = Arc::clone(&observations);
        let embedded = Arc::new(std::sync::atomic::AtomicBool::new(false));
        let embedded_hook = Arc::clone(&embedded);
        let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
            if point == SemanticLifecyclePoint::EmbeddingInside {
                embedded_hook.store(true, std::sync::atomic::Ordering::Relaxed);
            }
            if matches!(
                point,
                SemanticLifecyclePoint::BeforePublication
                    | SemanticLifecyclePoint::AfterPublication
            ) {
                captured.lock().unwrap().push((
                    point,
                    current(ledger, Category::PreparedDocument),
                    current(ledger, Category::PreparedVector),
                ));
            }
            SemanticLifecycleFault::None
        });
        let body = (0..3)
            .map(|i| {
                format!(
                    "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{i}\"}}}}\n\
                     {{\"content\":\"semantic document number {i}\"}}\n"
                )
            })
            .collect::<String>();
        let result = crate::ingest_memory::with_test_ledger(
            ledger,
            with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
        )
        .await;
        assert!(!result.errors, "{:?}", result.items);
        assert!(embedded.load(std::sync::atomic::Ordering::Relaxed));
        let observations = observations.lock().unwrap();
        assert_eq!(observations.len(), 6);
        for pair in observations.as_chunks::<2>().0 {
            assert_eq!(pair[0].0, SemanticLifecyclePoint::BeforePublication);
            assert_eq!(pair[1].0, SemanticLifecyclePoint::AfterPublication);
            assert!(pair[0].1 > pair[1].1);
            assert!(pair[0].2 > pair[1].2);
        }
        for pair in observations.as_chunks::<2>().0 {
            assert!(pair[0].1 > 0);
            assert!(pair[0].2 > 0);
            assert_eq!(pair[1].1, 0, "published document ownership stayed charged");
            assert_eq!(pair[1].2, 0, "published vector ownership stayed charged");
        }
        assert_eq!(observations.last().unwrap().1, 0);
        assert_eq!(observations.last().unwrap().2, 0);
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_mixed_publication_outputs_balance_per_item() {
        let name = "semantic-lifecycle-mixed";
        let (_dir, engine) = semantic_engine(name);
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        let publication = Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let publication_hook = Arc::clone(&publication);
        let points = Arc::new(Mutex::new(Vec::new()));
        let captured_points = Arc::clone(&points);
        let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
            captured_points.lock().unwrap().push(point);
            if point == SemanticLifecyclePoint::PublicationInside
                && publication_hook.fetch_add(1, std::sync::atomic::Ordering::Relaxed) == 1
            {
                SemanticLifecycleFault::Publication
            } else {
                SemanticLifecycleFault::None
            }
        });
        let body = (0..3)
            .map(|i| {
                format!(
                    "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{i}\"}}}}\n\
                     {{\"content\":\"mixed output {i}\"}}\n"
                )
            })
            .collect::<String>();
        let result = crate::ingest_memory::with_test_ledger(
            ledger,
            with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
        )
        .await;
        assert!(result.errors);
        assert_eq!(
            result
                .items
                .iter()
                .map(|item| item.status)
                .collect::<Vec<_>>(),
            [201, 400, 201]
        );
        let points = points.lock().unwrap();
        assert!(points.contains(&SemanticLifecyclePoint::EmbeddingInside));
        assert_eq!(
            points
                .iter()
                .filter(|point| **point == SemanticLifecyclePoint::PublicationInside)
                .count(),
            3
        );
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_mixed_embedding_outputs_balance_per_item() {
        let name = "semantic-lifecycle-mixed-embedding";
        let (_dir, engine) = semantic_engine(name);
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        let item = Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let item_hook = Arc::clone(&item);
        let points = Arc::new(Mutex::new(Vec::new()));
        let captured_points = Arc::clone(&points);
        let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
            captured_points.lock().unwrap().push((
                point,
                current(ledger, Category::ParsedSource),
                current(ledger, Category::ParsedVector),
            ));
            if point == SemanticLifecyclePoint::EmbeddingItemInside
                && item_hook.fetch_add(1, std::sync::atomic::Ordering::Relaxed) == 1
            {
                SemanticLifecycleFault::Embedding
            } else {
                SemanticLifecycleFault::None
            }
        });
        let body = (0..3)
            .map(|i| {
                format!(
                    "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{i}\"}}}}\n\
                     {{\"content\":\"mixed embedding output {i}\"}}\n"
                )
            })
            .collect::<String>();
        let result = crate::ingest_memory::with_test_ledger(
            ledger,
            with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
        )
        .await;
        assert!(result.errors);
        assert_eq!(
            result
                .items
                .iter()
                .map(|item| item.status)
                .collect::<Vec<_>>(),
            [201, 500, 201]
        );
        let points = points.lock().unwrap();
        assert!(points.iter().any(|(point, parsed, _)| *point
            == SemanticLifecyclePoint::EmbeddingInside
            && *parsed > 0));
        assert_eq!(
            points
                .iter()
                .filter(|(point, _, _)| *point == SemanticLifecyclePoint::EmbeddingItemInside)
                .count(),
            3
        );
        assert_eq!(
            points
                .iter()
                .filter(|(point, _, _)| *point == SemanticLifecyclePoint::PublicationInside)
                .count(),
            2
        );
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_covers_malformed_caller_vectors_and_literal_dotted_target() {
        let name = "semantic-lifecycle-input-shapes";
        let (_dir, engine) =
            semantic_engine_with_targets(name, &[("content", "custom.vector"), ("summary", "v2")]);
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        let points = Arc::new(Mutex::new(Vec::new()));
        let captured_points = Arc::clone(&points);
        let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
            captured_points.lock().unwrap().push(point);
            SemanticLifecycleFault::None
        });
        let body = format!(
            "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"bad\"}}}}\n\
             {{\"content\":\n\
             {{\"index\":{{\"_index\":\"{name}\",\"_id\":\"supplied\"}}}}\n\
             {{\"content\":\"caller vector\",\"custom.vector\":[0.1,0.2,0.3],\
             \"summary\":\"second target\",\"v2\":[0.4,0.5]}}\n\
             {{\"index\":{{\"_index\":\"{name}\",\"_id\":\"derived\"}}}}\n\
             {{\"content\":\"derive literal dotted target\",\"summary\":\"derive second\"}}\n"
        );
        let result = crate::ingest_memory::with_test_ledger(
            ledger,
            with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
        )
        .await;
        assert!(result.errors);
        assert_eq!(
            result
                .items
                .iter()
                .map(|item| item.status)
                .collect::<Vec<_>>(),
            [400, 201, 201]
        );
        assert!(
            ledger
                .gauge(Category::ParsedVector, Measurement::ExactCapacity)
                .peak
                > 0
        );
        let points = points.lock().unwrap();
        assert!(points.contains(&SemanticLifecyclePoint::EmbeddingInside));
        assert_eq!(
            points
                .iter()
                .filter(|point| **point == SemanticLifecyclePoint::PublicationInside)
                .count(),
            2
        );
        assert!(
            ledger
                .gauge(Category::PreparedVector, Measurement::ExactCapacity)
                .peak
                > 0
        );
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
    }

    #[tokio::test]
    async fn semantic_lifecycle_multiple_targets_and_index_creation_failure_balance() {
        let ok = "semantic-lifecycle-target-a";
        let fails = "semantic-lifecycle-target-b";
        let (dir, engine) = semantic_engine(ok);
        let mut schema = Schema::empty();
        let mut content = FieldConfig::new("content", FieldType::Text);
        content.options.dimensions = Some(16);
        content.embedding = Some(EmbeddingConfig {
            endpoint: None,
            model: None,
            target_field: Some("content_vector".into()),
        });
        schema.fields.push(content);
        engine.create_index(fails, schema).unwrap();
        engine
            .put_index_mapping(
                fails,
                json!({"properties": {"content": {"type": "semantic_text"}}}),
            )
            .unwrap();
        let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
        let engine = Arc::new(engine);
        let hook_engine = Arc::clone(&engine);
        let collision = dir.path().join(fails);
        let points = Arc::new(Mutex::new(Vec::new()));
        let captured_points = Arc::clone(&points);
        let hook: SemanticLifecycleHook = Arc::new(move |target, point| {
            captured_points
                .lock()
                .unwrap()
                .push((target.to_string(), point));
            if target == fails && point == SemanticLifecyclePoint::Grouped {
                let engine = Arc::clone(&hook_engine);
                std::thread::spawn(move || {
                    tokio::runtime::Runtime::new()
                        .unwrap()
                        .block_on(engine.delete_index(fails))
                        .unwrap();
                })
                .join()
                .unwrap();
                std::fs::write(&collision, b"blocks index directory creation").unwrap();
            }
            SemanticLifecycleFault::None
        });
        let body = format!(
            "{{\"index\":{{\"_index\":\"{ok}\",\"_id\":\"ok\"}}}}\n\
             {{\"content\":\"first target\"}}\n\
             {{\"index\":{{\"_index\":\"{fails}\",\"_id\":\"fail\"}}}}\n\
             {{\"content\":\"second target\"}}\n"
        );
        let result = crate::ingest_memory::with_test_ledger(
            ledger,
            with_semantic_lifecycle_hook("*", hook, process_bulk(&engine, None, &body)),
        )
        .await;
        assert!(result.errors);
        assert_eq!(
            result
                .items
                .iter()
                .map(|item| item.status)
                .collect::<Vec<_>>(),
            [201, 500]
        );
        let points = points.lock().unwrap();
        assert!(points.contains(&(ok.to_string(), SemanticLifecyclePoint::EmbeddingInside)));
        assert!(points.contains(&(ok.to_string(), SemanticLifecyclePoint::PublicationInside)));
        assert!(points.contains(&(fails.to_string(), SemanticLifecyclePoint::Grouped)));
        assert!(!points.contains(&(fails.to_string(), SemanticLifecyclePoint::EmbeddingInside)));
        assert_eq!(all_semantic_current(ledger), 0);
        assert_eq!(ledger.accounting_errors(), 0);
    }

    #[tokio::test]
    async fn tracing_off_semantic_path_skips_all_instrumentation_structures() {
        assert_eq!(
            crate::ingest_memory::config().mode,
            crate::ingest_memory::TraceMode::Off,
            "this structural proof requires tracing to be off; it must not silently skip"
        );
        let name = "semantic-lifecycle-disabled";
        let (_dir, engine) = semantic_engine(name);
        let counters = Arc::new(DisabledSemanticCounters::default());
        let body = format!(
            "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"one\"}}}}\n\
             {{\"content\":\"disabled structural proof\"}}\n"
        );
        let result = DISABLED_SEMANTIC_COUNTERS
            .scope(Arc::clone(&counters), process_bulk(&engine, None, &body))
            .await;
        assert!(!result.errors, "{:?}", result.items);
        assert_eq!(
            counters.snapshot(),
            DisabledSemanticInstrumentation::default(),
            "tracing-off path read schema, allocated its guard vector, or walked JSON for sizing"
        );
        assert_eq!(all_semantic_current(&crate::ingest_memory::LEDGER), 0);
        assert_eq!(crate::ingest_memory::LEDGER.accounting_errors(), 0);
    }
}

#[cfg(test)]
mod lone_surrogate_tests {
    use super::*;
    use tempfile::TempDir;
    use xerj_common::config::Config;
    use xerj_common::types::Schema;

    fn plain_engine(name: &str) -> (TempDir, Engine) {
        let dir = TempDir::new().unwrap();
        let mut config = Config::default();
        config.server.data_dir = dir.path().to_string_lossy().into_owned();
        let engine = Engine::new(config).unwrap();
        engine.create_index(name, Schema::empty()).unwrap();
        (dir, engine)
    }

    /// The per-item scan must reject exactly the documents serde_json's own
    /// `Value` parse rejects for surrogate escapes — no more, no less. If it
    /// were stricter it would drop valid documents; if it were laxer the bad
    /// document would still reach the batch `Value` parse and sink its
    /// neighbours, which is the bug. Every case below first passes
    /// `IgnoredAny` (the fast path the scan runs after), so the comparison is
    /// apples-to-apples.
    #[test]
    fn surrogate_scan_matches_serde_value_decision() {
        // Build every `\uXXXX` escape from a runtime backslash (code point 92)
        // so the test source carries no literal escape sequences that a tool
        // or editor might normalise — the bytes under test are exactly these.
        let bs = char::from_u32(92).unwrap();
        let u = |hex: &str| format!("{bs}u{hex}");
        let body = |inner: String| format!(r#"{{"body":"{inner}"}}"#).into_bytes();
        let key = |inner: String| format!(r#"{{"{inner}":"v"}}"#).into_bytes();

        let cases: Vec<Vec<u8>> = vec![
            body("plain ascii".to_string()),
            body(format!("emoji {}{} ok", u("d83d"), u("de00"))), // valid pair
            body(format!("clef {}{}", u("d834"), u("dd1e"))),     // valid astral pair
            body(format!("a{}b", u("d83d"))),                     // lone high (issue #1304)
            body(u("d83d")),                                      // lone high at string end
            body(format!("{} low", u("dc00"))),                   // lone low surrogate
            body(format!("{}{}", u("d83d"), u("0041"))),          // high then a non-low escape
            body(format!("{}text", u("d83d"))),                   // high then plain text
            body(format!("{}{}", u("dc00"), u("d83d"))),          // low before high (both wrong)
            body(format!("escaped {}{}u1234 literal", bs, bs)),   // `\\u1234` is not an escape
            body(format!("{}t {}n {}{} tame", bs, bs, bs, bs)),   // ordinary escapes only
            body(format!("bom {} null {}", u("feff"), u("0000"))), // valid non-surrogate escapes
            key(format!("{}{}", u("d83d"), u("de00"))),           // valid pair in an object key
            key(u("d83d")),                                       // lone surrogate in a key
        ];
        for raw in &cases {
            let readable = String::from_utf8_lossy(raw);
            assert!(
                serde_json::from_slice::<serde::de::IgnoredAny>(raw).is_ok(),
                "precondition: IgnoredAny should accept {readable:?}",
            );
            let scan_rejects = lone_surrogate_escape_reason(raw).is_some();
            let value_rejects = serde_json::from_slice::<serde_json::Value>(raw).is_err();
            assert_eq!(
                scan_rejects, value_rejects,
                "scan and serde_json::Value disagree on {readable:?}",
            );
        }
    }

    /// Issue #1304: a single auto-id document carrying an unpaired UTF-16
    /// surrogate must fail per-item while its 127 well-formed neighbours
    /// index. Before the fix the whole batch failed with a single
    /// `lone leading surrogate in hex escape` and nothing was indexed.
    #[tokio::test]
    async fn one_lone_surrogate_does_not_sink_its_bulk_batch() {
        let name = "issue-1304";
        let (_dir, engine) = plain_engine(name);

        const TOTAL: usize = 128;
        const BAD_POS: usize = 42;
        let mut body = String::new();
        for i in 0..TOTAL {
            // Auto-id: no `_id`, so every doc is grouped into one turbo batch.
            body.push_str(&format!("{{\"index\":{{\"_index\":\"{name}\"}}}}\n"));
            if i == BAD_POS {
                // `"a" + String.fromCharCode(0xd83d) + "b"` -> `"a\ud83db"`.
                body.push_str("{\"body\":\"a\\ud83db\"}\n");
            } else {
                body.push_str(&format!("{{\"body\":\"chunk {i} is well formed\"}}\n"));
            }
        }

        let result = process_bulk(&engine, None, &body).await;

        assert!(
            result.errors,
            "a batch containing one bad document must report errors=true",
        );
        assert_eq!(result.items.len(), TOTAL);

        let failed: Vec<usize> = result
            .items
            .iter()
            .enumerate()
            .filter(|(_, item)| item.status != 201)
            .map(|(i, _)| i)
            .collect();
        assert_eq!(
            failed,
            vec![BAD_POS],
            "exactly the one unpaired-surrogate document must fail, not its neighbours",
        );

        let bad = &result.items[BAD_POS];
        assert_eq!(bad.status, 400, "the bad document is a 400, not a 500");
        assert!(
            bad.error
                .as_deref()
                .unwrap_or_default()
                .contains("surrogate"),
            "the per-item error should name the surrogate: {:?}",
            bad.error,
        );

        // The 127 good documents are actually indexed, not merely acked.
        let index = engine.get_index(name).unwrap();
        index.refresh().await.unwrap();
        assert_eq!(
            index.live_doc_count(),
            (TOTAL - 1) as u64,
            "every well-formed document in the batch must be indexed",
        );
    }

    /// Two bad documents in the same batch each fail on their own; the rest
    /// still index. Guards against an off-by-one in the per-item routing.
    #[tokio::test]
    async fn multiple_bad_surrogates_each_fail_individually() {
        let name = "issue-1304-multi";
        let (_dir, engine) = plain_engine(name);

        const TOTAL: usize = 64;
        let bad_positions = [7usize, 50];
        let mut body = String::new();
        for i in 0..TOTAL {
            body.push_str(&format!("{{\"index\":{{\"_index\":\"{name}\"}}}}\n"));
            if bad_positions.contains(&i) {
                body.push_str("{\"body\":\"\\udc00 trailing\"}\n");
            } else {
                body.push_str(&format!("{{\"body\":\"doc {i}\"}}\n"));
            }
        }

        let result = process_bulk(&engine, None, &body).await;
        assert!(result.errors);
        let failed: Vec<usize> = result
            .items
            .iter()
            .enumerate()
            .filter(|(_, item)| item.status != 201)
            .map(|(i, _)| i)
            .collect();
        assert_eq!(failed, bad_positions.to_vec());

        let index = engine.get_index(name).unwrap();
        index.refresh().await.unwrap();
        assert_eq!(index.live_doc_count(), (TOTAL - bad_positions.len()) as u64);
    }
}

#[cfg(test)]
mod parse_admission_tests {
    use super::*;

    #[test]
    fn action_line_kind_reads_the_first_key_without_parsing() {
        assert_eq!(action_line_kind(r#"{"index":{"_index":"a"}}"#), "index");
        assert_eq!(action_line_kind(r#" { "create":{}}"#), "create");
        assert_eq!(action_line_kind(r#"{"update":{"_id":"1"}}"#), "update");
        assert_eq!(action_line_kind(r#"{"delete":{"_id":"1"}}"#), "delete");
        assert_eq!(action_line_kind("not json"), "index");
    }

    /// #2427: a request refused before its parse answers one 429 per action,
    /// in body order, so a client re-offering 429 items by position can map
    /// every item back onto the body it sent.
    #[test]
    fn a_refused_bulk_answers_one_429_per_action() {
        let pairs: Vec<(usize, &str, Option<&str>, usize)> = vec![
            (0, r#"{"index":{}}"#, Some(r#"{"a":1}"#), 0),
            (2, r#"{"delete":{"_id":"x"}}"#, None, 1),
            (3, r#"{"update":{"_id":"y"}}"#, Some(r#"{"doc":{}}"#), 2),
        ];
        let error = EngineError::Common(xerj_common::XerjError::circuit_breaking(
            "[parent] real memory circuit breaker tripped",
        ));
        let items = refuse_every_action(&pairs, Some("logs"), &error);
        assert_eq!(items.len(), 3);
        assert_eq!(
            items.iter().map(|i| i.action.as_str()).collect::<Vec<_>>(),
            ["index", "delete", "update"]
        );
        for item in &items {
            assert_eq!(item.status, 429);
            assert_eq!(item.index, "logs");
            assert!(item.error.as_deref().unwrap().contains("circuit breaker"));
        }
    }
}

#[cfg(test)]
mod explicit_id_batch_tests {
    use super::*;
    use serde_json::json;
    use tempfile::TempDir;
    use xerj_common::config::Config;
    use xerj_common::types::{EmbeddingConfig, FieldConfig, FieldType, Schema};

    fn engine_with(name: &str, schema: Schema) -> (TempDir, Engine) {
        let dir = TempDir::new().unwrap();
        let mut config = Config::default();
        config.server.data_dir = dir.path().to_string_lossy().into_owned();
        let engine = Engine::new(config).unwrap();
        engine.create_index(name, schema).unwrap();
        (dir, engine)
    }

    fn statuses(result: &BulkResult) -> Vec<(u16, Option<String>)> {
        result
            .items
            .iter()
            .map(|item| (item.status, item.result.clone()))
            .collect()
    }

    fn created() -> (u16, Option<String>) {
        (201, Some("created".into()))
    }

    fn updated() -> (u16, Option<String>) {
        (200, Some("updated".into()))
    }

    /// #2427: explicit-id `index` actions were published one
    /// `index_document` call at a time, each also copying the source into
    /// the storage memtable. They now go through one turbo batch, which
    /// keeps only the WAL + FTS representation, while `created`/`updated`
    /// and `_version` stay exactly what the per-doc path reported.
    #[tokio::test]
    async fn explicit_id_index_actions_publish_as_one_batch() {
        let name = "explicit-id-batch";
        let (_dir, engine) = engine_with(name, Schema::empty());
        let body = format!(
            "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"a\"}}}}\n{{\"n\":1,\"t\":\"alpha\"}}\n\
             {{\"index\":{{\"_index\":\"{name}\",\"_id\":\"b\"}}}}\n{{\"n\":2,\"t\":\"beta\"}}\n\
             {{\"index\":{{\"_index\":\"{name}\",\"_id\":\"a\"}}}}\n{{\"n\":3,\"t\":\"alpha again\"}}\n"
        );
        EXPLICIT_ID_BATCHES.with(|count| count.set(0));
        let result = process_bulk(&engine, None, &body).await;
        assert!(!result.errors, "{:?}", result.items);
        assert_eq!(statuses(&result), vec![created(), created(), updated()]);
        assert_eq!(EXPLICIT_ID_BATCHES.with(|count| count.get()), 1);

        let idx = engine.get_or_create_index(name).unwrap();
        assert_eq!(
            idx.resident_memtable_entries(),
            0,
            "explicit-id bulk documents were copied into the storage memtable one by one"
        );
        assert_eq!(idx.lookup_version("a"), Some(2));
        assert_eq!(idx.lookup_version("b"), Some(1));
        let a = idx.get_document("a").await.unwrap().unwrap();
        assert_eq!(a["n"], json!(3));
        assert_eq!(a["t"], json!("alpha again"));

        // A tombstone keeps counting; a re-index after delete is "created".
        let body = format!(
            "{{\"delete\":{{\"_index\":\"{name}\",\"_id\":\"b\"}}}}\n\
             {{\"index\":{{\"_index\":\"{name}\",\"_id\":\"a\"}}}}\n{{\"n\":4}}\n"
        );
        let result = process_bulk(&engine, None, &body).await;
        assert!(!result.errors, "{:?}", result.items);
        assert_eq!(idx.lookup_version("a"), Some(3));
        assert_eq!(idx.lookup_version("b"), None);
        let body = format!("{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"b\"}}}}\n{{\"n\":5}}\n");
        let result = process_bulk(&engine, None, &body).await;
        assert_eq!(statuses(&result), vec![created()]);
        assert_eq!(idx.lookup_version("b"), Some(3));
        let b = idx.get_document("b").await.unwrap().unwrap();
        assert_eq!(b["n"], json!(5));
    }

    /// The batch must keep per-document default-format date refusal: one
    /// bad date fails only its own item.
    #[tokio::test]
    async fn explicit_id_batch_keeps_per_item_date_errors() {
        let name = "explicit-id-batch-dates";
        let mut schema = Schema::empty();
        schema.fields.push(FieldConfig::new("ts", FieldType::Date));
        let (_dir, engine) = engine_with(name, schema);
        let body = format!(
            "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"ok1\"}}}}\n{{\"ts\":\"2024-01-02\"}}\n\
             {{\"index\":{{\"_index\":\"{name}\",\"_id\":\"bad\"}}}}\n{{\"ts\":\"not a date\"}}\n\
             {{\"index\":{{\"_index\":\"{name}\",\"_id\":\"ok2\"}}}}\n{{\"ts\":\"2024-01-03T04:05:06Z\"}}\n"
        );
        let result = process_bulk(&engine, None, &body).await;
        assert!(result.errors);
        assert_eq!(result.items[0].status, 201, "{:?}", result.items);
        assert_eq!(result.items[1].status, 400, "{:?}", result.items);
        assert_eq!(result.items[1].id, "bad");
        assert_eq!(result.items[2].status, 201, "{:?}", result.items);
        let idx = engine.get_or_create_index(name).unwrap();
        assert!(idx.get_document("bad").await.unwrap().is_none());
        assert!(idx.get_document("ok2").await.unwrap().is_some());
    }

    /// Semantic documents (ingest-memory tracing off) publish their prepared
    /// sources as one batch too, vectors included.
    #[tokio::test]
    async fn semantic_index_actions_publish_as_one_batch() {
        let name = "explicit-id-batch-semantic";
        let mut schema = Schema::empty();
        let mut field = FieldConfig::new("content", FieldType::Text);
        field.options.dimensions = Some(16);
        field.options.similarity = Some("cosine".to_string());
        field.embedding = Some(EmbeddingConfig {
            endpoint: None,
            model: None,
            target_field: Some("content_vector".into()),
        });
        schema.fields.push(field);
        let (_dir, engine) = engine_with(name, schema);
        engine
            .put_index_mapping(
                name,
                json!({"properties": {"content": {"type": "semantic_text"}}}),
            )
            .unwrap();
        let body = (0..3)
            .map(|i| {
                format!(
                    "{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{}\"}}}}\n\
                     {{\"content\":\"semantic document number {i}\"}}\n",
                    i % 2
                )
            })
            .collect::<String>();
        EXPLICIT_ID_BATCHES.with(|count| count.set(0));
        let result = process_bulk(&engine, None, &body).await;
        assert!(!result.errors, "{:?}", result.items);
        assert_eq!(statuses(&result), vec![created(), created(), updated()]);
        assert_eq!(EXPLICIT_ID_BATCHES.with(|count| count.get()), 1);
        let idx = engine.get_or_create_index(name).unwrap();
        assert_eq!(idx.resident_memtable_entries(), 0);
        assert_eq!(idx.lookup_version("0"), Some(2));
        let doc = idx.get_document("0").await.unwrap().unwrap();
        assert_eq!(doc["content"], json!("semantic document number 2"));
        assert!(
            idx.semantic_vector_fields()
                .await
                .contains("content_vector"),
            "semantic target field missing"
        );
    }
}