perf(net11): #5 struct-enumerator refactor — ExecuteQueryStruct point lookups 976->471 B/op (-52%)

Replace the two yield-iterator state machines on the StructRow point-lookup path with
struct enumerators so foreach is genuinely allocation-free.

- Table.ScanStructRowsWhere: now returns a StructRowWhereEnumerable struct (non-yield);
  the struct enumerator handles the hash-index and primary-key fast paths allocation-free,
  and delegates the numeric-SIMD/full-scan fallback to the yield-based core
  (ScanStructRowsWhereCore). Implements IEnumerable<StructRow> for LINQ/boxing via a small
  class-based enumerator.
- SqlParser.ExecuteQueryStruct: eager plan setup (table lookup + WHERE build) returning a
  StructRowQueryEnumerable struct; the offset/limit logic now lives in the struct
  enumerator (removed the ExecuteSimpleSelectStruct yield iterator).
- Database.ExecuteQueryStruct + IDatabase.ExecuteQueryStruct: return StructRowQueryEnumerable
  (struct) instead of IEnumerable<StructRow> — foreach on the result (including via IDatabase,
  the DatabaseFactory return type) is now allocation-free; callers that store the result as
  IEnumerable<StructRow> still compile (implicit conversion).

Microbench (Release, net11): SYNC READ-STRUCT 976 -> 471 B/op (-52%), +13% ops/sec;
dictionary ExecuteQuery path unchanged (911 B/op). 1,630 tests green; full CI solution builds.

Author: MPCoreDeveloper

docs/benchmarks/V198_V20_V21_PERFORMANCE_COMPARISON.md

