Skip to main content

rypipe_core/engine/
table_builder.rs

1#[cfg(test)]
2use std::borrow::Cow;
3use std::panic::{catch_unwind, AssertUnwindSafe};
4use std::sync::Arc;
5
6#[cfg(feature = "profile")]
7use std::sync::atomic::{AtomicUsize, Ordering};
8
9/// Diagnostic: counts resolve_and_put calls across all TableBuilder instances.
10#[cfg(feature = "profile")]
11pub static RESOLVE_AND_PUT_COUNT: AtomicUsize = AtomicUsize::new(0);
12/// Diagnostic: counts predicate evaluations across all TableBuilder instances.
13#[cfg(feature = "profile")]
14pub static PREDICATE_EVALUATIONS: AtomicUsize = AtomicUsize::new(0);
15/// Diagnostic: counts how many times evaluate_predicate_state returns Fail.
16#[cfg(feature = "profile")]
17pub static PREDICATE_FAILS: AtomicUsize = AtomicUsize::new(0);
18/// Diagnostic: counts how many times evaluate_predicate_state returns Undecided.
19#[cfg(feature = "profile")]
20pub static PREDICATE_UNDECIDED: AtomicUsize = AtomicUsize::new(0);
21/// Diagnostic: counts how many times is_predicate_slot returns true.
22#[cfg(feature = "profile")]
23pub static IS_PRED_TRUE: AtomicUsize = AtomicUsize::new(0);
24/// Diagnostic: counts how many times is_predicate_slot returns false.
25#[cfg(feature = "profile")]
26pub static IS_PRED_FALSE: AtomicUsize = AtomicUsize::new(0);
27
28use arrow::datatypes::{Field as ArrowField, Schema};
29use arrow::record_batch::RecordBatch;
30use rustc_hash::FxHashMap as HashMap;
31
32use smallvec::SmallVec;
33
34use crate::columnar::ColumnBuilder;
35use crate::decoder::ColumnarSink;
36use crate::engine::predicate::{PredicateState, RowBuffer};
37use crate::plan::{ExecutionPlan, FieldType, FilterPredicate};
38use crate::value::Value;
39use crate::Result;
40
41mod memory;
42mod predicates;
43
44/// Generic columnar table builder.  Implements `ColumnarSink` so any decoder
45/// can feed it field/value events; at the end it produces an Arrow
46/// `RecordBatch`.
47pub struct TableBuilder {
48    pub(crate) memory_limit: Option<usize>,
49    pub(crate) columns: Vec<ColumnBuilder>,
50    pub(crate) field_index: HashMap<String, usize>,
51    pub(crate) column_order: Vec<String>,
52    pub(crate) row_count: usize,
53    pub(crate) estimated_rows: usize,
54    pub(crate) plan: Arc<ExecutionPlan>,
55    /// Dirty mask for the current row: bit `i` set iff column `i` received a
56    /// value in this row. `Vec<u64>` word array so >64 columns work (e.g.,
57    /// Crystal Reports exports with >64 fields). One compare `mask != full`
58    /// replaces `for col in 0..ncols` loop when every field is present (dense).
59    pub(crate) row_dirty: Vec<u64>,
60    /// Frozen schema for parallel streaming. When Some, any field not in the
61    /// schema is an unknown field and hard-errors on `finish()` (data loss
62    /// would otherwise be silent). Discovery samples 16×2 MiB for >128 MiB.
63    pub(crate) frozen: Option<std::sync::Arc<crate::schema::FrozenSchema>>,
64    pub(crate) unknown_error: Option<String>,
65    /// Heap-allocated row buffer for predicate-first deferred materialization.
66    /// `None` when `plan.filter` is `None`; unfiltered parses carry zero
67    /// overhead from predicate machinery.
68    pub(crate) row_buf: Option<Box<RowBuffer>>,
69    /// Cached projection mask for `wanted_mask()`/`row_satisfied()`: bit `i`
70    /// set iff column `i` is wanted by the schema projection (declared schema
71    /// columns plus any extra fields the row filter needs).  Computed once in
72    /// `with_plan` after schema columns are pre-declared, so it is complete
73    /// from the first row — unlike a mask derived from `field_index` at call
74    /// time, which only covers columns already seen in the data.  0 when no
75    /// schema projection is active (short-circuit disabled).
76    pub(crate) cached_wanted_mask: u64,
77    /// Per-ordinal layout expectation: after row 1, each ordinal maps to a
78    /// (slot_index, raw_name) pair.  The adapter can memcmp the raw bytes
79    /// in-place instead of running the full attribute scan → UTF-8 decode →
80    /// hash → lookup path.  `None` after `layout_broken` or before row 1.
81    pub(crate) ordinal_expect: Vec<Option<(u32, Vec<u8>)>>,
82    /// Current ordinal within the row (incremented per put_field call).
83    /// Used to populate `ordinal_expect` on the first row.
84    pub(crate) current_ordinal: u32,
85    /// First strict-types violation (column, value, row). Recorded during
86    /// puts (the `ColumnarSink` trait is infallible) and surfaced by
87    /// `finish()` as an error.
88    pub(crate) strict_error: Option<crate::Error>,
89    /// Rows committed since the last `finish()`/`reset()` (for observer
90    /// `on_chunk_finished`). Tracked unconditionally: two usize increments.
91    pub(crate) rows_accepted: usize,
92    /// Rows rejected by the filter since the last `finish()`/`reset()`.
93    pub(crate) rows_rejected: usize,
94}
95
96impl TableBuilder {
97    pub fn new() -> Self {
98        Self {
99            memory_limit: None,
100            columns: Vec::new(),
101            field_index: HashMap::default(),
102            column_order: Vec::new(),
103            row_count: 0,
104            estimated_rows: 0,
105            plan: Arc::new(ExecutionPlan::new()),
106            row_dirty: Vec::new(),
107            frozen: None,
108            unknown_error: None,
109            row_buf: None,
110            cached_wanted_mask: 0,
111            ordinal_expect: Vec::new(),
112            current_ordinal: 0,
113            strict_error: None,
114            rows_accepted: 0,
115            rows_rejected: 0,
116        }
117    }
118
119    pub fn with_capacity(cap: usize) -> Self {
120        Self {
121            memory_limit: None,
122            columns: Vec::new(),
123            field_index: HashMap::default(),
124            column_order: Vec::new(),
125            row_count: 0,
126            estimated_rows: cap,
127            plan: Arc::new(ExecutionPlan::new()),
128            row_dirty: Vec::new(),
129            frozen: None,
130            unknown_error: None,
131            row_buf: None,
132            cached_wanted_mask: 0,
133            ordinal_expect: Vec::new(),
134            current_ordinal: 0,
135            strict_error: None,
136            rows_accepted: 0,
137            rows_rejected: 0,
138        }
139    }
140
141    pub fn with_plan(cap: usize, plan: Arc<ExecutionPlan>) -> Self {
142        let mut b = Self {
143            memory_limit: None,
144            columns: Vec::new(),
145            field_index: HashMap::default(),
146            column_order: Vec::new(),
147            row_count: 0,
148            estimated_rows: cap,
149            plan: Arc::clone(&plan),
150            row_dirty: Vec::new(),
151            frozen: None,
152            unknown_error: None,
153            row_buf: if plan.filter.is_some() {
154                Some(Box::new(RowBuffer {
155                    fields: SmallVec::new(),
156                    state: PredicateState::Undecided,
157                    predicate_mask: SmallVec::new(),
158                    direct: false,
159                    predicate_ordinal: None,
160                    buffer_worthwhile: true,
161                    pred_names: SmallVec::new(),
162                }))
163            } else {
164                None
165            },
166            cached_wanted_mask: 0,
167            ordinal_expect: Vec::new(),
168            current_ordinal: 0,
169            strict_error: None,
170            rows_accepted: 0,
171            rows_rejected: 0,
172        };
173        b.predeclare_schema_columns();
174        b.cached_wanted_mask = b.compute_wanted_mask();
175        b
176    }
177
178    /// Pre-create the declared schema columns (plus any extra columns the row
179    /// filter needs) when `schema_order` is a projection.  This makes the
180    /// output layout, per-row null-filling, and `cached_wanted_mask` stable
181    /// from the first row, regardless of which fields appear in the data or
182    /// in what order.  No-op when no schema projection is declared.
183    fn predeclare_schema_columns(&mut self) {
184        if self.plan.schema_order.is_empty() {
185            return;
186        }
187        let mut names: Vec<String> = Vec::new();
188        for name in &self.plan.schema_order {
189            // drop_fields wins over schema: a column listed in both is dropped
190            // (dropping is an explicit exclusion; silently null-filling it
191            // would resurrect a column the user asked to remove).
192            if !self.plan.drop_fields.contains(name) {
193                names.push(name.clone());
194            }
195        }
196        // Filter-referenced fields are materialized even when not in the
197        // schema so predicates evaluate correctly; finish() projects them out.
198        if let Some(ref filter) = self.plan.filter {
199            let mut pred_names: SmallVec<[String; 4]> = SmallVec::new();
200            Self::collect_predicate_field_names(filter, &self.plan, &mut pred_names);
201            names.extend(pred_names);
202        }
203        for name in names {
204            if self.field_index.contains_key(&name) || self.plan.drop_fields.contains(&name) {
205                continue;
206            }
207            let ty = self.plan.column_type(&name);
208            let col = ColumnBuilder::with_capacity(self.estimated_rows.max(64), &ty);
209            self.columns.push(col);
210            self.field_index
211                .insert(name.clone(), self.columns.len() - 1);
212            self.column_order.push(name);
213        }
214        let words = self.columns.len().div_ceil(64);
215        self.row_dirty.resize(words, 0);
216    }
217
218    /// Bitmask of wanted columns for the projection short-circuit.  All
219    /// wanted columns are pre-declared by `predeclare_schema_columns`, and
220    /// non-wanted fields are rejected by `plan.resolve_field`, so the set of
221    /// columns existing at construction time is exactly the wanted set.
222    /// Returns 0 (short-circuit disabled) when no projection is declared or
223    /// when more than 64 columns are wanted.
224    fn compute_wanted_mask(&self) -> u64 {
225        if self.plan.schema_order.is_empty() {
226            return 0;
227        }
228        let mut mask = 0u64;
229        for &idx in self.field_index.values() {
230            if idx >= 64 {
231                return 0;
232            }
233            mask |= 1u64 << idx;
234        }
235        mask
236    }
237
238    /// Pre-size all columns from a `FrozenSchema`.
239    ///
240    /// Called by parallel streaming workers so that every chunk's
241    /// `TableBuilder` has the full column set from construction,
242    /// regardless of which fields appear in that chunk.
243    pub fn ensure_schema(&mut self, schema: &crate::schema::FrozenSchema) -> Result<()> {
244        for (slot, name) in schema.column_names().iter().enumerate() {
245            let name_str: &str = name;
246            if self.field_index.contains_key(name_str) {
247                continue; // already present
248            }
249            let ty = schema.column_types()[slot].clone();
250            let col = ColumnBuilder::with_capacity(self.estimated_rows, &ty);
251            self.columns.push(col);
252            self.field_index
253                .insert(name_str.to_string(), self.columns.len() - 1);
254            self.column_order.push(name_str.to_string());
255        }
256        // Resize row_dirty bitmask to cover all columns.
257        let words = self.columns.len().div_ceil(64);
258        self.row_dirty.resize(words, 0);
259        // Freeze: any later field not in this schema is an unknown field and
260        // must hard-error (otherwise data loss would be silent on a default
261        // path). Sampling 16×2 MiB covers ~6% of a 533 MB file, so 1% Text21
262        // is expected ~280 hits, but 0.05% would be missed.
263        self.frozen = Some(std::sync::Arc::new(schema.clone()));
264        Ok(())
265    }
266
267    /// Lookup a column by resolved name.
268    pub(crate) fn get_column(&self, name: &str) -> Option<&ColumnBuilder> {
269        self.field_index.get(name).map(|&i| &self.columns[i])
270    }
271
272    /// Mutable lookup by resolved name.
273    pub(crate) fn get_column_mut(&mut self, name: &str) -> Option<&mut ColumnBuilder> {
274        if let Some(&i) = self.field_index.get(name) {
275            Some(&mut self.columns[i])
276        } else {
277            None
278        }
279    }
280
281    #[allow(dead_code)]
282    pub(crate) fn bytes_used(&self) -> usize {
283        self.columns.iter().map(|c| c.bytes_used()).sum::<usize>()
284            + self.column_order.iter().map(|s| s.len()).sum::<usize>()
285            + self.row_dirty.len() * 8
286    }
287
288    /// Split off the first `n` rows into a new `TableBuilder`.
289    ///
290    /// Leaves `n` rows in `self`'s remainder as `self - n`. Used for
291    /// 64KB streaming where a single file chunk may contain many more rows
292    /// than `rows_per_batch`.
293    pub(crate) fn split_off(&mut self, n: usize) -> Self {
294        assert!(n <= self.row_count, "split_off beyond row_count");
295        assert!(n > 0);
296        let mut other = Self {
297            memory_limit: self.memory_limit,
298            columns: Vec::with_capacity(self.columns.len()),
299            field_index: self.field_index.clone(),
300            column_order: self.column_order.clone(),
301            row_count: n,
302            estimated_rows: n,
303            plan: Arc::clone(&self.plan),
304            row_dirty: vec![0; self.columns.len().div_ceil(64)],
305            frozen: self.frozen.clone(),
306            unknown_error: None,
307            cached_wanted_mask: self.cached_wanted_mask,
308            row_buf: if self.plan.filter.is_some() {
309                Some(Box::new(RowBuffer {
310                    fields: SmallVec::new(),
311                    state: PredicateState::Undecided,
312                    predicate_mask: self
313                        .row_buf
314                        .as_ref()
315                        .map_or_else(SmallVec::new, |b| b.predicate_mask.clone()),
316                    direct: false,
317                    predicate_ordinal: None,
318                    buffer_worthwhile: true,
319                    pred_names: self
320                        .row_buf
321                        .as_ref()
322                        .map_or_else(SmallVec::new, |b| b.pred_names.clone()),
323                }))
324            } else {
325                None
326            },
327            ordinal_expect: Vec::new(),
328            current_ordinal: 0,
329            strict_error: None,
330            // The split-off batch reports the rows accumulated since the
331            // previous split; the remainder starts a fresh delta.
332            rows_accepted: std::mem::take(&mut self.rows_accepted),
333            rows_rejected: std::mem::take(&mut self.rows_rejected),
334        };
335        for (idx, col) in self.columns.iter_mut().enumerate() {
336            let drain = col.split_off(n);
337            other.columns.push(drain);
338            // Remainder stays in self.columns[idx]
339            let _ = idx;
340        }
341        self.row_count -= n;
342        // row_dirty for self should be all false (no dirty in remainder yet)
343        self.row_dirty = vec![0; self.columns.len().div_ceil(64)];
344        // row_dirty for other is also false (just finished batch)
345        other
346    }
347
348    /// Remove and return a column by name, fixing the Vec index map.
349    /// Used by `merge::extend` to move builders out of the `other` table.
350    pub(crate) fn take_column(&mut self, name: &str) -> Option<ColumnBuilder> {
351        let idx = self.field_index.remove(name)?;
352        // Keep row_dirty in sync: Vec<u64> bitmask, need to handle bit removal
353        // For simplicity, just rebuild row_dirty as all zeros after column removal
354        // (row_dirty is per-row, not per-column persistent, so clearing is fine)
355        // Rebuild to correct length
356        let new_len = self.columns.len().div_ceil(64);
357        self.row_dirty.resize(new_len, 0);
358        // Clear all bits (no dirty in remainder for take_column case)
359        self.row_dirty.fill(0);
360        let _ = idx; // suppress unused warning
361                     // After removal, columns.len() == old_len; last index = old_len - 1.
362                     // swap_remove will move the last element into idx (if not already last).
363        let last = self.columns.len() - 1;
364        let col = if idx == last {
365            self.columns.pop().unwrap()
366        } else {
367            let col = self.columns.swap_remove(idx);
368            // The element that was at `last` is now at `idx`; fix its map entry.
369            let old_last = self.columns.len(); // == last, new len after pop/swap
370                                               // Find the key that pointed to old_last and repoint it to idx.
371                                               // We must not borrow field_index mutably while iterating, so clone the key first.
372            let moved_name = self.field_index.iter().find_map(|(k, &v)| {
373                if v == old_last {
374                    Some(k.clone())
375                } else {
376                    None
377                }
378            });
379            if let Some(k) = moved_name {
380                self.field_index.insert(k, idx);
381            }
382            col
383        };
384        Some(col)
385    }
386
387    pub fn num_rows(&self) -> usize {
388        self.row_count
389    }
390
391    pub fn num_columns(&self) -> usize {
392        self.column_order.len()
393    }
394
395    pub fn column_names(&self) -> &[String] {
396        &self.column_order
397    }
398
399    /// Diagnostic: (name, bytes_used, bytes_capacity) for each column.
400    pub fn column_diagnostics(&self) -> Vec<(String, usize, usize)> {
401        self.column_order
402            .iter()
403            .map(|name| {
404                let idx = self.field_index[name];
405                let col = &self.columns[idx];
406                (name.clone(), col.bytes_used(), col.capacity_bytes())
407            })
408            .collect()
409    }
410
411    /// The estimated_rows capacity hint passed to with_plan.
412    pub fn estimated_rows(&self) -> usize {
413        self.estimated_rows
414    }
415
416    /// Finalize the builder into an Arrow `RecordBatch`.
417    ///
418    /// This is also available as the `ColumnarSink::finish` trait method.
419    pub fn finish(&mut self) -> Result<RecordBatch> {
420        ColumnarSink::finish(self)
421    }
422
423    pub(crate) fn prepare_finish(&mut self) -> Result<()> {
424        if let Some(err) = self.unknown_error.take() {
425            return Err(crate::Error::Merge(err));
426        }
427        if let Some(err) = self.strict_error.take() {
428            return Err(err);
429        }
430        self.check_memory_budget()?;
431        if let Some(ref observer) = self.plan.observer {
432            let result = catch_unwind(AssertUnwindSafe(|| {
433                observer.on_chunk_finished(
434                    self.rows_accepted + self.rows_rejected,
435                    self.rows_accepted,
436                    self.rows_rejected,
437                );
438            }));
439            if let Err(payload) = result {
440                let message = payload
441                    .downcast_ref::<&str>()
442                    .map(|s| (*s).to_string())
443                    .or_else(|| payload.downcast_ref::<String>().cloned())
444                    .unwrap_or_else(|| "unknown panic".to_string());
445                return Err(crate::Error::Parser(format!(
446                    "observer panicked at chunk completion: {message}"
447                )));
448            }
449        }
450        self.normalize();
451        Ok(())
452    }
453
454    /// Reset all data while preserving the plan and estimated rows.
455    pub fn reset(&mut self) {
456        self.columns.clear();
457        self.field_index.clear();
458        self.column_order.clear();
459        self.row_dirty.fill(0);
460        self.row_count = 0;
461        if let Some(ref mut buf) = self.row_buf {
462            buf.fields.clear();
463            buf.state = PredicateState::Undecided;
464        }
465        // Keep frozen/row_buf (per builder, not per row)
466        self.unknown_error = None;
467        self.strict_error = None;
468        self.rows_accepted = 0;
469        self.rows_rejected = 0;
470    }
471
472    /// Truncate every column back to `row_count`, dropping any partial-row
473    /// values from a mid-field EOF.  Idempotent.
474    pub fn normalize(&mut self) {
475        for b in &mut self.columns {
476            while b.len() > self.row_count {
477                b.pop();
478            }
479        }
480        // Discard any dirty state for the partial row.
481        self.row_dirty.fill(0);
482    }
483
484    /// If `auto_dict` is set, upgrade low-cardinality string columns using the
485    /// plan's threshold/max-size tuning (defaults: 5% ratio, max size 256).
486    pub fn auto_dict_upgrade(&mut self) {
487        if self.plan.auto_dict {
488            let max_ratio = self.plan.dict_threshold.unwrap_or(0.05);
489            let max_size = self.plan.dict_max_size.unwrap_or(256);
490            for b in &mut self.columns {
491                b.try_upgrade_to_dict(512, max_ratio, max_size);
492            }
493        }
494    }
495
496    /// Sort columns according to `schema_order`.  Columns named in
497    /// `schema_order` appear in that order; any other columns keep their
498    /// relative first-appearance order after the ordered ones.
499    pub fn sort_columns(&mut self) {
500        if self.plan.schema_order.is_empty() {
501            return;
502        }
503        let order = &self.plan.schema_order;
504        let rank = |name: &String| order.iter().position(|n| n == name).unwrap_or(usize::MAX);
505        self.column_order.sort_by_key(rank);
506    }
507
508    pub(crate) fn schema_insert_index(&self, name: &str) -> usize {
509        let order = &self.plan.schema_order;
510        if order.is_empty() {
511            return self.column_order.len();
512        }
513        let pos = order.iter().position(|n| n == name);
514        match pos {
515            Some(p) => self
516                .column_order
517                .iter()
518                .position(|existing| {
519                    order
520                        .iter()
521                        .position(|n| n == existing)
522                        .is_some_and(|ep| ep > p)
523                })
524                .unwrap_or(self.column_order.len()),
525            None => self.column_order.len(),
526        }
527    }
528
529    /// Ensure the column exists and return its Vec index.
530    /// Single hash lookup for the hot path; new columns are created and
531    /// inserted into `column_order` via `schema_insert_index`.
532    fn ensure_column_idx(&mut self, name: &str) -> usize {
533        if let Some(&idx) = self.field_index.get(name) {
534            return idx;
535        }
536        // Frozen schema: any new column not pre-sized by ensure_schema is an
537        // unknown field (sampling miss or file has column absent during
538        // discovery). Don't silently create it; hard-error on finish().
539        // We still return a dummy idx to keep the hot path inlinable, but
540        // push_field_resolved will have already early-returned after setting
541        // unknown_error, so this path is only for non-frozen builders.
542        if self.frozen.is_some() {
543            if let Some(frozen) = &self.frozen {
544                if frozen.is_exact() {
545                    // Exact schema: error on unknown fields
546                    if self.unknown_error.is_none() {
547                        self.unknown_error = Some(format!(
548                            "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...] with full column list or use full-scan discovery",
549                            name,
550                            frozen.num_columns(),
551                            frozen.is_exact()
552                        ));
553                    }
554                    return 0;
555                }
556                // Non-exact (partial schema): fall through to create column dynamically
557            }
558        }
559        let est = self.estimated_rows.max(64);
560        let col_type = self.plan.column_type(name);
561        let mut b = ColumnBuilder::with_capacity(est, &col_type);
562        // When the predicate passes mid-row, drain_buffered increments
563        // row_count before all fields are pushed. New columns created after
564        // that must backfill row_count-1 Nones (for the already-committed
565        // rows), not row_count, because the current row's value follows.
566        let backfill = if self.row_buf.as_ref().is_some_and(|b| b.direct) {
567            self.row_count.saturating_sub(1)
568        } else {
569            self.row_count
570        };
571        for _ in 0..backfill {
572            b.push(None);
573        }
574        let idx = self.columns.len();
575        self.columns.push(b);
576        self.field_index.insert(name.to_owned(), idx);
577        // Ensure row_dirty has enough words for new column
578        let needed = self.columns.len().div_ceil(64);
579        if self.row_dirty.len() < needed {
580            self.row_dirty.resize(needed, 0);
581        }
582        let order_idx = self.schema_insert_index(name);
583        self.column_order.insert(order_idx, name.to_owned());
584        idx
585    }
586
587    /// Strict-types check for the value about to land in column `idx`: when
588    /// `plan.strict_types` is set, a non-null string that does not parse into
589    /// the declared `field_types` type is recorded as the first strict
590    /// violation (surfaced by `finish()`). Nulls and non-string values never
591    /// trigger it.
592    #[inline]
593    fn record_strict_violation_at(&mut self, idx: usize, value: &Value<'_>) {
594        if !self.plan.strict_types || self.strict_error.is_some() {
595            return;
596        }
597        let Value::Str(s) = value else {
598            return;
599        };
600        let Some(name) = self.column_order.get(idx) else {
601            return;
602        };
603        let Some(ft) = self.plan.field_types.get(name) else {
604            return;
605        };
606        if crate::columnar::parses_as(s, ft) {
607            return;
608        }
609        let truncated: String = s.chars().take(64).collect();
610        self.strict_error = Some(crate::Error::Plan(format!(
611            "strict_types: value {truncated:?} in column {name:?} at row {} \
612             does not parse as declared type {ft:?}",
613            self.row_count
614        )));
615    }
616
617    /// Notify the plan's observer (if any) that `value` landed in column
618    /// `idx`. Not called for buffered values; those fire on drain instead.
619    #[inline]
620    fn notify_put_field(&self, idx: usize, value: &Value<'_>) {
621        if let Some(ref obs) = self.plan.observer {
622            if let Some(name) = self.column_order.get(idx) {
623                obs.on_put_field(self.row_count, name, idx, value);
624            }
625        }
626    }
627
628    /// Push a field value without resolving renames/drops.
629    /// Caller must have already resolved `resolved_name` (or know it is kept).
630    #[inline]
631    fn push_field_resolved(&mut self, resolved_name: &str, value: Value<'_>) {
632        // #[inline]: small hot path, called per-field. ensure_column_idx is not
633        // inlined (too large); push_value is the real work and benefits from
634        // being in the same compilation unit as its caller.
635        // Frozen check: hard error on unknown field when exact schema (data loss
636        // would be silent on a default path). Non-exact schemas allow unknown
637        // fields to be created dynamically.
638        if self.frozen.is_some() && !self.field_index.contains_key(resolved_name) {
639            if let Some(frozen) = &self.frozen {
640                if frozen.is_exact() {
641                    // Exact schema: error on unknown fields
642                    if self.unknown_error.is_none() {
643                        self.unknown_error = Some(format!(
644                            "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...] with full column list or use full-scan discovery",
645                            resolved_name,
646                            frozen.num_columns(),
647                            frozen.is_exact()
648                        ));
649                    }
650                    return;
651                }
652                // Non-exact (partial schema): fall through to ensure_column_idx
653            }
654        }
655        let idx = self.ensure_column_idx(resolved_name);
656        self.record_strict_violation_at(idx, &value);
657        self.notify_put_field(idx, &value);
658        // Track ordinal→slot mapping on first row for expect_slot fast path.
659        if self.row_count == 0 {
660            let ord = self.current_ordinal as usize;
661            if ord >= self.ordinal_expect.len() {
662                self.ordinal_expect.resize_with(ord + 1, || None);
663            }
664            self.ordinal_expect[ord] = Some((idx as u32, resolved_name.as_bytes().to_vec()));
665        }
666        self.current_ordinal += 1;
667        let word = idx / 64;
668        let bit = idx % 64;
669        self.row_dirty[word] |= 1u64 << bit;
670        let b = &mut self.columns[idx];
671        let row_count = self.row_count;
672        if b.len() > row_count {
673            b.pop();
674        }
675        b.push_value(value);
676    }
677
678    /// Push a field value, resolving renames/drops and applying last-write-wins
679    /// within the current uncommitted row.
680    #[inline]
681    fn push_field(&mut self, name: &str, value: Value<'_>) {
682        // #[inline]: fast-path (no rename/drop) is a single branch + delegate.
683        // Fast path: no rename/drop/projection configured; zero allocation.
684        if self.plan.field_map.is_empty()
685            && self.plan.drop_fields.is_empty()
686            && self.plan.schema_order.is_empty()
687        {
688            self.push_field_resolved(name, value);
689            return;
690        }
691        // Resolve name via plan's field_map (borrows &self.plan).
692        // Try the zero-allocation fast path: column already exists.
693        if let Some(idx) = Self::resolve_and_slot(&self.plan, &self.field_index, name) {
694            self.record_strict_violation_at(idx, &value);
695            self.notify_put_field(idx, &value);
696            // Track ordinal→slot mapping on first row for expect_slot fast path.
697            if self.row_count == 0 {
698                let ord = self.current_ordinal as usize;
699                if ord >= self.ordinal_expect.len() {
700                    self.ordinal_expect.resize_with(ord + 1, || None);
701                }
702                // Store the resolved name (what plan.resolve_field would return).
703                let resolved = self.plan.resolve_field(name).unwrap_or(name);
704                self.ordinal_expect[ord] = Some((idx as u32, resolved.as_bytes().to_vec()));
705            }
706            self.current_ordinal += 1;
707            let word = idx / 64;
708            let bit = idx % 64;
709            self.row_dirty[word] |= 1u64 << bit;
710            let b = &mut self.columns[idx];
711            let row_count = self.row_count;
712            if b.len() > row_count {
713                b.pop();
714            }
715            b.push_value(value);
716        } else {
717            // Column doesn't exist yet (first row with rename) or field was
718            // dropped. Only allocate when the field is kept.
719            if let Some(resolved) = self.plan.resolve_field(name) {
720                let owned = resolved.to_owned();
721                self.push_field_resolved(&owned, value);
722            }
723        }
724    }
725
726    /// Resolve a field name through the plan's field_map and look up its slot
727    /// index. Returns `Some(slot)` only if the column already exists in
728    /// field_index. Zero allocation; borrows plan and field_index as
729    /// separate fields.
730    #[inline]
731    fn resolve_and_slot(
732        plan: &ExecutionPlan,
733        field_index: &HashMap<String, usize>,
734        name: &str,
735    ) -> Option<usize> {
736        let resolved = plan.resolve_field(name)?;
737        field_index.get(resolved).copied()
738    }
739
740    /// Advance the row counter without null-fill, filter, or dirty-mask clear.
741    /// For benchmarking only; separates per-field push cost from per-row
742    /// finalization.
743    #[doc(hidden)]
744    pub fn advance_row(&mut self) {
745        self.row_count += 1;
746    }
747
748    /// Null-fill any column missing this row, then apply the per-row filter.
749    /// If the filter rejects the row, undo it by popping values.
750    /// Uses the dirty bitmask so only missing columns are touched; fast path
751    /// when every column was set (dense data, 10 cols) skips the loop.
752    fn finish_row(&mut self) {
753        // No #[inline]: 30+ lines with loops; inlining causes code bloat.
754        let ncols = self.columns.len();
755        // Fast path: check if all bits set
756        let full_words = ncols / 64;
757        let rem_bits = ncols % 64;
758        let is_full = (0..full_words).all(|w| self.row_dirty[w] == u64::MAX)
759            && (rem_bits == 0
760                || self.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem_bits) - 1);
761        if is_full {
762            self.row_dirty.fill(0);
763        } else {
764            for (i, b) in self.columns.iter_mut().enumerate() {
765                let word = i / 64;
766                let bit = i % 64;
767                let is_set = (self.row_dirty[word] >> bit) & 1 == 1;
768                if !is_set {
769                    b.push(None);
770                }
771            }
772            self.row_dirty.fill(0);
773        }
774
775        if let Some(ref filter) = self.plan.filter {
776            if !filter.check(&self.columns, &self.field_index, self.row_count, &self.plan) {
777                for b in &mut self.columns {
778                    b.pop();
779                }
780                self.rows_rejected += 1;
781                if let Some(ref obs) = self.plan.observer {
782                    obs.on_row_rejected(self.row_count);
783                }
784                return;
785            }
786        }
787
788        self.row_count += 1;
789        self.rows_accepted += 1;
790        if let Some(ref obs) = self.plan.observer {
791            obs.on_row_accepted(self.row_count - 1);
792        }
793    }
794
795    /// Null-fill any column missing the current row, then clear row_dirty.
796    /// Called when the predicate resolved to Pass mid-row (direct mode).
797    fn null_fill_missing(&mut self) {
798        let ncols = self.columns.len();
799        let full_words = ncols / 64;
800        let rem_bits = ncols % 64;
801        let is_full = (0..full_words).all(|w| self.row_dirty[w] == u64::MAX)
802            && (rem_bits == 0
803                || self.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem_bits) - 1);
804        if is_full {
805            self.row_dirty.fill(0);
806        } else {
807            for (i, b) in self.columns.iter_mut().enumerate() {
808                let word = i / 64;
809                let bit = i % 64;
810                let is_set = (self.row_dirty[word] >> bit) & 1 == 1;
811                if !is_set {
812                    b.push(None);
813                }
814            }
815            self.row_dirty.fill(0);
816        }
817        // Note: row_count was already incremented by drain_buffered(true)
818        // when the predicate resolved to Pass mid-row. Do NOT increment here.
819    }
820}
821
822impl Default for TableBuilder {
823    fn default() -> Self {
824        Self::new()
825    }
826}
827
828impl ColumnarSink for TableBuilder {
829    #[inline]
830    fn begin_row(&mut self) {
831        if !self.reserve_memory(0) {
832            return;
833        }
834        if let Some(ref obs) = self.plan.observer {
835            obs.on_begin_row(self.row_count);
836        }
837        self.current_ordinal = 0;
838        if let Some(ref mut buf) = self.row_buf {
839            // Adaptive strategy: after at least one committed row, decide
840            // whether buffering is worthwhile based on the predicate column's
841            // ordinal relative to the total number of columns.  We must wait
842            // until row_count > 0 because early-rejected rows don't create
843            // all columns, making ncols unreliable for the ordinal comparison.
844            if buf.predicate_ordinal.is_some() && buf.buffer_worthwhile && self.row_count > 0 {
845                // Use the most accurate column count available. self.columns.len()
846                // is unreliable for sparse files where not all columns exist yet.
847                let ncols = self
848                    .frozen
849                    .as_ref()
850                    .map(|f| f.num_columns() as u32)
851                    .or_else(|| {
852                        (!self.plan.schema_order.is_empty())
853                            .then(|| self.plan.schema_order.len() as u32)
854                    })
855                    .unwrap_or(self.columns.len() as u32);
856                if let Some(ordinal) = buf.predicate_ordinal {
857                    if ordinal >= ncols * 4 / 5 {
858                        buf.buffer_worthwhile = false;
859                    }
860                }
861            }
862            buf.fields.clear();
863            buf.state = PredicateState::Undecided;
864            buf.direct = false;
865        }
866    }
867
868    #[inline]
869    fn put_field(&mut self, name: &str, value: Value<'_>) {
870        if !self.reserve_field_memory(name.len(), &value) {
871            return;
872        }
873        if self.plan.filter.is_none() {
874            self.push_field(name, value);
875            return;
876        }
877        // Adaptive: late predicate → push directly, pop-on-reject at end_row.
878        let buf_worthwhile = self.row_buf.as_ref().is_none_or(|b| b.buffer_worthwhile);
879        if !buf_worthwhile {
880            self.push_field(name, value);
881            return;
882        }
883        // Buffered path: resolve name → slot, buffer (slot, value).
884        let resolved = match self.plan.resolve_field(name) {
885            Some(r) => r.to_owned(),
886            None => return,
887        };
888        // Check frozen unknown (as in push_field_resolved)
889        if self.frozen.is_some()
890            && !self.field_index.contains_key(&resolved)
891            && self.unknown_error.is_none()
892        {
893            if let Some(ref frozen) = self.frozen {
894                if frozen.is_exact()
895                    && !frozen.column_names().iter().any(|n| n.as_ref() == resolved)
896                {
897                    self.unknown_error = Some(format!(
898                            "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
899                            resolved,
900                            frozen.num_columns(),
901                            frozen.is_exact()
902                        ));
903                    return;
904                }
905            }
906        }
907        let slot = self.ensure_column_idx(&resolved) as u32;
908        self.record_strict_violation_at(slot as usize, &value);
909        self.mark_predicate_slot(slot);
910        let val_static: Value<'static> = value.into_static();
911        let is_pred = self.is_predicate_slot(slot);
912        #[cfg(feature = "profile")]
913        if is_pred {
914            crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
915        } else {
916            crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
917        }
918        // Push value to buffer BEFORE evaluating predicate (value must be findable).
919        if let Some(ref mut buf) = self.row_buf {
920            if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
921                buf.fields[pos].1 = val_static;
922            } else {
923                buf.fields.push((slot, val_static));
924            }
925        }
926        if is_pred {
927            // Record predicate ordinal for adaptive strategy (once)
928            if let Some(ref mut buf) = self.row_buf {
929                if buf.predicate_ordinal.is_none() {
930                    buf.predicate_ordinal = Some(slot);
931                }
932            }
933            let state = self.evaluate_predicate_state();
934            if let Some(ref mut buf) = self.row_buf {
935                buf.state = state;
936            }
937        }
938    }
939
940    #[inline]
941    fn end_row(&mut self) {
942        if !self.reserve_memory(0) {
943            return;
944        }
945        if self.plan.filter.is_none() {
946            self.finish_row();
947            return;
948        }
949        // Check adaptive strategy: if buffering is not worthwhile (late
950        // predicate), use direct push + pop-on-reject (finish_row).
951        let buf_worthwhile = self.row_buf.as_ref().is_none_or(|b| b.buffer_worthwhile);
952        if !buf_worthwhile {
953            // Late predicate: values were pushed directly to columns.
954            // finish_row null-fills missing, evaluates filter against columns,
955            // and pops on reject; exactly the pre-buffering behavior.
956            self.finish_row();
957            return;
958        }
959        // Buffered path
960        let (state, direct) = self
961            .row_buf
962            .as_ref()
963            .map_or((PredicateState::Pass, false), |b| (b.state, b.direct));
964        if direct {
965            // Already flushed to columns; just null-fill missing columns.
966            self.null_fill_missing();
967            return;
968        }
969        let state = if state == PredicateState::Undecided {
970            self.evaluate_against_null()
971        } else {
972            state
973        };
974        let pass = state == PredicateState::Pass;
975        self.drain_buffered(pass);
976    }
977
978    #[inline]
979    fn wants(&self, name: &str) -> bool {
980        self.resolve(name).is_some()
981    }
982
983    #[inline]
984    fn resolve<'a>(&'a self, name: &'a str) -> Option<&'a str> {
985        self.plan.resolve_field(name)
986    }
987
988    #[inline]
989    fn put_field_resolved(&mut self, resolved_name: &str, value: Value<'_>) {
990        if !self.reserve_field_memory(resolved_name.len(), &value) {
991            return;
992        }
993        if self.plan.filter.is_none() {
994            self.push_field_resolved(resolved_name, value);
995            return;
996        }
997        // Adaptive: late predicate → push directly, pop-on-reject at end_row.
998        let buf_worthwhile = self.row_buf.as_ref().is_none_or(|b| b.buffer_worthwhile);
999        if !buf_worthwhile {
1000            self.push_field_resolved(resolved_name, value);
1001            return;
1002        }
1003        // Buffered path for already-resolved name (no rename lookup)
1004        if self.frozen.is_some() && !self.field_index.contains_key(resolved_name) {
1005            if let Some(ref frozen) = self.frozen {
1006                if frozen.is_exact()
1007                    && !frozen
1008                        .column_names()
1009                        .iter()
1010                        .any(|n| n.as_ref() == resolved_name)
1011                {
1012                    if self.unknown_error.is_none() {
1013                        self.unknown_error = Some(format!(
1014                            "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1015                            resolved_name,
1016                            frozen.num_columns(),
1017                            frozen.is_exact()
1018                        ));
1019                    }
1020                    return;
1021                }
1022            }
1023        }
1024        let slot = self.ensure_column_idx(resolved_name) as u32;
1025        self.record_strict_violation_at(slot as usize, &value);
1026        self.mark_predicate_slot(slot);
1027        let val_static: Value<'static> = value.into_static();
1028        let is_pred = self.is_predicate_slot(slot);
1029        #[cfg(feature = "profile")]
1030        if is_pred {
1031            crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1032        } else {
1033            crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1034        }
1035        if let Some(ref mut buf) = self.row_buf {
1036            if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
1037                buf.fields[pos].1 = val_static;
1038            } else {
1039                buf.fields.push((slot, val_static));
1040            }
1041        }
1042        if is_pred {
1043            // Record predicate ordinal for adaptive strategy (once)
1044            if let Some(ref mut buf) = self.row_buf {
1045                if buf.predicate_ordinal.is_none() {
1046                    buf.predicate_ordinal = Some(slot);
1047                }
1048            }
1049            let state = self.evaluate_predicate_state();
1050            if let Some(ref mut buf) = self.row_buf {
1051                buf.state = state;
1052            }
1053        }
1054    }
1055
1056    /// Push a value directly to a known slot index, bypassing all name
1057    /// resolution and hash lookups.  Used by adapters that verified the
1058    /// field identity via `expect_slot` + memcmp on raw bytes.
1059    #[inline]
1060    fn put_field_at(&mut self, slot: u32, value: Value<'_>) {
1061        if !self.reserve_field_memory(0, &value) {
1062            return;
1063        }
1064        let idx = slot as usize;
1065        if idx >= self.columns.len() {
1066            // Slot doesn't exist yet (sparse row). Fall back to ensure.
1067            // This shouldn't happen after row 1 with a stable layout.
1068            return;
1069        }
1070        self.record_strict_violation_at(idx, &value);
1071        self.notify_put_field(idx, &value);
1072        let word = idx / 64;
1073        let bit = idx % 64;
1074        self.row_dirty[word] |= 1u64 << bit;
1075        let b = &mut self.columns[idx];
1076        let row_count = self.row_count;
1077        if b.len() > row_count {
1078            b.pop();
1079        }
1080        b.push_value(value);
1081    }
1082
1083    /// `put_field_at` specialized for a known `&str` value: skips the `Value`
1084    /// construction and its match. Used by adapters that know a field is a
1085    /// plain string (no declared type). Falls back to the general path when a
1086    /// memory budget or a filter row-buffer is active.
1087    #[inline]
1088    fn put_str_at(&mut self, slot: u32, value: &str) {
1089        if self.memory_limit.is_some() || self.row_buf.is_some() {
1090            self.put_field_at(slot, Value::Str(std::borrow::Cow::Borrowed(value)));
1091            return;
1092        }
1093        let idx = slot as usize;
1094        if idx >= self.columns.len() {
1095            return;
1096        }
1097        if self.plan.strict_types {
1098            self.record_strict_violation_at(idx, &Value::Str(std::borrow::Cow::Borrowed(value)));
1099        }
1100        if self.plan.observer.is_some() {
1101            self.notify_put_field(idx, &Value::Str(std::borrow::Cow::Borrowed(value)));
1102        }
1103        let word = idx / 64;
1104        let bit = idx % 64;
1105        self.row_dirty[word] |= 1u64 << bit;
1106        let b = &mut self.columns[idx];
1107        let row_count = self.row_count;
1108        if b.len() > row_count {
1109            b.pop();
1110        }
1111        b.push_str(Some(value));
1112    }
1113
1114    #[inline]
1115    fn resolve_and_put(&mut self, name: &str, value: Value<'_>) {
1116        if !self.reserve_field_memory(name.len(), &value) {
1117            return;
1118        }
1119        #[cfg(feature = "profile")]
1120        RESOLVE_AND_PUT_COUNT.fetch_add(1, Ordering::Relaxed);
1121        if self.plan.filter.is_none() {
1122            if self.plan.field_map.is_empty()
1123                && self.plan.drop_fields.is_empty()
1124                && self.plan.schema_order.is_empty()
1125            {
1126                self.push_field_resolved(name, value);
1127            } else {
1128                if let Some(resolved) = self.plan.resolve_field(name) {
1129                    let owned = resolved.to_owned();
1130                    self.push_field_resolved(&owned, value);
1131                }
1132            }
1133            return;
1134        }
1135        // Adaptive: late predicate → push directly, pop-on-reject at end_row.
1136        if self.row_buf.as_ref().is_some_and(|b| !b.buffer_worthwhile) {
1137            if self.plan.field_map.is_empty()
1138                && self.plan.drop_fields.is_empty()
1139                && self.plan.schema_order.is_empty()
1140            {
1141                self.push_field_resolved(name, value);
1142            } else {
1143                if let Some(resolved) = self.plan.resolve_field(name) {
1144                    let owned = resolved.to_owned();
1145                    self.push_field_resolved(&owned, value);
1146                }
1147            }
1148            return;
1149        }
1150        // Direct mode: predicate already passed, push directly to columns.
1151        if let Some(ref buf) = self.row_buf {
1152            if buf.direct {
1153                let resolved = match self.plan.resolve_field(name) {
1154                    Some(r) => r.to_owned(),
1155                    None => return, // field is dropped
1156                };
1157                if self.frozen.is_some() && !self.field_index.contains_key(resolved.as_str()) {
1158                    if let Some(ref frozen) = self.frozen {
1159                        if frozen.is_exact()
1160                            && !frozen
1161                                .column_names()
1162                                .iter()
1163                                .any(|n| n.as_ref() == resolved.as_str())
1164                        {
1165                            if self.unknown_error.is_none() {
1166                                self.unknown_error = Some(format!(
1167                                    "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1168                                    resolved, frozen.num_columns(), frozen.is_exact()
1169                                ));
1170                            }
1171                            return;
1172                        }
1173                    }
1174                }
1175                self.push_field_resolved(&resolved, value);
1176                return;
1177            }
1178        }
1179        // Buffered path: resolve → slot, buffer (slot, value).
1180        if self.plan.field_map.is_empty()
1181            && self.plan.drop_fields.is_empty()
1182            && self.plan.schema_order.is_empty()
1183        {
1184            // No rename/drop, raw == resolved
1185            let resolved = name;
1186            if self.frozen.is_some() && !self.field_index.contains_key(resolved) {
1187                if let Some(ref frozen) = self.frozen {
1188                    if frozen.is_exact()
1189                        && !frozen.column_names().iter().any(|n| n.as_ref() == resolved)
1190                    {
1191                        if self.unknown_error.is_none() {
1192                            self.unknown_error = Some(format!(
1193                                "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1194                                resolved,
1195                                frozen.num_columns(),
1196                                frozen.is_exact()
1197                            ));
1198                        }
1199                        return;
1200                    }
1201                }
1202            }
1203            let slot = self.ensure_column_idx(resolved) as u32;
1204            self.record_strict_violation_at(slot as usize, &value);
1205            self.mark_predicate_slot(slot);
1206            let val_static: Value<'static> = value.into_static();
1207            let is_pred = self.is_predicate_slot(slot);
1208            #[cfg(feature = "profile")]
1209            if is_pred {
1210                crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1211            } else {
1212                crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1213            }
1214            if let Some(ref mut buf) = self.row_buf {
1215                if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
1216                    buf.fields[pos].1 = val_static;
1217                } else {
1218                    buf.fields.push((slot, val_static));
1219                }
1220            }
1221            if is_pred {
1222                // Record predicate ordinal for adaptive strategy (once)
1223                if let Some(ref mut buf) = self.row_buf {
1224                    if buf.predicate_ordinal.is_none() {
1225                        buf.predicate_ordinal = Some(slot);
1226                    }
1227                }
1228                let state = self.evaluate_predicate_state();
1229                if let Some(ref mut buf) = self.row_buf {
1230                    buf.state = state;
1231                    if state == PredicateState::Pass {
1232                        buf.direct = true;
1233                    }
1234                }
1235                if state == PredicateState::Pass {
1236                    // Predicate passed: drain buffered fields, switch to direct mode.
1237                    self.drain_buffered(true);
1238                }
1239            }
1240        } else {
1241            if let Some(resolved) = self.plan.resolve_field(name) {
1242                let owned = resolved.to_owned();
1243                if self.frozen.is_some() && !self.field_index.contains_key(&owned) {
1244                    if let Some(ref frozen) = self.frozen {
1245                        if frozen.is_exact()
1246                            && !frozen.column_names().iter().any(|n| n.as_ref() == owned)
1247                        {
1248                            if self.unknown_error.is_none() {
1249                                self.unknown_error = Some(format!(
1250                                    "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1251                                    owned,
1252                                    frozen.num_columns(),
1253                                    frozen.is_exact()
1254                                ));
1255                            }
1256                            return;
1257                        }
1258                    }
1259                }
1260                let slot = self.ensure_column_idx(&owned) as u32;
1261                self.record_strict_violation_at(slot as usize, &value);
1262                self.mark_predicate_slot(slot);
1263                let val_static: Value<'static> = value.into_static();
1264                let is_pred = self.is_predicate_slot(slot);
1265                #[cfg(feature = "profile")]
1266                if is_pred {
1267                    crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1268                } else {
1269                    crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1270                }
1271                if let Some(ref mut buf) = self.row_buf {
1272                    if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
1273                        buf.fields[pos].1 = val_static;
1274                    } else {
1275                        buf.fields.push((slot, val_static));
1276                    }
1277                }
1278                if is_pred {
1279                    // Record predicate ordinal for adaptive strategy (once)
1280                    if let Some(ref mut buf) = self.row_buf {
1281                        if buf.predicate_ordinal.is_none() {
1282                            buf.predicate_ordinal = Some(slot);
1283                        }
1284                    }
1285                    let state = self.evaluate_predicate_state();
1286                    if let Some(ref mut buf) = self.row_buf {
1287                        buf.state = state;
1288                    }
1289                }
1290            }
1291        }
1292    }
1293
1294    #[inline]
1295    fn row_rejected(&self) -> bool {
1296        self.plan.filter.is_some()
1297            && self
1298                .row_buf
1299                .as_ref()
1300                .is_some_and(|b| b.state == PredicateState::Fail)
1301    }
1302
1303    #[inline]
1304    fn row_satisfied(&self) -> bool {
1305        let mask = self.wanted_mask();
1306        if mask == 0 {
1307            return false;
1308        }
1309        // Check that every wanted bit is set in row_dirty.
1310        let dirty = self
1311            .row_dirty
1312            .iter()
1313            .copied()
1314            .reduce(|a, b| a | b)
1315            .unwrap_or(0);
1316        (dirty & mask) == mask
1317    }
1318
1319    #[inline]
1320    fn wanted_mask(&self) -> u64 {
1321        // Precomputed in with_plan after schema columns are pre-declared.
1322        // Complete from the first row; 0 when no projection is active (the
1323        // short-circuit stays disabled unless the user explicitly declared
1324        // which columns they want via schema_order).
1325        self.cached_wanted_mask
1326    }
1327
1328    #[inline]
1329    fn finish(&mut self) -> Result<RecordBatch> {
1330        self.prepare_finish()?;
1331
1332        if self.column_order.is_empty() {
1333            let schema = Arc::new(Schema::empty());
1334            return Ok(RecordBatch::new_empty(schema));
1335        }
1336
1337        self.auto_dict_upgrade();
1338
1339        // Schema projection: emit exactly the declared columns, in the
1340        // declared order.  Columns declared but absent from the data are
1341        // null-filled; materialized non-schema columns (e.g. filter-only
1342        // fields kept for predicate evaluation) are projected out.
1343        if !self.plan.schema_order.is_empty() {
1344            let order = self.plan.schema_order.clone();
1345            let mut fields = Vec::with_capacity(order.len());
1346            let mut arrays = Vec::with_capacity(order.len());
1347            for name in &order {
1348                // drop_fields wins over schema (see predeclare_schema_columns).
1349                if self.plan.drop_fields.contains(name) {
1350                    continue;
1351                }
1352                let idx = match self.field_index.get(name.as_str()) {
1353                    Some(&i) => i,
1354                    None => {
1355                        // Declared but never seen: all-null column.
1356                        let ty = self.plan.column_type(name);
1357                        let mut b = ColumnBuilder::with_capacity(self.row_count.max(1), &ty);
1358                        for _ in 0..self.row_count {
1359                            b.push(None);
1360                        }
1361                        let idx = self.columns.len();
1362                        self.columns.push(b);
1363                        self.field_index.insert(name.clone(), idx);
1364                        idx
1365                    }
1366                };
1367                let b = &mut self.columns[idx];
1368                fields.push(ArrowField::new(name.as_str(), b.arrow_datatype(), true));
1369                arrays.push(b.to_arrow_array()?);
1370            }
1371            let schema = Arc::new(Schema::new(fields));
1372            return Ok(RecordBatch::try_new(schema, arrays)?);
1373        }
1374
1375        self.sort_columns();
1376
1377        let mut fields = Vec::with_capacity(self.column_order.len());
1378        let mut arrays = Vec::with_capacity(self.column_order.len());
1379        // Iterate by index so we can borrow columns mutably for zero-copy export.
1380        for name in &self.column_order {
1381            if let Some(&idx) = self.field_index.get(name.as_str()) {
1382                let b = &mut self.columns[idx];
1383                fields.push(ArrowField::new(name.as_str(), b.arrow_datatype(), true));
1384                arrays.push(b.to_arrow_array()?);
1385            }
1386        }
1387
1388        let schema = Arc::new(Schema::new(fields));
1389        Ok(RecordBatch::try_new(schema, arrays)?)
1390    }
1391
1392    #[inline]
1393    fn expect_slot(&self, ordinal: u32) -> Option<(u32, &[u8])> {
1394        self.ordinal_expect
1395            .get(ordinal as usize)
1396            .and_then(|entry| entry.as_ref())
1397            .map(|(slot, raw)| (*slot, raw.as_slice()))
1398    }
1399
1400    #[inline]
1401    fn record_slot(&mut self, ordinal: u32, slot: u32, raw_name: &[u8]) {
1402        let idx = ordinal as usize;
1403        let growth = idx
1404            .saturating_add(1)
1405            .saturating_sub(self.ordinal_expect.capacity())
1406            .saturating_mul(std::mem::size_of::<Option<(u32, Vec<u8>)>>());
1407        if !self.reserve_memory(growth.saturating_add(raw_name.len())) {
1408            return;
1409        }
1410        if idx >= self.ordinal_expect.len() {
1411            self.ordinal_expect.resize_with(idx + 1, || None);
1412        }
1413        self.ordinal_expect[idx] = Some((slot, raw_name.to_vec()));
1414    }
1415
1416    #[inline]
1417    fn layout_broken(&mut self, ordinal: u32) {
1418        if let Some(entry) = self.ordinal_expect.get_mut(ordinal as usize) {
1419            *entry = None;
1420        }
1421    }
1422
1423    #[inline]
1424    fn reset_child_ordinal(&mut self) {
1425        self.current_ordinal = 0;
1426    }
1427}
1428
1429// ---------------------------------------------------------------------------
1430// LocateOnly sink: walk rows, resolve field names, decode nothing.
1431// ---------------------------------------------------------------------------
1432
1433#[cfg(test)]
1434mod tests {
1435    use super::*;
1436    use crate::columnar::ColumnBuilder;
1437    use crate::decoder::{ColumnarSink, RecordParser, Splitter};
1438    use crate::plan::{CompareOp, ExecutionPlan, FieldType, FilterPredicate};
1439    use crate::value::Value;
1440    use crate::Result;
1441    use arrow::array::{Array, AsArray};
1442
1443    /// Simple newline-delimited parser for test data.
1444    /// Each line is a row; fields are `key=value` separated by spaces.
1445    #[derive(Clone)]
1446    struct LineParser;
1447
1448    impl RecordParser for LineParser {
1449        fn validate(&self, bytes: &[u8]) -> Result<()> {
1450            simdutf8::basic::from_utf8(bytes)?;
1451            Ok(())
1452        }
1453
1454        fn parse_chunk(&self, bytes: &[u8], sink: &mut dyn ColumnarSink) -> Result<()> {
1455            let text = std::str::from_utf8(bytes).map_err(|e| crate::Error::Plan(e.to_string()))?;
1456            for line in text.lines() {
1457                if line.is_empty() {
1458                    continue;
1459                }
1460                sink.begin_row();
1461                for token in line.split_whitespace() {
1462                    if let Some((k, v)) = token.split_once('=') {
1463                        sink.put_field(k, Value::Str(Cow::Borrowed(v)));
1464                    }
1465                }
1466                sink.end_row();
1467            }
1468            Ok(())
1469        }
1470    }
1471
1472    #[derive(Clone)]
1473    struct LineSplitter;
1474
1475    impl Splitter for LineSplitter {
1476        fn next_record_start(&self, bytes: &[u8], from: usize) -> Option<usize> {
1477            if from >= bytes.len() {
1478                return None;
1479            }
1480            // If we're at a newline, advance past it.
1481            let start = if bytes[from] == b'\n' { from + 1 } else { from };
1482            if start >= bytes.len() {
1483                return None;
1484            }
1485            memchr::memchr(b'\n', &bytes[start..]).map(|rel| start + rel + 1)
1486        }
1487
1488        fn find_split_points(&self, bytes: &[u8], max_chunks: usize) -> Vec<usize> {
1489            if max_chunks <= 1 || bytes.is_empty() {
1490                return vec![0, bytes.len()];
1491            }
1492            let mut points = vec![0usize];
1493            let mut last = 0;
1494            for (i, &b) in bytes.iter().enumerate() {
1495                if b == b'\n' {
1496                    let next = i + 1;
1497                    if next > last && points.len() < max_chunks {
1498                        points.push(next);
1499                        last = next;
1500                    }
1501                }
1502            }
1503            if *points.last().unwrap() != bytes.len() {
1504                points.push(bytes.len());
1505            }
1506            points
1507        }
1508
1509        fn estimate_bytes_per_row(&self, sample: &[u8]) -> usize {
1510            let newline_count = sample.iter().filter(|&&b| b == b'\n').count().max(1);
1511            (sample.len() / newline_count).max(1)
1512        }
1513    }
1514
1515    /// Records every hook call into a shared log, in call order.
1516    #[derive(Default)]
1517    struct RecObserver {
1518        events: std::sync::Mutex<Vec<String>>,
1519    }
1520
1521    impl RecObserver {
1522        fn log(&self, e: String) {
1523            self.events.lock().unwrap().push(e);
1524        }
1525        fn events(&self) -> Vec<String> {
1526            self.events.lock().unwrap().clone()
1527        }
1528    }
1529
1530    impl crate::RowObserver for RecObserver {
1531        fn on_begin_row(&self, row_index: usize) {
1532            self.log(format!("begin:{row_index}"));
1533        }
1534        fn on_put_field(&self, row_index: usize, name: &str, _slot: usize, _value: &Value<'_>) {
1535            self.log(format!("put:{row_index}:{name}"));
1536        }
1537        fn on_row_accepted(&self, row_index: usize) {
1538            self.log(format!("accept:{row_index}"));
1539        }
1540        fn on_row_rejected(&self, row_index: usize) {
1541            self.log(format!("reject:{row_index}"));
1542        }
1543        fn on_chunk_finished(&self, total: usize, accepted: usize, rejected: usize) {
1544            self.log(format!("fin:{total}:{accepted}:{rejected}"));
1545        }
1546    }
1547
1548    #[test]
1549    fn test_observer_lifecycle() {
1550        let obs = Arc::new(RecObserver::default());
1551        let mut plan = ExecutionPlan::new();
1552        plan.observer = Some(obs.clone());
1553        let mut engine = parse_bytes(b"X=1 Y=2\nX=3 Y=4\n", plan);
1554        engine.finish().unwrap();
1555        assert_eq!(
1556            obs.events(),
1557            vec![
1558                "begin:0",
1559                "put:0:X",
1560                "put:0:Y",
1561                "accept:0",
1562                "begin:1",
1563                "put:1:X",
1564                "put:1:Y",
1565                "accept:1",
1566                "fin:2:2:0",
1567                // finish() a second time re-fires with the same counters.
1568            ]
1569        );
1570    }
1571
1572    #[test]
1573    fn test_observer_with_filter() {
1574        let obs = Arc::new(RecObserver::default());
1575        let mut plan = ExecutionPlan::new();
1576        plan.filter = Some(FilterPredicate::Equal {
1577            field: "X".to_string(),
1578            value: "keep".to_string(),
1579        });
1580        plan.observer = Some(obs.clone());
1581        let mut engine = parse_bytes(b"X=keep A=1\nX=drop A=2\n", plan);
1582        engine.finish().unwrap();
1583        let ev = obs.events();
1584        // Rejected row: begin + reject, but its buffered fields never fire put.
1585        assert!(ev.contains(&"reject:1".to_string()), "events: {ev:?}");
1586        assert_eq!(
1587            ev.iter().filter(|e| e.starts_with("put:")).count(),
1588            2,
1589            "only the accepted row's fields may be observed: {ev:?}"
1590        );
1591        assert!(ev.contains(&"fin:2:1:1".to_string()), "events: {ev:?}");
1592    }
1593
1594    #[test]
1595    fn test_observer_parallel_counts_all_rows() {
1596        use std::sync::atomic::{AtomicUsize, Ordering as AOrd};
1597        #[derive(Default)]
1598        struct Counting {
1599            accepted: AtomicUsize,
1600            rejected: AtomicUsize,
1601        }
1602        impl crate::RowObserver for Counting {
1603            fn on_row_accepted(&self, _i: usize) {
1604                self.accepted.fetch_add(1, AOrd::Relaxed);
1605            }
1606            fn on_row_rejected(&self, _i: usize) {
1607                self.rejected.fetch_add(1, AOrd::Relaxed);
1608            }
1609        }
1610        let obs = Arc::new(Counting::default());
1611        let mut plan = ExecutionPlan::new();
1612        plan.filter = Some(FilterPredicate::NotEqual {
1613            field: "X".to_string(),
1614            value: "drop".to_string(),
1615        });
1616        plan.observer = Some(obs.clone());
1617        let mut data = Vec::new();
1618        for i in 0..1000 {
1619            let v = if i % 3 == 0 { "drop" } else { "keep" };
1620            data.extend_from_slice(format!("X={v} N={i}\n").as_bytes());
1621        }
1622        let pipeline = crate::Pipeline::new(LineSplitter, LineParser).with_plan(plan);
1623        let batches = pipeline.read_bytes_par(&data, 4).unwrap();
1624        let total: usize = batches.iter().map(|b| b.num_rows()).sum();
1625        let accepted = obs.accepted.load(AOrd::Relaxed);
1626        let rejected = obs.rejected.load(AOrd::Relaxed);
1627        assert_eq!(accepted + rejected, 1000);
1628        assert_eq!(accepted, total);
1629        assert_eq!(rejected, 334);
1630    }
1631
1632    #[test]
1633    fn test_not_wraps_leaf_predicates_predicate_first() {
1634        // Every leaf under Not must invert its result in the predicate-first
1635        // (buffered) path used when plan.filter is set.
1636        let cases: Vec<(FilterPredicate, &[u8], Vec<&str>)> = vec![
1637            (
1638                FilterPredicate::not(FilterPredicate::Equal {
1639                    field: "X".into(),
1640                    value: "keep".into(),
1641                }),
1642                b"X=keep\nX=drop\n",
1643                vec!["drop"],
1644            ),
1645            (
1646                FilterPredicate::not(FilterPredicate::IsNull { field: "X".into() }),
1647                b"X=1\nY=2\n",
1648                vec!["1"],
1649            ),
1650            (
1651                FilterPredicate::not(FilterPredicate::StartsWith {
1652                    field: "X".into(),
1653                    value: "ab".into(),
1654                }),
1655                b"X=abc\nX=zzz\n",
1656                vec!["zzz"],
1657            ),
1658            (
1659                FilterPredicate::not(FilterPredicate::In {
1660                    field: "X".into(),
1661                    values: vec!["a".into(), "b".into()],
1662                }),
1663                b"X=a\nX=b\nX=c\n",
1664                vec!["c"],
1665            ),
1666            (
1667                FilterPredicate::not(FilterPredicate::Regex {
1668                    field: "X".into(),
1669                    re: crate::plan::RegexSpec::new("^ERR").unwrap(),
1670                }),
1671                b"X=ERR1\nX=ok\n",
1672                vec!["ok"],
1673            ),
1674            (
1675                FilterPredicate::not(FilterPredicate::Contains {
1676                    field: "X".into(),
1677                    value: "zz".into(),
1678                }),
1679                b"X=azza\nX=hello\n",
1680                vec!["hello"],
1681            ),
1682        ];
1683        for (pred, data, want) in cases {
1684            let mut plan = ExecutionPlan::new();
1685            plan.filter = Some(pred);
1686            let engine = parse_bytes(data, plan);
1687            let col = engine.get_column("X").unwrap();
1688            assert_eq!(
1689                col.as_str_vec().iter().flatten().collect::<Vec<_>>(),
1690                want,
1691                "data: {}",
1692                String::from_utf8_lossy(data)
1693            );
1694        }
1695    }
1696
1697    #[test]
1698    fn test_not_wraps_leaf_predicates_batch_check() {
1699        // The batch path (FilterPredicate::check over finished columns) must
1700        // agree with the predicate-first path for Not-wrapped leaves.
1701        let data = b"X=keep N=1\nX=drop N=2\nX=keep N=3\n";
1702        let engine = parse_bytes(data, ExecutionPlan::new());
1703        let pred = FilterPredicate::not(FilterPredicate::Equal {
1704            field: "X".into(),
1705            value: "keep".into(),
1706        });
1707        let kept: Vec<usize> = (0..engine.num_rows())
1708            .filter(|&r| pred.check(&engine.columns, &engine.field_index, r, &engine.plan))
1709            .collect();
1710        assert_eq!(kept, vec![1]);
1711
1712        let pred = FilterPredicate::not(FilterPredicate::IsNull { field: "X".into() });
1713        let kept: Vec<usize> = (0..engine.num_rows())
1714            .filter(|&r| pred.check(&engine.columns, &engine.field_index, r, &engine.plan))
1715            .collect();
1716        assert_eq!(kept, vec![0, 1, 2]);
1717
1718        let pred = FilterPredicate::not(FilterPredicate::Regex {
1719            field: "X".into(),
1720            re: crate::plan::RegexSpec::new("ke*p").unwrap(),
1721        });
1722        let kept: Vec<usize> = (0..engine.num_rows())
1723            .filter(|&r| pred.check(&engine.columns, &engine.field_index, r, &engine.plan))
1724            .collect();
1725        assert_eq!(kept, vec![1]);
1726    }
1727
1728    #[test]
1729    fn test_regex_predicate() {
1730        let mut plan = ExecutionPlan::new();
1731        plan.filter = Some(FilterPredicate::Regex {
1732            field: "X".into(),
1733            re: crate::plan::RegexSpec::new("^ERR\\d+$").unwrap(),
1734        });
1735        let engine = parse_bytes(b"X=ERR12\nX=ok\nX=ERRx\nX=ERR0\n", plan);
1736        let col = engine.get_column("X").unwrap();
1737        assert_eq!(
1738            col.as_str_vec().iter().flatten().collect::<Vec<_>>(),
1739            vec!["ERR12", "ERR0"]
1740        );
1741        // Missing field never matches.
1742        let mut plan = ExecutionPlan::new();
1743        plan.filter = Some(FilterPredicate::Regex {
1744            field: "X".into(),
1745            re: crate::plan::RegexSpec::new(".*").unwrap(),
1746        });
1747        let engine = parse_bytes(b"X=a\nY=2\n", plan);
1748        assert_eq!(engine.num_rows(), 1);
1749        // Invalid pattern is rejected at construction.
1750        assert!(crate::plan::RegexSpec::new("(").is_err());
1751        // Equality follows the pattern string.
1752        assert_eq!(
1753            crate::plan::RegexSpec::new("^a").unwrap(),
1754            crate::plan::RegexSpec::new("^a").unwrap()
1755        );
1756        assert_ne!(
1757            crate::plan::RegexSpec::new("^a").unwrap(),
1758            crate::plan::RegexSpec::new("^b").unwrap()
1759        );
1760    }
1761
1762    #[test]
1763    fn test_no_observer_smoke() {
1764        // plan.observer = None: hooks compile to a skipped branch.
1765        let engine = parse_bytes(b"X=1\nX=2\n", ExecutionPlan::new());
1766        assert_eq!(engine.num_rows(), 2);
1767    }
1768
1769    fn parse_bytes(bytes: &[u8], plan: ExecutionPlan) -> TableBuilder {
1770        let mut sink = TableBuilder::with_plan((bytes.len() / 16).max(4), Arc::new(plan));
1771        LineParser.parse_chunk(bytes, &mut sink).unwrap();
1772        sink
1773    }
1774
1775    #[test]
1776    fn test_extend_no_duplicates() {
1777        let e1 = parse_bytes(b"A=1 B=2\n", ExecutionPlan::new());
1778        let mut merged = TableBuilder::new();
1779        merged.extend(e1).unwrap();
1780        assert_eq!(merged.num_rows(), 1);
1781        for col in &merged.columns {
1782            assert_eq!(col.len(), merged.num_rows(), "column length mismatch");
1783        }
1784    }
1785
1786    #[test]
1787    fn test_multi_chunk_same_as_single() {
1788        let data = b"A=1\nA=2\nA=3\n";
1789        let single = parse_bytes(data, ExecutionPlan::new());
1790        assert_eq!(single.num_rows(), 3);
1791
1792        let splitter = LineSplitter;
1793        let points = splitter.find_split_points(data, 2);
1794        let mut merged = TableBuilder::new();
1795        for w in points.windows(2) {
1796            let chunk = &data[w[0]..w[1]];
1797            let engine = parse_bytes(chunk, ExecutionPlan::new());
1798            merged.extend(engine).unwrap();
1799        }
1800        assert_eq!(merged.num_rows(), single.num_rows());
1801    }
1802
1803    #[test]
1804    fn test_last_write_wins_duplicate_field() {
1805        let engine = parse_bytes(b"X=10 X=20\n", ExecutionPlan::new());
1806        assert_eq!(engine.num_rows(), 1);
1807        let col = engine.get_column("X").unwrap();
1808        assert_eq!(col.as_str_vec(), vec![Some("20".into())]);
1809    }
1810
1811    #[test]
1812    fn test_build_plan_rename() {
1813        let mut plan = ExecutionPlan::new();
1814        plan.field_map.insert("X".to_string(), "Y".to_string());
1815        let engine = parse_bytes(b"X=hello\n", plan);
1816        assert_eq!(engine.num_rows(), 1);
1817        assert!(engine.get_column("Y").is_some());
1818        assert!(engine.get_column("X").is_none());
1819        assert_eq!(
1820            engine.get_column("Y").unwrap().as_str_vec(),
1821            vec![Some("hello".into())]
1822        );
1823    }
1824
1825    #[test]
1826    fn test_build_plan_drop() {
1827        let mut plan = ExecutionPlan::new();
1828        plan.drop_fields.insert("X".to_string());
1829        let engine = parse_bytes(b"X=hello Y=world\n", plan);
1830        assert_eq!(engine.num_rows(), 1);
1831        assert!(engine.get_column("X").is_none());
1832        assert!(engine.get_column("Y").is_some());
1833    }
1834
1835    #[test]
1836    fn test_build_plan_filter_ne() {
1837        let mut plan = ExecutionPlan::new();
1838        plan.filter = Some(FilterPredicate::NotEqual {
1839            field: "X".to_string(),
1840            value: "42".to_string(),
1841        });
1842        let engine = parse_bytes(b"X=10\nX=42\nX=30\n", plan);
1843        assert_eq!(engine.num_rows(), 2);
1844        let col = engine.get_column("X").unwrap();
1845        assert_eq!(col.as_str_vec(), vec![Some("10".into()), Some("30".into())]);
1846    }
1847
1848    #[test]
1849    fn test_build_plan_filter_eq() {
1850        let mut plan = ExecutionPlan::new();
1851        plan.filter = Some(FilterPredicate::Equal {
1852            field: "X".to_string(),
1853            value: "10".to_string(),
1854        });
1855        let engine = parse_bytes(b"X=10\nX=20\nX=10\n", plan);
1856        assert_eq!(engine.num_rows(), 2);
1857        let col = engine.get_column("X").unwrap();
1858        assert_eq!(col.as_str_vec(), vec![Some("10".into()), Some("10".into())]);
1859    }
1860
1861    #[test]
1862    fn test_build_plan_filter_missing_field() {
1863        let mut plan = ExecutionPlan::new();
1864        plan.filter = Some(FilterPredicate::NotEqual {
1865            field: "X".to_string(),
1866            value: "10".to_string(),
1867        });
1868        let engine = parse_bytes(b"X=10\nY=99\n", plan);
1869        assert_eq!(engine.num_rows(), 1);
1870        let col = engine.get_column("Y").unwrap();
1871        assert_eq!(col.as_str_vec(), vec![Some("99".into())]);
1872    }
1873
1874    #[test]
1875    fn test_typed_int64_column() {
1876        let mut plan = ExecutionPlan::new();
1877        plan.field_types.insert("X".to_string(), FieldType::Int64);
1878        let engine = parse_bytes(b"X=42\nX=bad\nX=100\n", plan);
1879        assert_eq!(engine.num_rows(), 3);
1880        if let ColumnBuilder::Int64(v) = engine.get_column("X").unwrap() {
1881            assert_eq!(v.get(0), Some(42));
1882            assert_eq!(v.get(1), None);
1883            assert_eq!(v.get(2), Some(100));
1884        } else {
1885            panic!("expected Int64 builder");
1886        }
1887    }
1888
1889    #[test]
1890    fn test_typed_float64_column() {
1891        let mut plan = ExecutionPlan::new();
1892        plan.field_types.insert("X".to_string(), FieldType::Float64);
1893        let engine = parse_bytes(b"X=1.5\n", plan);
1894        if let ColumnBuilder::Float64(v) = engine.get_column("X").unwrap() {
1895            assert!((v.get(0).unwrap() - 1.5).abs() < 1e-9);
1896        } else {
1897            panic!("expected Float64 builder");
1898        }
1899    }
1900
1901    #[test]
1902    fn test_is_null_filter() {
1903        let mut plan = ExecutionPlan::new();
1904        plan.filter = Some(FilterPredicate::IsNull {
1905            field: "X".to_string(),
1906        });
1907        let engine = parse_bytes(b"X=hello\nY=world\nX=fallback\n", plan);
1908        assert_eq!(engine.num_rows(), 1);
1909        let col = engine.get_column("Y").unwrap();
1910        assert_eq!(col.as_str_vec(), vec![Some("world".into())]);
1911    }
1912
1913    #[test]
1914    fn test_not_is_null_filter_predicate_first() {
1915        let mut plan = ExecutionPlan::new();
1916        plan.filter = Some(FilterPredicate::not(FilterPredicate::IsNull {
1917            field: "X".to_string(),
1918        }));
1919        let engine = parse_bytes(b"X=a\nY=only\nX=b\n", plan);
1920        assert_eq!(engine.num_rows(), 2);
1921        let col = engine.get_column("X").unwrap();
1922        assert_eq!(col.as_str_vec(), vec![Some("a".into()), Some("b".into())]);
1923    }
1924
1925    #[test]
1926    fn test_not_is_null_filter_batch_eval() {
1927        // Force the late-predicate path (direct push + pop-on-reject at
1928        // end_row, evaluated via FilterPredicate::check in plan.rs).
1929        let mut plan = ExecutionPlan::new();
1930        plan.filter = Some(FilterPredicate::not(FilterPredicate::IsNull {
1931            field: "X".to_string(),
1932        }));
1933        let mut sink = TableBuilder::with_plan(4, Arc::new(plan));
1934        sink.row_buf.as_mut().unwrap().buffer_worthwhile = false;
1935        LineParser
1936            .parse_chunk(b"X=a\nY=only\nX=b\n", &mut sink)
1937            .unwrap();
1938        assert_eq!(sink.num_rows(), 2);
1939        let col = sink.get_column("X").unwrap();
1940        assert_eq!(col.as_str_vec(), vec![Some("a".into()), Some("b".into())]);
1941    }
1942
1943    #[test]
1944    fn test_strict_types_errors_on_malformed_int64() {
1945        let mut plan = ExecutionPlan::new();
1946        plan.field_types.insert("X".to_string(), FieldType::Int64);
1947        plan.strict_types = true;
1948        let mut engine = parse_bytes(b"X=42\nX=abc\n", plan);
1949        let err = engine.finish().unwrap_err();
1950        let msg = err.to_string();
1951        assert!(msg.contains("\"abc\""), "message should name value: {msg}");
1952        assert!(msg.contains("\"X\""), "message should name column: {msg}");
1953        assert!(msg.contains("Int64"), "message should name type: {msg}");
1954        assert!(msg.contains("row 1"), "message should name row: {msg}");
1955    }
1956
1957    #[test]
1958    fn test_strict_types_off_yields_null() {
1959        let mut plan = ExecutionPlan::new();
1960        plan.field_types.insert("X".to_string(), FieldType::Int64);
1961        let engine = parse_bytes(b"X=42\nX=abc\n", plan);
1962        assert!(engine.strict_error.is_none());
1963        if let ColumnBuilder::Int64(v) = engine.get_column("X").unwrap() {
1964            assert_eq!(v.get(0), Some(42));
1965            assert_eq!(v.get(1), None);
1966        } else {
1967            panic!("expected Int64 builder");
1968        }
1969    }
1970
1971    #[test]
1972    fn test_strict_types_missing_field_stays_null() {
1973        let mut plan = ExecutionPlan::new();
1974        plan.field_types.insert("X".to_string(), FieldType::Int64);
1975        plan.strict_types = true;
1976        let mut engine = parse_bytes(b"X=42\nY=1\n", plan);
1977        let batch = engine.finish().unwrap();
1978        let idx = batch.schema().index_of("X").unwrap();
1979        let arr = batch
1980            .column(idx)
1981            .as_primitive::<arrow::datatypes::Int64Type>();
1982        assert_eq!(arr.value(0), 42);
1983        assert!(arr.is_null(1));
1984    }
1985
1986    #[test]
1987    fn test_strict_types_buffered_filter_path() {
1988        // With a filter, values travel through the predicate row buffer; the
1989        // strict check must fire there too.
1990        let mut plan = ExecutionPlan::new();
1991        plan.field_types.insert("X".to_string(), FieldType::Int64);
1992        plan.strict_types = true;
1993        plan.filter = Some(FilterPredicate::Equal {
1994            field: "Y".to_string(),
1995            value: "1".to_string(),
1996        });
1997        let mut engine = parse_bytes(b"Y=1 X=abc\n", plan);
1998        let err = engine.finish().unwrap_err();
1999        assert!(err.to_string().contains("strict_types"));
2000    }
2001
2002    #[test]
2003    fn test_is_type_filter_int64() {
2004        let mut plan = ExecutionPlan::new();
2005        plan.field_types.insert("X".to_string(), FieldType::Int64);
2006        plan.filter = Some(FilterPredicate::IsType {
2007            field: "X".to_string(),
2008            field_type: FieldType::Int64,
2009        });
2010        let engine = parse_bytes(b"X=42\nX=bad\nX=100\n", plan);
2011        assert_eq!(engine.num_rows(), 2);
2012        if let ColumnBuilder::Int64(v) = engine.get_column("X").unwrap() {
2013            assert_eq!(v.get(0), Some(42));
2014            assert_eq!(v.get(1), Some(100));
2015        } else {
2016            panic!("expected Int64 builder");
2017        }
2018    }
2019
2020    #[test]
2021    fn test_is_type_filter_float64() {
2022        let mut plan = ExecutionPlan::new();
2023        plan.field_types.insert("X".to_string(), FieldType::Float64);
2024        plan.filter = Some(FilterPredicate::IsType {
2025            field: "X".to_string(),
2026            field_type: FieldType::Float64,
2027        });
2028        let engine = parse_bytes(b"X=1.5\nX=bad\nX=2.5\n", plan);
2029        assert_eq!(engine.num_rows(), 2);
2030        if let ColumnBuilder::Float64(v) = engine.get_column("X").unwrap() {
2031            assert!((v.get(0).unwrap() - 1.5).abs() < 1e-9);
2032            assert!((v.get(1).unwrap() - 2.5).abs() < 1e-9);
2033        } else {
2034            panic!("expected Float64 builder");
2035        }
2036    }
2037
2038    #[test]
2039    fn test_dictionary_column() {
2040        let mut plan = ExecutionPlan::new();
2041        plan.dictionary_columns.insert("P".to_string());
2042        let engine = parse_bytes(b"P=Widget\nP=Gadget\nP=Widget\n", plan);
2043        assert_eq!(engine.num_rows(), 3);
2044        if let ColumnBuilder::Dictionary { codes, offsets, .. } = engine.get_column("P").unwrap() {
2045            let dict_len = offsets.len() - 1;
2046            assert_eq!(dict_len, 2);
2047            assert_eq!(
2048                codes.iter().map(|o| o.copied()).collect::<Vec<_>>(),
2049                vec![Some(0), Some(1), Some(0)]
2050            );
2051        } else {
2052            panic!("expected Dictionary builder");
2053        }
2054    }
2055
2056    #[test]
2057    fn test_ragged_late_chunk_column_debut() {
2058        let e1 = parse_bytes(b"A=1 B=2\nA=3\n", ExecutionPlan::new());
2059        let e2 = parse_bytes(b"B=4 C=5\n", ExecutionPlan::new());
2060        let mut merged = TableBuilder::new();
2061        merged.extend(e1).unwrap();
2062        merged.extend(e2).unwrap();
2063
2064        assert_eq!(
2065            merged.get_column("A").unwrap().as_str_vec(),
2066            vec![Some("1".into()), Some("3".into()), None]
2067        );
2068        assert_eq!(
2069            merged.get_column("B").unwrap().as_str_vec(),
2070            vec![Some("2".into()), None, Some("4".into())]
2071        );
2072        assert_eq!(
2073            merged.get_column("C").unwrap().as_str_vec(),
2074            vec![None, None, Some("5".into())]
2075        );
2076    }
2077
2078    #[test]
2079    fn test_auto_dict_upgrade_only_post_merge() {
2080        let mut plan = ExecutionPlan::new();
2081        plan.auto_dict = true;
2082        let a = parse_bytes(b"P=x\nP=y\n", plan.clone());
2083        let b = parse_bytes(b"P=x\nP=y\n", plan.clone());
2084        let mut merged = TableBuilder::with_plan(64, Arc::new(plan));
2085        merged.extend(a).unwrap();
2086        merged.extend(b).unwrap();
2087        merged.auto_dict_upgrade();
2088        assert_eq!(merged.num_rows(), 4);
2089    }
2090
2091    #[test]
2092    fn test_extend_string_dictionary_promotes_not_panics() {
2093        let mut e1 = parse_bytes(b"P=x\n", ExecutionPlan::new());
2094        let mut plan = ExecutionPlan::new();
2095        plan.dictionary_columns.insert("P".to_string());
2096        let e2 = parse_bytes(b"P=x\n", plan);
2097        // Safe promotion: string + dictionary reconcile to dictionary.
2098        e1.extend(e2).expect("String/Dictionary must reconcile");
2099        assert!(matches!(
2100            e1.get_column("P").unwrap(),
2101            crate::columnar::ColumnBuilder::Dictionary { .. }
2102        ));
2103    }
2104
2105    #[test]
2106    fn test_extend_irreconcilable_variants_error_not_panic() {
2107        let mut e1 = parse_bytes(b"S=x\n", ExecutionPlan::new());
2108        let mut plan = ExecutionPlan::new();
2109        plan.field_types.insert("S".to_string(), FieldType::Int64);
2110        let e2 = parse_bytes(b"S=7\n", plan);
2111        let result = e1.extend(e2);
2112        match result {
2113            Err(crate::Error::Merge(msg)) => {
2114                assert!(msg.contains("'S'"), "error should name the column: {msg}");
2115            }
2116            other => panic!("String/Int64 mismatch must return Merge error, got {other:?}"),
2117        }
2118    }
2119
2120    #[test]
2121    fn test_compare_filter_via_arrow_compute() {
2122        use crate::arrow_export::apply_compare_filter;
2123
2124        let mut plan = ExecutionPlan::new();
2125        plan.filter = Some(FilterPredicate::Compare {
2126            field_a: "A".to_string(),
2127            op: CompareOp::Gt,
2128            field_b: "B".to_string(),
2129        });
2130        let mut engine = parse_bytes(b"A=3 B=1\nA=2 B=2\nA=5 B=4\n", plan);
2131        let batch = engine.finish().unwrap();
2132        let filtered = apply_compare_filter(
2133            batch,
2134            &FilterPredicate::Compare {
2135                field_a: "A".to_string(),
2136                op: CompareOp::Gt,
2137                field_b: "B".to_string(),
2138            },
2139        )
2140        .unwrap();
2141        assert_eq!(filtered.num_rows(), 2);
2142        let a = filtered.column_by_name("A").unwrap().as_string::<i32>();
2143        assert_eq!(a.value(0), "3");
2144        assert_eq!(a.value(1), "5");
2145    }
2146
2147    #[test]
2148    fn test_row_dirty_is_full_edge_cases() {
2149        // Directly test the is_full logic for ncols = 1,63,64,65,127,128,129
2150        // We do this via TableBuilder with varying column counts
2151        for ncols in [1, 63, 64, 65, 127, 128, 129] {
2152            let mut tb = TableBuilder::new();
2153            for i in 0..ncols {
2154                let name = format!("col{i}");
2155                tb.field_index.insert(name.clone(), i);
2156                tb.columns.push(crate::columnar::ColumnBuilder::String(
2157                    crate::columnar::StrColumn::default(),
2158                ));
2159                tb.column_order.push(name);
2160            }
2161            // row_dirty should be vec![0; (ncols+63)/64]
2162            tb.row_dirty = vec![0; ncols.div_ceil(64)];
2163            // Test is_full when all bits set
2164            for i in 0..ncols {
2165                let word = i / 64;
2166                let bit = i % 64;
2167                tb.row_dirty[word] |= 1u64 << bit;
2168            }
2169            let full_words = ncols / 64;
2170            let rem = ncols % 64;
2171            let is_full = (0..full_words).all(|w| tb.row_dirty[w] == u64::MAX)
2172                && (rem == 0
2173                    || tb.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem) - 1);
2174            assert!(
2175                is_full,
2176                "ncols={ncols} should be full, row_dirty={:?}",
2177                tb.row_dirty
2178            );
2179            // Clear one bit and check not full
2180            if ncols > 0 {
2181                let word = (ncols - 1) / 64;
2182                let bit = (ncols - 1) % 64;
2183                tb.row_dirty[word] &= !(1u64 << bit);
2184                let is_full2 = (0..full_words).all(|w| tb.row_dirty[w] == u64::MAX)
2185                    && (rem == 0
2186                        || tb.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem) - 1);
2187                assert!(
2188                    !is_full2,
2189                    "ncols={ncols} should not be full after clearing one bit"
2190                );
2191            }
2192        }
2193    }
2194
2195    #[test]
2196    fn test_finish_twice_does_not_panic() {
2197        // L7: zero-copy export (mem::take) leaves builders empty. Calling
2198        // finish() twice should return an empty batch, not panic.
2199        let mut tb = parse_bytes(b"A=1 B=2\nA=3 B=4\n", ExecutionPlan::new());
2200        let batch1 = tb.finish().unwrap();
2201        assert_eq!(batch1.num_rows(), 2);
2202        // Second call: columns are empty after mem::take.
2203        let batch2 = tb.finish().unwrap();
2204        assert_eq!(batch2.num_rows(), 0);
2205    }
2206
2207    #[test]
2208    fn test_c2_compound_reorder() {
2209        // L7: C2 reorder: Field2 == x AND Field1 == y must give the same
2210        // result as Field1 == y AND Field2 == x.
2211        let data = b"A=1 B=2\nA=2 B=2\nA=1 B=3\nA=2 B=3\n";
2212        let make_filter = |a: &str, va: &str, b: &str, vb: &str| -> ExecutionPlan {
2213            let mut plan = ExecutionPlan::new();
2214            plan.filter = Some(FilterPredicate::And(
2215                Box::new(FilterPredicate::Equal {
2216                    field: a.to_string(),
2217                    value: va.to_string(),
2218                }),
2219                Box::new(FilterPredicate::Equal {
2220                    field: b.to_string(),
2221                    value: vb.to_string(),
2222                }),
2223            ));
2224            plan
2225        };
2226        let r1 = parse_bytes(data, make_filter("A", "1", "B", "2"));
2227        let r2 = parse_bytes(data, make_filter("B", "2", "A", "1"));
2228        assert_eq!(
2229            r1.num_rows(),
2230            r2.num_rows(),
2231            "C2 reorder must produce identical results"
2232        );
2233        assert_eq!(r1.num_rows(), 1); // A=1 B=2
2234    }
2235
2236    #[test]
2237    fn test_c2_or_reorder() {
2238        // L7: Or reorder: same result regardless of operand order.
2239        // Row 1: A=1 B=2 → A==1 → Pass
2240        // Row 2: A=2 B=2 → A!=1, B!=3 → Fail
2241        // Row 3: A=3 B=3 → B==3 → Pass
2242        let data = b"A=1 B=2\nA=2 B=2\nA=3 B=3\n";
2243        let make_filter = |a: &str, va: &str, b: &str, vb: &str| -> ExecutionPlan {
2244            let mut plan = ExecutionPlan::new();
2245            plan.filter = Some(FilterPredicate::Or(
2246                Box::new(FilterPredicate::Equal {
2247                    field: a.to_string(),
2248                    value: va.to_string(),
2249                }),
2250                Box::new(FilterPredicate::Equal {
2251                    field: b.to_string(),
2252                    value: vb.to_string(),
2253                }),
2254            ));
2255            plan
2256        };
2257        let r1 = parse_bytes(data, make_filter("A", "1", "B", "3"));
2258        let r2 = parse_bytes(data, make_filter("B", "3", "A", "1"));
2259        assert_eq!(
2260            r1.num_rows(),
2261            r2.num_rows(),
2262            "Or reorder must produce identical results"
2263        );
2264        assert_eq!(r1.num_rows(), 2); // rows 1 and 3
2265    }
2266
2267    #[test]
2268    fn test_predicate_slot_created_after_mask_build() {
2269        // Regression: when the predicate column appears AFTER other columns
2270        // in document order, build_predicate_mask runs before the predicate
2271        // column exists in field_index, so its bit is never set. The old
2272        // early-return optimization prevented it from being added later.
2273        //
2274        // Data: A comes first, B is the predicate column (comes second).
2275        // Filter: B == "reject" → all rows should be rejected.
2276        let data = b"A=1 B=ok\nA=2 B=ok\nA=3 B=ok\n";
2277        let mut plan = ExecutionPlan::new();
2278        plan.filter = Some(FilterPredicate::Equal {
2279            field: "B".to_string(),
2280            value: "reject".to_string(),
2281        });
2282        let engine = parse_bytes(data, plan);
2283        assert_eq!(
2284            engine.num_rows(),
2285            0,
2286            "all rows should be rejected (B != reject)"
2287        );
2288
2289        // Positive case: some rows pass
2290        let data2 = b"A=1 B=ok\nA=2 B=reject\nA=3 B=ok\n";
2291        let mut plan2 = ExecutionPlan::new();
2292        plan2.filter = Some(FilterPredicate::Equal {
2293            field: "B".to_string(),
2294            value: "ok".to_string(),
2295        });
2296        let engine2 = parse_bytes(data2, plan2);
2297        assert_eq!(engine2.num_rows(), 2, "rows 1 and 3 pass (B == ok)");
2298        let col = engine2.get_column("A").unwrap();
2299        assert_eq!(col.as_str_vec(), vec![Some("1".into()), Some("3".into())]);
2300    }
2301
2302    #[test]
2303    fn test_predicate_first_via_resolve_and_put() {
2304        // Uses resolve_and_put (scanner path) instead of put_field (LineParser path)
2305        // to verify the predicate machinery works through the scanner's code path.
2306        let mut plan = ExecutionPlan::new();
2307        plan.filter = Some(FilterPredicate::Equal {
2308            field: "B".to_string(),
2309            value: "reject".to_string(),
2310        });
2311        let mut tb = TableBuilder::with_plan(16, Arc::new(plan));
2312        // Row 1: B=ok → should pass
2313        tb.begin_row();
2314        tb.resolve_and_put("A", Value::Str(Cow::Borrowed("1")));
2315        tb.resolve_and_put("B", Value::Str(Cow::Borrowed("ok")));
2316        tb.end_row();
2317        // Row 2: B=reject → should fail
2318        tb.begin_row();
2319        tb.resolve_and_put("A", Value::Str(Cow::Borrowed("2")));
2320        tb.resolve_and_put("B", Value::Str(Cow::Borrowed("reject")));
2321        tb.end_row();
2322        // Row 3: B=ok → should pass
2323        tb.begin_row();
2324        tb.resolve_and_put("A", Value::Str(Cow::Borrowed("3")));
2325        tb.resolve_and_put("B", Value::Str(Cow::Borrowed("ok")));
2326        tb.end_row();
2327        let batch = tb.finish().unwrap();
2328        assert_eq!(batch.num_rows(), 1, "only row 2 (B==reject) should pass");
2329    }
2330
2331    #[test]
2332    fn test_owned_cow_values_survive_buffered_filter() {
2333        // Regression for the use-after-free behind this change: Value::Str
2334        // used to be `&'a str`, and the buffered filtered path transmutes
2335        // `Value<'a>` to `Value<'static>` to hold values until the predicate
2336        // is decided. Adapters that unescape entities produce owned Strings;
2337        // the owned buffer was dropped at the end of the scan function and
2338        // the transmuted reference dangled, so heap reuse corrupted accepted
2339        // rows after enough rejections. With `Str(Cow<'a, str>)` the owned
2340        // buffer moves into the row buffer.
2341        let mut plan = ExecutionPlan::new();
2342        plan.filter = Some(FilterPredicate::Equal {
2343            field: "B".to_string(),
2344            value: "ok".to_string(),
2345        });
2346        let mut tb = TableBuilder::with_plan(16, Arc::new(plan));
2347        for i in 0..50 {
2348            tb.begin_row();
2349            // Owned values, as produced by entity unescaping in an adapter.
2350            let a = Cow::Owned(format!("value-{i}-unescaped"));
2351            let b = Cow::Owned(if i % 2 == 0 {
2352                "ok".to_string()
2353            } else {
2354                "no".to_string()
2355            });
2356            tb.resolve_and_put("A", Value::Str(a));
2357            tb.resolve_and_put("B", Value::Str(b));
2358            tb.end_row();
2359        }
2360        assert_eq!(tb.num_rows(), 25, "even rows pass (B == ok)");
2361        let col = tb.get_column("A").unwrap();
2362        let vals = col.as_str_vec();
2363        assert_eq!(vals.len(), 25);
2364        assert_eq!(vals[0], Some("value-0-unescaped".to_string()));
2365        assert_eq!(vals[24], Some("value-48-unescaped".to_string()));
2366    }
2367
2368    #[test]
2369    fn test_predicate_first_skip_via_resolve_and_put() {
2370        // Test the skip path: predicate on first field, all rows rejected.
2371        // This exercises the mark_predicate_slot + row_rejected + end_row path
2372        // that the scanner uses via resolve_and_put.
2373        let mut plan = ExecutionPlan::new();
2374        plan.filter = Some(FilterPredicate::Equal {
2375            field: "A".to_string(),
2376            value: "999".to_string(),
2377        });
2378        let mut tb = TableBuilder::with_plan(16, Arc::new(plan));
2379        for _i in 0..100 {
2380            tb.begin_row();
2381            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("0")));
2382            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("x")));
2383            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("y")));
2384            tb.end_row();
2385        }
2386        let batch = tb.finish().unwrap();
2387        assert_eq!(
2388            batch.num_rows(),
2389            0,
2390            "all rows should be rejected (A=0 != 999)"
2391        );
2392    }
2393
2394    #[test]
2395    fn test_sparse_column_predicate_skip() {
2396        // Regression test for ncols gate: sparse column appears only after
2397        // row 50, predicate on early field (A). The adaptive strategy must
2398        // not disable buffering because ncols is computed from the incomplete
2399        // column set before the sparse column appears.
2400        //
2401        // Data: 100 rows. Rows 1-50 have A, B, C. Rows 51-100 also have D.
2402        // Filter: A == "reject" → all rows rejected.
2403        // The skip must fire for all rows, not just the first few.
2404        let mut plan = ExecutionPlan::new();
2405        plan.filter = Some(FilterPredicate::Equal {
2406            field: "A".to_string(),
2407            value: "reject".to_string(),
2408        });
2409        let mut tb = TableBuilder::with_plan(128, Arc::new(plan));
2410        for i in 0..100 {
2411            tb.begin_row();
2412            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("ok")));
2413            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("x")));
2414            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("y")));
2415            if i >= 50 {
2416                tb.resolve_and_put("D", Value::Str(Cow::Borrowed("z")));
2417            }
2418            tb.end_row();
2419        }
2420        let batch = tb.finish().unwrap();
2421        assert_eq!(batch.num_rows(), 0, "all rows rejected (A=ok != reject)");
2422    }
2423
2424    #[test]
2425    fn test_sparse_column_predicate_pass() {
2426        // Like above, but predicate passes. The sparse column D should appear
2427        // only for rows 51-100; rows 1-50 should have D = null.
2428        let mut plan = ExecutionPlan::new();
2429        plan.filter = Some(FilterPredicate::Equal {
2430            field: "A".to_string(),
2431            value: "ok".to_string(),
2432        });
2433        let mut tb = TableBuilder::with_plan(128, Arc::new(plan));
2434        for _i in 0..100 {
2435            tb.begin_row();
2436            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("ok")));
2437            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("x")));
2438            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("y")));
2439            if _i >= 50 {
2440                tb.resolve_and_put("D", Value::Str(Cow::Borrowed("z")));
2441            }
2442            tb.end_row();
2443        }
2444        let batch = tb.finish().unwrap();
2445        assert_eq!(batch.num_rows(), 100, "all rows pass (A=ok == ok)");
2446        // D column: null for first 50, "z" for last 50
2447        if let Some(col) = batch.column_by_name("D") {
2448            let arr = col.as_string::<i32>();
2449            for i in 0..50 {
2450                assert!(arr.is_null(i), "row {} should have D=null", i);
2451            }
2452            for i in 50..100 {
2453                assert!(
2454                    !arr.is_null(i),
2455                    "row {} should not be null (D len={}, total rows={})",
2456                    i,
2457                    arr.len(),
2458                    batch.num_rows()
2459                );
2460                assert_eq!(arr.value(i), "z", "rows 50+ should have D=z");
2461            }
2462        } else {
2463            panic!("D column should exist");
2464        }
2465    }
2466
2467    #[test]
2468    fn test_sparse_late_predicate_ordinal() {
2469        // Regression: predicate on column E that only appears after row 30.
2470        // ncols gate must use schema/column count that includes E, not just
2471        // the columns seen so far.
2472        let mut plan = ExecutionPlan::new();
2473        plan.filter = Some(FilterPredicate::Equal {
2474            field: "E".to_string(),
2475            value: "999".to_string(),
2476        });
2477        let mut tb = TableBuilder::with_plan(128, Arc::new(plan));
2478        // First 30 rows: only A, B
2479        for _i in 0..30 {
2480            tb.begin_row();
2481            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("x")));
2482            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("y")));
2483            tb.end_row();
2484        }
2485        // Rows 31-100: A, B, C, D, E
2486        for _i in 30..100 {
2487            tb.begin_row();
2488            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("x")));
2489            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("y")));
2490            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("c")));
2491            tb.resolve_and_put("D", Value::Str(Cow::Borrowed("d")));
2492            tb.resolve_and_put("E", Value::Str(Cow::Borrowed("e")));
2493            tb.end_row();
2494        }
2495        let batch = tb.finish().unwrap();
2496        // E="e" != "999" → all rows rejected
2497        assert_eq!(batch.num_rows(), 0, "all rows rejected (E=\"e\" != 999)");
2498    }
2499
2500    #[test]
2501    fn raw_name_helpers_apply_rename_and_drop() {
2502        use crate::decoder::ColumnarSink;
2503
2504        let plan = ExecutionPlan::new()
2505            .rename("raw", "renamed")
2506            .drop("ignored");
2507        let mut tb = TableBuilder::with_plan(2, Arc::new(plan));
2508        tb.begin_row();
2509        tb.resolve_and_put_raw(b"raw", Value::Str(Cow::Borrowed("value")));
2510        tb.resolve_and_put_raw(b"ignored", Value::Str(Cow::Borrowed("not stored")));
2511        tb.put_row(&[("other", Value::Str(Cow::Borrowed("also stored")))]);
2512        tb.end_row();
2513
2514        assert_eq!(tb.column_names(), &["renamed", "other"]);
2515        assert_eq!(tb.resolve_raw(b"raw"), Some("renamed"));
2516    }
2517
2518    // -----------------------------------------------------------------------
2519    // Schema projection semantics: schema=[...] declares exactly which
2520    // columns are extracted, in order.  Unlisted fields are skipped during
2521    // parsing (wants()/resolve() reject them); listed columns absent from
2522    // the data are null-filled.
2523    // -----------------------------------------------------------------------
2524
2525    /// Parser that mimics adapter projection behavior (e.g. crxml's scanner):
2526    /// skips fields the sink rejects via `resolve()` and byte-jumps to the
2527    /// end of the row once `row_satisfied()` reports all wanted columns seen.
2528    struct SkippingParser;
2529
2530    impl RecordParser for SkippingParser {
2531        fn validate(&self, bytes: &[u8]) -> Result<()> {
2532            simdutf8::basic::from_utf8(bytes)?;
2533            Ok(())
2534        }
2535
2536        fn parse_chunk(&self, bytes: &[u8], sink: &mut dyn ColumnarSink) -> Result<()> {
2537            let text = std::str::from_utf8(bytes).map_err(|e| crate::Error::Plan(e.to_string()))?;
2538            for line in text.lines() {
2539                if line.is_empty() {
2540                    continue;
2541                }
2542                sink.begin_row();
2543                for token in line.split_whitespace() {
2544                    if sink.row_satisfied() {
2545                        break; // byte-jump to row close: remaining fields skipped
2546                    }
2547                    if let Some((k, v)) = token.split_once('=') {
2548                        if sink.resolve(k).is_some() {
2549                            sink.resolve_and_put(k, Value::Str(Cow::Borrowed(v)));
2550                        }
2551                    }
2552                }
2553                sink.end_row();
2554            }
2555            Ok(())
2556        }
2557    }
2558
2559    fn parse_skipping(bytes: &[u8], plan: ExecutionPlan) -> TableBuilder {
2560        let mut sink = TableBuilder::with_plan((bytes.len() / 16).max(4), Arc::new(plan));
2561        SkippingParser.parse_chunk(bytes, &mut sink).unwrap();
2562        sink
2563    }
2564
2565    fn batch_names(tb: &mut TableBuilder) -> Vec<String> {
2566        tb.finish()
2567            .unwrap()
2568            .schema()
2569            .fields()
2570            .iter()
2571            .map(|f| f.name().clone())
2572            .collect()
2573    }
2574
2575    const REPORT: &[u8] = b"Name=n1 Department=d1 Amount=1 Status=s1 Date=2024\n\
2576                            Name=n2 Department=d2 Amount=2 Status=s2 Date=2024\n";
2577
2578    #[test]
2579    fn schema_projection_subset() {
2580        // schema=["Name","Department"] must yield exactly those two columns,
2581        // in that order.  Regression: the old wanted_mask was derived from
2582        // field_index mid-row, so row_satisfied fired after "Name" on row 1
2583        // and "Department" was never materialized (output was ["Name"]).
2584        let mut tb = parse_skipping(
2585            REPORT,
2586            ExecutionPlan::new().schema_order(["Name", "Department"]),
2587        );
2588        assert_eq!(batch_names(&mut tb), vec!["Name", "Department"]);
2589    }
2590
2591    #[test]
2592    fn schema_projection_single_non_first_column() {
2593        // Regression: the old code emitted ["Department", "Name"] here —
2594        // "Name" was materialized because resolve_field did no projection.
2595        let mut tb = parse_skipping(REPORT, ExecutionPlan::new().schema_order(["Department"]));
2596        assert_eq!(batch_names(&mut tb), vec!["Department"]);
2597    }
2598
2599    #[test]
2600    fn schema_projection_full_natural_order() {
2601        let mut tb = parse_skipping(
2602            REPORT,
2603            ExecutionPlan::new().schema_order(["Name", "Department", "Amount", "Status", "Date"]),
2604        );
2605        assert_eq!(
2606            batch_names(&mut tb),
2607            vec!["Name", "Department", "Amount", "Status", "Date"]
2608        );
2609    }
2610
2611    #[test]
2612    fn schema_projection_reversed_order() {
2613        let mut tb = parse_skipping(
2614            REPORT,
2615            ExecutionPlan::new().schema_order(["Date", "Status", "Amount", "Department", "Name"]),
2616        );
2617        assert_eq!(
2618            batch_names(&mut tb),
2619            vec!["Date", "Status", "Amount", "Department", "Name"]
2620        );
2621    }
2622
2623    #[test]
2624    fn schema_projection_absent_column_null_filled() {
2625        // Schema is a superset of the data: the absent column is null-filled.
2626        let mut tb = parse_skipping(
2627            REPORT,
2628            ExecutionPlan::new().schema_order(["Name", "Missing"]),
2629        );
2630        let batch = tb.finish().unwrap();
2631        assert_eq!(batch.num_rows(), 2);
2632        let missing = batch.column_by_name("Missing").unwrap().as_string::<i32>();
2633        assert!(missing.is_null(0) && missing.is_null(1));
2634        let name = batch.column_by_name("Name").unwrap().as_string::<i32>();
2635        assert_eq!(name.value(0), "n1");
2636    }
2637
2638    #[test]
2639    fn schema_projection_wants_rejects_unlisted_fields() {
2640        // The perf contract: unlisted fields are rejected by wants()/resolve()
2641        // so adapters skip extracting them entirely.
2642        let plan = ExecutionPlan::new().schema_order(["Name"]);
2643        let tb = TableBuilder::with_plan(4, Arc::new(plan));
2644        assert!(tb.wants("Name"));
2645        assert!(!tb.wants("Department"));
2646        assert_eq!(tb.resolve("Amount"), None);
2647    }
2648
2649    #[test]
2650    fn schema_projection_rename_then_match() {
2651        // field_mapping applies before schema matching: the schema lists the
2652        // renamed (output) column name.
2653        let plan = ExecutionPlan::new()
2654            .rename("Name", "Employee")
2655            .schema_order(["Employee", "Amount"]);
2656        let mut tb = parse_skipping(REPORT, plan);
2657        assert_eq!(batch_names(&mut tb), vec!["Employee", "Amount"]);
2658    }
2659
2660    #[test]
2661    fn schema_projection_field_types_apply() {
2662        let plan = ExecutionPlan::new()
2663            .type_as("Amount", FieldType::Int64)
2664            .schema_order(["Name", "Amount"]);
2665        let mut tb = parse_skipping(REPORT, plan);
2666        let batch = tb.finish().unwrap();
2667        let amount = batch.column_by_name("Amount").unwrap();
2668        assert!(matches!(
2669            amount.data_type(),
2670            arrow::datatypes::DataType::Int64
2671        ));
2672        assert_eq!(
2673            amount
2674                .as_primitive::<arrow::datatypes::Int64Type>()
2675                .value(1),
2676            2
2677        );
2678    }
2679
2680    #[test]
2681    fn schema_projection_filter_on_unlisted_field() {
2682        // Filter fields are materialized for predicate evaluation even when
2683        // not in the schema, but are projected out of the final batch.
2684        let plan = ExecutionPlan::new()
2685            .schema_order(["Name"])
2686            .filter_eq("Status", "s2");
2687        let mut tb = parse_skipping(REPORT, plan);
2688        let batch = tb.finish().unwrap();
2689        assert_eq!(batch.num_rows(), 1);
2690        assert_eq!(batch.schema().fields().len(), 1);
2691        let name = batch.column_by_name("Name").unwrap().as_string::<i32>();
2692        assert_eq!(name.value(0), "n2");
2693    }
2694
2695    #[test]
2696    fn schema_projection_drop_wins_over_schema() {
2697        // A column listed in both schema and drop_fields is dropped:
2698        // dropping is an explicit exclusion and would otherwise be
2699        // resurrected as a null-filled column.
2700        let plan = ExecutionPlan::new()
2701            .schema_order(["Name", "Department"])
2702            .drop("Department");
2703        let mut tb = parse_skipping(REPORT, plan);
2704        assert_eq!(batch_names(&mut tb), vec!["Name"]);
2705    }
2706
2707    #[test]
2708    fn schema_projection_no_parser_cooperation() {
2709        // Even when the adapter pushes every field (no wants/resolve checks),
2710        // the projection still holds: unlisted fields are never materialized.
2711        let mut tb = parse_bytes(
2712            REPORT,
2713            ExecutionPlan::new().schema_order(["Department", "Name"]),
2714        );
2715        let batch = tb.finish().unwrap();
2716        let names: Vec<String> = batch
2717            .schema()
2718            .fields()
2719            .iter()
2720            .map(|f| f.name().clone())
2721            .collect();
2722        assert_eq!(names, vec!["Department", "Name"]);
2723        let dept = batch
2724            .column_by_name("Department")
2725            .unwrap()
2726            .as_string::<i32>();
2727        assert_eq!(dept.value(0), "d1");
2728    }
2729}