@@ -160,11 +160,15 @@ Changes landed:
 
 Note on row-dictionary pooling (#5 headline): pooling `Dictionary<string, object>` rows is
 structurally unsafe for the existing API — callers retain the returned rows, so a shared pool
-would corrupt data across queries. The measured "zero-alloc" `ExecuteQueryStruct` path is still
-~1 KB/op on a point lookup: two yield-iterator state machines plus the plan-cache key, the
-WHERE-string build and `engine.Read`'s per-read byte[] dominate. A struct-enumerator refactor
-of `ExecuteSimpleSelectStruct`/`ScanStructRowsWhere` is the remaining path to genuinely
-allocation-free point lookups (deferred — public-API surface change, higher risk).
+would corrupt data across queries. The `ExecuteQueryStruct` StructRow path is now genuinely the
+low-alloc read path: the two yield-iterator state machines (`ExecuteSimpleSelectStruct` /
+`ScanStructRowsWhere`) were replaced with struct enumerators, and `IDatabase.ExecuteQueryStruct`
+now returns a struct enumerable (foreach is allocation-free). Post-refactor, a point lookup
+allocates **471 B/op** (was 976 B/op after the §6.4 allocation cuts, −52%) against 911 B/op for
+the dictionary `ExecuteQuery` path — the remaining bytes are the plan-cache key, the WHERE-string
+build, `TryParseSimpleWhereClause`'s two strings, the hash-index position list and `engine.Read`'s
+per-read byte[]. The full-scan/SIMD fallback paths delegate to the yield-based core (they allocate
+by nature), and LINQ/boxing usage goes through a small class-based enumerator.
 
 ### Recommendations for a follow-up benchmark
 - Run on a quiet machine with ≥5 repetitions per version and report medians.

docs/performance/V2_PERFORMANCE_PLAN.md

@@ -142,13 +142,17 @@ four `parameters ?? []` empty-dictionary allocations removed; single-file `Execu
 hoists the per-query `PRAGMA table_info` regex to a compiled static field and replaces
 `sql.Trim().ToUpperInvariant()` with span checks.
 
-**Remaining #5 work — struct-enumerator refactor:** full row-dictionary pooling is
-structurally unsafe (callers retain the returned rows; a shared pool would corrupt data),
-and `ExecuteQueryStruct` is still ~1 KB/op on a point lookup because two yield-iterator
-state machines (plus plan-cache key, WHERE-string build, `engine.Read` byte[]) dominate.
-Converting `ExecuteSimpleSelectStruct`/`ScanStructRowsWhere` to struct enumerators
-(source-compatible for `foreach`) is the path to genuinely allocation-free point lookups;
-it changes the public return-type surface and is deferred as a focused, higher-risk item.
+**#5 struct-enumerator refactor — DONE (2026-08-30):** full row-dictionary pooling is
+structurally unsafe (callers retain the returned rows; a shared pool would corrupt data), so the
+zero-allocation win was delivered via struct enumerators instead. `ExecuteSimpleSelectStruct` and
+`ScanStructRowsWhere` are no longer yield iterators: `Table.ScanStructRowsWhere` returns a
+`StructRowWhereEnumerable` struct whose enumerator handles the hash-index / primary-key point-lookup
+fast paths allocation-free (the SIMD/full-scan fallback delegates to the yield-based core), and
+`IDatabase.ExecuteQueryStruct` now returns a `StructRowQueryEnumerable` struct (foreach is
+allocation-free; LINQ/boxing goes through a small class-based enumerator). A point lookup dropped
+from **976 → 471 B/op (−52%)** on the StructRow path (911 B/op on the dictionary path), with +13%
+throughput. Remaining bytes are the plan-cache key, WHERE-string build, `TryParseSimpleWhereClause`
+strings, hash-index position list and `engine.Read`'s per-read byte[].
 
 
 ---

src/SharpCoreDB/DataStructures/StructRowQueryEnumerable.cs

@@ -0,0 +1,129 @@
+#nullable enable
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+
+namespace SharpCoreDB.DataStructures;
+
+/// <summary>
+/// Zero-allocation enumerable returned by <c>ExecuteQueryStruct</c>. Foreach on this concrete
+/// type uses <see cref="StructRowQueryEnumerator"/> (no heap allocation); treating it as
+/// <c>IEnumerable&lt;StructRow&gt;</c> (LINQ, boxing) uses a small class-based enumerator.
+/// </summary>
+public readonly struct StructRowQueryEnumerable : IEnumerable<StructRow>
+{
+    private readonly Table? _table;
+    private readonly string? _where;
+    private readonly bool _hasRows;
+    private readonly int _skipped;
+    private readonly int? _limit;
+
+    internal StructRowQueryEnumerable(Table? table, string? where, bool hasRows, int skipped, int? limit)
+    {
+        _table = table;
+        _where = where;
+        _hasRows = hasRows;
+        _skipped = skipped;
+        _limit = limit;
+    }
+
+    /// <summary>Gets the allocation-free enumerator.</summary>
+    public StructRowQueryEnumerator GetEnumerator() => new(_table, _where, _hasRows, _skipped, _limit);
+
+    IEnumerator<StructRow> IEnumerable<StructRow>.GetEnumerator()
+        => new BoxedEnumerator(_table, _where, _hasRows, _skipped, _limit);
+
+    IEnumerator IEnumerable.GetEnumerator()
+        => ((IEnumerable<StructRow>)this).GetEnumerator();
+
+    private sealed class BoxedEnumerator : IEnumerator<StructRow>
+    {
+        // NOT readonly: MoveNext mutates the struct enumerator's state.
+        private StructRowQueryEnumerator _inner;
+
+        internal BoxedEnumerator(Table? table, string? where, bool hasRows, int skipped, int? limit)
+        {
+            _inner = new StructRowQueryEnumerator(table, where, hasRows, skipped, limit);
+        }
+
+        public StructRow Current => _inner.Current;
+        object IEnumerator.Current => _inner.Current;
+
+        public bool MoveNext() => _inner.MoveNext();
+        public void Reset() => throw new NotSupportedException();
+        public void Dispose() => _inner.Dispose();
+    }
+}
+
+/// <summary>
+/// Allocation-free enumerator for <see cref="StructRowQueryEnumerable"/>. Drives the table-level
+/// <see cref="Table.StructRowWhereEnumerator"/> and applies LIMIT/OFFSET.
+/// </summary>
+public struct StructRowQueryEnumerator : IDisposable
+{
+    private readonly Table? _table;
+    private readonly string? _where;
+    private readonly bool _hasRows;
+    private readonly int _skipped;
+    private readonly int? _limit;
+    private Table.StructRowWhereEnumerator _rows;
+    private int _index;
+    private bool _initialized;
+    private StructRow _current;
+
+    internal StructRowQueryEnumerator(Table? table, string? where, bool hasRows, int skipped, int? limit)
+    {
+        _table = table;
+        _where = where;
+        _hasRows = hasRows;
+        _skipped = skipped;
+        _limit = limit;
+        _rows = default;
+        _index = 0;
+        _initialized = false;
+        _current = default;
+    }
+
+    /// <summary>Gets the current row.</summary>
+    public StructRow Current => _current;
+
+    /// <summary>Advances to the next row (applies OFFSET then LIMIT).</summary>
+    public bool MoveNext()
+    {
+        if (!_initialized)
+        {
+            _initialized = true;
+            if (!_hasRows || _table is null)
+            {
+                return false;
+            }
+
+            _rows = _table.ScanStructRowsWhere(_where).GetEnumerator();
+            _index = 0;
+        }
+
+        while (_rows.MoveNext())
+        {
+            if (_index < _skipped)
+            {
+                _index++;
+                continue;
+            }
+
+            if (_limit.HasValue && _index - _skipped >= _limit.Value)
+            {
+                return false;
+            }
+
+            _index++;
+            _current = _rows.Current;
+            return true;
+        }
+
+        return false;
+    }
+
+    /// <summary>Releases the table-level enumerator (no-op on the allocation-free fast paths).</summary>
+    public void Dispose() => _rows.Dispose();
+}