diff --git a/src/aggregate.zig b/src/aggregate.zig
new file mode 100644
index 0000000..6af3ab7
--- /dev/null
+++ b/src/aggregate.zig
@@ -0,0 +1,1338 @@
+const std = @import("std");
+const rowmod = @import("row.zig");
+const querymod = @import("query.zig");
+
+const Allocator = std.mem.Allocator;
+const Value = rowmod.Value;
+const Row = rowmod.Row;
+const Page = querymod.Page;
+const Predicate = querymod.Predicate;
+
+/// GROUP BY / aggregate engine over already-materialized `Row` slices (the
+/// same currency `join.zig` uses): callers filter and fetch rows through
+/// `Table.select`/`Table.scanAll` first, then feed them here one at a time.
+/// Keeping this decoupled from `query.zig`'s `Table` (rather than adding a
+/// method on it) mirrors the existing split between the storage-facing
+/// `Table` and the purely row-shaped `join.zig`.
+pub const AggKind = enum {
+    /// Counts rows. `field.len == 0` counts every observed row
+    /// (`COUNT(*)`); otherwise only rows where `field` is present
+    /// (`COUNT(field)`).
+    count,
+    sum,
+    avg,
+    min,
+    max,
+    /// Counts distinct non-none values of `field` (SQL's
+    /// `COUNT(DISTINCT field)`). Always requires a `field` - there is no
+    /// bare `COUNT(DISTINCT *)` form, mirroring `sum`/`avg`/`min`/`max`.
+    count_distinct,
+};
+
+pub const AggSpec = struct {
+    /// Ignored for `.count` with `COUNT(*)` semantics (pass `""`).
+    field: []const u8,
+    kind: AggKind,
+};
+
+pub const AggregateError = error{
+    /// `.sum`/`.avg` observed a field holding a non-numeric `Value`
+    /// (anything but `.int`/`.float`).
+    NonNumericField,
+    /// The running integer sum of a `.sum`/`.avg` accumulator would not fit
+    /// in `i64`. Never silently wraps or drops precision by switching to
+    /// float behind the caller's back.
+    Overflow,
+    /// `sortGroupsBy` was asked to order by a field that names neither the
+    /// GROUP BY key nor any `specLabel` of the aggregate results - the
+    /// ORDER BY counterpart of `expr.parse`'s "malformed input is an error,
+    /// not a guess" convention `filterHaving` already applies to HAVING.
+    UnknownOrderField,
+} || Allocator.Error;
+
+/// One row of `GroupBy.finish()`'s result: `group` is the distinct group-key
+/// value, `values` holds one result `Value` per input `AggSpec`, same order.
+pub const GroupRow = struct {
+    group: Value,
+    values: []Value,
+
+    pub fn deinit(self: *GroupRow, allocator: Allocator) void {
+        self.group.free(allocator);
+        for (self.values) |v| v.free(allocator);
+        allocator.free(self.values);
+    }
+};
+
+fn freeGroupRows(allocator: Allocator, rows: []GroupRow) void {
+    for (rows) |*r| r.deinit(allocator);
+    allocator.free(rows);
+}
+
+/// Trims a `GroupBy.finish()`/`run()` result to a `query.zig` `Page` window
+/// (0 = unlimited, the same convention `Table.selectPage`/`join.applyPage`
+/// use) - the GROUP BY counterpart of pagination for `table_aggregate`/
+/// `remote-aggregate`. Grouping has already had to materialize every
+/// distinct group to know how many there are, so - exactly like
+/// `join.applyPage` - there is no cheaper way to honor `offset`/`limit`
+/// than windowing the already-complete result; this always runs after
+/// `run()` returns, never instead of it. Not a generic
+/// `join.applyPage(GroupRow, ...)` call because `GroupRow.deinit` takes an
+/// `allocator` argument (it owns heap payloads on `.group`/`.values`)
+/// where `join.applyPage`'s `T.deinit()` takes none.
+///
+/// Takes ownership of `rows`: frees the backing slice, `.deinit()`s every
+/// row that falls outside `[offset, offset+limit)`, and returns a freshly
+/// allocated slice holding only the kept rows in their original (first-seen)
+/// order. Callers own the returned slice and the rows in it exactly as they
+/// would have owned `rows`.
+pub fn applyPageGroups(allocator: Allocator, rows: []GroupRow, page: Page) ![]GroupRow {
+    const total = rows.len;
+    const start = @min(page.offset, total);
+    const end = if (page.limit == 0) total else @min(start + page.limit, total);
+
+    for (rows[0..start]) |*r| r.deinit(allocator);
+    for (rows[end..total]) |*r| r.deinit(allocator);
+
+    const kept = end - start;
+    const result = allocator.alloc(GroupRow, kept) catch |err| {
+        for (rows[start..end]) |*r| r.deinit(allocator);
+        allocator.free(rows);
+        return err;
+    };
+    @memcpy(result, rows[start..end]);
+    allocator.free(rows);
+    return result;
+}
+
+/// The row field name a `GroupRow`/global aggregate result is exposed under
+/// for HAVING and CLI output purposes: bare `AggKind` name for `field.len ==
+/// 0` (`COUNT(*)`), otherwise `"kind_field"`. Must stay in sync with
+/// `main.zig`'s `printAggLabel`, which prints this same format directly to a
+/// writer without allocating - `filterHaving`/`globalMatchesHaving` need an
+/// owned string instead because it becomes a `Row` field name, so this is a
+/// separate (but format-identical) helper rather than a shared one.
+pub fn specLabel(allocator: Allocator, spec: AggSpec) Allocator.Error![]u8 {
+    if (spec.field.len == 0) return allocator.dupe(u8, @tagName(spec.kind));
+    return std.fmt.allocPrint(allocator, "{s}_{s}", .{ @tagName(spec.kind), spec.field });
+}
+
+/// Builds the synthetic probe `Row` a HAVING predicate is evaluated against:
+/// one field per `spec` (named via `specLabel`) holding that spec's result
+/// `Value` for this group, plus (when `groupField.len > 0`) one field named
+/// `groupField` holding the group's own key - so a HAVING clause can
+/// reference an aggregate result (`count`, `sum_score`, ...) or the group key
+/// itself through the exact same `expr.zig` grammar `WHERE` already uses.
+/// Does not take ownership of `groupValue`/`values` - `Row.set` dupes.
+fn buildHavingProbe(allocator: Allocator, groupField: []const u8, groupValue: ?Value, specs: []const AggSpec, values: []const Value) !Row {
+    var probe = Row.init(allocator);
+    errdefer probe.deinit();
+    if (groupValue) |gv| try probe.set(groupField, gv);
+    for (specs, values) |spec, v| {
+        const label = try specLabel(allocator, spec);
+        defer allocator.free(label);
+        try probe.set(label, v);
+    }
+    return probe;
+}
+
+/// Filters an already-grouped `run()` result by a HAVING predicate - the
+/// GROUP BY counterpart of `Predicate.evaluate` on plain rows, applied AFTER
+/// aggregation instead of before it (the same WHERE/HAVING split SQL makes).
+/// Takes ownership of `groups` (same convention as `applyPageGroups`): every
+/// group that fails `having` is `.deinit()`-ed here, the rest are moved
+/// (first-seen order preserved) into a freshly allocated result slice.
+/// Callers typically run this between `run()` and `applyPageGroups` - HAVING
+/// narrows which groups exist before LIMIT/OFFSET windows them, exactly like
+/// SQL evaluates `HAVING` before `LIMIT`.
+pub fn filterHaving(allocator: Allocator, groups: []GroupRow, groupField: []const u8, specs: []const AggSpec, having: Predicate) AggregateError![]GroupRow {
+    var kept: std.ArrayListUnmanaged(GroupRow) = .{};
+    var i: usize = 0;
+    // `groups[0..i)` is always fully accounted for by this point: each one
+    // either moved into `kept` (accepted) or was already `.deinit()`-ed
+    // in-loop (rejected) - touching it again here would double-free. Only
+    // `groups[i..]` (the current index, mid-evaluation when this errdefer
+    // fires, plus everything not yet reached) is still owned by `groups`
+    // and needs disposing, the same "always dispose of the input on every
+    // path" contract `applyPageGroups` upholds for its own OOM case.
+    errdefer {
+        for (kept.items) |*g| g.deinit(allocator);
+        kept.deinit(allocator);
+        for (groups[i..]) |*g| g.deinit(allocator);
+        allocator.free(groups);
+    }
+
+    while (i < groups.len) : (i += 1) {
+        var probe = try buildHavingProbe(allocator, groupField, groups[i].group, specs, groups[i].values);
+        defer probe.deinit();
+        if (having.evaluate(&probe)) {
+            try kept.append(allocator, groups[i]);
+        } else {
+            groups[i].deinit(allocator);
+        }
+    }
+    allocator.free(groups);
+    return kept.toOwnedSlice(allocator);
+}
+
+/// HAVING for the ungrouped (`runGlobal`, CLI's `*` sentinel) aggregate path:
+/// evaluates `having` against the same kind of synthetic probe row
+/// `filterHaving` builds, minus any group-key field (there is no group).
+/// Reports only whether the single global result should be kept - unlike
+/// `filterHaving` it never frees `values`, since `runGlobal` always produces
+/// exactly one result and the caller (which already owns it via
+/// `freeGlobalResult`) decides whether to print it or not.
+pub fn globalMatchesHaving(allocator: Allocator, specs: []const AggSpec, values: []const Value, having: Predicate) AggregateError!bool {
+    var probe = try buildHavingProbe(allocator, "", null, specs, values);
+    defer probe.deinit();
+    return having.evaluate(&probe);
+}
+
+/// Which part of a `GroupRow` a single `OrderBy` column reads from -
+/// resolved once per column by `resolveSortKeys` rather than re-matching
+/// `ob.field` against `groupField`/every `specLabel` on every comparison
+/// `sortGroupsBy`'s sort makes.
+const SortKey = union(enum) {
+    group,
+    value: usize,
+};
+
+/// Resolves each `order[i].field` to either the group key itself
+/// (`groupField`, e.g. `city`) or the index of the `specs` entry whose
+/// `specLabel` matches (e.g. `sum_score`) - the same two-namespace lookup
+/// `buildHavingProbe` exposes to a HAVING predicate, done once up front
+/// instead of building a probe `Row` per comparison. An `order[i].field`
+/// matching neither is `error.UnknownOrderField` rather than silently
+/// sorting as if every row tied on that column. Caller owns the returned
+/// slice.
+fn resolveSortKeys(allocator: Allocator, groupField: []const u8, specs: []const AggSpec, order: []const querymod.OrderBy) AggregateError![]SortKey {
+    var keys = try allocator.alloc(SortKey, order.len);
+    errdefer allocator.free(keys);
+    for (order, 0..) |ob, i| {
+        if (groupField.len > 0 and std.mem.eql(u8, ob.field, groupField)) {
+            keys[i] = .group;
+            continue;
+        }
+        var found: ?usize = null;
+        for (specs, 0..) |spec, j| {
+            const label = try specLabel(allocator, spec);
+            defer allocator.free(label);
+            if (std.mem.eql(u8, label, ob.field)) {
+                found = j;
+                break;
+            }
+        }
+        keys[i] = .{ .value = found orelse return error.UnknownOrderField };
+    }
+    return keys;
+}
+
+/// Stable in-place sort of `groups` by `order` - the GROUP BY counterpart of
+/// `query.zig`'s `sortRowsBy`, applied to already-aggregated `GroupRow`s
+/// instead of plain `Row`s so an ORDER BY column can name either the group
+/// key (`city`) or an aggregate result (`sum_score`), the same two things a
+/// HAVING predicate can reference. Columns compare left to right exactly
+/// like `sortRowsBy`/SQL's `ORDER BY a, b`: the first entry decides unless
+/// it ties, in which case the next breaks it. `order.len == 0` is a no-op
+/// (the common case - most `table aggregate` calls have no ORDER BY).
+/// Does not take ownership of `groups` - unlike `filterHaving`/
+/// `applyPageGroups`, this never frees or reallocates any group, only
+/// reorders the slice in place, so callers keep using their own `defer
+/// freeGroupRows(...)` around the call exactly as if it were never made.
+/// Typically run after `filterHaving` and before `applyPageGroups` - ORDER
+/// BY sees the HAVING-narrowed set and decides what LIMIT/OFFSET's window
+/// actually keeps, the same clause order SQL evaluates.
+pub fn sortGroupsBy(allocator: Allocator, groups: []GroupRow, groupField: []const u8, specs: []const AggSpec, order: []const querymod.OrderBy) AggregateError!void {
+    if (order.len == 0) return;
+    const keys = try resolveSortKeys(allocator, groupField, specs, order);
+    defer allocator.free(keys);
+
+    const Ctx = struct {
+        order: []const querymod.OrderBy,
+        keys: []const SortKey,
+
+        fn lessThan(ctx: @This(), a: GroupRow, b: GroupRow) bool {
+            for (ctx.order, ctx.keys) |ob, key| {
+                const av = switch (key) {
+                    .group => a.group,
+                    .value => |j| a.values[j],
+                };
+                const bv = switch (key) {
+                    .group => b.group,
+                    .value => |j| b.values[j],
+                };
+                const cmp = rowmod.compare(av, bv);
+                if (cmp == .eq) continue;
+                return if (ob.descending) cmp == .gt else cmp == .lt;
+            }
+            return false;
+        }
+    };
+    std.sort.block(GroupRow, groups, Ctx{ .order = order, .keys = keys }, Ctx.lessThan);
+}
+
+const AccState = struct {
+    kind: AggKind,
+    field: []const u8,
+    n: u64 = 0,
+    sumInt: i64 = 0,
+    sumFloat: f64 = 0,
+    allInt: bool = true,
+    minv: ?Value = null,
+    maxv: ?Value = null,
+    /// `.count_distinct` only: encoded-`Value` bytes seen so far, one entry
+    /// per distinct value (owns each key, same encode-as-hashmap-key trick
+    /// `GroupBy.observe` uses for the group key itself).
+    distinct: std.StringHashMapUnmanaged(void) = .{},
+
+    fn numericFieldValue(self: *const AccState, row: *const Row) ?Value {
+        return row.get(self.field);
+    }
+
+    fn observe(self: *AccState, allocator: Allocator, row: *const Row) AggregateError!void {
+        switch (self.kind) {
+            .count => {
+                if (self.field.len == 0) {
+                    self.n += 1;
+                } else if (row.get(self.field) != null) {
+                    self.n += 1;
+                }
+            },
+            .sum, .avg => {
+                const v = self.numericFieldValue(row) orelse return;
+                switch (v) {
+                    .int => |i| {
+                        if (self.allInt) {
+                            self.sumInt = std.math.add(i64, self.sumInt, i) catch return error.Overflow;
+                        } else {
+                            self.sumFloat += @floatFromInt(i);
+                        }
+                    },
+                    .float => |f| {
+                        if (self.allInt) {
+                            // First float observed after an int-only run:
+                            // migrate the exact integer sum so far into the
+                            // float accumulator once, then continue in float.
+                            self.sumFloat = @floatFromInt(self.sumInt);
+                            self.allInt = false;
+                        }
+                        self.sumFloat += f;
+                    },
+                    else => return error.NonNumericField,
+                }
+                self.n += 1;
+            },
+            .min => {
+                const v = row.get(self.field) orelse return;
+                if (self.minv == null or rowmod.compare(v, self.minv.?) == .lt) {
+                    if (self.minv) |old| old.free(allocator);
+                    self.minv = try v.dupe(allocator);
+                }
+            },
+            .max => {
+                const v = row.get(self.field) orelse return;
+                if (self.maxv == null or rowmod.compare(v, self.maxv.?) == .gt) {
+                    if (self.maxv) |old| old.free(allocator);
+                    self.maxv = try v.dupe(allocator);
+                }
+            },
+            .count_distinct => {
+                const v = row.get(self.field) orelse return;
+                const key = try rowmod.encodeValue(allocator, v);
+                const res = try self.distinct.getOrPut(allocator, key);
+                if (res.found_existing) allocator.free(key);
+            },
+        }
+    }
+
+    /// Produces the final result `Value`, transferring ownership of any
+    /// heap payload (`.min`/`.max` on text/bytes fields) out of this
+    /// accumulator - a subsequent `deinit` sees `null` and frees nothing,
+    /// so the same payload is never freed twice. `.count_distinct` instead
+    /// frees its whole tracking set right here (the result is a plain
+    /// `.int`, nothing to hand ownership of), which is why this needs
+    /// `allocator` - both call sites (`GroupBy.finish`, `runGlobal`) skip a
+    /// separate `deinit` call after `take()` entirely, so this is the only
+    /// place that set is ever freed on the success path.
+    fn take(self: *AccState, allocator: Allocator) Value {
+        return switch (self.kind) {
+            .count => .{ .int = @intCast(self.n) },
+            .sum => if (self.allInt) .{ .int = self.sumInt } else .{ .float = self.sumFloat },
+            .avg => blk: {
+                if (self.n == 0) break :blk .{ .none = {} };
+                const total: f64 = if (self.allInt) @floatFromInt(self.sumInt) else self.sumFloat;
+                break :blk .{ .float = total / @as(f64, @floatFromInt(self.n)) };
+            },
+            .min => blk: {
+                const v = self.minv orelse Value{ .none = {} };
+                self.minv = null;
+                break :blk v;
+            },
+            .max => blk: {
+                const v = self.maxv orelse Value{ .none = {} };
+                self.maxv = null;
+                break :blk v;
+            },
+            .count_distinct => blk: {
+                const result = Value{ .int = @intCast(self.distinct.count()) };
+                var it = self.distinct.keyIterator();
+                while (it.next()) |k| allocator.free(k.*);
+                self.distinct.deinit(allocator);
+                self.distinct = .{};
+                break :blk result;
+            },
+        };
+    }
+
+    fn deinit(self: *AccState, allocator: Allocator) void {
+        if (self.minv) |v| v.free(allocator);
+        if (self.maxv) |v| v.free(allocator);
+        var it = self.distinct.keyIterator();
+        while (it.next()) |k| allocator.free(k.*);
+        self.distinct.deinit(allocator);
+    }
+};
+
+const Bundle = struct {
+    groupValue: Value,
+    accs: []AccState,
+
+    fn deinit(self: *Bundle, allocator: Allocator) void {
+        self.groupValue.free(allocator);
+        for (self.accs) |*a| a.deinit(allocator);
+        allocator.free(self.accs);
+    }
+};
+
+/// Streaming GROUP BY accumulator: call `observe` once per candidate row
+/// (already filtered by whatever `Predicate` the caller wants applied), then
+/// `finish` to materialize one `GroupRow` per distinct group-key value seen,
+/// in first-seen order (stable, not sorted - callers that want sorted
+/// output can sort the returned slice by `.group` using `row.compare`).
+pub const GroupBy = struct {
+    allocator: Allocator,
+    groupField: []const u8,
+    specs: []const AggSpec,
+    map: std.StringHashMapUnmanaged(*Bundle) = .{},
+    order: std.ArrayListUnmanaged([]const u8) = .{},
+
+    pub fn init(allocator: Allocator, groupField: []const u8, specs: []const AggSpec) GroupBy {
+        return .{ .allocator = allocator, .groupField = groupField, .specs = specs };
+    }
+
+    /// Safe to call after `finish()` (which empties the internal maps) or on
+    /// a `GroupBy` that was never `finish()`-ed (e.g. `observe` returned an
+    /// error partway through a batch) - either way, exactly what is still
+    /// owned gets freed once.
+    pub fn deinit(self: *GroupBy) void {
+        var it = self.map.iterator();
+        while (it.next()) |entry| {
+            self.allocator.free(entry.key_ptr.*);
+            entry.value_ptr.*.deinit(self.allocator);
+            self.allocator.destroy(entry.value_ptr.*);
+        }
+        self.map.deinit(self.allocator);
+        self.order.deinit(self.allocator);
+        self.map = .{};
+        self.order = .{};
+    }
+
+    /// Rows missing `groupField` entirely are excluded from every group
+    /// (no "null group" bucket) - the same omission `Table.createIndex`'s
+    /// backfill applies to rows missing an indexed field.
+    pub fn observe(self: *GroupBy, row: *const Row) AggregateError!void {
+        const groupVal = row.get(self.groupField) orelse return;
+        const key = try rowmod.encodeValue(self.allocator, groupVal);
+
+        if (self.map.get(key)) |bundle| {
+            self.allocator.free(key);
+            for (bundle.accs) |*a| try a.observe(self.allocator, row);
+            return;
+        }
+
+        // Scoped to this block so the errdefers below only guard the
+        // allocation itself: once `bundle` is handed to `self.map.put`
+        // just after, ownership has moved there, and a later failure (the
+        // final observe loop) must NOT free it out from under the map -
+        // an errdefer spanning the whole function would do exactly that
+        // and leave a dangling pointer in `self.map`.
+        const bundle = blk: {
+            const b = try self.allocator.create(Bundle);
+            errdefer self.allocator.destroy(b);
+            const accs = try self.allocator.alloc(AccState, self.specs.len);
+            errdefer self.allocator.free(accs);
+            for (self.specs, 0..) |spec, i| accs[i] = .{ .kind = spec.kind, .field = spec.field };
+            const dupedGroup = try groupVal.dupe(self.allocator);
+            b.* = .{ .groupValue = dupedGroup, .accs = accs };
+            break :blk b;
+        };
+
+        try self.map.put(self.allocator, key, bundle);
+        try self.order.append(self.allocator, key);
+        for (bundle.accs) |*a| try a.observe(self.allocator, row);
+    }
+
+    /// Consumes the accumulated groups into an owned `[]GroupRow` and
+    /// leaves `self` empty (a subsequent `deinit()` is then a no-op).
+    pub fn finish(self: *GroupBy) AggregateError![]GroupRow {
+        var results = try self.allocator.alloc(GroupRow, self.order.items.len);
+        var filled: usize = 0;
+        errdefer freeGroupRows(self.allocator, results[0..filled]);
+
+        for (self.order.items) |key| {
+            const bundle = self.map.get(key).?;
+            var values = try self.allocator.alloc(Value, bundle.accs.len);
+            errdefer self.allocator.free(values);
+            for (bundle.accs, 0..) |*a, j| values[j] = a.take(self.allocator);
+            results[filled] = .{ .group = bundle.groupValue, .values = values };
+            filled += 1;
+        }
+
+        var it = self.map.iterator();
+        while (it.next()) |entry| {
+            self.allocator.free(entry.key_ptr.*);
+            self.allocator.free(entry.value_ptr.*.accs);
+            self.allocator.destroy(entry.value_ptr.*);
+        }
+        self.map.deinit(self.allocator);
+        self.order.deinit(self.allocator);
+        self.map = .{};
+        self.order = .{};
+
+        return results;
+    }
+};
+
+/// Convenience wrapper: groups `rows` by `groupField`, applies `specs`, and
+/// returns the finished result in one call.
+pub fn run(allocator: Allocator, rows: []const Row, groupField: []const u8, specs: []const AggSpec) AggregateError![]GroupRow {
+    var gb = GroupBy.init(allocator, groupField, specs);
+    errdefer gb.deinit();
+    for (rows) |*r| try gb.observe(r);
+    return gb.finish();
+}
+
+/// A single aggregate row over all of `rows` with no grouping (SQL's
+/// `SELECT COUNT(*), SUM(x) FROM t` with no `GROUP BY`) - always produces
+/// exactly one result, even for zero input rows (every accumulator still
+/// reports its identity result: `count` 0, `sum` 0, `avg`/`min`/`max`
+/// `.none`).
+pub fn runGlobal(allocator: Allocator, rows: []const Row, specs: []const AggSpec) AggregateError![]Value {
+    var accs = try allocator.alloc(AccState, specs.len);
+    defer allocator.free(accs);
+    for (specs, 0..) |spec, i| accs[i] = .{ .kind = spec.kind, .field = spec.field };
+    errdefer for (accs) |*a| a.deinit(allocator);
+
+    for (rows) |*r| {
+        for (accs) |*a| try a.observe(allocator, r);
+    }
+
+    var values = try allocator.alloc(Value, specs.len);
+    for (accs, 0..) |*a, i| values[i] = a.take(allocator);
+    return values;
+}
+
+pub fn freeGlobalResult(allocator: Allocator, values: []Value) void {
+    for (values) |v| v.free(allocator);
+    allocator.free(values);
+}
+
+fn makeRow(allocator: Allocator, fields: []const rowmod.Field) !Row {
+    var r = Row.init(allocator);
+    for (fields) |f| try r.set(f.name, f.value);
+    return r;
+}
+
+fn findGroup(rows: []const GroupRow, group: Value) ?*const GroupRow {
+    for (rows) |*r| {
+        if (Value.eql(r.group, group)) return r;
+    }
+    return null;
+}
+
+test "count sum avg min max group by text field" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { city: []const u8, score: i64 }{
+        .{ .city = "warsaw", .score = 10 },
+        .{ .city = "warsaw", .score = 30 },
+        .{ .city = "krakow", .score = 5 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "score", .value = .{ .int = d.score } },
+        }));
+    }
+
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+        .{ .field = "score", .kind = .avg },
+        .{ .field = "score", .kind = .min },
+        .{ .field = "score", .kind = .max },
+    };
+    const groups = try run(allocator, rows.items, "city", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    try std.testing.expectEqual(@as(usize, 2), groups.len);
+
+    const warsaw = findGroup(groups, .{ .text = "warsaw" }).?;
+    try std.testing.expectEqual(@as(i64, 2), warsaw.values[0].int);
+    try std.testing.expectEqual(@as(i64, 40), warsaw.values[1].int);
+    try std.testing.expectApproxEqAbs(@as(f64, 20), warsaw.values[2].float, 1e-9);
+    try std.testing.expectEqual(@as(i64, 10), warsaw.values[3].int);
+    try std.testing.expectEqual(@as(i64, 30), warsaw.values[4].int);
+
+    const krakow = findGroup(groups, .{ .text = "krakow" }).?;
+    try std.testing.expectEqual(@as(i64, 1), krakow.values[0].int);
+    try std.testing.expectEqual(@as(i64, 5), krakow.values[1].int);
+}
+
+test "sum and avg skip rows missing the field, count star still counts them" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "team", .value = .{ .text = "a" } },
+        .{ .name = "points", .value = .{ .int = 7 } },
+    }));
+    // No "points" field on this row - must not participate in sum/avg, but
+    // must still be counted by COUNT(*).
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "team", .value = .{ .text = "a" } },
+    }));
+
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "points", .kind = .count },
+        .{ .field = "points", .kind = .sum },
+        .{ .field = "points", .kind = .avg },
+    };
+    const groups = try run(allocator, rows.items, "team", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    try std.testing.expectEqual(@as(usize, 1), groups.len);
+    try std.testing.expectEqual(@as(i64, 2), groups[0].values[0].int); // COUNT(*)
+    try std.testing.expectEqual(@as(i64, 1), groups[0].values[1].int); // COUNT(points)
+    try std.testing.expectEqual(@as(i64, 7), groups[0].values[2].int); // SUM(points)
+    try std.testing.expectApproxEqAbs(@as(f64, 7), groups[0].values[3].float, 1e-9); // AVG(points)
+}
+
+test "avg on a group where the field is always missing reports none" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{.{ .name = "team", .value = .{ .text = "a" } }}));
+
+    const specs = [_]AggSpec{.{ .field = "points", .kind = .avg }};
+    const groups = try run(allocator, rows.items, "team", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    try std.testing.expectEqual(@as(usize, 1), groups.len);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, groups[0].values[0]));
+}
+
+test "sum stays exact integer until a float value forces it to switch" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "g", .value = .{ .int = 1 } },
+        .{ .name = "x", .value = .{ .int = 3 } },
+    }));
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "g", .value = .{ .int = 1 } },
+        .{ .name = "x", .value = .{ .int = 4 } },
+    }));
+
+    const specs = [_]AggSpec{.{ .field = "x", .kind = .sum }};
+    {
+        const groups = try run(allocator, rows.items, "g", &specs);
+        defer freeGroupRows(allocator, groups);
+        // All-int input: exact int result, not a float with rounding risk.
+        try std.testing.expectEqual(rowmod.ValueTag.int, @as(rowmod.ValueTag, groups[0].values[0]));
+        try std.testing.expectEqual(@as(i64, 7), groups[0].values[0].int);
+    }
+
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "g", .value = .{ .int = 1 } },
+        .{ .name = "x", .value = .{ .float = 0.5 } },
+    }));
+    {
+        const groups = try run(allocator, rows.items, "g", &specs);
+        defer freeGroupRows(allocator, groups);
+        try std.testing.expectEqual(rowmod.ValueTag.float, @as(rowmod.ValueTag, groups[0].values[0]));
+        try std.testing.expectApproxEqAbs(@as(f64, 7.5), groups[0].values[0].float, 1e-9);
+    }
+}
+
+test "sum reports overflow instead of silently wrapping" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "g", .value = .{ .int = 1 } },
+        .{ .name = "x", .value = .{ .int = std.math.maxInt(i64) } },
+    }));
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "g", .value = .{ .int = 1 } },
+        .{ .name = "x", .value = .{ .int = 1 } },
+    }));
+
+    const specs = [_]AggSpec{.{ .field = "x", .kind = .sum }};
+    var gb = GroupBy.init(allocator, "g", &specs);
+    defer gb.deinit();
+    try gb.observe(&rows.items[0]);
+    try std.testing.expectError(error.Overflow, gb.observe(&rows.items[1]));
+}
+
+test "sum on a non-numeric field errors without leaking accumulated state" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "g", .value = .{ .int = 1 } },
+        .{ .name = "x", .value = .{ .text = "nope" } },
+    }));
+
+    const specs = [_]AggSpec{.{ .field = "x", .kind = .sum }};
+    var gb = GroupBy.init(allocator, "g", &specs);
+    defer gb.deinit();
+    try std.testing.expectError(error.NonNumericField, gb.observe(&rows.items[0]));
+}
+
+test "min and max use the total order across owned text values" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "delta", "alpha", "charlie", "bravo" };
+    for (names) |n| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "g", .value = .{ .int = 1 } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+
+    const specs = [_]AggSpec{
+        .{ .field = "name", .kind = .min },
+        .{ .field = "name", .kind = .max },
+    };
+    const groups = try run(allocator, rows.items, "g", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    try std.testing.expectEqualStrings("alpha", groups[0].values[0].text);
+    try std.testing.expectEqualStrings("delta", groups[0].values[1].text);
+}
+
+test "count_distinct counts unique field values once per group, repeats collapsed" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { team: []const u8, tag: []const u8 }{
+        .{ .team = "a", .tag = "red" },
+        .{ .team = "a", .tag = "blue" },
+        .{ .team = "a", .tag = "red" }, // repeat, must not double count
+        .{ .team = "b", .tag = "green" },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "team", .value = .{ .text = d.team } },
+            .{ .name = "tag", .value = .{ .text = d.tag } },
+        }));
+    }
+
+    const specs = [_]AggSpec{.{ .field = "tag", .kind = .count_distinct }};
+    const groups = try run(allocator, rows.items, "team", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    const a = findGroup(groups, .{ .text = "a" }).?;
+    try std.testing.expectEqual(@as(i64, 2), a.values[0].int);
+    const b = findGroup(groups, .{ .text = "b" }).?;
+    try std.testing.expectEqual(@as(i64, 1), b.values[0].int);
+}
+
+test "count_distinct ignores rows missing the field and never counts none as a value" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "team", .value = .{ .text = "a" } },
+        .{ .name = "tag", .value = .{ .text = "red" } },
+    }));
+    // No "tag" field on this row - must not create a phantom distinct value.
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "team", .value = .{ .text = "a" } },
+    }));
+
+    const specs = [_]AggSpec{.{ .field = "tag", .kind = .count_distinct }};
+    const groups = try run(allocator, rows.items, "team", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    try std.testing.expectEqual(@as(usize, 1), groups.len);
+    try std.testing.expectEqual(@as(i64, 1), groups[0].values[0].int);
+}
+
+test "count_distinct on zero observed values reports zero, not none" {
+    const allocator = std.testing.allocator;
+    const rows: []const Row = &.{};
+    const specs = [_]AggSpec{.{ .field = "tag", .kind = .count_distinct }};
+    const values = try runGlobal(allocator, rows, &specs);
+    defer freeGlobalResult(allocator, values);
+
+    try std.testing.expectEqual(@as(i64, 0), values[0].int);
+}
+
+test "count_distinct propagates OutOfMemory without leaking already-tracked distinct values" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const tags = [_][]const u8{ "red", "blue", "green" };
+    for (tags) |t| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "g", .value = .{ .text = "x" } },
+            .{ .name = "tag", .value = .{ .text = t } },
+        }));
+    }
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 6 });
+    const specs = [_]AggSpec{.{ .field = "tag", .kind = .count_distinct }};
+    var gb = GroupBy.init(failing.allocator(), "g", &specs);
+    defer gb.deinit();
+
+    var sawError = false;
+    for (rows.items) |*r| {
+        gb.observe(r) catch {
+            sawError = true;
+            break;
+        };
+    }
+    try std.testing.expect(sawError);
+}
+
+test "rows missing the group field are excluded from every group" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{.{ .name = "team", .value = .{ .text = "a" } }}));
+    try rows.append(try makeRow(allocator, &.{})); // no "team" field at all
+
+    const specs = [_]AggSpec{.{ .field = "", .kind = .count }};
+    const groups = try run(allocator, rows.items, "team", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    try std.testing.expectEqual(@as(usize, 1), groups.len);
+    try std.testing.expectEqual(@as(i64, 1), groups[0].values[0].int);
+}
+
+test "group order is first-seen, not sorted" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const order = [_][]const u8{ "z", "a", "m" };
+    for (order) |g| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "g", .value = .{ .text = g } }}));
+    }
+
+    const specs = [_]AggSpec{.{ .field = "", .kind = .count }};
+    const groups = try run(allocator, rows.items, "g", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    try std.testing.expectEqual(@as(usize, 3), groups.len);
+    try std.testing.expectEqualStrings("z", groups[0].group.text);
+    try std.testing.expectEqualStrings("a", groups[1].group.text);
+    try std.testing.expectEqualStrings("m", groups[2].group.text);
+}
+
+test "runGlobal aggregates every row into a single result with no grouping" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    var i: i64 = 1;
+    while (i <= 4) : (i += 1) {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "x", .value = .{ .int = i } }}));
+    }
+
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "x", .kind = .sum },
+        .{ .field = "x", .kind = .max },
+    };
+    const values = try runGlobal(allocator, rows.items, &specs);
+    defer freeGlobalResult(allocator, values);
+
+    try std.testing.expectEqual(@as(i64, 4), values[0].int);
+    try std.testing.expectEqual(@as(i64, 10), values[1].int);
+    try std.testing.expectEqual(@as(i64, 4), values[2].int);
+}
+
+test "runGlobal on zero rows still reports identity results, not an error" {
+    const allocator = std.testing.allocator;
+    const rows: []const Row = &.{};
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "x", .kind = .sum },
+        .{ .field = "x", .kind = .max },
+    };
+    const values = try runGlobal(allocator, rows, &specs);
+    defer freeGlobalResult(allocator, values);
+
+    try std.testing.expectEqual(@as(i64, 0), values[0].int);
+    try std.testing.expectEqual(@as(i64, 0), values[1].int);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, values[2]));
+}
+
+test "GroupBy propagates OutOfMemory without leaking any accumulated group" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const groupNames = [_][]const u8{ "a", "b", "c" };
+    for (groupNames) |g| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "g", .value = .{ .text = g } },
+            .{ .name = "x", .value = .{ .int = 1 } },
+        }));
+    }
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 6 });
+    const specs = [_]AggSpec{.{ .field = "x", .kind = .sum }};
+    var gb = GroupBy.init(failing.allocator(), "g", &specs);
+    defer gb.deinit();
+
+    var sawError = false;
+    for (rows.items) |*r| {
+        gb.observe(r) catch {
+            sawError = true;
+            break;
+        };
+    }
+    try std.testing.expect(sawError);
+}
+
+fn fourGroupRows(allocator: Allocator) ![]GroupRow {
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const groupNames = [_][]const u8{ "a", "b", "c", "d" };
+    for (groupNames) |g| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "g", .value = .{ .text = g } }}));
+    }
+    const specs = [_]AggSpec{.{ .field = "", .kind = .count }};
+    return run(allocator, rows.items, "g", &specs);
+}
+
+fn firstLettersOf(rows: []const GroupRow) [4]u8 {
+    var out: [4]u8 = undefined;
+    for (rows, 0..) |r, i| out[i] = r.group.text[0];
+    return out;
+}
+
+test "applyPageGroups with offset and limit keeps a middle window in first-seen order" {
+    const allocator = std.testing.allocator;
+    const groups = try fourGroupRows(allocator);
+    try std.testing.expectEqual(@as(usize, 4), groups.len);
+
+    const paged = try applyPageGroups(allocator, groups, .{ .offset = 1, .limit = 2 });
+    defer freeGroupRows(allocator, paged);
+
+    try std.testing.expectEqual(@as(usize, 2), paged.len);
+    try std.testing.expectEqualStrings("b", paged[0].group.text);
+    try std.testing.expectEqualStrings("c", paged[1].group.text);
+}
+
+test "applyPageGroups with limit 0 returns every group, matching unpaged run" {
+    const allocator = std.testing.allocator;
+    const groups = try fourGroupRows(allocator);
+    const paged = try applyPageGroups(allocator, groups, .{});
+    defer freeGroupRows(allocator, paged);
+
+    try std.testing.expectEqualSlices(u8, &.{ 'a', 'b', 'c', 'd' }, &firstLettersOf(paged));
+}
+
+test "applyPageGroups with offset past the end returns nothing" {
+    const allocator = std.testing.allocator;
+    const groups = try fourGroupRows(allocator);
+    const paged = try applyPageGroups(allocator, groups, .{ .offset = 50 });
+    defer freeGroupRows(allocator, paged);
+
+    try std.testing.expectEqual(@as(usize, 0), paged.len);
+}
+
+test "applyPageGroups with limit larger than the remaining groups stops at the end" {
+    const allocator = std.testing.allocator;
+    const groups = try fourGroupRows(allocator);
+    const paged = try applyPageGroups(allocator, groups, .{ .offset = 3, .limit = 100 });
+    defer freeGroupRows(allocator, paged);
+
+    try std.testing.expectEqual(@as(usize, 1), paged.len);
+    try std.testing.expectEqualStrings("d", paged[0].group.text);
+}
+
+test "applyPageGroups propagates OutOfMemory from its own result allocation without leaking any group" {
+    const allocator = std.testing.allocator;
+    const groups = try fourGroupRows(allocator);
+    try std.testing.expectEqual(@as(usize, 4), groups.len);
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 0 });
+    try std.testing.expectError(error.OutOfMemory, applyPageGroups(failing.allocator(), groups, .{ .offset = 1, .limit = 2 }));
+    // No explicit assertion beyond this: `testing.allocator`'s leak detector
+    // at process exit is the real check - every one of the 4 `GroupRow`s (2
+    // kept by the window, 2 trimmed outside it) must have been
+    // `.deinit(allocator)`-ed on the error path, and the `rows` backing
+    // slice itself freed, or this test fails on leak. Every `GroupRow` here
+    // was built by `run()` using the real `testing.allocator`, so the error
+    // path frees through that same allocator regardless of which allocator
+    // `applyPageGroups` was asked to allocate its OWN result slice with -
+    // the exact isolation `join.zig`'s analogous OOM test documents.
+}
+
+fn threeCityGroups(allocator: Allocator) ![]GroupRow {
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { city: []const u8, score: i64 }{
+        .{ .city = "warsaw", .score = 10 },
+        .{ .city = "warsaw", .score = 30 },
+        .{ .city = "krakow", .score = 5 },
+        .{ .city = "gdansk", .score = 100 },
+        .{ .city = "gdansk", .score = 100 },
+        .{ .city = "gdansk", .score = 100 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "score", .value = .{ .int = d.score } },
+        }));
+    }
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    return run(allocator, rows.items, "city", &specs);
+}
+
+test "filterHaving keeps only groups whose aggregate result matches the predicate" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    // warsaw: count=2 sum=40, krakow: count=1 sum=5, gdansk: count=3 sum=300
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    const having = Predicate{ .gt = .{ .field = "count", .value = .{ .int = 1 } } };
+    const kept = try filterHaving(allocator, groups, "city", &specs, having);
+    defer freeGroupRows(allocator, kept);
+
+    try std.testing.expectEqual(@as(usize, 2), kept.len);
+    try std.testing.expectEqualStrings("warsaw", kept[0].group.text);
+    try std.testing.expectEqualStrings("gdansk", kept[1].group.text);
+}
+
+test "filterHaving can reference the underlying aggregate field name (sum_field)" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    const having = Predicate{ .gte = .{ .field = "sum_score", .value = .{ .int = 100 } } };
+    const kept = try filterHaving(allocator, groups, "city", &specs, having);
+    defer freeGroupRows(allocator, kept);
+
+    try std.testing.expectEqual(@as(usize, 1), kept.len);
+    try std.testing.expectEqualStrings("gdansk", kept[0].group.text);
+}
+
+test "filterHaving can also reference the group key itself, not just an aggregate result" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    const having = Predicate{ .ne = .{ .field = "city", .value = .{ .text = "krakow" } } };
+    const kept = try filterHaving(allocator, groups, "city", &specs, having);
+    defer freeGroupRows(allocator, kept);
+
+    try std.testing.expectEqual(@as(usize, 2), kept.len);
+    try std.testing.expectEqualStrings("warsaw", kept[0].group.text);
+    try std.testing.expectEqualStrings("gdansk", kept[1].group.text);
+}
+
+test "filterHaving that rejects every group returns an empty, still-valid slice" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    const having = Predicate{ .gt = .{ .field = "count", .value = .{ .int = 1000 } } };
+    const kept = try filterHaving(allocator, groups, "city", &specs, having);
+    defer freeGroupRows(allocator, kept);
+
+    try std.testing.expectEqual(@as(usize, 0), kept.len);
+}
+
+test "filterHaving composes with applyPageGroups: HAVING narrows before LIMIT/OFFSET windows" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    // Only warsaw and gdansk survive HAVING; a limit of 1 then keeps just
+    // the first of those two (warsaw, first-seen), not the first of all
+    // three original groups.
+    const having = Predicate{ .gt = .{ .field = "count", .value = .{ .int = 1 } } };
+    const filtered = try filterHaving(allocator, groups, "city", &specs, having);
+    const paged = try applyPageGroups(allocator, filtered, .{ .limit = 1 });
+    defer freeGroupRows(allocator, paged);
+
+    try std.testing.expectEqual(@as(usize, 1), paged.len);
+    try std.testing.expectEqualStrings("warsaw", paged[0].group.text);
+}
+
+test "filterHaving propagates OutOfMemory without leaking any group, kept or rejected" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    const having = Predicate{ .gt = .{ .field = "count", .value = .{ .int = 1 } } };
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 0 });
+    try std.testing.expectError(error.OutOfMemory, filterHaving(failing.allocator(), groups, "city", &specs, having));
+    // Leak detector on `std.testing.allocator` at process exit is the real
+    // check here (same pattern as `applyPageGroups`'s analogous OOM test):
+    // every one of the 3 groups `threeCityGroups` built with the real
+    // allocator must still get freed on this early failure, even though
+    // `filterHaving` itself was asked to allocate its OWN bookkeeping
+    // (`kept`) through the failing allocator.
+}
+
+test "globalMatchesHaving reports true or false without freeing the caller's values" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    var i: i64 = 1;
+    while (i <= 5) : (i += 1) {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "x", .value = .{ .int = i } }}));
+    }
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "x", .kind = .sum },
+    };
+    const values = try runGlobal(allocator, rows.items, &specs);
+    defer freeGlobalResult(allocator, values);
+
+    const passing = Predicate{ .eq = .{ .field = "count", .value = .{ .int = 5 } } };
+    try std.testing.expect(try globalMatchesHaving(allocator, &specs, values, passing));
+
+    const failing = Predicate{ .gt = .{ .field = "sum_x", .value = .{ .int = 1000 } } };
+    try std.testing.expect(!try globalMatchesHaving(allocator, &specs, values, failing));
+}
+
+test "sortGroupsBy orders by the group key ascending by default" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    defer freeGroupRows(allocator, groups);
+
+    const order = [_]querymod.OrderBy{.{ .field = "city" }};
+    try sortGroupsBy(allocator, groups, "city", &.{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    }, &order);
+
+    try std.testing.expectEqualStrings("gdansk", groups[0].group.text);
+    try std.testing.expectEqualStrings("krakow", groups[1].group.text);
+    try std.testing.expectEqualStrings("warsaw", groups[2].group.text);
+}
+
+test "sortGroupsBy orders by the group key descending when asked" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    defer freeGroupRows(allocator, groups);
+
+    const order = [_]querymod.OrderBy{.{ .field = "city", .descending = true }};
+    try sortGroupsBy(allocator, groups, "city", &.{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    }, &order);
+
+    try std.testing.expectEqualStrings("warsaw", groups[0].group.text);
+    try std.testing.expectEqualStrings("krakow", groups[1].group.text);
+    try std.testing.expectEqualStrings("gdansk", groups[2].group.text);
+}
+
+test "sortGroupsBy orders by an aggregate result label, not just the group key" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    defer freeGroupRows(allocator, groups);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+
+    // warsaw sum=40, krakow sum=5, gdansk sum=300 - ascending by sum_score
+    // is a completely different order than ascending by city.
+    const order = [_]querymod.OrderBy{.{ .field = "sum_score" }};
+    try sortGroupsBy(allocator, groups, "city", &specs, &order);
+
+    try std.testing.expectEqualStrings("krakow", groups[0].group.text);
+    try std.testing.expectEqualStrings("warsaw", groups[1].group.text);
+    try std.testing.expectEqualStrings("gdansk", groups[2].group.text);
+}
+
+test "sortGroupsBy breaks ties left to right across multiple order columns" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // Every group has count == 1 (a full tie on the first order column), so
+    // only the second column (the group key itself) can decide the order -
+    // built out of first-seen order d,b,a,c specifically so an
+    // alphabetical result proves the second column actually ran, rather
+    // than the sort coincidentally matching input order.
+    const groupNames = [_][]const u8{ "d", "b", "a", "c" };
+    for (groupNames) |g| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "g", .value = .{ .text = g } }}));
+    }
+    const specs = [_]AggSpec{.{ .field = "", .kind = .count }};
+    const groups = try run(allocator, rows.items, "g", &specs);
+    defer freeGroupRows(allocator, groups);
+
+    const order = [_]querymod.OrderBy{
+        .{ .field = "count" },
+        .{ .field = "g" },
+    };
+    try sortGroupsBy(allocator, groups, "g", &specs, &order);
+
+    try std.testing.expectEqualStrings("a", groups[0].group.text);
+    try std.testing.expectEqualStrings("b", groups[1].group.text);
+    try std.testing.expectEqualStrings("c", groups[2].group.text);
+    try std.testing.expectEqualStrings("d", groups[3].group.text);
+}
+
+test "sortGroupsBy with an empty order list leaves groups in first-seen order" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    defer freeGroupRows(allocator, groups);
+
+    try sortGroupsBy(allocator, groups, "city", &.{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    }, &.{});
+
+    try std.testing.expectEqualStrings("warsaw", groups[0].group.text);
+    try std.testing.expectEqualStrings("krakow", groups[1].group.text);
+    try std.testing.expectEqualStrings("gdansk", groups[2].group.text);
+}
+
+test "sortGroupsBy rejects a field that names neither the group key nor a known aggregate label" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    defer freeGroupRows(allocator, groups);
+
+    const order = [_]querymod.OrderBy{.{ .field = "not_a_real_field" }};
+    try std.testing.expectError(error.UnknownOrderField, sortGroupsBy(allocator, groups, "city", &.{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    }, &order));
+}
+
+test "sortGroupsBy composes with filterHaving and applyPageGroups: ORDER BY reorders before LIMIT/OFFSET windows" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+    // HAVING keeps only warsaw (count=2, sum=40) and gdansk (count=3,
+    // sum=300); descending sum_score then puts gdansk first even though
+    // warsaw was first-seen - a limit of 1 must keep gdansk, not warsaw.
+    const having = Predicate{ .gt = .{ .field = "count", .value = .{ .int = 1 } } };
+    const filtered = try filterHaving(allocator, groups, "city", &specs, having);
+    const order = [_]querymod.OrderBy{.{ .field = "sum_score", .descending = true }};
+    try sortGroupsBy(allocator, filtered, "city", &specs, &order);
+    const paged = try applyPageGroups(allocator, filtered, .{ .limit = 1 });
+    defer freeGroupRows(allocator, paged);
+
+    try std.testing.expectEqual(@as(usize, 1), paged.len);
+    try std.testing.expectEqualStrings("gdansk", paged[0].group.text);
+}
+
+test "sortGroupsBy propagates OutOfMemory without leaking or freeing the caller's groups" {
+    const allocator = std.testing.allocator;
+    const groups = try threeCityGroups(allocator);
+    defer freeGroupRows(allocator, groups);
+    const specs = [_]AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "score", .kind = .sum },
+    };
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 0 });
+    const order = [_]querymod.OrderBy{.{ .field = "city" }};
+    try std.testing.expectError(error.OutOfMemory, sortGroupsBy(failing.allocator(), groups, "city", &specs, &order));
+
+    // `sortGroupsBy` never took ownership of `groups` (unlike
+    // `filterHaving`), so the outer `defer freeGroupRows(allocator, ...)`
+    // above must still see every group intact and still first-seen order
+    // (untouched, not partially sorted) - both the leak detector on
+    // `std.testing.allocator` and this ordering check are the real
+    // assertions here.
+    try std.testing.expectEqualStrings("warsaw", groups[0].group.text);
+    try std.testing.expectEqualStrings("krakow", groups[1].group.text);
+    try std.testing.expectEqualStrings("gdansk", groups[2].group.text);
+}
diff --git a/src/auth.zig b/src/auth.zig
new file mode 100644
index 0000000..59d8fba
--- /dev/null
+++ b/src/auth.zig
@@ -0,0 +1,450 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Hmac256 = std.crypto.auth.hmac.sha2.HmacSha256;
+
+/// Username/password authentication and coarse-grained role authorization,
+/// layered over the same Db as tables/indexes/collections under its own
+/// namespace tag 'A' (row.zig/index.zig use 'R'/'I'/'M', collections.zig
+/// uses 'X', so no keyspace ever collides):
+///   "A" "U\0" username -> UserRecord{role, rounds, salt[16], hash[32]}
+/// Passwords are never stored: only a per-user salted PBKDF2-HMAC-SHA256
+/// hash, using `std.crypto.pwhash.pbkdf2` - the same primitive the standard
+/// library itself ships for exactly this purpose, not a hand-rolled one.
+pub const nsTag: u8 = 'A';
+const userPrefixBytes = [_]u8{ nsTag, 'U', 0 };
+const saltLen = 16;
+const hashLen = 32;
+const recordLen = 1 + 4 + saltLen + hashLen;
+
+pub const AuthError = error{
+    UserNotFound,
+    UserExists,
+    InvalidCredentials,
+    Malformed,
+};
+
+/// Roles form a total order, not a set of independent flags: readwrite
+/// implies readonly, admin implies both. `atLeast` is the only check any
+/// caller (server.zig's dispatch) ever needs.
+pub const Role = enum(u8) {
+    readonly = 0,
+    readwrite = 1,
+    admin = 2,
+
+    pub fn fromByte(b: u8) !Role {
+        return std.meta.intToEnum(Role, b) catch error.Malformed;
+    }
+
+    pub fn parse(text: []const u8) !Role {
+        if (std.mem.eql(u8, text, "readonly")) return .readonly;
+        if (std.mem.eql(u8, text, "readwrite")) return .readwrite;
+        if (std.mem.eql(u8, text, "admin")) return .admin;
+        return error.Malformed;
+    }
+
+    pub fn name(self: Role) []const u8 {
+        return switch (self) {
+            .readonly => "readonly",
+            .readwrite => "readwrite",
+            .admin => "admin",
+        };
+    }
+
+    pub fn atLeast(self: Role, min: Role) bool {
+        return @intFromEnum(self) >= @intFromEnum(min);
+    }
+};
+
+/// Recommended real-world cost factor for interactive login (OWASP's floor
+/// for PBKDF2-HMAC-SHA256 as of 2023). A constant rather than a value
+/// baked into `hashPassword` so tests can pass a tiny round count and stay
+/// fast, while `main.zig` and any other real caller default to this.
+pub const recommendedRounds: u32 = 100_000;
+
+fn userKey(allocator: Allocator, username: []const u8) ![]u8 {
+    const out = try allocator.alloc(u8, userPrefixBytes.len + username.len);
+    @memcpy(out[0..userPrefixBytes.len], &userPrefixBytes);
+    @memcpy(out[userPrefixBytes.len..], username);
+    return out;
+}
+
+const UserRecord = struct {
+    role: Role,
+    rounds: u32,
+    salt: [saltLen]u8,
+    hash: [hashLen]u8,
+
+    fn encode(self: UserRecord) [recordLen]u8 {
+        var out: [recordLen]u8 = undefined;
+        out[0] = @intFromEnum(self.role);
+        std.mem.writeInt(u32, out[1..5], self.rounds, .little);
+        @memcpy(out[5 .. 5 + saltLen], &self.salt);
+        @memcpy(out[5 + saltLen .. recordLen], &self.hash);
+        return out;
+    }
+
+    fn decode(data: []const u8) !UserRecord {
+        if (data.len != recordLen) return error.Malformed;
+        var rec: UserRecord = undefined;
+        rec.role = try Role.fromByte(data[0]);
+        rec.rounds = std.mem.readInt(u32, data[1..5], .little);
+        @memcpy(&rec.salt, data[5 .. 5 + saltLen]);
+        @memcpy(&rec.hash, data[5 + saltLen .. recordLen]);
+        return rec;
+    }
+};
+
+fn randomSalt() [saltLen]u8 {
+    var salt: [saltLen]u8 = undefined;
+    std.crypto.random.bytes(&salt);
+    return salt;
+}
+
+fn hashPassword(password: []const u8, salt: [saltLen]u8, rounds: u32) ![hashLen]u8 {
+    var out: [hashLen]u8 = undefined;
+    try std.crypto.pwhash.pbkdf2(&out, password, &salt, rounds, Hmac256);
+    return out;
+}
+
+/// Fixed salt/rounds used to cost a lookup against a username that does not
+/// exist, so `verify` spends roughly the same CPU whether the account is
+/// missing or the password was merely wrong - closing the most obvious
+/// timing side channel for username enumeration over the network (the
+/// key comparison itself still only runs on the "user exists" path, since
+/// there is nothing real to compare against otherwise).
+const dummySalt = [_]u8{0} ** saltLen;
+const dummyRounds: u32 = 4096;
+
+pub const UserInfo = struct {
+    username: []u8,
+    role: Role,
+
+    pub fn deinit(self: UserInfo, allocator: Allocator) void {
+        allocator.free(self.username);
+    }
+};
+
+pub fn freeUserList(allocator: Allocator, users: []UserInfo) void {
+    for (users) |u| u.deinit(allocator);
+    allocator.free(users);
+}
+
+/// Username/password/role management layered over a `*Db`. Every method
+/// touches only keys under `userPrefixBytes`; unrelated data in the same
+/// Db (tables, collections, raw KV) is never read or written. Not
+/// synchronized on its own, same as every other module built over Db -
+/// server.zig serializes access with its own connection-handling mutex.
+pub const Store = struct {
+    db: *Db,
+
+    pub fn init(db: *Db) Store {
+        return .{ .db = db };
+    }
+
+    pub fn createUser(self: Store, allocator: Allocator, username: []const u8, password: []const u8, role: Role, rounds: u32) !void {
+        const key = try userKey(allocator, username);
+        defer allocator.free(key);
+        if (try self.db.get(allocator, key)) |existing| {
+            allocator.free(existing);
+            return error.UserExists;
+        }
+        const salt = randomSalt();
+        const record = UserRecord{
+            .role = role,
+            .rounds = rounds,
+            .salt = salt,
+            .hash = try hashPassword(password, salt, rounds),
+        };
+        const encoded = record.encode();
+        try self.db.put(key, &encoded);
+    }
+
+    fn mustGet(self: Store, allocator: Allocator, key: []const u8) !UserRecord {
+        const raw = try self.db.get(allocator, key) orelse return error.UserNotFound;
+        defer allocator.free(raw);
+        return UserRecord.decode(raw);
+    }
+
+    pub fn setPassword(self: Store, allocator: Allocator, username: []const u8, newPassword: []const u8, rounds: u32) !void {
+        const key = try userKey(allocator, username);
+        defer allocator.free(key);
+        var record = try self.mustGet(allocator, key);
+        record.rounds = rounds;
+        record.salt = randomSalt();
+        record.hash = try hashPassword(newPassword, record.salt, rounds);
+        const encoded = record.encode();
+        try self.db.put(key, &encoded);
+    }
+
+    pub fn setRole(self: Store, allocator: Allocator, username: []const u8, role: Role) !void {
+        const key = try userKey(allocator, username);
+        defer allocator.free(key);
+        var record = try self.mustGet(allocator, key);
+        record.role = role;
+        const encoded = record.encode();
+        try self.db.put(key, &encoded);
+    }
+
+    pub fn deleteUser(self: Store, allocator: Allocator, username: []const u8) !void {
+        const key = try userKey(allocator, username);
+        defer allocator.free(key);
+        _ = try self.mustGet(allocator, key);
+        try self.db.delete(key);
+    }
+
+    /// Verifies `password` for `username`, returning the stored role on
+    /// success. See `dummySalt`/`dummyRounds` for why a missing user still
+    /// pays a full PBKDF2 pass before failing. The final comparison uses
+    /// `std.crypto.utils.timingSafeEql` rather than `std.mem.eql`, since an
+    /// early-exit byte comparison on the hash would leak how many leading
+    /// bytes matched to a network attacker timing repeated attempts.
+    pub fn verify(self: Store, allocator: Allocator, username: []const u8, password: []const u8) !Role {
+        const key = try userKey(allocator, username);
+        defer allocator.free(key);
+        const raw = try self.db.get(allocator, key) orelse {
+            _ = hashPassword(password, dummySalt, dummyRounds) catch {};
+            return error.InvalidCredentials;
+        };
+        defer allocator.free(raw);
+        const record = try UserRecord.decode(raw);
+        const candidate = try hashPassword(password, record.salt, record.rounds);
+        if (!std.crypto.utils.timingSafeEql([hashLen]u8, candidate, record.hash)) return error.InvalidCredentials;
+        return record.role;
+    }
+
+    /// Whether at least one admin account exists - `main.zig` uses this to
+    /// refuse turning on server-side auth enforcement until an operator has
+    /// created a way back in, so enabling `--auth` can never lock everyone
+    /// out of a fresh database.
+    pub fn hasAnyAdmin(self: Store, allocator: Allocator) !bool {
+        var it = try self.db.scanPrefix(allocator, &userPrefixBytes);
+        defer it.deinit();
+        while (try it.next()) |entry| {
+            const record = UserRecord.decode(entry.value) catch continue;
+            if (record.role == .admin) return true;
+        }
+        return false;
+    }
+
+    /// Returns every user with their role, independently owned - free with
+    /// `freeUserList`. Order follows key order (lexicographic by username).
+    pub fn listUsers(self: Store, allocator: Allocator) ![]UserInfo {
+        var it = try self.db.scanPrefix(allocator, &userPrefixBytes);
+        defer it.deinit();
+        var out = std.ArrayList(UserInfo).init(allocator);
+        errdefer {
+            for (out.items) |u| u.deinit(allocator);
+            out.deinit();
+        }
+        while (try it.next()) |entry| {
+            const record = UserRecord.decode(entry.value) catch continue;
+            const uname = entry.key[userPrefixBytes.len..];
+            try out.append(.{ .username = try allocator.dupe(u8, uname), .role = record.role });
+        }
+        return out.toOwnedSlice();
+    }
+};
+
+fn testDb(allocator: Allocator, dir: std.fs.Dir) !Db {
+    const path = try dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+    return Db.open(allocator, path, .{});
+}
+
+test "role ordering is a total order across readonly/readwrite/admin" {
+    try std.testing.expect(Role.readwrite.atLeast(.readonly));
+    try std.testing.expect(Role.admin.atLeast(.readonly));
+    try std.testing.expect(Role.admin.atLeast(.readwrite));
+    try std.testing.expect(Role.admin.atLeast(.admin));
+    try std.testing.expect(!Role.readonly.atLeast(.readwrite));
+    try std.testing.expect(!Role.readwrite.atLeast(.admin));
+}
+
+test "Role.parse rejects an unknown role name" {
+    try std.testing.expectEqual(Role.admin, try Role.parse("admin"));
+    try std.testing.expectError(error.Malformed, Role.parse("superuser"));
+}
+
+test "createUser then verify accepts the correct password" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    const role = try store.verify(allocator, "alice", "hunter2");
+    try std.testing.expectEqual(Role.readwrite, role);
+}
+
+test "verify rejects a wrong password without revealing which part was wrong" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readonly, 16);
+
+    try std.testing.expectError(error.InvalidCredentials, store.verify(allocator, "alice", "wrong"));
+}
+
+test "verify rejects an unknown username the same way as a wrong password" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try std.testing.expectError(error.InvalidCredentials, store.verify(allocator, "ghost", "anything"));
+}
+
+test "createUser rejects a duplicate username" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readonly, 16);
+    try std.testing.expectError(error.UserExists, store.createUser(allocator, "alice", "different", .admin, 16));
+}
+
+test "setPassword replaces the password and invalidates the old one" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try store.createUser(allocator, "alice", "old-pass", .readonly, 16);
+    try store.setPassword(allocator, "alice", "new-pass", 16);
+
+    try std.testing.expectError(error.InvalidCredentials, store.verify(allocator, "alice", "old-pass"));
+    try std.testing.expectEqual(Role.readonly, try store.verify(allocator, "alice", "new-pass"));
+}
+
+test "setPassword on a missing user reports UserNotFound" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try std.testing.expectError(error.UserNotFound, store.setPassword(allocator, "ghost", "x", 16));
+}
+
+test "setRole changes role without disturbing the password" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readonly, 16);
+    try store.setRole(allocator, "alice", .admin);
+
+    try std.testing.expectEqual(Role.admin, try store.verify(allocator, "alice", "hunter2"));
+}
+
+test "deleteUser removes the account so verify and mustGet both fail" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readonly, 16);
+    try store.deleteUser(allocator, "alice");
+
+    try std.testing.expectError(error.InvalidCredentials, store.verify(allocator, "alice", "hunter2"));
+    try std.testing.expectError(error.UserNotFound, store.deleteUser(allocator, "alice"));
+}
+
+test "hasAnyAdmin reflects whether any created user carries the admin role" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try std.testing.expect(!(try store.hasAnyAdmin(allocator)));
+
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+    try std.testing.expect(!(try store.hasAnyAdmin(allocator)));
+
+    try store.createUser(allocator, "root", "toor", .admin, 16);
+    try std.testing.expect(try store.hasAnyAdmin(allocator));
+}
+
+test "listUsers returns every account with its role" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const store = Store.init(&db);
+    try store.createUser(allocator, "alice", "a-pass", .readonly, 16);
+    try store.createUser(allocator, "bob", "b-pass", .readwrite, 16);
+    try store.createUser(allocator, "root", "r-pass", .admin, 16);
+
+    const users = try store.listUsers(allocator);
+    defer freeUserList(allocator, users);
+    try std.testing.expectEqual(@as(usize, 3), users.len);
+
+    var sawAdmin = false;
+    for (users) |u| {
+        if (std.mem.eql(u8, u.username, "root")) {
+            try std.testing.expectEqual(Role.admin, u.role);
+            sawAdmin = true;
+        }
+    }
+    try std.testing.expect(sawAdmin);
+}
+
+test "users survive a Db close and reopen" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    {
+        var db = try testDb(allocator, tmp.dir);
+        defer db.close();
+        const store = Store.init(&db);
+        try store.createUser(allocator, "alice", "hunter2", .admin, 16);
+    }
+
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+    const store = Store.init(&db);
+    try std.testing.expectEqual(Role.admin, try store.verify(allocator, "alice", "hunter2"));
+}
+
+test "a malformed stored record is reported as Malformed, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try testDb(allocator, tmp.dir);
+    defer db.close();
+
+    const key = try userKey(allocator, "alice");
+    defer allocator.free(key);
+    try db.put(key, "too short to be a real record");
+
+    const store = Store.init(&db);
+    try std.testing.expectError(error.Malformed, store.verify(allocator, "alice", "anything"));
+}
diff --git a/src/backup.zig b/src/backup.zig
new file mode 100644
index 0000000..d43a934
--- /dev/null
+++ b/src/backup.zig
@@ -0,0 +1,527 @@
+const std = @import("std");
+const db_mod = @import("db.zig");
+const encode = @import("encode.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = db_mod.Db;
+const Snapshot = db_mod.Snapshot;
+const WriteBatch = db_mod.WriteBatch;
+
+// Portable logical backup format for cobalt. Dumps a consistent, point-in-time
+// view of the live keyspace (as returned by Snapshot.scan - tombstones already
+// resolved) into a self-describing file that can be replayed into any Db.
+//
+// Layout:
+//   header: magic("CBLB" 4B) | version(u32) | seq(u64)
+//   entry*: keyLen(u32) | valueLen(u32) | key | value | entryCrc(u32)
+//           entryCrc = crc32(keyLen le bytes || valueLen le bytes || key || value)
+//   footer: magic("CBLE" 4B) | entryCount(u64) | fileCrc(u32)
+//           fileCrc = crc32 of every byte written before the footer magic
+//           (header + all entries), rolling-accumulated while writing.
+//
+// Restore validates the whole file (magics, per-entry crc, trailing count,
+// whole-file crc) before touching the target Db, so a corrupt or truncated
+// backup never applies a partial write.
+
+const headerMagic = "CBLB";
+const footerMagic = "CBLE";
+const formatVersion: u32 = 1;
+
+pub const BackupError = error{
+    BadMagic,
+    UnsupportedVersion,
+    Truncated,
+    Corrupt,
+    CountMismatch,
+};
+
+pub const BackupInfo = struct {
+    seq: u64,
+    entryCount: u64,
+};
+
+const RollingCrc = struct {
+    hasher: std.hash.Crc32,
+
+    fn init() RollingCrc {
+        return .{ .hasher = std.hash.Crc32.init() };
+    }
+
+    fn feed(self: *RollingCrc, bytes: []const u8) void {
+        self.hasher.update(bytes);
+    }
+
+    fn value(self: RollingCrc) u32 {
+        var copy = self.hasher;
+        return copy.final();
+    }
+};
+
+fn writeAllCrc(writer: anytype, roll: *RollingCrc, bytes: []const u8) !void {
+    try writer.writeAll(bytes);
+    roll.feed(bytes);
+}
+
+fn putU32Crc(writer: anytype, roll: *RollingCrc, v: u32) !void {
+    var b: [4]u8 = undefined;
+    std.mem.writeInt(u32, &b, v, encode.endian);
+    try writeAllCrc(writer, roll, &b);
+}
+
+fn putU64Crc(writer: anytype, roll: *RollingCrc, v: u64) !void {
+    var b: [8]u8 = undefined;
+    std.mem.writeInt(u64, &b, v, encode.endian);
+    try writeAllCrc(writer, roll, &b);
+}
+
+/// Writes a full, consistent backup of `snapshot` to `path` (created/truncated).
+/// Returns the number of entries written.
+pub fn dumpToFile(allocator: Allocator, snapshot: Snapshot, path: []const u8) !u64 {
+    const file = try std.fs.cwd().createFile(path, .{ .truncate = true });
+    defer file.close();
+
+    var bufferedWriter = std.io.bufferedWriter(file.writer());
+    const writer = bufferedWriter.writer();
+
+    var roll = RollingCrc.init();
+    try writeAllCrc(writer, &roll, headerMagic);
+    try putU32Crc(writer, &roll, formatVersion);
+    try putU64Crc(writer, &roll, snapshot.seq);
+
+    var iter = try snapshot.scan(allocator, null, null);
+    defer iter.deinit();
+
+    var count: u64 = 0;
+    var entryScratch = std.ArrayList(u8).init(allocator);
+    defer entryScratch.deinit();
+
+    while (try iter.next()) |entry| {
+        entryScratch.clearRetainingCapacity();
+        var lenBuf: [8]u8 = undefined;
+        std.mem.writeInt(u32, lenBuf[0..4], @intCast(entry.key.len), encode.endian);
+        std.mem.writeInt(u32, lenBuf[4..8], @intCast(entry.value.len), encode.endian);
+        try entryScratch.appendSlice(&lenBuf);
+        try entryScratch.appendSlice(entry.key);
+        try entryScratch.appendSlice(entry.value);
+        const entryCrc = std.hash.Crc32.hash(entryScratch.items);
+
+        try writeAllCrc(writer, &roll, entryScratch.items);
+        try putU32Crc(writer, &roll, entryCrc);
+        count += 1;
+    }
+
+    try writer.writeAll(footerMagic);
+    var countBuf: [8]u8 = undefined;
+    std.mem.writeInt(u64, &countBuf, count, encode.endian);
+    try writer.writeAll(&countBuf);
+
+    const fileCrc = roll.value();
+    var crcBuf: [4]u8 = undefined;
+    std.mem.writeInt(u32, &crcBuf, fileCrc, encode.endian);
+    try writer.writeAll(&crcBuf);
+
+    try bufferedWriter.flush();
+    return count;
+}
+
+const ParsedEntry = struct {
+    key: []const u8,
+    value: []const u8,
+};
+
+/// One pass over a fully-loaded backup buffer: validates structure end to end
+/// (magics, per-entry crc, declared count, whole-file crc) without allocating
+/// per-entry copies. Returns the entries slice (positions into `data`) plus
+/// backup metadata, or a BackupError describing the first problem found.
+const ParsedBackup = struct {
+    seq: u64,
+    entries: []ParsedEntry,
+};
+
+fn parse(allocator: Allocator, data: []const u8) !ParsedBackup {
+    if (data.len < headerMagic.len + 4 + 8) return BackupError.Truncated;
+    if (!std.mem.eql(u8, data[0..4], headerMagic)) return BackupError.BadMagic;
+
+    const version = encode.readU32(data, 4);
+    if (version != formatVersion) return BackupError.UnsupportedVersion;
+    const seq = encode.readU64(data, 8);
+
+    var pos: usize = 16;
+    var entries = std.ArrayList(ParsedEntry).init(allocator);
+    errdefer entries.deinit();
+
+    while (true) {
+        if (pos + footerMagic.len <= data.len and std.mem.eql(u8, data[pos .. pos + 4], footerMagic)) {
+            break;
+        }
+        if (pos + 8 > data.len) return BackupError.Truncated;
+        const keyLen = encode.readU32(data, pos);
+        const valueLen = encode.readU32(data, pos + 4);
+        const entryStart = pos;
+        const keyStart = pos + 8;
+        const valueStart = keyStart + keyLen;
+        const valueEnd = valueStart + valueLen;
+        if (valueEnd + 4 > data.len) return BackupError.Truncated;
+
+        const entryBytes = data[entryStart..valueEnd];
+        const storedCrc = encode.readU32(data, valueEnd);
+        const actualCrc = std.hash.Crc32.hash(entryBytes);
+        if (storedCrc != actualCrc) return BackupError.Corrupt;
+
+        try entries.append(.{ .key = data[keyStart..valueStart], .value = data[valueStart..valueEnd] });
+        pos = valueEnd + 4;
+    }
+
+    if (pos + 4 + 8 + 4 > data.len) return BackupError.Truncated;
+    const declaredCount = encode.readU64(data, pos + 4);
+    if (declaredCount != entries.items.len) return BackupError.CountMismatch;
+
+    const storedFileCrc = encode.readU32(data, pos + 4 + 8);
+    const actualFileCrc = std.hash.Crc32.hash(data[0..pos]);
+    if (storedFileCrc != actualFileCrc) return BackupError.Corrupt;
+
+    return .{ .seq = seq, .entries = try entries.toOwnedSlice() };
+}
+
+/// Reads and structurally validates a backup file without applying it,
+/// returning its metadata (seq, entry count). Useful to verify a backup
+/// before trusting it for disaster recovery.
+pub fn inspectFile(allocator: Allocator, path: []const u8) !BackupInfo {
+    const data = try std.fs.cwd().readFileAlloc(allocator, path, 1 << 34);
+    defer allocator.free(data);
+    const parsed = try parse(allocator, data);
+    defer allocator.free(parsed.entries);
+    return .{ .seq = parsed.seq, .entryCount = parsed.entries.len };
+}
+
+/// Restores every entry from the backup at `path` into `db`, in chunks of
+/// `chunkSize` applied atomically via WriteBatch. The whole file is validated
+/// (magics, per-entry and whole-file crc, declared count) before any chunk is
+/// applied, so a corrupt backup fails without mutating the target database.
+/// Existing keys in `db` outside the backup are left untouched; keys present
+/// in both are overwritten with the backup's value.
+pub fn restoreFromFile(allocator: Allocator, db: *Db, path: []const u8, chunkSize: usize) !BackupInfo {
+    const data = try std.fs.cwd().readFileAlloc(allocator, path, 1 << 34);
+    defer allocator.free(data);
+
+    const parsed = try parse(allocator, data);
+    defer allocator.free(parsed.entries);
+
+    var i: usize = 0;
+    while (i < parsed.entries.len) {
+        const end = @min(i + chunkSize, parsed.entries.len);
+        var batch = WriteBatch.init(allocator);
+        defer batch.deinit();
+        for (parsed.entries[i..end]) |entry| {
+            try batch.put(entry.key, entry.value);
+        }
+        try db.apply(&batch);
+        i = end;
+    }
+
+    return .{ .seq = parsed.seq, .entryCount = parsed.entries.len };
+}
+
+test "backup round trip: dump then restore into a fresh db reproduces every key" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-1";
+    const dstDir = "test-backup-dst-1";
+    const backupPath = "test-backup-1.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+
+    var keyBuf: [16]u8 = undefined;
+    var valBuf: [16]u8 = undefined;
+    var i: usize = 0;
+    while (i < 200) : (i += 1) {
+        const key = try std.fmt.bufPrint(&keyBuf, "k{d:0>6}", .{i});
+        const value = try std.fmt.bufPrint(&valBuf, "v{d:0>6}", .{i});
+        try src.put(key, value);
+    }
+    // overwrite one, delete another: backup must reflect resolved state.
+    try src.put("k000005", "updated");
+    try src.delete("k000010");
+
+    const snap = try src.snapshot();
+    const count = try dumpToFile(allocator, snap, backupPath);
+    try std.testing.expectEqual(@as(u64, 199), count);
+
+    var dst = try Db.open(allocator, dstDir, .{});
+    defer dst.close();
+    const info = try restoreFromFile(allocator, &dst, backupPath, 32);
+    try std.testing.expectEqual(@as(u64, 199), info.entryCount);
+
+    i = 0;
+    while (i < 200) : (i += 1) {
+        const key = try std.fmt.bufPrint(&keyBuf, "k{d:0>6}", .{i});
+        const got = try dst.get(allocator, key);
+        if (i == 10) {
+            try std.testing.expect(got == null);
+            continue;
+        }
+        defer allocator.free(got.?);
+        if (i == 5) {
+            try std.testing.expectEqualStrings("updated", got.?);
+        } else {
+            const expected = try std.fmt.bufPrint(&valBuf, "v{d:0>6}", .{i});
+            try std.testing.expectEqualStrings(expected, got.?);
+        }
+    }
+}
+
+test "backup of empty db round trips to zero entries" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-empty";
+    const dstDir = "test-backup-dst-empty";
+    const backupPath = "test-backup-empty.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+    const snap = try src.snapshot();
+    const count = try dumpToFile(allocator, snap, backupPath);
+    try std.testing.expectEqual(@as(u64, 0), count);
+
+    const info = try inspectFile(allocator, backupPath);
+    try std.testing.expectEqual(@as(u64, 0), info.entryCount);
+
+    var dst = try Db.open(allocator, dstDir, .{});
+    defer dst.close();
+    _ = try restoreFromFile(allocator, &dst, backupPath, 32);
+    var iter = try dst.scan(allocator, null, null);
+    defer iter.deinit();
+    try std.testing.expect((try iter.next()) == null);
+}
+
+test "backup is point-in-time: writes after snapshot are excluded" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-pit";
+    const backupPath = "test-backup-pit.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+    try src.put("before", "1");
+    const snap = try src.snapshot();
+    try src.put("after", "2");
+
+    const count = try dumpToFile(allocator, snap, backupPath);
+    try std.testing.expectEqual(@as(u64, 1), count);
+
+    const info = try inspectFile(allocator, backupPath);
+    try std.testing.expectEqual(snap.seq, info.seq);
+}
+
+test "restore into db with pre-existing disjoint keys merges without touching them" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-merge";
+    const dstDir = "test-backup-dst-merge";
+    const backupPath = "test-backup-merge.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+    try src.put("from-backup", "yes");
+    const count = try dumpToFile(allocator, try src.snapshot(), backupPath);
+    try std.testing.expectEqual(@as(u64, 1), count);
+
+    var dst = try Db.open(allocator, dstDir, .{});
+    defer dst.close();
+    try dst.put("already-here", "kept");
+
+    _ = try restoreFromFile(allocator, &dst, backupPath, 32);
+
+    const kept = try dst.get(allocator, "already-here");
+    defer allocator.free(kept.?);
+    try std.testing.expectEqualStrings("kept", kept.?);
+
+    const restored = try dst.get(allocator, "from-backup");
+    defer allocator.free(restored.?);
+    try std.testing.expectEqualStrings("yes", restored.?);
+}
+
+test "restore chunking applies every entry across multiple write batches" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-chunks";
+    const dstDir = "test-backup-dst-chunks";
+    const backupPath = "test-backup-chunks.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+    var keyBuf: [16]u8 = undefined;
+    var i: usize = 0;
+    while (i < 97) : (i += 1) {
+        const key = try std.fmt.bufPrint(&keyBuf, "c{d:0>6}", .{i});
+        try src.put(key, "x");
+    }
+    _ = try dumpToFile(allocator, try src.snapshot(), backupPath);
+
+    var dst = try Db.open(allocator, dstDir, .{});
+    defer dst.close();
+    const info = try restoreFromFile(allocator, &dst, backupPath, 10);
+    try std.testing.expectEqual(@as(u64, 97), info.entryCount);
+
+    var found: usize = 0;
+    var iter = try dst.scan(allocator, null, null);
+    defer iter.deinit();
+    while (try iter.next()) |_| found += 1;
+    try std.testing.expectEqual(@as(usize, 97), found);
+}
+
+test "corrupted entry payload is rejected before any restore write happens" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-corrupt";
+    const dstDir = "test-backup-dst-corrupt";
+    const backupPath = "test-backup-corrupt.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+    try src.put("intact", "value-one");
+    try src.put("victim", "value-two");
+    _ = try dumpToFile(allocator, try src.snapshot(), backupPath);
+
+    {
+        const file = try std.fs.cwd().openFile(backupPath, .{ .mode = .read_write });
+        defer file.close();
+        // flip a byte squarely inside the entry region (well past the 16 byte header).
+        try file.seekTo(24);
+        var byte: [1]u8 = undefined;
+        _ = try file.read(&byte);
+        try file.seekTo(24);
+        try file.writeAll(&.{byte[0] ^ 0xFF});
+    }
+
+    var dst = try Db.open(allocator, dstDir, .{});
+    defer dst.close();
+    const result = restoreFromFile(allocator, &dst, backupPath, 32);
+    try std.testing.expectError(BackupError.Corrupt, result);
+
+    // nothing from the corrupt backup should have been applied: validation
+    // happens over the whole in-memory buffer before the first WriteBatch.
+    var iter = try dst.scan(allocator, null, null);
+    defer iter.deinit();
+    try std.testing.expect((try iter.next()) == null);
+}
+
+test "truncated file is rejected as Truncated, not a crash" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-trunc";
+    const dstDir = "test-backup-dst-trunc";
+    const backupPath = "test-backup-trunc.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(dstDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+    try src.put("a", "b");
+    _ = try dumpToFile(allocator, try src.snapshot(), backupPath);
+
+    {
+        const data = try std.fs.cwd().readFileAlloc(allocator, backupPath, 1 << 20);
+        defer allocator.free(data);
+        const truncated = data[0 .. data.len - 5];
+        const file = try std.fs.cwd().createFile(backupPath, .{ .truncate = true });
+        defer file.close();
+        try file.writeAll(truncated);
+    }
+
+    var dst = try Db.open(allocator, dstDir, .{});
+    defer dst.close();
+    const result = restoreFromFile(allocator, &dst, backupPath, 32);
+    try std.testing.expectError(BackupError.Truncated, result);
+}
+
+test "bad magic header is rejected without reading the rest of the file" {
+    const allocator = std.testing.allocator;
+    const backupPath = "test-backup-badmagic.cblb";
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    const file = try std.fs.cwd().createFile(backupPath, .{ .truncate = true });
+    {
+        defer file.close();
+        try file.writeAll("XXXX" ++ [_]u8{0} ** 12);
+    }
+
+    const result = inspectFile(allocator, backupPath);
+    try std.testing.expectError(BackupError.BadMagic, result);
+}
+
+test "unsupported version is rejected" {
+    const allocator = std.testing.allocator;
+    const backupPath = "test-backup-badversion.cblb";
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    const file = try std.fs.cwd().createFile(backupPath, .{ .truncate = true });
+    {
+        defer file.close();
+        var buf: [16]u8 = undefined;
+        @memcpy(buf[0..4], headerMagic);
+        std.mem.writeInt(u32, buf[4..8], 99, encode.endian);
+        std.mem.writeInt(u64, buf[8..16], 0, encode.endian);
+        try file.writeAll(&buf);
+    }
+
+    const result = inspectFile(allocator, backupPath);
+    try std.testing.expectError(BackupError.UnsupportedVersion, result);
+}
+
+test "declared entry count mismatch is caught even if per-entry crcs are valid" {
+    const allocator = std.testing.allocator;
+    const srcDir = "test-backup-src-countmismatch";
+    const backupPath = "test-backup-countmismatch.cblb";
+    std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteTree(srcDir) catch {};
+    defer std.fs.cwd().deleteFile(backupPath) catch {};
+
+    var src = try Db.open(allocator, srcDir, .{});
+    defer src.close();
+    try src.put("a", "1");
+    try src.put("b", "2");
+    _ = try dumpToFile(allocator, try src.snapshot(), backupPath);
+
+    {
+        const data = try std.fs.cwd().readFileAlloc(allocator, backupPath, 1 << 20);
+        defer allocator.free(data);
+        // footer is the last 4(magic)+8(count)+4(crc)=16 bytes; corrupt count only,
+        // which necessarily also breaks the whole-file crc, but count is checked first.
+        const countPos = data.len - 12;
+        var mutated = try allocator.dupe(u8, data);
+        defer allocator.free(mutated);
+        std.mem.writeInt(u64, mutated[countPos..][0..8], 999, encode.endian);
+        const file = try std.fs.cwd().createFile(backupPath, .{ .truncate = true });
+        defer file.close();
+        try file.writeAll(mutated);
+    }
+
+    const result = inspectFile(allocator, backupPath);
+    try std.testing.expectError(BackupError.CountMismatch, result);
+}
diff --git a/src/client.zig b/src/client.zig
new file mode 100644
index 0000000..1217124
--- /dev/null
+++ b/src/client.zig
@@ -0,0 +1,703 @@
+const std = @import("std");
+const protocol = @import("protocol.zig");
+const dbmod = @import("db.zig");
+const rowmod = @import("row.zig");
+const authmod = @import("auth.zig");
+const ttlmod = @import("ttl.zig");
+const collmod = @import("collections.zig");
+const aggregatemod = @import("aggregate.zig");
+const windowmod = @import("window.zig");
+const querymod = @import("query.zig");
+
+const Allocator = std.mem.Allocator;
+
+pub const ClientError = error{
+    ServerBadRequest,
+    ServerInternal,
+    ServerConflict,
+    ServerRateLimited,
+    ServerUnauthorized,
+    ServerForbidden,
+    ServerUserNotFound,
+    ServerKeyNotFound,
+    ServerCollectionNotFound,
+    UnexpectedStatus,
+};
+
+/// Result of a remote `table export`: the row count `dump.zig`'s exporter
+/// reported plus the rendered bytes, independently allocated so they
+/// outlive the response frame they arrived in.
+pub const RemoteExport = struct {
+    rowCount: u64,
+    content: []u8,
+
+    pub fn deinit(self: RemoteExport, allocator: Allocator) void {
+        allocator.free(self.content);
+    }
+};
+
+fn statusToError(status: protocol.Status) ClientError {
+    return switch (status) {
+        .bad_request => error.ServerBadRequest,
+        .internal => error.ServerInternal,
+        .conflict => error.ServerConflict,
+        .rate_limited => error.ServerRateLimited,
+        .unauthorized => error.ServerUnauthorized,
+        .forbidden => error.ServerForbidden,
+        else => error.UnexpectedStatus,
+    };
+}
+
+/// A blocking client for the wire protocol in `protocol.zig`. Each call
+/// writes one request frame and reads exactly one response frame, so a
+/// `Client` must not be shared across threads without external locking.
+pub const Client = struct {
+    allocator: Allocator,
+    stream: std.net.Stream,
+    /// The session token from the last successful `authenticate` call, if
+    /// the server had `enableSessions` on (see server.zig) - null on a
+    /// server without sessions, or before any successful `authenticate`.
+    /// Owned by the `Client`, freed on `close()` and on every subsequent
+    /// `authenticate`/`authenticateWithToken` call.
+    token: ?[]u8 = null,
+
+    pub fn connect(allocator: Allocator, address: std.net.Address) !Client {
+        const stream = try std.net.tcpConnectToAddress(address);
+        return .{ .allocator = allocator, .stream = stream };
+    }
+
+    pub fn close(self: *Client) void {
+        if (self.token) |t| self.allocator.free(t);
+        self.stream.close();
+    }
+
+    fn setToken(self: *Client, payload: []const u8) !void {
+        if (self.token) |old| self.allocator.free(old);
+        self.token = if (payload.len > 0) try self.allocator.dupe(u8, payload) else null;
+    }
+
+    /// The session token captured by the last successful `authenticate`,
+    /// if any (see `token` above). Callers that want to reconnect later
+    /// without a password should dupe this before the `Client` closes.
+    pub fn sessionToken(self: *Client) ?[]const u8 {
+        return self.token;
+    }
+
+    fn roundTrip(self: *Client, op: protocol.Op, payload: []const u8) !protocol.Frame {
+        try protocol.writeFrame(self.stream.writer(), @intFromEnum(op), payload);
+        return protocol.readFrame(self.allocator, self.stream.reader());
+    }
+
+    /// Authenticates this connection against a server that has auth
+    /// enabled (see `server.zig`'s `enableAuth`). Every request on this
+    /// stream after a successful call is dispatched under the role
+    /// returned by the server's `auth.Store.verify`; a server without auth
+    /// enabled always answers `ok` regardless of the credentials given. If
+    /// the server also has sessions enabled (`enableSessions`), the
+    /// response carries a fresh token captured into `sessionToken()` -
+    /// otherwise `sessionToken()` reads null afterwards, same as before
+    /// this call was ever made.
+    pub fn authenticate(self: *Client, username: []const u8, password: []const u8) !void {
+        const payload = try protocol.encodeAuth(self.allocator, username, password);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.auth, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        try self.setToken(frame.payload);
+    }
+
+    /// Authenticates this connection using a token obtained from another
+    /// connection's `sessionToken()`, instead of a username/password pair
+    /// (see server.zig's `auth_token` opcode) - skips the password
+    /// entirely and resumes the same role until the session expires. A
+    /// server without sessions enabled accepts any token unconditionally,
+    /// matching `authenticate`'s behavior against a server without auth.
+    pub fn authenticateWithToken(self: *Client, token: []const u8) !void {
+        const payload = try protocol.encodeAuthToken(self.allocator, token);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.auth_token, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    pub fn ping(self: *Client) !void {
+        var frame = try self.roundTrip(.ping, "");
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    pub fn get(self: *Client, allocator: Allocator, key: []const u8) !?[]u8 {
+        var frame = try self.roundTrip(.get, key);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        return switch (status) {
+            .ok => try allocator.dupe(u8, frame.payload),
+            .not_found => null,
+            else => statusToError(status),
+        };
+    }
+
+    pub fn set(self: *Client, key: []const u8, value: []const u8) !void {
+        const payload = try protocol.encodeSet(self.allocator, key, value);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.set, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    pub fn delete(self: *Client, key: []const u8) !void {
+        var frame = try self.roundTrip(.del, key);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    pub fn scan(self: *Client, allocator: Allocator, args: protocol.ScanArgs) ![]protocol.OwnedEntry {
+        const payload = try protocol.encodeScan(self.allocator, args);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.scan, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeEntries(allocator, frame.payload);
+    }
+
+    pub fn prefix(self: *Client, allocator: Allocator, prefixBytes: []const u8, limit: u32) ![]protocol.OwnedEntry {
+        const payload = try protocol.encodePrefix(self.allocator, prefixBytes, limit);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.prefix, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeEntries(allocator, frame.payload);
+    }
+
+    pub fn stats(self: *Client) !dbmod.Stats {
+        var frame = try self.roundTrip(.stats, "");
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeStats(frame.payload);
+    }
+
+    /// Fetches the server's combined Prometheus text export (its own
+    /// request/rate-limit/auth/session counters from `Server.registerMetrics`
+    /// plus `Db.stats()`, in the one payload `Server.handleMetrics` builds) -
+    /// the network counterpart of the CLI's local-only `stats --prom`.
+    /// Returned text is independently owned; free with `allocator.free`.
+    pub fn metricsText(self: *Client, allocator: Allocator) ![]u8 {
+        var frame = try self.roundTrip(.metrics, "");
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return allocator.dupe(u8, frame.payload);
+    }
+
+    pub fn flush(self: *Client) !void {
+        var frame = try self.roundTrip(.flush, "");
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    pub fn compact(self: *Client) !void {
+        var frame = try self.roundTrip(.compact, "");
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    pub fn batch(self: *Client, ops: []const protocol.BatchOp) !void {
+        const payload = try protocol.encodeBatch(self.allocator, ops);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.batch, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// Remote `table explain`: the wire counterpart of the CLI's local
+    /// `table explain`, reporting which strategy `query.Table.explain`
+    /// says a matching `tableSelect` would take against the server's
+    /// `*Db`, without running the query. `exprText` is the same `expr.zig`
+    /// grammar as `tableSelect`'s (empty means no predicate, i.e. always a
+    /// full scan). Returned `Plan` owns its `indexName` - free with
+    /// `Plan.deinit`.
+    pub fn tableExplain(self: *Client, allocator: Allocator, table: []const u8, exprText: []const u8) !querymod.Plan {
+        const payload = try protocol.encodeTableExplain(self.allocator, table, exprText);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_explain, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodePlan(allocator, frame.payload);
+    }
+
+    /// Remote `table update`: the wire counterpart of the CLI's local
+    /// `table update`, applying `sets` to every row matching `exprText`
+    /// (empty means every row, the same convention `tableSelect`/
+    /// `tableExplain` use) against the server's `*Db` via
+    /// `query.Table.updateWhere`. Returns the number of rows updated.
+    pub fn tableUpdate(self: *Client, table: []const u8, sets: []const rowmod.Field, exprText: []const u8) !u64 {
+        const payload = try protocol.encodeTableUpdate(self.allocator, table, sets, exprText);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_update, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTtlSweepCount(frame.payload);
+    }
+
+    /// Remote `table delete`: the wire counterpart of the CLI's local
+    /// `table delete`, removing every row matching `exprText` (empty means
+    /// every row, the same convention `tableUpdate`/`tableExplain` use)
+    /// against the server's `*Db` via `query.Table.deleteWhere`. Returns the
+    /// number of rows deleted.
+    pub fn tableDelete(self: *Client, table: []const u8, exprText: []const u8) !u64 {
+        const payload = try protocol.encodeTableDelete(self.allocator, table, exprText);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_delete, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTtlSweepCount(frame.payload);
+    }
+
+    /// Remote `table export`: the wire counterpart of the CLI's local
+    /// `table export <table> csv|json <path>`, rendering the whole table on
+    /// the server and returning both the row count and the rendered bytes
+    /// in one round trip. `content` is a fresh allocation independent of
+    /// the response frame - free it with `RemoteExport.deinit`.
+    pub fn tableExport(self: *Client, allocator: Allocator, table: []const u8, format: protocol.DumpFormat) !RemoteExport {
+        const payload = try protocol.encodeTableExport(self.allocator, table, format);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_export, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        const result = try protocol.decodeExportResult(frame.payload);
+        const content = try allocator.dupe(u8, result.content);
+        return .{ .rowCount = result.rowCount, .content = content };
+    }
+
+    /// Remote `table import`: the wire counterpart of the CLI's local
+    /// `table import <table> csv|json <path>`. `content` is data the
+    /// caller already read into memory (e.g. from a local file) and sends
+    /// to the server in one frame; the server runs it through `dump.zig`'s
+    /// importer there. Returns the number of rows imported.
+    pub fn tableImport(self: *Client, table: []const u8, format: protocol.DumpFormat, content: []const u8) !u64 {
+        const payload = try protocol.encodeTableImport(self.allocator, table, format, content);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_import, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTtlSweepCount(frame.payload);
+    }
+
+    /// Remote `table select`: `exprText` is the same `expr.zig` predicate
+    /// grammar the local CLI's `table select` accepts (empty selects every
+    /// row). `offset`/`limit` page the result the same way
+    /// `query.Table.selectPage` does locally (0 limit = unlimited), so a
+    /// large remote result does not have to come back in a single frame.
+    /// `orderBy`, when non-empty, sorts server-side via
+    /// `Table.selectPageOrdered` before that page window applies (one or
+    /// more columns applied left to right, ties on earlier columns broken
+    /// by later ones) - the network counterpart of the local CLI's `table
+    /// select --order-by`. Returned rows are independently owned - free
+    /// with `protocol.freeRows`.
+    pub fn tableSelect(self: *Client, allocator: Allocator, table: []const u8, exprText: []const u8, offset: u32, limit: u32, orderBy: []const querymod.OrderBy) ![]rowmod.Row {
+        const payload = try protocol.encodeTableSelect(self.allocator, table, exprText, offset, limit, orderBy);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_select, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeRows(allocator, frame.payload);
+    }
+
+    /// Remote `table join`: the wire counterpart of the CLI's local `table
+    /// join [--left|--right|--full]`, running whichever of `join.zig`'s four
+    /// equi-join variants `mode` names against the server's `*Db` instead of
+    /// a locally opened one. `leftExprText`/`rightExprText` are the same
+    /// `expr.zig` predicate grammar as `tableSelect`'s `exprText` (empty
+    /// selects every row on that side), filtering each table before the
+    /// join runs - the network counterpart of `innerJoin`'s
+    /// `leftPred`/`rightPred` parameters. `offset`/`limit` window the
+    /// already-joined result server-side (0/0 = unlimited), the same
+    /// convention `tableSelect` uses, via `join.applyPage`. Returned pairs
+    /// are independently owned - free with `protocol.freeJoinPairs`.
+    pub fn tableJoin(
+        self: *Client,
+        allocator: Allocator,
+        mode: protocol.JoinMode,
+        leftTable: []const u8,
+        leftField: []const u8,
+        rightTable: []const u8,
+        rightField: []const u8,
+        offset: u32,
+        limit: u32,
+        leftExprText: []const u8,
+        rightExprText: []const u8,
+    ) ![]protocol.JoinPair {
+        const payload = try protocol.encodeTableJoin(self.allocator, mode, leftTable, leftField, rightTable, rightField, offset, limit, leftExprText, rightExprText);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_join, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeJoinedRows(allocator, frame.payload);
+    }
+
+    /// Remote `table aggregate <table> * <specs> [expr...]` (no `GROUP BY`):
+    /// the wire counterpart of the CLI's local `table aggregate` with a `*`
+    /// group field, calling `aggregate.runGlobal` server-side over rows
+    /// filtered by `exprText` (same `expr.zig` grammar, empty selects every
+    /// row, as `tableSelect`). `havingText` (empty = no HAVING) filters the
+    /// single result server-side via `aggregate.globalMatchesHaving` -
+    /// returns zero values (not an error) when it excludes the only row.
+    /// Otherwise always returns exactly `specs.len` values in the same order
+    /// as `specs` - free with `protocol.freeAggValues`.
+    pub fn tableAggregateGlobal(self: *Client, allocator: Allocator, table: []const u8, specs: []const aggregatemod.AggSpec, havingText: []const u8, exprText: []const u8) ![]rowmod.Value {
+        const payload = try protocol.encodeTableAggregate(self.allocator, table, "", specs, 0, 0, &.{}, havingText, exprText);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_aggregate, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeAggGlobalResult(allocator, frame.payload);
+    }
+
+    /// Remote `table aggregate <table> <groupField> <specs> [expr...]
+    /// [having <expr>] [--limit N] [--offset N]`: the wire counterpart of
+    /// the CLI's local `table aggregate` with a real GROUP BY field, calling
+    /// `aggregate.run` server-side, then (when `havingText` is non-empty)
+    /// `aggregate.filterHaving` to narrow the groups, then windowing what
+    /// remains server-side with `aggregate.applyPageGroups` (0/0 =
+    /// unlimited, the same convention `tableJoin`'s `offset`/`limit` use -
+    /// HAVING always runs before the window, same as SQL). `orderBy`
+    /// (possibly empty) sorts the HAVING-narrowed groups server-side via
+    /// `aggregate.sortGroupsBy` before that window, the same
+    /// HAVING-then-ORDER-BY-then-LIMIT clause order SQL evaluates - each
+    /// `orderBy[i].field` must name either `groupField` or one of `specs`'
+    /// result labels (see `aggregate.specLabel`). One `GroupRow` per
+    /// distinct group value kept by HAVING and the window, in `orderBy`
+    /// order when non-empty, otherwise first-seen order (not sorted), same
+    /// as the local library call - free with `protocol.freeAggGroupRows`.
+    pub fn tableAggregateGroups(self: *Client, allocator: Allocator, table: []const u8, groupField: []const u8, specs: []const aggregatemod.AggSpec, offset: u32, limit: u32, orderBy: []const querymod.OrderBy, havingText: []const u8, exprText: []const u8) ![]aggregatemod.GroupRow {
+        const payload = try protocol.encodeTableAggregate(self.allocator, table, groupField, specs, offset, limit, orderBy, havingText, exprText);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_aggregate, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeAggGroupRows(allocator, frame.payload);
+    }
+
+    /// Remote `table window <table> <kind[:field]> [expr...] [partition
+    /// <field>[,field...]] [order <field[:desc]>[,field...]] [--limit N]
+    /// [--offset N]`: the wire counterpart of the CLI's local `table
+    /// window`, calling `window.compute` server-side over rows filtered by
+    /// `exprText` (same `expr.zig` grammar, empty selects every row).
+    /// Unlike `tableAggregateGroups`, this never collapses rows - every
+    /// matching row keeps its own `protocol.WindowRow` - but `offset`/`limit`
+    /// still window WHICH rows come back, walked in the same
+    /// partition-then-order display sequence `window.orderedIndices`
+    /// produces server-side (0/0 means unlimited, same convention as every
+    /// other paginated opcode). Returns one `WindowRow` per surviving row, in
+    /// that display order - free with `protocol.freeWindowRows`.
+    pub fn tableWindow(self: *Client, allocator: Allocator, table: []const u8, specs: []const windowmod.WindowSpec, partitionBy: []const []const u8, orderBy: []const querymod.OrderBy, offset: u32, limit: u32, exprText: []const u8, windowFrame: windowmod.FrameMode) ![]protocol.WindowRow {
+        const payload = try protocol.encodeTableWindow(self.allocator, table, specs, partitionBy, orderBy, offset, limit, exprText, windowFrame);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.table_window, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeWindowRows(allocator, frame.payload);
+    }
+
+    /// Remote `subscribe <channel>[,channel...]`: registers this connection
+    /// with the server's `pubsub.Hub` and blocks until the server's ack
+    /// frame comes back, so a `publish` issued on a different connection
+    /// right after this returns is guaranteed to reach this subscription -
+    /// see `server.zig`'s `handleSubscribe` doc comment for why the ack
+    /// exists at all. After this call, `self` must only ever be used with
+    /// `nextMessage` - the server never answers another request opcode on
+    /// this same connection again (a real, documented protocol
+    /// simplification, not an oversight: see `handleSubscribe`'s doc
+    /// comment on why a subscribed connection is receive-only). Returns the
+    /// `pubsub.Hub`-assigned subscriber id, the only handle a later
+    /// `unsubscribe` call - necessarily made through a DIFFERENT `Client`,
+    /// since this one can never send another request - can use to name this
+    /// subscription.
+    pub fn subscribe(self: *Client, channels: []const []const u8) !u64 {
+        const payload = try protocol.encodeSubscribe(self.allocator, channels);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.subscribe, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        const ack = try protocol.decodeSubscribeAck(frame.payload);
+        return ack.subscriberId;
+    }
+
+    /// Remote `unsubscribe <subscriber-id> <channel>[,channel...]`: the
+    /// client-side counterpart of `server.zig`'s `unsubscribe` opcode. Sent
+    /// over an ordinary connection (this one may be reused for other
+    /// requests afterward, unlike the subscribe connection it targets) to
+    /// drop a subset of `subscriberId`'s channels - or, if it names every
+    /// channel that subscriber still has left, to end it outright (see
+    /// `pubsub.Hub.unsubscribe`'s doc comment). Returns how many of
+    /// `channels` were actually removed.
+    pub fn unsubscribe(self: *Client, subscriberId: u64, channels: []const []const u8) !u32 {
+        const payload = try protocol.encodeUnsubscribe(self.allocator, subscriberId, channels);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.unsubscribe, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeUnsubscribeResult(frame.payload);
+    }
+
+    /// Reads the next pushed message on a connection that already called
+    /// `subscribe`, or `null` once the server closes the connection (the
+    /// same "no more frames coming" signal `roundTrip` treats as an error
+    /// everywhere else, but is the routine end of a subscription here).
+    /// Blocks indefinitely otherwise - there is no polling variant, exactly
+    /// like `Subscriber.waitMessage` server-side. Returns an independently
+    /// owned `protocol.PubSubMessage` - free with its own `deinit`.
+    pub fn nextMessage(self: *Client, allocator: Allocator) !?protocol.PubSubMessage {
+        var frame = protocol.readFrame(self.allocator, self.stream.reader()) catch |err| switch (err) {
+            error.EndOfStream => return null,
+            else => return err,
+        };
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return try protocol.decodePubSubMessage(allocator, frame.payload);
+    }
+
+    /// Remote `publish <channel> <message>`: delivers `message` to every
+    /// subscriber currently registered on `channel` across every connection
+    /// the server has, returning how many subscribers it reached (0 is a
+    /// normal outcome for a channel nobody is listening to, not an error -
+    /// see `pubsub.Hub.publish`'s doc comment). Any connection may publish,
+    /// whether or not it has ever subscribed to anything itself.
+    pub fn publish(self: *Client, channel: []const u8, message: []const u8) !u64 {
+        const payload = try protocol.encodePublish(self.allocator, channel, message);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.publish, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodePublishResult(frame.payload);
+    }
+
+    /// Remote `txn <script>`: applies every entry in `entries` as one atomic
+    /// `Transaction` commit across however many tables they touch - the wire
+    /// counterpart of the CLI's local `txn <script-file>` (main.zig's
+    /// `runTxn`). Returns the number of operations committed, always
+    /// `entries.len` on success since a partial commit is impossible; a
+    /// conflicting transaction surfaces as `error.ServerConflict` with
+    /// nothing applied, matching `error.Conflict` from a local `Transaction.
+    /// commit()`.
+    pub fn txnOp(self: *Client, entries: []const protocol.TxnOpEntry) !u32 {
+        const payload = try protocol.encodeTxnOp(self.allocator, entries);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.txn_op, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTxnResult(frame.payload);
+    }
+
+    fn userAdminRoundTrip(self: *Client, action: protocol.UserAdminAction, username: []const u8, password: []const u8, role: authmod.Role, rounds: u32) !protocol.Frame {
+        const payload = try protocol.encodeUserAdmin(self.allocator, action, username, password, role, rounds);
+        defer self.allocator.free(payload);
+        return self.roundTrip(.user_admin, payload);
+    }
+
+    /// The wire counterpart of `auth.Store.createUser`, gated server-side
+    /// behind `admin` role whenever the server has auth enabled (see
+    /// `server.zig`'s `requiredRole`). `rounds` of 0 asks the server to use
+    /// its own `auth.recommendedRounds` default.
+    pub fn adminCreateUser(self: *Client, username: []const u8, password: []const u8, role: authmod.Role, rounds: u32) !void {
+        var frame = try self.userAdminRoundTrip(.create, username, password, role, rounds);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `auth.Store.setPassword`. Reports
+    /// `error.ServerUserNotFound` (not the generic `UnexpectedStatus`) when
+    /// the account does not exist, since that is a normal, expected outcome
+    /// worth distinguishing from every other non-ok status.
+    pub fn adminSetPassword(self: *Client, username: []const u8, password: []const u8, rounds: u32) !void {
+        var frame = try self.userAdminRoundTrip(.set_password, username, password, .readonly, rounds);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status == .not_found) return error.ServerUserNotFound;
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `auth.Store.setRole`.
+    pub fn adminSetRole(self: *Client, username: []const u8, role: authmod.Role) !void {
+        var frame = try self.userAdminRoundTrip(.set_role, username, "", role, 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status == .not_found) return error.ServerUserNotFound;
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `auth.Store.deleteUser`.
+    pub fn adminDeleteUser(self: *Client, username: []const u8) !void {
+        var frame = try self.userAdminRoundTrip(.delete, username, "", .readonly, 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status == .not_found) return error.ServerUserNotFound;
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `auth.Store.listUsers`. Returned entries are
+    /// independently owned - free with `authmod.freeUserList`.
+    pub fn adminListUsers(self: *Client, allocator: Allocator) ![]authmod.UserInfo {
+        var frame = try self.userAdminRoundTrip(.list, "", "", .readonly, 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeUserList(allocator, frame.payload);
+    }
+
+    fn ttlOpRoundTrip(self: *Client, action: protocol.TtlAction, key: []const u8, seconds: u64) !protocol.Frame {
+        const payload = try protocol.encodeTtlOp(self.allocator, action, key, seconds);
+        defer self.allocator.free(payload);
+        return self.roundTrip(.ttl_op, payload);
+    }
+
+    /// The wire counterpart of `ttl.setExpireSeconds`, gated server-side the
+    /// same way the CLI's local `expire` is: `error.ServerKeyNotFound` (not
+    /// the generic `UnexpectedStatus`) when `key` does not currently exist,
+    /// since that is a normal, expected outcome worth distinguishing from
+    /// every other non-ok status - matching `adminSetPassword`'s treatment
+    /// of an unknown username.
+    pub fn ttlExpire(self: *Client, key: []const u8, seconds: u64) !void {
+        var frame = try self.ttlOpRoundTrip(.expire, key, seconds);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status == .not_found) return error.ServerKeyNotFound;
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `ttl.clearExpire`.
+    pub fn ttlPersist(self: *Client, key: []const u8) !void {
+        var frame = try self.ttlOpRoundTrip(.persist, key, 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `ttl.remaining`.
+    pub fn ttlQuery(self: *Client, key: []const u8) !ttlmod.TtlResult {
+        var frame = try self.ttlOpRoundTrip(.query, key, 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTtlResult(frame.payload);
+    }
+
+    /// The wire counterpart of `ttl.sweepExpired`: reaps every due key on
+    /// the server and reports how many were removed.
+    pub fn ttlSweep(self: *Client) !u64 {
+        var frame = try self.ttlOpRoundTrip(.sweep, "", 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTtlSweepCount(frame.payload);
+    }
+
+    fn collTtlOpRoundTrip(self: *Client, action: protocol.TtlAction, kind: collmod.Kind, name: []const u8, seconds: u64) !protocol.Frame {
+        const payload = try protocol.encodeCollTtlOp(self.allocator, action, kind, name, seconds);
+        defer self.allocator.free(payload);
+        return self.roundTrip(.coll_ttl_op, payload);
+    }
+
+    /// The wire counterpart of `collttl.setExpireSeconds`, gated server-side
+    /// the same way the CLI's local `coll <kind> expire` is:
+    /// `error.ServerCollectionNotFound` (not the generic `UnexpectedStatus`)
+    /// when the collection does not currently exist, matching `ttlExpire`'s
+    /// treatment of an unknown flat key.
+    pub fn collTtlExpire(self: *Client, kind: collmod.Kind, name: []const u8, seconds: u64) !void {
+        var frame = try self.collTtlOpRoundTrip(.expire, kind, name, seconds);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status == .not_found) return error.ServerCollectionNotFound;
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `collttl.clearExpire`.
+    pub fn collTtlPersist(self: *Client, kind: collmod.Kind, name: []const u8) !void {
+        var frame = try self.collTtlOpRoundTrip(.persist, kind, name, 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+    }
+
+    /// The wire counterpart of `collttl.remaining`.
+    pub fn collTtlQuery(self: *Client, kind: collmod.Kind, name: []const u8) !ttlmod.TtlResult {
+        var frame = try self.collTtlOpRoundTrip(.query, kind, name, 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTtlResult(frame.payload);
+    }
+
+    /// The wire counterpart of `collttl.sweepExpired`: reaps every due
+    /// collection of every kind on the server and reports how many were
+    /// removed. The `kind` argument to `collTtlOpRoundTrip` is a
+    /// placeholder here (see `protocol.encodeCollTtlOp`'s doc comment) -
+    /// `.counter` is chosen arbitrarily, same convention as `ttlSweep`
+    /// passing an empty key.
+    pub fn collTtlSweep(self: *Client) !u64 {
+        var frame = try self.collTtlOpRoundTrip(.sweep, .counter, "", 0);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeTtlSweepCount(frame.payload);
+    }
+
+    /// The wire counterpart of `main.zig`'s local `coll <kind> <op> ...`
+    /// (backed by `collections.zig`) - one generic round trip for every
+    /// `protocol.CollAction`, mirroring that opcode's own "one opcode, many
+    /// actions" shape rather than exposing thirty near-identical wrapper
+    /// methods here. `args` are the same CLI-text-form string arguments
+    /// (values/members/indices/scores) `runColl` already parses locally, so
+    /// the server decodes exactly the same numbers with exactly the same
+    /// `std.fmt.parseInt`/`parseFloat` calls the local command uses. Unlike
+    /// `collTtlExpire`, a missing hash field/list element/zset member is not
+    /// an error here - it comes back as `OwnedCollReply.nil`, exactly like
+    /// the local CLI prints `(nil)` rather than failing. Returned reply is
+    /// independently owned; free with `reply.deinit(allocator)`.
+    pub fn collOp(self: *Client, allocator: Allocator, action: protocol.CollAction, name: []const u8, args: []const []const u8) !protocol.OwnedCollReply {
+        const payload = try protocol.encodeCollOp(self.allocator, action, name, args);
+        defer self.allocator.free(payload);
+        var frame = try self.roundTrip(.coll_op, payload);
+        defer frame.deinit();
+        const status = try protocol.Status.fromByte(frame.tag);
+        if (status != .ok) return statusToError(status);
+        return protocol.decodeCollReply(allocator, frame.payload);
+    }
+};
+
+test "statusToError maps every non-ok status to a distinct error" {
+    try std.testing.expectEqual(error.ServerBadRequest, statusToError(.bad_request));
+    try std.testing.expectEqual(error.ServerInternal, statusToError(.internal));
+    try std.testing.expectEqual(error.ServerConflict, statusToError(.conflict));
+    try std.testing.expectEqual(error.ServerRateLimited, statusToError(.rate_limited));
+    try std.testing.expectEqual(error.ServerUnauthorized, statusToError(.unauthorized));
+    try std.testing.expectEqual(error.ServerForbidden, statusToError(.forbidden));
+    try std.testing.expectEqual(error.UnexpectedStatus, statusToError(.not_found));
+}
diff --git a/src/collections.zig b/src/collections.zig
new file mode 100644
index 0000000..c3cfc52
--- /dev/null
+++ b/src/collections.zig
@@ -0,0 +1,1423 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+const row = @import("row.zig");
+const txnmod = @import("txn.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Transaction = txnmod.Transaction;
+
+/// Redis-like typed collections layered over the flat KV keyspace, sharing
+/// one Db with tables/indexes (row.zig/index.zig use tags 'R'/'I'/'M'; every
+/// key here starts with 'X' so the two namespaces never collide):
+///   "X" "C\0" name                         -> raw i64 (counter)
+///   "X" "H\0" name "\0" field               -> raw bytes (hash field)
+///   "X" "S\0" name "\0" member               -> empty marker (set member)
+///   "X" "L\0" name "\0M"                    -> raw {headSeq i64, tailSeq i64} (list meta)
+///   "X" "L\0" name "\0E\0" orderedInt(seq)  -> raw bytes (list element)
+///   "X" "Z\0" name "\0M\0" member            -> raw f64 (zset member -> score)
+///   "X" "Z\0" name "\0S\0" orderedFloat(score) orderedText(member) -> empty marker (zset score index)
+pub const nsTag: u8 = 'X';
+const sep: u8 = 0x00;
+const maxConflictRetries: usize = 64;
+
+fn appendSegment(out: *std.ArrayList(u8), segment: []const u8) !void {
+    try out.appendSlice(segment);
+    try out.append(sep);
+}
+
+fn putI64(out: *std.ArrayList(u8), v: i64) !void {
+    var b: [8]u8 = undefined;
+    std.mem.writeInt(i64, &b, v, .big);
+    try out.appendSlice(&b);
+}
+
+fn readI64(data: []const u8) !i64 {
+    if (data.len != 8) return error.Malformed;
+    return std.mem.readInt(i64, data[0..8], .big);
+}
+
+fn putF64(out: *std.ArrayList(u8), v: f64) !void {
+    var b: [8]u8 = undefined;
+    std.mem.writeInt(u64, &b, @bitCast(v), .big);
+    try out.appendSlice(&b);
+}
+
+fn readF64(data: []const u8) !f64 {
+    if (data.len != 8) return error.Malformed;
+    return @bitCast(std.mem.readInt(u64, data[0..8], .big));
+}
+
+/// Every atomic collection mutator below retries up to `maxConflictRetries`
+/// times on error.Conflict, re-reading current state fresh through `txn.get`
+/// on each attempt rather than replaying a stale value. `error.TooManyConflicts`
+/// is returned only if the retry budget is exhausted.
+/// Identifies which typed collection a name belongs to - used by collttl.zig
+/// to expire a WHOLE collection (every physical key under its namespace),
+/// since unlike a flat key a collection has no single Db key of its own
+/// (except Counter, see `exists`/`drop` below).
+pub const Kind = enum {
+    counter,
+    hash,
+    set,
+    list,
+    zset,
+
+    pub fn parse(s: []const u8) ?Kind {
+        if (std.mem.eql(u8, s, "counter")) return .counter;
+        if (std.mem.eql(u8, s, "hash")) return .hash;
+        if (std.mem.eql(u8, s, "set")) return .set;
+        if (std.mem.eql(u8, s, "list")) return .list;
+        if (std.mem.eql(u8, s, "zset")) return .zset;
+        return null;
+    }
+
+    pub fn label(self: Kind) []const u8 {
+        return switch (self) {
+            .counter => "counter",
+            .hash => "hash",
+            .set => "set",
+            .list => "list",
+            .zset => "zset",
+        };
+    }
+
+    pub fn tagByte(self: Kind) u8 {
+        return switch (self) {
+            .counter => 'C',
+            .hash => 'H',
+            .set => 'S',
+            .list => 'L',
+            .zset => 'Z',
+        };
+    }
+
+    /// Inverse of `tagByte`, null on any other byte. Used to decode a
+    /// `Kind` back out of a wire payload (`protocol.zig`'s `coll_ttl_op`)
+    /// or a marker key (`collttl.zig`'s `sweepExpired`), which previously
+    /// duplicated this exact switch inline.
+    pub fn fromTagByte(b: u8) ?Kind {
+        return switch (b) {
+            'C' => .counter,
+            'H' => .hash,
+            'S' => .set,
+            'L' => .list,
+            'Z' => .zset,
+            else => null,
+        };
+    }
+};
+
+/// Prefix common to every physical key a Hash/Set/List/ZSet named `name`
+/// owns - each of those four kinds always segments as
+/// nsTag+kindTag+sep+name+sep+<rest>, so this single prefix reaches every
+/// field/member/element/score-entry at once. Counter is the one kind NOT
+/// covered here: its single key has no trailing separator after `name`
+/// (see Counter.key), so a same-named counter is handled separately in
+/// `exists`/`drop` below rather than through a prefix scan.
+fn genericPrefix(allocator: Allocator, k: Kind, name: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(nsTag);
+    try appendSegment(&out, &[_]u8{k.tagByte()});
+    try appendSegment(&out, name);
+    return out.toOwnedSlice();
+}
+
+/// True if `name` currently has any physical presence under `k`'s namespace.
+/// A counter counts as existing once `set`/`incrBy` has stored a value for
+/// it, even 0 - that stored 0 is real data, not the "absent" default
+/// Counter.get returns for a name nothing ever touched.
+pub fn collectionExists(db: *Db, allocator: Allocator, k: Kind, name: []const u8) !bool {
+    if (k == .counter) {
+        const ck = try Counter.key(allocator, name);
+        defer allocator.free(ck);
+        const raw = try db.get(allocator, ck) orelse return false;
+        allocator.free(raw);
+        return true;
+    }
+    const p = try genericPrefix(allocator, k, name);
+    defer allocator.free(p);
+    var it = try db.scanPrefix(allocator, p);
+    defer it.deinit();
+    return (try it.next()) != null;
+}
+
+/// Deletes every physical key belonging to `name` under `k`'s namespace -
+/// every field of a hash, the meta record and every element of a list, both
+/// the member row and score-index row of every zset entry. Returns the
+/// count of physical keys removed. This is what makes a collection-level
+/// TTL (collttl.zig) actually mean something: expiring a collection has to
+/// remove ALL of it, not just one key the way ttl.zig's flat-key expiry does.
+pub fn dropCollection(db: *Db, allocator: Allocator, k: Kind, name: []const u8) !usize {
+    if (k == .counter) {
+        const ck = try Counter.key(allocator, name);
+        defer allocator.free(ck);
+        const raw = try db.get(allocator, ck) orelse return 0;
+        allocator.free(raw);
+        try db.delete(ck);
+        return 1;
+    }
+
+    const p = try genericPrefix(allocator, k, name);
+    defer allocator.free(p);
+
+    var keys = std.ArrayList([]u8).init(allocator);
+    defer {
+        for (keys.items) |kk| allocator.free(kk);
+        keys.deinit();
+    }
+    {
+        // Collect first, delete after: db.delete mid-scan would mutate the
+        // memtable structure a live RangeIterator's cursors are threaded
+        // through (same reasoning as ttl.zig's sweepExpired).
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+        while (try it.next()) |entry| {
+            try keys.append(try allocator.dupe(u8, entry.key));
+        }
+    }
+    for (keys.items) |kk| try db.delete(kk);
+    return keys.items.len;
+}
+
+fn prefixUpperBound(allocator: Allocator, prefix: []const u8) !?[]u8 {
+    var end = prefix.len;
+    while (end > 0 and prefix[end - 1] == 0xff) end -= 1;
+    if (end == 0) return null;
+    const upper = try allocator.alloc(u8, end);
+    @memcpy(upper, prefix[0..end]);
+    upper[end - 1] += 1;
+    return upper;
+}
+
+// ---------------------------------------------------------------------
+// Counter
+// ---------------------------------------------------------------------
+
+pub const Counter = struct {
+    fn key(allocator: Allocator, name: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "C");
+        try out.appendSlice(name);
+        return out.toOwnedSlice();
+    }
+
+    pub fn get(db: *Db, allocator: Allocator, name: []const u8) !i64 {
+        const k = try key(allocator, name);
+        defer allocator.free(k);
+        const raw = try db.get(allocator, k) orelse return 0;
+        defer allocator.free(raw);
+        return readI64(raw);
+    }
+
+    pub fn set(db: *Db, allocator: Allocator, name: []const u8, value: i64) !void {
+        const k = try key(allocator, name);
+        defer allocator.free(k);
+        var out = std.ArrayList(u8).init(allocator);
+        defer out.deinit();
+        try putI64(&out, value);
+        try db.put(k, out.items);
+    }
+
+    /// Atomically adds `delta` to the counter (creating it at 0 if absent)
+    /// and returns the new value. Uses an OCC transaction so concurrent
+    /// increments never lose an update to a lost read-modify-write race.
+    pub fn incrBy(db: *Db, allocator: Allocator, name: []const u8, delta: i64) !i64 {
+        const k = try key(allocator, name);
+        defer allocator.free(k);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            const current: i64 = blk: {
+                const raw = try txn.get(allocator, k) orelse break :blk 0;
+                defer allocator.free(raw);
+                break :blk try readI64(raw);
+            };
+            const next = current + delta;
+
+            var out = std.ArrayList(u8).init(allocator);
+            defer out.deinit();
+            try putI64(&out, next);
+            try txn.put(k, out.items);
+
+            txn.commit() catch |err| {
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return next;
+        }
+        return error.TooManyConflicts;
+    }
+};
+
+// ---------------------------------------------------------------------
+// Hash
+// ---------------------------------------------------------------------
+
+pub const HashField = struct {
+    field: []u8,
+    value: []u8,
+
+    pub fn free(self: HashField, allocator: Allocator) void {
+        allocator.free(self.field);
+        allocator.free(self.value);
+    }
+};
+
+pub const Hash = struct {
+    fn prefix(allocator: Allocator, name: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "H");
+        try appendSegment(&out, name);
+        return out.toOwnedSlice();
+    }
+
+    fn fieldKey(allocator: Allocator, name: []const u8, field: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "H");
+        try appendSegment(&out, name);
+        try out.appendSlice(field);
+        return out.toOwnedSlice();
+    }
+
+    /// Sets a field, returning true if the field was newly created.
+    pub fn set(db: *Db, allocator: Allocator, name: []const u8, field: []const u8, value: []const u8) !bool {
+        const k = try fieldKey(allocator, name, field);
+        defer allocator.free(k);
+        const existing = try db.get(allocator, k);
+        if (existing) |raw| allocator.free(raw);
+        try db.put(k, value);
+        return existing == null;
+    }
+
+    pub fn get(db: *Db, allocator: Allocator, name: []const u8, field: []const u8) !?[]u8 {
+        const k = try fieldKey(allocator, name, field);
+        defer allocator.free(k);
+        return db.get(allocator, k);
+    }
+
+    pub fn exists(db: *Db, allocator: Allocator, name: []const u8, field: []const u8) !bool {
+        const raw = try get(db, allocator, name, field) orelse return false;
+        allocator.free(raw);
+        return true;
+    }
+
+    /// Deletes a field, returning true if it existed.
+    pub fn del(db: *Db, allocator: Allocator, name: []const u8, field: []const u8) !bool {
+        const existed = try exists(db, allocator, name, field);
+        if (!existed) return false;
+        const k = try fieldKey(allocator, name, field);
+        defer allocator.free(k);
+        try db.delete(k);
+        return true;
+    }
+
+    pub fn len(db: *Db, allocator: Allocator, name: []const u8) !usize {
+        const p = try prefix(allocator, name);
+        defer allocator.free(p);
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+        var count: usize = 0;
+        while (try it.next()) |_| count += 1;
+        return count;
+    }
+
+    /// Returns every field/value pair currently stored under `name`. Caller
+    /// owns the returned slice and each entry's `field`/`value` buffers.
+    pub fn getAll(db: *Db, allocator: Allocator, name: []const u8) ![]HashField {
+        const p = try prefix(allocator, name);
+        defer allocator.free(p);
+
+        var results = std.ArrayList(HashField).init(allocator);
+        errdefer {
+            for (results.items) |f| f.free(allocator);
+            results.deinit();
+        }
+
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+        while (try it.next()) |entry| {
+            const field = try allocator.dupe(u8, entry.key[p.len..]);
+            errdefer allocator.free(field);
+            const value = try allocator.dupe(u8, entry.value);
+            try results.append(.{ .field = field, .value = value });
+        }
+        return results.toOwnedSlice();
+    }
+};
+
+// ---------------------------------------------------------------------
+// Set
+// ---------------------------------------------------------------------
+
+pub const Set = struct {
+    fn prefix(allocator: Allocator, name: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "S");
+        try appendSegment(&out, name);
+        return out.toOwnedSlice();
+    }
+
+    fn memberKey(allocator: Allocator, name: []const u8, member: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "S");
+        try appendSegment(&out, name);
+        try out.appendSlice(member);
+        return out.toOwnedSlice();
+    }
+
+    /// Returns true if the member was newly added (false if already present).
+    pub fn add(db: *Db, allocator: Allocator, name: []const u8, member: []const u8) !bool {
+        if (try isMember(db, allocator, name, member)) return false;
+        const k = try memberKey(allocator, name, member);
+        defer allocator.free(k);
+        try db.put(k, &.{});
+        return true;
+    }
+
+    /// Returns true if the member was present and has been removed.
+    pub fn remove(db: *Db, allocator: Allocator, name: []const u8, member: []const u8) !bool {
+        if (!try isMember(db, allocator, name, member)) return false;
+        const k = try memberKey(allocator, name, member);
+        defer allocator.free(k);
+        try db.delete(k);
+        return true;
+    }
+
+    pub fn isMember(db: *Db, allocator: Allocator, name: []const u8, member: []const u8) !bool {
+        const k = try memberKey(allocator, name, member);
+        defer allocator.free(k);
+        const raw = try db.get(allocator, k) orelse return false;
+        allocator.free(raw);
+        return true;
+    }
+
+    pub fn card(db: *Db, allocator: Allocator, name: []const u8) !usize {
+        const members_ = try members(db, allocator, name);
+        defer {
+            for (members_) |m| allocator.free(m);
+            allocator.free(members_);
+        }
+        return members_.len;
+    }
+
+    /// Returns every member currently in the set. Caller owns the slice and
+    /// each element.
+    pub fn members(db: *Db, allocator: Allocator, name: []const u8) ![][]u8 {
+        const p = try prefix(allocator, name);
+        defer allocator.free(p);
+
+        var results = std.ArrayList([]u8).init(allocator);
+        errdefer {
+            for (results.items) |m| allocator.free(m);
+            results.deinit();
+        }
+
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+        while (try it.next()) |entry| {
+            try results.append(try allocator.dupe(u8, entry.key[p.len..]));
+        }
+        return results.toOwnedSlice();
+    }
+
+    fn containsSorted(haystack: [][]const u8, needle: []const u8) bool {
+        for (haystack) |h| {
+            if (std.mem.eql(u8, h, needle)) return true;
+        }
+        return false;
+    }
+
+    /// Members present in every one of `names`. Caller owns the result.
+    pub fn intersect(db: *Db, allocator: Allocator, names: []const []const u8) ![][]u8 {
+        var results = std.ArrayList([]u8).init(allocator);
+        errdefer {
+            for (results.items) |m| allocator.free(m);
+            results.deinit();
+        }
+        if (names.len == 0) return results.toOwnedSlice();
+
+        const first = try members(db, allocator, names[0]);
+        defer {
+            for (first) |m| allocator.free(m);
+            allocator.free(first);
+        }
+
+        outer: for (first) |candidate| {
+            for (names[1..]) |other| {
+                if (!try isMember(db, allocator, other, candidate)) continue :outer;
+            }
+            try results.append(try allocator.dupe(u8, candidate));
+        }
+        return results.toOwnedSlice();
+    }
+
+    /// Members present in any of `names`, deduplicated. Caller owns the result.
+    pub fn unionOf(db: *Db, allocator: Allocator, names: []const []const u8) ![][]u8 {
+        var results = std.ArrayList([]u8).init(allocator);
+        errdefer {
+            for (results.items) |m| allocator.free(m);
+            results.deinit();
+        }
+
+        for (names) |name| {
+            const ms = try members(db, allocator, name);
+            defer {
+                for (ms) |m| allocator.free(m);
+                allocator.free(ms);
+            }
+            for (ms) |m| {
+                var seen = false;
+                for (results.items) |existing| {
+                    if (std.mem.eql(u8, existing, m)) {
+                        seen = true;
+                        break;
+                    }
+                }
+                if (!seen) try results.append(try allocator.dupe(u8, m));
+            }
+        }
+        return results.toOwnedSlice();
+    }
+
+    /// Members in `name` that are not in any set of `others`. Caller owns the result.
+    pub fn difference(db: *Db, allocator: Allocator, name: []const u8, others: []const []const u8) ![][]u8 {
+        var results = std.ArrayList([]u8).init(allocator);
+        errdefer {
+            for (results.items) |m| allocator.free(m);
+            results.deinit();
+        }
+
+        const base = try members(db, allocator, name);
+        defer {
+            for (base) |m| allocator.free(m);
+            allocator.free(base);
+        }
+
+        outer: for (base) |candidate| {
+            for (others) |other| {
+                if (try isMember(db, allocator, other, candidate)) continue :outer;
+            }
+            try results.append(try allocator.dupe(u8, candidate));
+        }
+        return results.toOwnedSlice();
+    }
+};
+
+// ---------------------------------------------------------------------
+// List (double-ended queue keyed by a monotonic sequence range)
+// ---------------------------------------------------------------------
+
+const ListMeta = struct {
+    // Elements occupy sequence numbers (head+1 .. tail-1) inclusive; an
+    // empty list has tail == head + 1. Pushing left decrements head and
+    // writes at the new head; pushing right increments tail and writes at
+    // the slot just below the new tail.
+    head: i64,
+    tail: i64,
+};
+
+pub const List = struct {
+    fn metaKey(allocator: Allocator, name: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "L");
+        try appendSegment(&out, name);
+        try out.append('M');
+        return out.toOwnedSlice();
+    }
+
+    fn elementPrefix(allocator: Allocator, name: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "L");
+        try appendSegment(&out, name);
+        try appendSegment(&out, "E");
+        return out.toOwnedSlice();
+    }
+
+    fn elementKey(allocator: Allocator, name: []const u8, seq: i64) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "L");
+        try appendSegment(&out, name);
+        try appendSegment(&out, "E");
+        try row.appendOrdered(&out, .{ .int = seq });
+        return out.toOwnedSlice();
+    }
+
+    fn readMeta(txn: *Transaction, allocator: Allocator, k: []const u8) !ListMeta {
+        const raw = try txn.get(allocator, k) orelse return ListMeta{ .head = 0, .tail = 1 };
+        defer allocator.free(raw);
+        if (raw.len != 16) return error.Malformed;
+        return .{
+            .head = std.mem.readInt(i64, raw[0..8], .big),
+            .tail = std.mem.readInt(i64, raw[8..16], .big),
+        };
+    }
+
+    fn writeMeta(txn: *Transaction, k: []const u8, meta: ListMeta) !void {
+        var buf: [16]u8 = undefined;
+        std.mem.writeInt(i64, buf[0..8], meta.head, .big);
+        std.mem.writeInt(i64, buf[8..16], meta.tail, .big);
+        try txn.put(k, &buf);
+    }
+
+    pub fn pushLeft(db: *Db, allocator: Allocator, name: []const u8, value: []const u8) !void {
+        const mk = try metaKey(allocator, name);
+        defer allocator.free(mk);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            var meta = try readMeta(&txn, allocator, mk);
+            const seq = meta.head;
+            meta.head -= 1;
+
+            const ek = try elementKey(allocator, name, seq);
+            defer allocator.free(ek);
+            try txn.put(ek, value);
+            try writeMeta(&txn, mk, meta);
+
+            txn.commit() catch |err| {
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return;
+        }
+        return error.TooManyConflicts;
+    }
+
+    pub fn pushRight(db: *Db, allocator: Allocator, name: []const u8, value: []const u8) !void {
+        const mk = try metaKey(allocator, name);
+        defer allocator.free(mk);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            var meta = try readMeta(&txn, allocator, mk);
+            const seq = meta.tail;
+            meta.tail += 1;
+
+            const ek = try elementKey(allocator, name, seq);
+            defer allocator.free(ek);
+            try txn.put(ek, value);
+            try writeMeta(&txn, mk, meta);
+
+            txn.commit() catch |err| {
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return;
+        }
+        return error.TooManyConflicts;
+    }
+
+    pub fn popLeft(db: *Db, allocator: Allocator, name: []const u8) !?[]u8 {
+        const mk = try metaKey(allocator, name);
+        defer allocator.free(mk);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            var meta = try readMeta(&txn, allocator, mk);
+            if (meta.tail - meta.head <= 1) return null;
+            const seq = meta.head + 1;
+            meta.head += 1;
+
+            const ek = try elementKey(allocator, name, seq);
+            defer allocator.free(ek);
+            const value = try txn.get(allocator, ek) orelse return error.Malformed;
+            errdefer allocator.free(value);
+            try txn.delete(ek);
+            try writeMeta(&txn, mk, meta);
+
+            txn.commit() catch |err| {
+                allocator.free(value);
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return value;
+        }
+        return error.TooManyConflicts;
+    }
+
+    pub fn popRight(db: *Db, allocator: Allocator, name: []const u8) !?[]u8 {
+        const mk = try metaKey(allocator, name);
+        defer allocator.free(mk);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            var meta = try readMeta(&txn, allocator, mk);
+            if (meta.tail - meta.head <= 1) return null;
+            const seq = meta.tail - 1;
+            meta.tail -= 1;
+
+            const ek = try elementKey(allocator, name, seq);
+            defer allocator.free(ek);
+            const value = try txn.get(allocator, ek) orelse return error.Malformed;
+            errdefer allocator.free(value);
+            try txn.delete(ek);
+            try writeMeta(&txn, mk, meta);
+
+            txn.commit() catch |err| {
+                allocator.free(value);
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return value;
+        }
+        return error.TooManyConflicts;
+    }
+
+    pub fn len(db: *Db, allocator: Allocator, name: []const u8) !usize {
+        const mk = try metaKey(allocator, name);
+        defer allocator.free(mk);
+        const raw = try db.get(allocator, mk) orelse return 0;
+        defer allocator.free(raw);
+        if (raw.len != 16) return error.Malformed;
+        const head = std.mem.readInt(i64, raw[0..8], .big);
+        const tail = std.mem.readInt(i64, raw[8..16], .big);
+        return @intCast(tail - head - 1);
+    }
+
+    /// Redis-style inclusive range with negative indices counting from the
+    /// end (-1 is the last element). Out-of-range indices are clamped;
+    /// start > stop after clamping yields an empty result. Caller owns the
+    /// returned slice and each element.
+    pub fn range(db: *Db, allocator: Allocator, name: []const u8, start: i64, stop: i64) ![][]u8 {
+        const total: i64 = @intCast(try len(db, allocator, name));
+
+        var results = std.ArrayList([]u8).init(allocator);
+        errdefer {
+            for (results.items) |m| allocator.free(m);
+            results.deinit();
+        }
+        if (total == 0) return results.toOwnedSlice();
+
+        var lo = if (start < 0) total + start else start;
+        var hi = if (stop < 0) total + stop else stop;
+        if (lo < 0) lo = 0;
+        if (hi > total - 1) hi = total - 1;
+        if (lo > hi) return results.toOwnedSlice();
+
+        const p = try elementPrefix(allocator, name);
+        defer allocator.free(p);
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+
+        var idx: i64 = 0;
+        while (try it.next()) |entry| {
+            if (idx >= lo and idx <= hi) {
+                try results.append(try allocator.dupe(u8, entry.value));
+            }
+            idx += 1;
+        }
+        return results.toOwnedSlice();
+    }
+};
+
+// ---------------------------------------------------------------------
+// ZSet (sorted set: member -> score, plus a score-ordered index for
+// range/rank queries)
+// ---------------------------------------------------------------------
+
+pub const ZMember = struct {
+    member: []u8,
+    score: f64,
+
+    pub fn free(self: ZMember, allocator: Allocator) void {
+        allocator.free(self.member);
+    }
+};
+
+pub const ZSet = struct {
+    fn memberKey(allocator: Allocator, name: []const u8, member: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "Z");
+        try appendSegment(&out, name);
+        try appendSegment(&out, "M");
+        try out.appendSlice(member);
+        return out.toOwnedSlice();
+    }
+
+    fn scorePrefix(allocator: Allocator, name: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "Z");
+        try appendSegment(&out, name);
+        try appendSegment(&out, "S");
+        return out.toOwnedSlice();
+    }
+
+    fn scoreEntryKey(allocator: Allocator, name: []const u8, scoreVal: f64, member: []const u8) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "Z");
+        try appendSegment(&out, name);
+        try appendSegment(&out, "S");
+        try row.appendOrdered(&out, .{ .float = scoreVal });
+        try row.appendOrdered(&out, .{ .text = member });
+        return out.toOwnedSlice();
+    }
+
+    /// Score-index key truncated to just the ordered score (no member
+    /// suffix), used as a scan bound. Every real entry is a strict byte
+    /// extension of this (the member part is never empty), so a key equal to
+    /// `scoreBound(s)` never itself denotes a stored member.
+    fn scoreBound(allocator: Allocator, name: []const u8, scoreVal: f64) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try out.append(nsTag);
+        try appendSegment(&out, "Z");
+        try appendSegment(&out, name);
+        try appendSegment(&out, "S");
+        try row.appendOrdered(&out, .{ .float = scoreVal });
+        return out.toOwnedSlice();
+    }
+
+    /// Upserts `member`'s score, atomically re-pointing the score index if
+    /// the member already existed with a different score.
+    pub fn add(db: *Db, allocator: Allocator, name: []const u8, member: []const u8, scoreVal: f64) !void {
+        const mk = try memberKey(allocator, name, member);
+        defer allocator.free(mk);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            const old = try txn.get(allocator, mk);
+            if (old) |raw| {
+                defer allocator.free(raw);
+                const oldScore = try readF64(raw);
+                if (oldScore == scoreVal) return;
+                const oldEntryKey = try scoreEntryKey(allocator, name, oldScore, member);
+                defer allocator.free(oldEntryKey);
+                try txn.delete(oldEntryKey);
+            }
+
+            var scoreBuf = std.ArrayList(u8).init(allocator);
+            defer scoreBuf.deinit();
+            try putF64(&scoreBuf, scoreVal);
+            try txn.put(mk, scoreBuf.items);
+
+            const entryKey = try scoreEntryKey(allocator, name, scoreVal, member);
+            defer allocator.free(entryKey);
+            try txn.put(entryKey, &.{});
+
+            txn.commit() catch |err| {
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return;
+        }
+        return error.TooManyConflicts;
+    }
+
+    pub fn score(db: *Db, allocator: Allocator, name: []const u8, member: []const u8) !?f64 {
+        const mk = try memberKey(allocator, name, member);
+        defer allocator.free(mk);
+        const raw = try db.get(allocator, mk) orelse return null;
+        defer allocator.free(raw);
+        return try readF64(raw);
+    }
+
+    pub fn incrBy(db: *Db, allocator: Allocator, name: []const u8, member: []const u8, delta: f64) !f64 {
+        const mk = try memberKey(allocator, name, member);
+        defer allocator.free(mk);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            const oldRaw = try txn.get(allocator, mk);
+            const oldScore: f64 = if (oldRaw) |raw| blk: {
+                defer allocator.free(raw);
+                break :blk try readF64(raw);
+            } else 0.0;
+            const newScore = oldScore + delta;
+
+            if (oldRaw != null) {
+                const oldEntryKey = try scoreEntryKey(allocator, name, oldScore, member);
+                defer allocator.free(oldEntryKey);
+                try txn.delete(oldEntryKey);
+            }
+
+            var scoreBuf = std.ArrayList(u8).init(allocator);
+            defer scoreBuf.deinit();
+            try putF64(&scoreBuf, newScore);
+            try txn.put(mk, scoreBuf.items);
+
+            const entryKey = try scoreEntryKey(allocator, name, newScore, member);
+            defer allocator.free(entryKey);
+            try txn.put(entryKey, &.{});
+
+            txn.commit() catch |err| {
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return newScore;
+        }
+        return error.TooManyConflicts;
+    }
+
+    /// Returns true if the member was present and has been removed.
+    pub fn remove(db: *Db, allocator: Allocator, name: []const u8, member: []const u8) !bool {
+        const mk = try memberKey(allocator, name, member);
+        defer allocator.free(mk);
+
+        var attempt: usize = 0;
+        while (attempt < maxConflictRetries) : (attempt += 1) {
+            var txn = Transaction.begin(db);
+            defer txn.deinit();
+
+            const raw = try txn.get(allocator, mk) orelse return false;
+            defer allocator.free(raw);
+            const existingScore = try readF64(raw);
+
+            try txn.delete(mk);
+            const entryKey = try scoreEntryKey(allocator, name, existingScore, member);
+            defer allocator.free(entryKey);
+            try txn.delete(entryKey);
+
+            txn.commit() catch |err| {
+                if (err == error.Conflict) continue;
+                return err;
+            };
+            return true;
+        }
+        return error.TooManyConflicts;
+    }
+
+    pub fn card(db: *Db, allocator: Allocator, name: []const u8) !usize {
+        const p = try scorePrefix(allocator, name);
+        defer allocator.free(p);
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+        var count: usize = 0;
+        while (try it.next()) |_| count += 1;
+        return count;
+    }
+
+    fn decodeScoreEntry(allocator: Allocator, name: []const u8, key: []const u8) !ZMember {
+        const p = try scorePrefix(allocator, name);
+        defer allocator.free(p);
+        if (key.len <= p.len or !std.mem.startsWith(u8, key, p)) return error.Malformed;
+        const rest = key[p.len..];
+
+        // rest = [tag u8][8-byte ordered score][tag u8][escaped member][0x00 0x00]
+        if (rest.len < 9 or rest[0] != @intFromEnum(row.ValueTag.float)) return error.Malformed;
+        var bits = std.mem.readInt(u64, rest[1..9], .big);
+        if (bits & 0x8000000000000000 != 0) {
+            bits &= 0x7fffffffffffffff;
+        } else {
+            bits = ~bits;
+        }
+        const decodedScore: f64 = @bitCast(bits);
+
+        const memberPart = rest[9..];
+        if (memberPart.len < 3 or memberPart[0] != @intFromEnum(row.ValueTag.text)) return error.Malformed;
+        var unescaped = std.ArrayList(u8).init(allocator);
+        errdefer unescaped.deinit();
+        var i: usize = 1;
+        while (i < memberPart.len) {
+            if (memberPart[i] == 0x00) {
+                if (i + 1 >= memberPart.len) return error.Malformed;
+                if (memberPart[i + 1] == 0x00) break;
+                if (memberPart[i + 1] == 0xFF) {
+                    try unescaped.append(0x00);
+                    i += 2;
+                    continue;
+                }
+                return error.Malformed;
+            }
+            try unescaped.append(memberPart[i]);
+            i += 1;
+        }
+        return .{ .member = try unescaped.toOwnedSlice(), .score = decodedScore };
+    }
+
+    /// Ascending-by-score range selected by rank (0-based, inclusive on both
+    /// ends), Redis-style: negative indices count from the end. Caller owns
+    /// the returned slice and each member's buffer.
+    pub fn rangeByRank(db: *Db, allocator: Allocator, name: []const u8, start: i64, stop: i64) ![]ZMember {
+        const total: i64 = @intCast(try card(db, allocator, name));
+
+        var results = std.ArrayList(ZMember).init(allocator);
+        errdefer {
+            for (results.items) |m| m.free(allocator);
+            results.deinit();
+        }
+        if (total == 0) return results.toOwnedSlice();
+
+        var lo = if (start < 0) total + start else start;
+        var hi = if (stop < 0) total + stop else stop;
+        if (lo < 0) lo = 0;
+        if (hi > total - 1) hi = total - 1;
+        if (lo > hi) return results.toOwnedSlice();
+
+        const p = try scorePrefix(allocator, name);
+        defer allocator.free(p);
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+
+        var idx: i64 = 0;
+        while (try it.next()) |entry| {
+            if (idx >= lo and idx <= hi) {
+                try results.append(try decodeScoreEntry(allocator, name, entry.key));
+            }
+            idx += 1;
+        }
+        return results.toOwnedSlice();
+    }
+
+    /// All members whose score falls within [min, max], found via a real
+    /// bounded scan over the score index (not a full-collection scan): the
+    /// start bound is `scoreBound(min)` and the end bound is the byte
+    /// immediately after `scoreBound(max)`, which is enough to include every
+    /// entry whose score equals `max` since real entries strictly extend
+    /// their score bound (see `scoreBound`'s doc comment). Caller owns the
+    /// returned slice and each member's buffer.
+    pub fn rangeByScore(db: *Db, allocator: Allocator, name: []const u8, min: f64, max: f64) ![]ZMember {
+        var results = std.ArrayList(ZMember).init(allocator);
+        errdefer {
+            for (results.items) |m| m.free(allocator);
+            results.deinit();
+        }
+
+        const startBound = try scoreBound(allocator, name, min);
+        defer allocator.free(startBound);
+        const maxBound = try scoreBound(allocator, name, max);
+        defer allocator.free(maxBound);
+        const endBound = try prefixUpperBound(allocator, maxBound) orelse try allocator.dupe(u8, maxBound);
+        defer allocator.free(endBound);
+
+        var it = try db.scanRange(allocator, .{
+            .start = startBound,
+            .end = endBound,
+            .startInclusive = true,
+            .endInclusive = false,
+        });
+        defer it.deinit();
+
+        while (try it.next()) |entry| {
+            try results.append(try decodeScoreEntry(allocator, name, entry.key));
+        }
+        return results.toOwnedSlice();
+    }
+
+    /// 0-based ascending-by-score rank of `member`, or null if absent.
+    pub fn rank(db: *Db, allocator: Allocator, name: []const u8, member: []const u8) !?usize {
+        const target = try score(db, allocator, name, member) orelse return null;
+
+        const p = try scorePrefix(allocator, name);
+        defer allocator.free(p);
+        var it = try db.scanPrefix(allocator, p);
+        defer it.deinit();
+
+        var idx: usize = 0;
+        while (try it.next()) |entry| {
+            const decoded = try decodeScoreEntry(allocator, name, entry.key);
+            defer decoded.free(allocator);
+            if (decoded.score == target and std.mem.eql(u8, decoded.member, member)) return idx;
+            idx += 1;
+        }
+        return null;
+    }
+};
+
+// ---------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+    return Db.open(allocator, dbPath, .{});
+}
+
+test "counter incrBy accumulates and get defaults to zero" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try std.testing.expectEqual(@as(i64, 0), try Counter.get(&db, allocator, "hits"));
+    try std.testing.expectEqual(@as(i64, 5), try Counter.incrBy(&db, allocator, "hits", 5));
+    try std.testing.expectEqual(@as(i64, 3), try Counter.incrBy(&db, allocator, "hits", -2));
+    try std.testing.expectEqual(@as(i64, 3), try Counter.get(&db, allocator, "hits"));
+
+    try Counter.set(&db, allocator, "hits", 100);
+    try std.testing.expectEqual(@as(i64, 100), try Counter.get(&db, allocator, "hits"));
+}
+
+test "counter incrBy rejects a real external conflict" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    // incrBy retries internally, so exercise the underlying primitive
+    // directly: begin a txn, let an external writer land in between, then
+    // confirm the stale commit is rejected rather than silently overwriting.
+    const k = try Counter.key(allocator, "race");
+    defer allocator.free(k);
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    _ = try txn.get(allocator, k);
+    try db.put(k, "external");
+    try txn.put(k, "mine");
+    try std.testing.expectError(error.Conflict, txn.commit());
+}
+
+test "hash set get del getAll" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try std.testing.expect(try Hash.set(&db, allocator, "user:1", "name", "ada"));
+    try std.testing.expect(!try Hash.set(&db, allocator, "user:1", "name", "ada lovelace"));
+    try std.testing.expect(try Hash.set(&db, allocator, "user:1", "age", "36"));
+
+    const name = (try Hash.get(&db, allocator, "user:1", "name")).?;
+    defer allocator.free(name);
+    try std.testing.expectEqualStrings("ada lovelace", name);
+
+    try std.testing.expectEqual(@as(usize, 2), try Hash.len(&db, allocator, "user:1"));
+
+    const all = try Hash.getAll(&db, allocator, "user:1");
+    defer {
+        for (all) |f| f.free(allocator);
+        allocator.free(all);
+    }
+    try std.testing.expectEqual(@as(usize, 2), all.len);
+
+    try std.testing.expect(try Hash.del(&db, allocator, "user:1", "age"));
+    try std.testing.expect(!try Hash.del(&db, allocator, "user:1", "age"));
+    try std.testing.expectEqual(@as(usize, 1), try Hash.len(&db, allocator, "user:1"));
+    try std.testing.expect(try Hash.get(&db, allocator, "user:1", "age") == null);
+}
+
+test "set add remove isMember card members" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try std.testing.expect(try Set.add(&db, allocator, "tags", "zig"));
+    try std.testing.expect(!try Set.add(&db, allocator, "tags", "zig"));
+    try std.testing.expect(try Set.add(&db, allocator, "tags", "db"));
+
+    try std.testing.expect(try Set.isMember(&db, allocator, "tags", "zig"));
+    try std.testing.expect(!try Set.isMember(&db, allocator, "tags", "rust"));
+    try std.testing.expectEqual(@as(usize, 2), try Set.card(&db, allocator, "tags"));
+
+    const members = try Set.members(&db, allocator, "tags");
+    defer {
+        for (members) |m| allocator.free(m);
+        allocator.free(members);
+    }
+    try std.testing.expectEqual(@as(usize, 2), members.len);
+
+    try std.testing.expect(try Set.remove(&db, allocator, "tags", "zig"));
+    try std.testing.expect(!try Set.remove(&db, allocator, "tags", "zig"));
+    try std.testing.expectEqual(@as(usize, 1), try Set.card(&db, allocator, "tags"));
+}
+
+test "set intersect union difference across multiple sets" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try Set.add(&db, allocator, "a", "1");
+    _ = try Set.add(&db, allocator, "a", "2");
+    _ = try Set.add(&db, allocator, "a", "3");
+    _ = try Set.add(&db, allocator, "b", "2");
+    _ = try Set.add(&db, allocator, "b", "3");
+    _ = try Set.add(&db, allocator, "b", "4");
+
+    const inter = try Set.intersect(&db, allocator, &.{ "a", "b" });
+    defer {
+        for (inter) |m| allocator.free(m);
+        allocator.free(inter);
+    }
+    try std.testing.expectEqual(@as(usize, 2), inter.len);
+
+    const uni = try Set.unionOf(&db, allocator, &.{ "a", "b" });
+    defer {
+        for (uni) |m| allocator.free(m);
+        allocator.free(uni);
+    }
+    try std.testing.expectEqual(@as(usize, 4), uni.len);
+
+    const diff = try Set.difference(&db, allocator, "a", &.{"b"});
+    defer {
+        for (diff) |m| allocator.free(m);
+        allocator.free(diff);
+    }
+    try std.testing.expectEqual(@as(usize, 1), diff.len);
+    try std.testing.expectEqualStrings("1", diff[0]);
+}
+
+test "list push pop both ends preserve order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try List.pushRight(&db, allocator, "queue", "b");
+    try List.pushRight(&db, allocator, "queue", "c");
+    try List.pushLeft(&db, allocator, "queue", "a");
+    try std.testing.expectEqual(@as(usize, 3), try List.len(&db, allocator, "queue"));
+
+    const first = (try List.popLeft(&db, allocator, "queue")).?;
+    defer allocator.free(first);
+    try std.testing.expectEqualStrings("a", first);
+
+    const last = (try List.popRight(&db, allocator, "queue")).?;
+    defer allocator.free(last);
+    try std.testing.expectEqualStrings("c", last);
+
+    try std.testing.expectEqual(@as(usize, 1), try List.len(&db, allocator, "queue"));
+    try std.testing.expect(try List.popLeft(&db, allocator, "empty") == null);
+}
+
+test "list range supports negative indices redis style" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try List.pushRight(&db, allocator, "l", "0");
+    try List.pushRight(&db, allocator, "l", "1");
+    try List.pushRight(&db, allocator, "l", "2");
+    try List.pushRight(&db, allocator, "l", "3");
+    try List.pushRight(&db, allocator, "l", "4");
+
+    const full = try List.range(&db, allocator, "l", 0, -1);
+    defer {
+        for (full) |v| allocator.free(v);
+        allocator.free(full);
+    }
+    try std.testing.expectEqual(@as(usize, 5), full.len);
+    try std.testing.expectEqualStrings("0", full[0]);
+    try std.testing.expectEqualStrings("4", full[4]);
+
+    const lastTwo = try List.range(&db, allocator, "l", -2, -1);
+    defer {
+        for (lastTwo) |v| allocator.free(v);
+        allocator.free(lastTwo);
+    }
+    try std.testing.expectEqual(@as(usize, 2), lastTwo.len);
+    try std.testing.expectEqualStrings("3", lastTwo[0]);
+    try std.testing.expectEqualStrings("4", lastTwo[1]);
+
+    const clamped = try List.range(&db, allocator, "l", -100, 100);
+    defer {
+        for (clamped) |v| allocator.free(v);
+        allocator.free(clamped);
+    }
+    try std.testing.expectEqual(@as(usize, 5), clamped.len);
+}
+
+test "zset add score incrBy remove rank" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try ZSet.add(&db, allocator, "leaderboard", "alice", 10);
+    try ZSet.add(&db, allocator, "leaderboard", "bob", 20);
+    try ZSet.add(&db, allocator, "leaderboard", "carol", 5);
+
+    try std.testing.expectEqual(@as(f64, 10), (try ZSet.score(&db, allocator, "leaderboard", "alice")).?);
+    try std.testing.expectEqual(@as(usize, 3), try ZSet.card(&db, allocator, "leaderboard"));
+
+    const newScore = try ZSet.incrBy(&db, allocator, "leaderboard", "alice", 100);
+    try std.testing.expectEqual(@as(f64, 110), newScore);
+
+    // Ranks ascending by score: carol(5), bob(20), alice(110).
+    try std.testing.expectEqual(@as(usize, 0), (try ZSet.rank(&db, allocator, "leaderboard", "carol")).?);
+    try std.testing.expectEqual(@as(usize, 2), (try ZSet.rank(&db, allocator, "leaderboard", "alice")).?);
+    try std.testing.expect(try ZSet.rank(&db, allocator, "leaderboard", "missing") == null);
+
+    try std.testing.expect(try ZSet.remove(&db, allocator, "leaderboard", "bob"));
+    try std.testing.expect(!try ZSet.remove(&db, allocator, "leaderboard", "bob"));
+    try std.testing.expectEqual(@as(usize, 2), try ZSet.card(&db, allocator, "leaderboard"));
+}
+
+test "zset rangeByRank and rangeByScore return ascending order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try ZSet.add(&db, allocator, "z", "a", -5.5);
+    try ZSet.add(&db, allocator, "z", "b", 0);
+    try ZSet.add(&db, allocator, "z", "c", 3.25);
+    try ZSet.add(&db, allocator, "z", "d", 100);
+
+    const byRank = try ZSet.rangeByRank(&db, allocator, "z", 0, -1);
+    defer {
+        for (byRank) |m| m.free(allocator);
+        allocator.free(byRank);
+    }
+    try std.testing.expectEqual(@as(usize, 4), byRank.len);
+    try std.testing.expectEqualStrings("a", byRank[0].member);
+    try std.testing.expectEqualStrings("d", byRank[3].member);
+
+    const top2 = try ZSet.rangeByRank(&db, allocator, "z", -2, -1);
+    defer {
+        for (top2) |m| m.free(allocator);
+        allocator.free(top2);
+    }
+    try std.testing.expectEqual(@as(usize, 2), top2.len);
+    try std.testing.expectEqualStrings("c", top2[0].member);
+    try std.testing.expectEqualStrings("d", top2[1].member);
+
+    const byScore = try ZSet.rangeByScore(&db, allocator, "z", -1.0, 50.0);
+    defer {
+        for (byScore) |m| m.free(allocator);
+        allocator.free(byScore);
+    }
+    try std.testing.expectEqual(@as(usize, 2), byScore.len);
+    try std.testing.expectEqualStrings("b", byScore[0].member);
+    try std.testing.expectEqualStrings("c", byScore[1].member);
+}
+
+test "Kind.parse accepts the five CLI names and rejects the rest" {
+    try std.testing.expectEqual(Kind.counter, Kind.parse("counter").?);
+    try std.testing.expectEqual(Kind.hash, Kind.parse("hash").?);
+    try std.testing.expectEqual(Kind.set, Kind.parse("set").?);
+    try std.testing.expectEqual(Kind.list, Kind.parse("list").?);
+    try std.testing.expectEqual(Kind.zset, Kind.parse("zset").?);
+    try std.testing.expect(Kind.parse("bogus") == null);
+}
+
+test "Kind.fromTagByte is the exact inverse of tagByte for all five kinds" {
+    const kinds = [_]Kind{ .counter, .hash, .set, .list, .zset };
+    for (kinds) |k| {
+        try std.testing.expectEqual(k, Kind.fromTagByte(k.tagByte()).?);
+    }
+    try std.testing.expect(Kind.fromTagByte('?') == null);
+}
+
+test "exists and drop cover counter (single key, no trailing separator)" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try std.testing.expect(!try collectionExists(&db, allocator, .counter, "hits"));
+    _ = try Counter.incrBy(&db, allocator, "hits", 0);
+    try std.testing.expect(try collectionExists(&db, allocator, .counter, "hits"));
+
+    // A same-prefixed name must not be swept up by the drop of "hits" - the
+    // counter key has no trailing separator, so this is the one case where a
+    // naive prefix scan (instead of an exact key) would over-delete.
+    _ = try Counter.incrBy(&db, allocator, "hitsExtra", 7);
+
+    try std.testing.expectEqual(@as(usize, 1), try dropCollection(&db, allocator, .counter, "hits"));
+    try std.testing.expect(!try collectionExists(&db, allocator, .counter, "hits"));
+    try std.testing.expectEqual(@as(i64, 7), try Counter.get(&db, allocator, "hitsExtra"));
+}
+
+test "drop removes every field of a hash and every element+meta of a list" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try Hash.set(&db, allocator, "user:1", "name", "ada");
+    _ = try Hash.set(&db, allocator, "user:1", "age", "36");
+    try std.testing.expect(try collectionExists(&db, allocator, .hash, "user:1"));
+    try std.testing.expectEqual(@as(usize, 2), try dropCollection(&db, allocator, .hash, "user:1"));
+    try std.testing.expect(!try collectionExists(&db, allocator, .hash, "user:1"));
+    try std.testing.expectEqual(@as(usize, 0), try Hash.len(&db, allocator, "user:1"));
+
+    try List.pushRight(&db, allocator, "queue", "a");
+    try List.pushRight(&db, allocator, "queue", "b");
+    try std.testing.expect(try collectionExists(&db, allocator, .list, "queue"));
+    // 2 elements + 1 meta record.
+    try std.testing.expectEqual(@as(usize, 3), try dropCollection(&db, allocator, .list, "queue"));
+    try std.testing.expect(!try collectionExists(&db, allocator, .list, "queue"));
+    try std.testing.expectEqual(@as(usize, 0), try List.len(&db, allocator, "queue"));
+
+    // Dropping something never created is a harmless no-op.
+    try std.testing.expectEqual(@as(usize, 0), try dropCollection(&db, allocator, .set, "never-existed"));
+}
+
+test "drop removes both the member row and score-index row of every zset entry" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try ZSet.add(&db, allocator, "leaderboard", "alice", 10);
+    try ZSet.add(&db, allocator, "leaderboard", "bob", 20);
+    try std.testing.expect(try collectionExists(&db, allocator, .zset, "leaderboard"));
+    // 2 members * (1 member row + 1 score-index row) = 4.
+    try std.testing.expectEqual(@as(usize, 4), try dropCollection(&db, allocator, .zset, "leaderboard"));
+    try std.testing.expect(!try collectionExists(&db, allocator, .zset, "leaderboard"));
+    try std.testing.expectEqual(@as(usize, 0), try ZSet.card(&db, allocator, "leaderboard"));
+}
+
+test "zset add is a no-op when the score does not change" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try ZSet.add(&db, allocator, "z", "a", 5.0);
+    try ZSet.add(&db, allocator, "z", "a", 5.0);
+    try std.testing.expectEqual(@as(usize, 1), try ZSet.card(&db, allocator, "z"));
+    try std.testing.expectEqual(@as(f64, 5.0), (try ZSet.score(&db, allocator, "z", "a")).?);
+}
diff --git a/src/collttl.zig b/src/collttl.zig
new file mode 100644
index 0000000..6473bbc
--- /dev/null
+++ b/src/collttl.zig
@@ -0,0 +1,354 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+const ttlmod = @import("ttl.zig");
+const collmod = @import("collections.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Kind = collmod.Kind;
+pub const TtlResult = ttlmod.TtlResult;
+
+/// Per-collection expiry markers, sibling to ttl.zig's per-key markers but
+/// for a different unit: a typed collection (Counter/Hash/Set/List/ZSet) is
+/// not one physical Db key, it is a whole namespace of them (every field of
+/// a hash, every element of a list, both rows of every zset entry), so
+/// "expiring" one here always means dropping the ENTIRE namespace via
+/// collections.drop, not a single db.delete.
+///   "Y" <kind tag byte> 0x00 <name> -> raw i128 (expiresAtNanos, big-endian)
+///
+/// This used to share ttl.zig's 'T' tag (with a leading 0x01 sub-byte to
+/// keep individual marker keys from colliding byte-for-byte). That was a
+/// real bug, not just an odd design: ttl.zig's own `sweepExpired` scans by
+/// the single-byte prefix "T", and every collttl marker IS a byte-for-byte
+/// extension of that same prefix, so the flat sweeper's scan matched them
+/// too. Both modules store the identical i128-expiresAt payload shape, so
+/// `readI128` on a collttl marker "succeeded" without error; if it looked
+/// due, the flat sweeper would `db.delete` a harmless nonexistent flat key
+/// and then reconstruct and delete the ORIGINAL collttl marker key via its
+/// own `clearExpire(key[1..])` - silently clearing the collection's expiry
+/// marker without ever calling `collections.dropCollection`, so the
+/// collection's actual data was never removed even though flat-key
+/// `ttlSweptTotal` had counted a phantom reap for it. Caught by a real
+/// test that runs both sweepers against the same Db at once (see
+/// server.zig's "flat ttl sweeper and the coll ttl sweeper enabled at once"
+/// test) - a manual `ttl expire-sweep`/`ttl_op sweep` run on a Db that also
+/// has due collection markers would trip the same bug even with only one
+/// sweeper. Fixed by giving collttl.zig its own top-level tag ('Y', not
+/// used by row.zig/index.zig/collections.zig/auth.zig/ttl.zig), so it is
+/// prefix-disjoint from every other namespace, not merely full-key-disjoint
+/// the way the shared-'T' scheme assumed.
+pub const nsTag: u8 = 'Y';
+const collSub: u8 = 0x01;
+const sep: u8 = 0x00;
+
+fn markerKey(allocator: Allocator, k: Kind, name: []const u8) ![]u8 {
+    const out = try allocator.alloc(u8, name.len + 3);
+    out[0] = nsTag;
+    out[1] = collSub;
+    out[2] = k.tagByte();
+    // name is appended without its own leading separator on purpose: the
+    // fixed 3-byte header (nsTag, collSub, kindTag) already makes every
+    // marker key length-disjoint per kind boundary at byte 2, so no two
+    // different (kind, name) pairs can ever produce the same marker key.
+    @memcpy(out[3..], name);
+    return out;
+}
+
+fn putI128(out: *std.ArrayList(u8), v: i128) !void {
+    var b: [16]u8 = undefined;
+    std.mem.writeInt(i128, &b, v, .big);
+    try out.appendSlice(&b);
+}
+
+fn readI128(data: []const u8) !i128 {
+    if (data.len != 16) return error.Malformed;
+    return std.mem.readInt(i128, data[0..16], .big);
+}
+
+/// Sets (or replaces) an absolute expiry deadline on the collection `name`
+/// of kind `k`. Does not verify the collection currently exists - callers
+/// that need existence-checked semantics (the CLI `coll <kind> expire`
+/// command) check collections.exists first, same as ttl.zig's setExpireAt
+/// vs the CLI's flat-key `expire`.
+pub fn setExpireAt(db: *Db, allocator: Allocator, k: Kind, name: []const u8, expiresAtNanos: i128) !void {
+    const mk = try markerKey(allocator, k, name);
+    defer allocator.free(mk);
+    var out = std.ArrayList(u8).init(allocator);
+    defer out.deinit();
+    try putI128(&out, expiresAtNanos);
+    try db.put(mk, out.items);
+}
+
+pub fn setExpireSeconds(db: *Db, allocator: Allocator, k: Kind, name: []const u8, nowNanos: i128, seconds: u64) !void {
+    try setExpireAt(db, allocator, k, name, nowNanos + @as(i128, @intCast(seconds)) * ttlmod.secondNanos);
+}
+
+pub fn getExpiresAt(db: *Db, allocator: Allocator, k: Kind, name: []const u8) !?i128 {
+    const mk = try markerKey(allocator, k, name);
+    defer allocator.free(mk);
+    const raw = try db.get(allocator, mk) orelse return null;
+    defer allocator.free(raw);
+    return try readI128(raw);
+}
+
+pub fn clearExpire(db: *Db, allocator: Allocator, k: Kind, name: []const u8) !void {
+    const mk = try markerKey(allocator, k, name);
+    defer allocator.free(mk);
+    try db.delete(mk);
+}
+
+/// Redis TTL(2)-shaped result, same three cases as ttl.zig's `remaining`:
+/// `.noKey` when the collection has no physical presence at all,
+/// `.noExpiry` when it exists but carries no marker, `.seconds` otherwise.
+pub fn remaining(db: *Db, allocator: Allocator, k: Kind, name: []const u8, nowNanos: i128) !TtlResult {
+    if (!try collmod.collectionExists(db, allocator, k, name)) return .noKey;
+    const expiresAt = try getExpiresAt(db, allocator, k, name) orelse return .noExpiry;
+    if (nowNanos >= expiresAt) return .{ .seconds = 0 };
+    return .{ .seconds = @intCast(@divFloor(expiresAt - nowNanos, ttlmod.secondNanos)) };
+}
+
+/// Lazily enforces expiry on access: if the collection carries a due
+/// marker, drops every physical key it owns (collections.drop - a real
+/// multi-key delete through the normal WAL/tombstone path, not a pretend
+/// removal) plus the marker itself, and reports true. The CLI's `coll`
+/// dispatcher calls this before every non-TTL operation so a caller never
+/// observes a logically-expired collection just because no sweep has run.
+pub fn expireIfDue(db: *Db, allocator: Allocator, k: Kind, name: []const u8, nowNanos: i128) !bool {
+    const expiresAt = try getExpiresAt(db, allocator, k, name) orelse return false;
+    if (!ttlmod.isDue(expiresAt, nowNanos)) return false;
+    _ = try collmod.dropCollection(db, allocator, k, name);
+    try clearExpire(db, allocator, k, name);
+    return true;
+}
+
+/// Same lazy check as `expireIfDue`, applied to every name in `names`
+/// instead of a single one. Closes the gap documented at the `Set`
+/// multi-set operations' call sites (`intersect`/`unionOf`/`difference`):
+/// those accept more than one set name, but only the first one was ever
+/// checked on the read path (the CLI's blanket single-name check runs on
+/// `args[0]` before dispatch), leaving `args[1..]` reachable only through
+/// the periodic/manual sweep. Returns the count actually reaped, same
+/// counting convention as `sweepExpired`.
+pub fn expireIfDueMany(db: *Db, allocator: Allocator, k: Kind, names: []const []const u8, nowNanos: i128) !usize {
+    var reaped: usize = 0;
+    for (names) |name| {
+        if (try expireIfDue(db, allocator, k, name, nowNanos)) reaped += 1;
+    }
+    return reaped;
+}
+
+/// Active sweep across every kind at once: scans the whole collection-TTL
+/// marker namespace, drops every collection whose marker is due. Returns
+/// the number of collections reaped (not the number of physical keys - a
+/// dropped hash with 5 fields counts once here, same granularity as
+/// ttl.zig's sweepExpired counts flat keys).
+pub fn sweepExpired(db: *Db, allocator: Allocator, nowNanos: i128) !usize {
+    const Due = struct { k: Kind, name: []u8 };
+    var due = std.ArrayList(Due).init(allocator);
+    defer {
+        for (due.items) |d| allocator.free(d.name);
+        due.deinit();
+    }
+    {
+        const prefix = &[_]u8{ nsTag, collSub };
+        var iter = try db.scanPrefix(allocator, prefix);
+        defer iter.deinit();
+        while (try iter.next()) |entry| {
+            // entry.key = nsTag collSub kindTag name...
+            if (entry.key.len < 3) continue;
+            const k: Kind = Kind.fromTagByte(entry.key[2]) orelse continue;
+            const expiresAt = try readI128(entry.value);
+            if (ttlmod.isDue(expiresAt, nowNanos)) {
+                try due.append(.{ .k = k, .name = try allocator.dupe(u8, entry.key[3..]) });
+            }
+        }
+    }
+    for (due.items) |d| {
+        _ = try collmod.dropCollection(db, allocator, d.k, d.name);
+        try clearExpire(db, allocator, d.k, d.name);
+    }
+    return due.items.len;
+}
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+    return Db.open(allocator, dbPath, .{});
+}
+
+test "remaining reports noKey for a collection that was never created" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try std.testing.expectEqual(TtlResult.noKey, try remaining(&db, allocator, .hash, "missing", 0));
+}
+
+test "remaining reports noExpiry then counted seconds for a real hash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try collmod.Hash.set(&db, allocator, "profile", "name", "ada");
+    try std.testing.expectEqual(TtlResult.noExpiry, try remaining(&db, allocator, .hash, "profile", 0));
+
+    try setExpireSeconds(&db, allocator, .hash, "profile", 1000, 30);
+    const r = try remaining(&db, allocator, .hash, "profile", 1000);
+    try std.testing.expectEqual(@as(u64, 30), r.seconds);
+}
+
+test "expireIfDue drops every field of a hash, not just one key" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try collmod.Hash.set(&db, allocator, "session:1", "user", "ada");
+    _ = try collmod.Hash.set(&db, allocator, "session:1", "role", "admin");
+    try setExpireSeconds(&db, allocator, .hash, "session:1", 0, 5);
+
+    try std.testing.expect(!try expireIfDue(&db, allocator, .hash, "session:1", 4 * ttlmod.secondNanos));
+    try std.testing.expectEqual(@as(usize, 2), try collmod.Hash.len(&db, allocator, "session:1"));
+
+    try std.testing.expect(try expireIfDue(&db, allocator, .hash, "session:1", 5 * ttlmod.secondNanos));
+    try std.testing.expectEqual(@as(usize, 0), try collmod.Hash.len(&db, allocator, "session:1"));
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .hash, "session:1"));
+    try std.testing.expectEqual(@as(?i128, null), try getExpiresAt(&db, allocator, .hash, "session:1"));
+}
+
+test "expireIfDueMany reaps only the due names among several, mirroring a Set.intersect call" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try collmod.Set.add(&db, allocator, "a", "x");
+    _ = try collmod.Set.add(&db, allocator, "b", "x");
+    _ = try collmod.Set.add(&db, allocator, "c", "x");
+    try setExpireSeconds(&db, allocator, .set, "b", 0, 5);
+
+    // Mirrors `coll set inter a b c`: the CLI's blanket lazy check only
+    // ever covered args[0] ("a"); this call is what now covers args[1..].
+    const reaped = try expireIfDueMany(&db, allocator, .set, &.{ "b", "c" }, 5 * ttlmod.secondNanos);
+    try std.testing.expectEqual(@as(usize, 1), reaped);
+
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .set, "b"));
+    try std.testing.expect(try collmod.collectionExists(&db, allocator, .set, "a"));
+    try std.testing.expect(try collmod.collectionExists(&db, allocator, .set, "c"));
+
+    // Now Set.intersect(a, c) sees a live pair and finds the real member,
+    // instead of silently intersecting against a phantom "b" that a
+    // periodic sweep hadn't reaped yet.
+    const inter = try collmod.Set.intersect(&db, allocator, &.{ "a", "c" });
+    defer {
+        for (inter) |m| allocator.free(m);
+        allocator.free(inter);
+    }
+    try std.testing.expectEqual(@as(usize, 1), inter.len);
+    try std.testing.expectEqualStrings("x", inter[0]);
+}
+
+test "expireIfDueMany is a no-op count of zero when nothing is due" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try collmod.Set.add(&db, allocator, "a", "x");
+    _ = try collmod.Set.add(&db, allocator, "b", "x");
+
+    try std.testing.expectEqual(@as(usize, 0), try expireIfDueMany(&db, allocator, .set, &.{ "a", "b" }, 0));
+}
+
+test "clearExpire makes a collection immortal again" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try collmod.List.pushRight(&db, allocator, "queue", "job-1");
+    try setExpireSeconds(&db, allocator, .list, "queue", 0, 1);
+    try clearExpire(&db, allocator, .list, "queue");
+
+    try std.testing.expectEqual(TtlResult.noExpiry, try remaining(&db, allocator, .list, "queue", 100 * ttlmod.secondNanos));
+    try std.testing.expect(!try expireIfDue(&db, allocator, .list, "queue", 100 * ttlmod.secondNanos));
+    try std.testing.expectEqual(@as(usize, 1), try collmod.List.len(&db, allocator, "queue"));
+}
+
+test "sweepExpired reaps due collections of every kind without touching live ones" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try collmod.Counter.incrBy(&db, allocator, "hits", 3);
+    try setExpireSeconds(&db, allocator, .counter, "hits", 0, 1);
+
+    _ = try collmod.Hash.set(&db, allocator, "profile", "name", "ada");
+    try setExpireSeconds(&db, allocator, .hash, "profile", 0, 100);
+
+    try collmod.ZSet.add(&db, allocator, "leaderboard", "alice", 10);
+    try setExpireSeconds(&db, allocator, .zset, "leaderboard", 0, 1);
+
+    _ = try collmod.Set.add(&db, allocator, "tags", "zig");
+
+    const reaped = try sweepExpired(&db, allocator, 2 * ttlmod.secondNanos);
+    try std.testing.expectEqual(@as(usize, 2), reaped);
+
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .counter, "hits"));
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .zset, "leaderboard"));
+    try std.testing.expect(try collmod.collectionExists(&db, allocator, .hash, "profile"));
+    try std.testing.expect(try collmod.collectionExists(&db, allocator, .set, "tags"));
+
+    // Idempotent: a second sweep at the same instant finds nothing left.
+    try std.testing.expectEqual(@as(usize, 0), try sweepExpired(&db, allocator, 2 * ttlmod.secondNanos));
+}
+
+test "collection sweep survives a wal reopen: markers are durable" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    {
+        var db = try openTemp(&tmp, allocator);
+        defer db.close();
+        _ = try collmod.Hash.set(&db, allocator, "durable", "k", "v");
+        try setExpireSeconds(&db, allocator, .hash, "durable", 0, 5);
+    }
+
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    const r = try remaining(&db, allocator, .hash, "durable", 1 * ttlmod.secondNanos);
+    try std.testing.expectEqual(@as(u64, 4), r.seconds);
+
+    try std.testing.expectEqual(@as(usize, 1), try sweepExpired(&db, allocator, 10 * ttlmod.secondNanos));
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .hash, "durable"));
+}
+
+test "markers for the same name under different kinds never collide" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    _ = try collmod.Hash.set(&db, allocator, "shared", "f", "v");
+    _ = try collmod.Set.add(&db, allocator, "shared", "m");
+
+    try setExpireSeconds(&db, allocator, .hash, "shared", 0, 5);
+    // The set named "shared" must still read as noExpiry - the marker for
+    // the hash "shared" must not leak across the kind boundary.
+    try std.testing.expectEqual(TtlResult.noExpiry, try remaining(&db, allocator, .set, "shared", 0));
+
+    const hashResult = try remaining(&db, allocator, .hash, "shared", 0);
+    try std.testing.expectEqual(@as(u64, 5), hashResult.seconds);
+}
diff --git a/src/concurrent.zig b/src/concurrent.zig
new file mode 100644
index 0000000..7e25402
--- /dev/null
+++ b/src/concurrent.zig
@@ -0,0 +1,437 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+const batchmod = @import("batch.zig");
+const txnmod = @import("txn.zig");
+const txntable = @import("txn_table.zig");
+const querymod = @import("query.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Transaction = txnmod.Transaction;
+const TableTxn = txntable.TableTxn;
+const WriteBatch = batchmod.WriteBatch;
+
+/// A thread-safe facade over `*Db`. `Db` itself keeps no internal locking -
+/// a fact documented (and worked around ad hoc) at every call site that
+/// already needs concurrent access from more than one OS thread:
+/// server.zig takes its own `mutex` before touching `db` on every request,
+/// and every session note about txn_table.zig/query.zig/collections.zig
+/// repeats the same known gap for the same reason. `GuardedDb` is that
+/// exact pattern promoted to one reusable, independently tested primitive
+/// instead of being reimplemented by hand wherever it is next needed.
+///
+/// This does not make `Db` itself thread-safe: it makes "every access to
+/// this particular `Db` goes through this particular lock" enforceable,
+/// which is the same guarantee `Server` already relies on. Two independent
+/// `GuardedDb` wrapping the same underlying `*Db` would NOT be safe - the
+/// mutex only serializes callers that agree to go through it.
+pub const GuardedDb = struct {
+    db: *Db,
+    mutex: std.Thread.Mutex = .{},
+
+    pub fn init(db: *Db) GuardedDb {
+        return .{ .db = db };
+    }
+
+    /// Exclusive handle returned by `acquire()`. Holds the lock until
+    /// `release()` runs, so a caller that needs several `Db` calls to
+    /// happen as one atomic unit (a read-modify-write, or several puts
+    /// that must never be observed half-applied by another guarded
+    /// reader) can acquire once and issue every call through `.db`
+    /// without releasing in between - the same shape as
+    /// `Server.dispatch` locking `self.mutex` once per request no matter
+    /// how many `Db` calls that request needs.
+    pub const Guard = struct {
+        db: *Db,
+        mutex: *std.Thread.Mutex,
+
+        pub fn release(self: Guard) void {
+            self.mutex.unlock();
+        }
+    };
+
+    pub fn acquire(self: *GuardedDb) Guard {
+        self.mutex.lock();
+        return .{ .db = self.db, .mutex = &self.mutex };
+    }
+
+    pub fn put(self: *GuardedDb, key: []const u8, value: []const u8) !void {
+        const g = self.acquire();
+        defer g.release();
+        try g.db.put(key, value);
+    }
+
+    pub fn delete(self: *GuardedDb, key: []const u8) !void {
+        const g = self.acquire();
+        defer g.release();
+        try g.db.delete(key);
+    }
+
+    pub fn get(self: *GuardedDb, allocator: Allocator, key: []const u8) !?[]u8 {
+        const g = self.acquire();
+        defer g.release();
+        return g.db.get(allocator, key);
+    }
+
+    pub fn apply(self: *GuardedDb, batch: *WriteBatch) !void {
+        const g = self.acquire();
+        defer g.release();
+        try g.db.apply(batch);
+    }
+
+    pub fn flush(self: *GuardedDb) !void {
+        const g = self.acquire();
+        defer g.release();
+        try g.db.flush();
+    }
+
+    pub fn compact(self: *GuardedDb) !void {
+        const g = self.acquire();
+        defer g.release();
+        try g.db.compact();
+    }
+
+    /// Atomic read-modify-write counter: decodes the current value at
+    /// `key` as a little-endian i64 (0 if absent or the wrong width),
+    /// adds `delta`, writes the new value back - the whole read, decide,
+    /// write sequence runs under one lock acquisition, so no other
+    /// guarded caller can observe or clobber the value partway through.
+    /// A bare `db.get` followed later by a separate `db.put` cannot make
+    /// that guarantee, which is exactly the lost-update hazard this
+    /// exists to close (see the test below that proves it with real
+    /// concurrent OS threads, not a simulated interleaving).
+    pub fn incrBy(self: *GuardedDb, allocator: Allocator, key: []const u8, delta: i64) !i64 {
+        const g = self.acquire();
+        defer g.release();
+        var current: i64 = 0;
+        if (try g.db.get(allocator, key)) |raw| {
+            defer allocator.free(raw);
+            if (raw.len == 8) current = std.mem.readInt(i64, raw[0..8], .little);
+        }
+        const next = current + delta;
+        var buf: [8]u8 = undefined;
+        std.mem.writeInt(i64, &buf, next, .little);
+        try g.db.put(key, &buf);
+        return next;
+    }
+};
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+    return Db.open(allocator, dbPath, .{});
+}
+
+test "put/get/delete round-trip through the guard like a plain Db call" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var guarded = GuardedDb.init(&db);
+
+    try guarded.put("k", "v1");
+    {
+        const got = try guarded.get(allocator, "k");
+        defer if (got) |g| allocator.free(g);
+        try std.testing.expectEqualStrings("v1", got.?);
+    }
+
+    try guarded.delete("k");
+    const afterDelete = try guarded.get(allocator, "k");
+    try std.testing.expectEqual(@as(?[]u8, null), afterDelete);
+}
+
+test "incrBy on a fresh key starts from zero and returns the running total" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var guarded = GuardedDb.init(&db);
+
+    try std.testing.expectEqual(@as(i64, 5), try guarded.incrBy(allocator, "ctr", 5));
+    try std.testing.expectEqual(@as(i64, 3), try guarded.incrBy(allocator, "ctr", -2));
+    try std.testing.expectEqual(@as(i64, 103), try guarded.incrBy(allocator, "ctr", 100));
+}
+
+const IncrWorker = struct {
+    guarded: *GuardedDb,
+    key: []const u8,
+    iterations: usize,
+
+    fn run(self: IncrWorker) void {
+        const allocator = std.heap.page_allocator;
+        var i: usize = 0;
+        while (i < self.iterations) : (i += 1) {
+            _ = self.guarded.incrBy(allocator, self.key, 1) catch |err| {
+                std.debug.panic("incrBy failed under real thread contention: {s}", .{@errorName(err)});
+            };
+        }
+    }
+};
+
+test "incrBy survives real concurrent OS threads with zero lost updates" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var guarded = GuardedDb.init(&db);
+
+    const threadCount = 6;
+    const perThread = 300;
+    var threads: [threadCount]std.Thread = undefined;
+    for (&threads) |*t| {
+        t.* = try std.Thread.spawn(.{}, IncrWorker.run, .{IncrWorker{
+            .guarded = &guarded,
+            .key = "shared-counter",
+            .iterations = perThread,
+        }});
+    }
+    for (threads) |t| t.join();
+
+    const raw = try guarded.get(allocator, "shared-counter");
+    defer allocator.free(raw.?);
+    const total = std.mem.readInt(i64, raw.?[0..8], .little);
+    // A bare unsynchronized `db.get` + `db.put` read-modify-write would
+    // routinely lose updates here (two threads read the same stale value,
+    // both write back the same next value, one increment vanishes). The
+    // mutex inside GuardedDb makes every incrBy fully serialized, so the
+    // total below must land exactly on threadCount*perThread every single
+    // run - not "usually", not "close to" - or the guard has a real bug.
+    try std.testing.expectEqual(@as(i64, threadCount * perThread), total);
+}
+
+const TransferWorker = struct {
+    guarded: *GuardedDb,
+    rounds: usize,
+
+    fn run(self: TransferWorker) void {
+        const allocator = std.heap.page_allocator;
+        var i: usize = 0;
+        while (i < self.rounds) : (i += 1) {
+            const g = self.guarded.acquire();
+            defer g.release();
+            const aRaw = g.db.get(allocator, "balanceA") catch @panic("get a failed");
+            defer allocator.free(aRaw.?);
+            const bRaw = g.db.get(allocator, "balanceB") catch @panic("get b failed");
+            defer allocator.free(bRaw.?);
+            const a = std.mem.readInt(i64, aRaw.?[0..8], .little);
+            const b = std.mem.readInt(i64, bRaw.?[0..8], .little);
+            if (a < 1) continue;
+            var aBuf: [8]u8 = undefined;
+            var bBuf: [8]u8 = undefined;
+            std.mem.writeInt(i64, &aBuf, a - 1, .little);
+            std.mem.writeInt(i64, &bBuf, b + 1, .little);
+            g.db.put("balanceA", &aBuf) catch @panic("put a failed");
+            g.db.put("balanceB", &bBuf) catch @panic("put b failed");
+        }
+    }
+};
+
+const InvariantReader = struct {
+    guarded: *GuardedDb,
+    checks: usize,
+    violations: *std.atomic.Value(usize),
+
+    fn run(self: InvariantReader) void {
+        const allocator = std.heap.page_allocator;
+        var i: usize = 0;
+        while (i < self.checks) : (i += 1) {
+            const g = self.guarded.acquire();
+            const aRaw = g.db.get(allocator, "balanceA") catch @panic("get a failed");
+            const bRaw = g.db.get(allocator, "balanceB") catch @panic("get b failed");
+            const a = std.mem.readInt(i64, aRaw.?[0..8], .little);
+            const b = std.mem.readInt(i64, bRaw.?[0..8], .little);
+            g.release();
+            allocator.free(aRaw.?);
+            allocator.free(bRaw.?);
+            if (a + b != 1000) _ = self.violations.fetchAdd(1, .monotonic);
+        }
+    }
+};
+
+test "acquire lets a writer move value between two keys atomically under a concurrent reader" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var guarded = GuardedDb.init(&db);
+
+    var initA: [8]u8 = undefined;
+    var initB: [8]u8 = undefined;
+    std.mem.writeInt(i64, &initA, 1000, .little);
+    std.mem.writeInt(i64, &initB, 0, .little);
+    try guarded.put("balanceA", &initA);
+    try guarded.put("balanceB", &initB);
+
+    var violations = std.atomic.Value(usize).init(0);
+    const writerThread = try std.Thread.spawn(.{}, TransferWorker.run, .{TransferWorker{
+        .guarded = &guarded,
+        .rounds = 1000,
+    }});
+    const readerThread = try std.Thread.spawn(.{}, InvariantReader.run, .{InvariantReader{
+        .guarded = &guarded,
+        .checks = 1000,
+        .violations = &violations,
+    }});
+    writerThread.join();
+    readerThread.join();
+
+    // Every single reader observation is required to see the invariant
+    // balanceA + balanceB == 1000 hold, because each transfer's two puts
+    // happen inside one `acquire()`/`release()` pair the reader's own
+    // acquire() must wait out entirely - a real race would show up here
+    // as a nonzero violation count, not as a crash, which is why this
+    // asserts the counter is exactly zero instead of merely "did not hang".
+    try std.testing.expectEqual(@as(usize, 0), violations.load(.monotonic));
+
+    const finalARaw = try guarded.get(allocator, "balanceA");
+    defer allocator.free(finalARaw.?);
+    const finalBRaw = try guarded.get(allocator, "balanceB");
+    defer allocator.free(finalBRaw.?);
+    const finalA = std.mem.readInt(i64, finalARaw.?[0..8], .little);
+    const finalB = std.mem.readInt(i64, finalBRaw.?[0..8], .little);
+    try std.testing.expectEqual(@as(i64, 1000), finalA + finalB);
+    try std.testing.expectEqual(@as(i64, 0), finalA);
+    try std.testing.expectEqual(@as(i64, 1000), finalB);
+}
+
+test "apply is usable concurrently: disjoint batches from different threads never clobber each other" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var guarded = GuardedDb.init(&db);
+
+    const ApplyWorker = struct {
+        guarded: *GuardedDb,
+        prefix: u8,
+        count: usize,
+
+        fn run(self: @This()) void {
+            var batch = WriteBatch.init(std.heap.page_allocator);
+            defer batch.deinit();
+            var i: usize = 0;
+            while (i < self.count) : (i += 1) {
+                const key = [_]u8{ self.prefix, @intCast(i) };
+                batch.put(&key, "v") catch @panic("batch put failed");
+            }
+            self.guarded.apply(&batch) catch |err| {
+                std.debug.panic("apply failed under contention: {s}", .{@errorName(err)});
+            };
+        }
+    };
+
+    var threads: [4]std.Thread = undefined;
+    for (&threads, 0..) |*t, idx| {
+        t.* = try std.Thread.spawn(.{}, ApplyWorker.run, .{ApplyWorker{
+            .guarded = &guarded,
+            .prefix = @intCast('a' + idx),
+            .count = 50,
+        }});
+    }
+    for (threads) |t| t.join();
+
+    inline for (.{ 'a', 'b', 'c', 'd' }) |prefix| {
+        var iter = try guarded.db.scanPrefix(allocator, &[_]u8{prefix});
+        defer iter.deinit();
+        var n: usize = 0;
+        while (try iter.next()) |_| n += 1;
+        try std.testing.expectEqual(@as(usize, 50), n);
+    }
+}
+
+const TableTransferWorker = struct {
+    guarded: *GuardedDb,
+    rounds: usize,
+
+    /// Runs a full `Transaction` + `TableTxn` transfer lifecycle (begin,
+    /// read both rows, stage both writes, commit) under a single
+    /// `acquire()`/`release()` pair, closing the specific gap every prior
+    /// session on this project flagged and deferred: "brak testu
+    /// wspolbieznosci wielowatkowej (dwa watki komituja TableTxn na tym
+    /// samym Db jednoczesnie)". `Db.get`/`Transaction.commit` touch shared
+    /// mutable state (the memtable, the OCC read-set bookkeeping) with no
+    /// locking of their own, so without the guard two real OS threads
+    /// racing through `TableTxn.open`/`get`/`put`/`commit` at once would
+    /// be exactly the kind of unguarded concurrent access every other
+    /// module in this project takes its own mutex to avoid.
+    fn run(self: TableTransferWorker) void {
+        const allocator = std.heap.page_allocator;
+        var i: usize = 0;
+        while (i < self.rounds) : (i += 1) {
+            const g = self.guarded.acquire();
+            defer g.release();
+
+            var txn = Transaction.begin(g.db);
+            defer txn.deinit();
+            var t = TableTxn.open(&txn, allocator, "accounts") catch @panic("TableTxn.open failed");
+            defer t.deinit();
+
+            var from = (t.get(.{ .int = 1 }) catch @panic("get 1 failed")).?;
+            defer from.deinit();
+            var to = (t.get(.{ .int = 2 }) catch @panic("get 2 failed")).?;
+            defer to.deinit();
+            if (from.get("balance").?.int < 1) continue;
+
+            t.put(.{ .int = 1 }, &.{.{ .name = "balance", .value = .{ .int = from.get("balance").?.int - 1 } }}) catch @panic("put 1 failed");
+            t.put(.{ .int = 2 }, &.{.{ .name = "balance", .value = .{ .int = to.get("balance").?.int + 1 } }}) catch @panic("put 2 failed");
+
+            // The whole sequence runs under one lock, so no external writer
+            // can ever appear mid-transfer here: commit() must never see a
+            // real error.Conflict in this test, unlike the deliberately
+            // racy scenario in txn_table.zig's own "all-or-nothing" test.
+            txn.commit() catch |err| std.debug.panic("unexpected commit failure under serialized access: {s}", .{@errorName(err)});
+        }
+    }
+};
+
+test "TableTxn commits from many real OS threads never lose or duplicate a unit of balance" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    const startBalance: i64 = 2000;
+    {
+        var setup = try querymod.Table.open(&db, allocator, "accounts");
+        defer setup.deinit();
+        try setup.put(.{ .int = 1 }, &.{.{ .name = "balance", .value = .{ .int = startBalance } }});
+        try setup.put(.{ .int = 2 }, &.{.{ .name = "balance", .value = .{ .int = 0 } }});
+    }
+
+    var guarded = GuardedDb.init(&db);
+    const threadCount = 4;
+    const roundsPerThread = 200;
+    var threads: [threadCount]std.Thread = undefined;
+    for (&threads) |*t| {
+        t.* = try std.Thread.spawn(.{}, TableTransferWorker.run, .{TableTransferWorker{
+            .guarded = &guarded,
+            .rounds = roundsPerThread,
+        }});
+    }
+    for (threads) |t| t.join();
+
+    var verify = try querymod.Table.open(&db, allocator, "accounts");
+    defer verify.deinit();
+    var row1 = (try verify.get(.{ .int = 1 })).?;
+    defer row1.deinit();
+    var row2 = (try verify.get(.{ .int = 2 })).?;
+    defer row2.deinit();
+    const balance1 = row1.get("balance").?.int;
+    const balance2 = row2.get("balance").?.int;
+
+    // Every transfer moves exactly 1 unit and every transfer's two writes
+    // commit together or not at all, so the total must be exactly
+    // preserved and account 2 must have gained exactly what account 1
+    // lost - no interleaving of `get`+`put`+`commit` across threads can
+    // produce any other pair of numbers.
+    try std.testing.expectEqual(startBalance, balance1 + balance2);
+    try std.testing.expectEqual(@as(i64, threadCount * roundsPerThread), balance2);
+    try std.testing.expectEqual(startBalance - threadCount * roundsPerThread, balance1);
+}
diff --git a/src/db.zig b/src/db.zig
index 84fc18d..4e3868c 100644
--- a/src/db.zig
+++ b/src/db.zig
@@ -4,7 +4,10 @@ const memtable = @import("memtable.zig");
 const sstable = @import("sstable.zig");
 const cache = @import("cache.zig");
 const statsmod = @import("stats.zig");
-const Wal = @import("wal.zig").Wal;
+const heap = @import("heap.zig");
+const version = @import("version.zig");
+const walmod = @import("wal.zig");
+const Wal = walmod.Wal;
 
 const Allocator = std.mem.Allocator;
 const Kind = encode.Kind;
@@ -13,6 +16,8 @@ const Memtable = memtable.Memtable;
 const Reader = sstable.Reader;
 const Builder = sstable.Builder;
 const BlockCache = cache.BlockCache;
+const VersionSet = version.VersionSet;
+const VersionEdit = version.VersionEdit;
 
 pub const WriteBatch = @import("batch.zig").WriteBatch;
 pub const Stats = statsmod.Stats;
@@ -22,7 +27,6 @@ fn order(a: []const u8, b: []const u8) std.math.Order {
 }
 
 const walName = "wal.log";
-const manifestName = "MANIFEST";
 
 pub const Options = struct {
     flushThreshold: usize = 4 * 1024 * 1024,
@@ -46,6 +50,8 @@ pub const Db = struct {
     wal: Wal,
     sstables: std.ArrayList(*Reader),
     blockCache: BlockCache,
+    versionSet: VersionSet,
+    versionState: std.AutoHashMap(u64, usize),
     nextFileId: u64,
     nextSeq: u64,
     flushThreshold: usize,
@@ -91,10 +97,11 @@ pub const Db = struct {
             if (id > maxId) maxId = id;
         }
 
-        var levelMap = try loadManifest(allocator, dir);
-        defer levelMap.deinit();
+        var opened = try VersionSet.open(allocator, dir);
+        errdefer opened.set.close();
+        errdefer opened.state.deinit();
         for (sstables.items) |reader| {
-            reader.level = levelMap.get(reader.fileId) orelse 0;
+            reader.level = opened.state.get(reader.fileId) orelse 0;
         }
 
         var table = try Memtable.init(allocator);
@@ -104,6 +111,20 @@ pub const Db = struct {
         const walMaxSeq = try wal.replay(&table);
         if (walMaxSeq > maxSeq) maxSeq = walMaxSeq;
 
+        // The directory scan alone can regress: a leveled compaction that
+        // fully garbage-collects a run of tombstones produces zero output
+        // files (see runMerge), so no fresh fileId is minted and the
+        // deleted inputs' seq/fileId watermark vanishes from disk. The
+        // manifest's persisted counters (stamped on every flush/compact,
+        // see VersionEdit.nextFileId/nextSeq) are the authoritative floor
+        // for exactly that case; take whichever recovery source is higher
+        // so this is purely additive safety, never a regression versus the
+        // scan-only behaviour this project already relied on.
+        const scanNextFileId = maxId + 1;
+        const scanNextSeq = maxSeq + 1;
+        const nextFileId = @max(scanNextFileId, opened.set.counters.nextFileId orelse 0);
+        const nextSeq = @max(scanNextSeq, opened.set.counters.nextSeq orelse 0);
+
         const dirPathCopy = try allocator.dupe(u8, dirPath);
 
         return .{
@@ -114,8 +135,10 @@ pub const Db = struct {
             .wal = wal,
             .sstables = sstables,
             .blockCache = BlockCache.init(allocator, options.blockCacheBytes),
-            .nextFileId = maxId + 1,
-            .nextSeq = maxSeq + 1,
+            .versionSet = opened.set,
+            .versionState = opened.state,
+            .nextFileId = nextFileId,
+            .nextSeq = nextSeq,
             .flushThreshold = options.flushThreshold,
             .l0Trigger = options.l0CompactionTrigger,
             .l1BaseBytes = options.l1BaseBytes,
@@ -132,6 +155,8 @@ pub const Db = struct {
         }
         self.sstables.deinit();
         self.blockCache.deinit();
+        self.versionSet.close();
+        self.versionState.deinit();
         self.memtable.deinit();
         self.dir.close();
         self.allocator.free(self.dirPath);
@@ -234,7 +259,14 @@ pub const Db = struct {
         self.nextFileId += 1;
         self.memtable.clear();
         try self.wal.reset();
-        try self.writeManifest();
+        _ = try walmod.bumpGeneration(self.dir);
+
+        var edit = VersionEdit.init(self.allocator);
+        defer edit.deinit();
+        try edit.addFile(fileId, 0);
+        edit.setNextFileId(self.nextFileId);
+        edit.setNextSeq(self.nextSeq);
+        try self.versionSet.logAndApply(&edit, &self.versionState);
         std.posix.fsync(self.dir.fd) catch {};
     }
 
@@ -254,7 +286,9 @@ pub const Db = struct {
         {
             var builder = try Builder.init(self.allocator, self.dir, name, expected);
             defer builder.deinit();
-            while (pickWinner(cursors)) |winner| {
+            var merger = try SstableMerger.init(self.allocator, cursors);
+            defer merger.deinit();
+            while (try merger.next()) |winner| {
                 if (winner.kind == .value) try builder.add(winner);
             }
             try builder.finish();
@@ -265,7 +299,10 @@ pub const Db = struct {
         reader.* = try Reader.open(self.allocator, self.dir, name, fileId);
         errdefer reader.deinit();
 
+        var edit = VersionEdit.init(self.allocator);
+        defer edit.deinit();
         for (self.sstables.items) |old| {
+            try edit.deleteFile(old.fileId);
             var oldNameBuf: [64]u8 = undefined;
             const oldName = sstName(&oldNameBuf, old.fileId) catch unreachable;
             old.deinit();
@@ -276,7 +313,10 @@ pub const Db = struct {
         reader.level = 0;
         try self.sstables.append(reader);
         self.nextFileId += 1;
-        try self.writeManifest();
+        try edit.addFile(fileId, 0);
+        edit.setNextFileId(self.nextFileId);
+        edit.setNextSeq(self.nextSeq);
+        try self.versionSet.logAndApply(&edit, &self.versionState);
         std.posix.fsync(self.dir.fd) catch {};
     }
 
@@ -365,7 +405,9 @@ pub const Db = struct {
         var outputName: [64]u8 = undefined;
         errdefer if (builder) |*b| b.deinit();
 
-        while (pickWinner(cursors)) |winner| {
+        var merger = try SstableMerger.init(self.allocator, cursors);
+        defer merger.deinit();
+        while (try merger.next()) |winner| {
             if (dropTombstones and winner.kind == .tombstone) continue;
             if (builder == null) {
                 outputId = self.nextFileId;
@@ -385,7 +427,10 @@ pub const Db = struct {
             try self.finishOutput(done, outputId, targetLevel, &outputs);
         }
 
+        var edit = VersionEdit.init(self.allocator);
+        defer edit.deinit();
         for (inputs) |old| {
+            try edit.deleteFile(old.fileId);
             self.removeReader(old);
             var oldNameBuf: [64]u8 = undefined;
             const oldName = sstName(&oldNameBuf, old.fileId) catch unreachable;
@@ -393,10 +438,21 @@ pub const Db = struct {
             self.allocator.destroy(old);
             self.dir.deleteFile(oldName) catch {};
         }
-        for (outputs.items) |produced| try self.sstables.append(produced);
+        for (outputs.items) |produced| {
+            try edit.addFile(produced.fileId, produced.level);
+            try self.sstables.append(produced);
+        }
         outputs.deinit();
 
-        try self.writeManifest();
+        // Stamped even when this round produced zero output files (every
+        // input was a dropped tombstone): that is exactly the case where no
+        // fresh fileId gets minted and a directory scan on the next restart
+        // could otherwise regress below the seq/fileId already consumed by
+        // the now-deleted inputs (see the comment on VersionEdit.nextFileId
+        // and Db.open's counter merge).
+        edit.setNextFileId(self.nextFileId);
+        edit.setNextSeq(self.nextSeq);
+        try self.versionSet.logAndApply(&edit, &self.versionState);
         std.posix.fsync(self.dir.fd) catch {};
     }
 
@@ -465,32 +521,6 @@ pub const Db = struct {
         return false;
     }
 
-    fn writeManifest(self: *Db) !void {
-        var buf = std.ArrayList(u8).init(self.allocator);
-        defer buf.deinit();
-        const bodyWriter = encode.ByteWriter.init(&buf);
-        try bodyWriter.putU32(@intCast(self.sstables.items.len));
-        for (self.sstables.items) |reader| {
-            try bodyWriter.putU64(reader.fileId);
-            try bodyWriter.putU32(@intCast(reader.level));
-        }
-
-        var frame = std.ArrayList(u8).init(self.allocator);
-        defer frame.deinit();
-        const frameWriter = encode.ByteWriter.init(&frame);
-        try frameWriter.putU32(encode.crc(buf.items));
-        try frameWriter.slice(buf.items);
-
-        const tmpName = "MANIFEST.tmp";
-        {
-            const file = try self.dir.createFile(tmpName, .{ .truncate = true });
-            defer file.close();
-            try file.writeAll(frame.items);
-            try file.sync();
-        }
-        try self.dir.rename(tmpName, manifestName);
-    }
-
     pub fn levelOf(self: *Db, fileId: u64) ?usize {
         for (self.sstables.items) |reader| {
             if (reader.fileId == fileId) return reader.level;
@@ -548,6 +578,12 @@ pub const Db = struct {
         cursors[0] = .{ .mem = self.memtable.cursor(options.start) };
         for (self.sstables.items, 0..) |reader, i| cursors[i + 1] = .{ .sst = reader.cursor(options.start) };
 
+        var mergeHeap = AscKeyHeap.init(allocator, {});
+        errdefer mergeHeap.deinit();
+        for (cursors, 0..) |*c, i| {
+            if (c.valid()) try mergeHeap.push(.{ .key = c.record().key, .idx = i });
+        }
+
         var startCopy: ?[]u8 = null;
         errdefer if (startCopy) |s| allocator.free(s);
         if (options.start) |bound| startCopy = try allocator.dupe(u8, bound);
@@ -558,6 +594,7 @@ pub const Db = struct {
             .resultAllocator = allocator,
             .arena = std.heap.ArenaAllocator.init(allocator),
             .cursors = cursors,
+            .heap = mergeHeap,
             .start = startCopy,
             .end = endCopy,
             .startInclusive = options.startInclusive,
@@ -596,6 +633,12 @@ pub const Db = struct {
             built += 1;
         }
 
+        var mergeHeap = DescKeyHeap.init(allocator, {});
+        errdefer mergeHeap.deinit();
+        for (cursors, 0..) |*c, i| {
+            if (c.valid()) try mergeHeap.push(.{ .key = c.record().key, .idx = i });
+        }
+
         var startCopy: ?[]u8 = null;
         if (options.start) |bound| startCopy = try allocator.dupe(u8, bound);
 
@@ -603,6 +646,7 @@ pub const Db = struct {
             .resultAllocator = allocator,
             .arena = std.heap.ArenaAllocator.init(allocator),
             .cursors = cursors,
+            .heap = mergeHeap,
             .start = startCopy,
             .startInclusive = options.startInclusive,
             .maxSeq = maxSeq,
@@ -678,30 +722,68 @@ const SourceCursor = union(enum) {
     }
 };
 
-fn pickWinner(cursors: []sstable.Cursor) ?Record {
-    var minKey: ?[]const u8 = null;
-    for (cursors) |*c| {
-        if (c.valid()) {
-            const key = c.record().key;
-            if (minKey == null or order(key, minKey.?) == .lt) minKey = key;
+/// One live position in a k-way merge: the key it currently points at
+/// (a snapshot valid for the underlying source's whole lifetime, since
+/// sstable/memtable cursors never overwrite already-decoded key bytes)
+/// plus the index of the source cursor it belongs to.
+const KeyedIndex = struct { key: []const u8, idx: usize };
+
+fn keyIndexLess(_: void, a: KeyedIndex, b: KeyedIndex) bool {
+    return order(a.key, b.key) == .lt;
+}
+fn keyIndexGreater(_: void, a: KeyedIndex, b: KeyedIndex) bool {
+    return order(a.key, b.key) == .gt;
+}
+
+/// Ascending k-way merge heap: root always holds the smallest live key.
+const AscKeyHeap = heap.MinHeap(KeyedIndex, void, keyIndexLess);
+/// Descending k-way merge heap: root always holds the largest live key.
+const DescKeyHeap = heap.MinHeap(KeyedIndex, void, keyIndexGreater);
+
+/// Merges N sorted sstable cursors (compaction inputs) in ascending key
+/// order using a binary heap: O(log N) per advance instead of the O(N)
+/// full rescan a naive linear-scan merge needs for every emitted record.
+/// Ties (same key present in several inputs) resolve to the entry with
+/// the highest seq, matching last-writer-wins semantics.
+const SstableMerger = struct {
+    cursors: []sstable.Cursor,
+    heap: AscKeyHeap,
+
+    fn init(allocator: Allocator, cursors: []sstable.Cursor) !SstableMerger {
+        var h = AscKeyHeap.init(allocator, {});
+        errdefer h.deinit();
+        for (cursors, 0..) |*c, i| {
+            if (c.valid()) try h.push(.{ .key = c.record().key, .idx = i });
         }
+        return .{ .cursors = cursors, .heap = h };
     }
-    if (minKey == null) return null;
-    var winner: ?Record = null;
-    for (cursors) |*c| {
-        if (c.valid() and order(c.record().key, minKey.?) == .eq) {
+
+    fn deinit(self: *SstableMerger) void {
+        self.heap.deinit();
+    }
+
+    fn next(self: *SstableMerger) !?Record {
+        const top = self.heap.peek() orelse return null;
+        const minKey = top.key;
+        var winner: ?Record = null;
+        while (self.heap.peek()) |entry| {
+            if (order(entry.key, minKey) != .eq) break;
+            const popped = self.heap.pop().?;
+            var c = &self.cursors[popped.idx];
             const rec = c.record();
             if (winner == null or rec.seq > winner.?.seq) winner = rec;
             c.advance();
+            if (c.valid()) try self.heap.push(.{ .key = c.record().key, .idx = popped.idx });
         }
+        return winner.?;
     }
-    return winner.?;
-}
+};
 
 pub const RangeIterator = struct {
     resultAllocator: Allocator,
     arena: std.heap.ArenaAllocator,
     cursors: []SourceCursor,
+    heap: AscKeyHeap,
     start: ?[]u8,
     end: ?[]u8,
     startInclusive: bool,
@@ -710,26 +792,22 @@ pub const RangeIterator = struct {
 
     pub fn next(self: *RangeIterator) !?Entry {
         while (true) {
-            var minKey: ?[]const u8 = null;
-            for (self.cursors) |*c| {
-                if (c.valid()) {
-                    const key = c.record().key;
-                    if (minKey == null or order(key, minKey.?) == .lt) minKey = key;
-                }
-            }
-            if (minKey == null) return null;
+            const top = self.heap.peek() orelse return null;
+            const minKey = top.key;
             if (self.end) |bound| {
-                const past = if (self.endInclusive) order(minKey.?, bound) == .gt else order(minKey.?, bound) != .lt;
+                const past = if (self.endInclusive) order(minKey, bound) == .gt else order(minKey, bound) != .lt;
                 if (past) return null;
             }
 
             var winner: ?Record = null;
-            for (self.cursors) |*c| {
-                if (c.valid() and order(c.record().key, minKey.?) == .eq) {
-                    const rec = c.record();
-                    if (rec.seq <= self.maxSeq and (winner == null or rec.seq > winner.?.seq)) winner = rec;
-                    c.advance();
-                }
+            while (self.heap.peek()) |entry| {
+                if (order(entry.key, minKey) != .eq) break;
+                const popped = self.heap.pop().?;
+                var c = &self.cursors[popped.idx];
+                const rec = c.record();
+                if (rec.seq <= self.maxSeq and (winner == null or rec.seq > winner.?.seq)) winner = rec;
+                c.advance();
+                if (c.valid()) try self.heap.push(.{ .key = c.record().key, .idx = popped.idx });
             }
             if (winner == null) continue;
             if (!self.startInclusive) {
@@ -749,6 +827,7 @@ pub const RangeIterator = struct {
 
     pub fn deinit(self: *RangeIterator) void {
         self.arena.deinit();
+        self.heap.deinit();
         if (self.start) |bound| self.resultAllocator.free(bound);
         if (self.end) |bound| self.resultAllocator.free(bound);
         self.resultAllocator.free(self.cursors);
@@ -792,32 +871,29 @@ pub const ReverseRangeIterator = struct {
     resultAllocator: Allocator,
     arena: std.heap.ArenaAllocator,
     cursors: []ReverseSource,
+    heap: DescKeyHeap,
     start: ?[]u8,
     startInclusive: bool,
     maxSeq: u64,
 
     pub fn next(self: *ReverseRangeIterator) !?Entry {
         while (true) {
-            var maxKey: ?[]const u8 = null;
-            for (self.cursors) |*c| {
-                if (c.valid()) {
-                    const key = c.record().key;
-                    if (maxKey == null or order(key, maxKey.?) == .gt) maxKey = key;
-                }
-            }
-            if (maxKey == null) return null;
+            const top = self.heap.peek() orelse return null;
+            const maxKey = top.key;
             if (self.start) |bound| {
-                const past = if (self.startInclusive) order(maxKey.?, bound) == .lt else order(maxKey.?, bound) != .gt;
+                const past = if (self.startInclusive) order(maxKey, bound) == .lt else order(maxKey, bound) != .gt;
                 if (past) return null;
             }
 
             var winner: ?Record = null;
-            for (self.cursors) |*c| {
-                if (c.valid() and order(c.record().key, maxKey.?) == .eq) {
-                    const rec = c.record();
-                    if (rec.seq <= self.maxSeq and (winner == null or rec.seq > winner.?.seq)) winner = rec;
-                    c.advance();
-                }
+            while (self.heap.peek()) |entry| {
+                if (order(entry.key, maxKey) != .eq) break;
+                const popped = self.heap.pop().?;
+                var c = &self.cursors[popped.idx];
+                const rec = c.record();
+                if (rec.seq <= self.maxSeq and (winner == null or rec.seq > winner.?.seq)) winner = rec;
+                c.advance();
+                if (c.valid()) try self.heap.push(.{ .key = c.record().key, .idx = popped.idx });
             }
             if (winner == null) continue;
             if (winner.?.kind == .tombstone) continue;
@@ -832,6 +908,7 @@ pub const ReverseRangeIterator = struct {
 
     pub fn deinit(self: *ReverseRangeIterator) void {
         self.arena.deinit();
+        self.heap.deinit();
         for (self.cursors) |*c| c.deinit();
         if (self.start) |bound| self.resultAllocator.free(bound);
         self.resultAllocator.free(self.cursors);
@@ -842,36 +919,6 @@ fn rangesOverlap(aMin: []const u8, aMax: []const u8, bMin: []const u8, bMax: []c
     return order(aMin, bMax) != .gt and order(bMin, aMax) != .gt;
 }
 
-fn loadManifest(allocator: Allocator, dir: std.fs.Dir) !std.AutoHashMap(u64, usize) {
-    var map = std.AutoHashMap(u64, usize).init(allocator);
-    errdefer map.deinit();
-
-    const file = dir.openFile(manifestName, .{}) catch |err| switch (err) {
-        error.FileNotFound => return map,
-        else => return err,
-    };
-    defer file.close();
-    const data = try file.readToEndAlloc(allocator, std.math.maxInt(usize));
-    defer allocator.free(data);
-    if (data.len < 8) return map;
-
-    const storedCrc = encode.readU32(data, 0);
-    const body = data[4..];
-    if (encode.crc(body) != storedCrc) return map;
-
-    const count = encode.readU32(body, 0);
-    var pos: usize = 4;
-    var i: u32 = 0;
-    while (i < count) : (i += 1) {
-        if (pos + 12 > body.len) break;
-        const fileId = encode.readU64(body, pos);
-        const level = encode.readU32(body, pos + 8);
-        try map.put(fileId, level);
-        pos += 12;
-    }
-    return map;
-}
-
 fn sstName(buf: []u8, id: u64) ![]const u8 {
     return std.fmt.bufPrint(buf, "sst-{d:0>10}.cbt", .{id});
 }
@@ -1234,6 +1281,67 @@ test "leveled compaction keeps levels disjoint and drops bottom tombstones" {
     try std.testing.expectEqual(@as(u64, 58), totalEntries);
 }
 
+test "seq and fileId counters survive a compaction that garbage-collects every key" {
+    // Reproduces a real recovery gap: when a bottom-level compaction merges
+    // inputs that are entirely tombstones, runMerge produces zero output
+    // files (see the `builder == null` guard around minting a fresh
+    // fileId). If every file that ever carried a high seq/fileId gets
+    // deleted in that round and nothing new gets flushed before a restart,
+    // a directory-scan-only recovery would compute too low a floor and
+    // risk reusing already-consumed seq numbers. The manifest's persisted
+    // counters (VersionEdit.nextFileId/nextSeq, stamped unconditionally in
+    // runMerge) must close that gap.
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var beforeNextSeq: u64 = 0;
+    var beforeNextFileId: u64 = 0;
+    {
+        var db = try openTemp(&tmp, allocator, .{
+            .l0CompactionTrigger = 2,
+            .l1BaseBytes = 4 * 1024 * 1024,
+        });
+        defer db.close();
+
+        var keyBuf: [16]u8 = undefined;
+        var round: usize = 0;
+        while (round < 2) : (round += 1) {
+            const key = try std.fmt.bufPrint(&keyBuf, "gone:{d}", .{round});
+            try db.put(key, "value");
+            try db.delete(key);
+            try db.flush();
+        }
+        try std.testing.expectEqual(@as(usize, 2), db.countLevel(0));
+
+        try db.maybeCompact();
+
+        // The whole point: every input was a dropped tombstone, so the
+        // compaction round produced no output file at all, and no new
+        // fileId was ever minted for it.
+        try std.testing.expectEqual(@as(usize, 0), db.sstables.items.len);
+
+        beforeNextSeq = db.nextSeq;
+        beforeNextFileId = db.nextFileId;
+        try std.testing.expect(beforeNextSeq > 1);
+    }
+
+    // On disk right now: no sstable files, an empty (reset) WAL. A
+    // scan-only recovery would compute nextSeq=1/nextFileId=1 here.
+    var reopened = try openTemp(&tmp, allocator, .{
+        .l0CompactionTrigger = 2,
+        .l1BaseBytes = 4 * 1024 * 1024,
+    });
+    defer reopened.close();
+    try std.testing.expectEqual(beforeNextSeq, reopened.nextSeq);
+    try std.testing.expectEqual(beforeNextFileId, reopened.nextFileId);
+
+    // Functional proof, not just counter equality: a fresh write after
+    // reopen must not reuse a seq number already spent on the GC'd keys.
+    try reopened.put("fresh", "value");
+    try std.testing.expect(reopened.nextSeq > beforeNextSeq);
+}
+
 fn lessByMinKey(_: void, a: *Reader, b: *Reader) bool {
     return order(a.minKey, b.minKey) == .lt;
 }
@@ -1309,6 +1417,56 @@ test "prefix scan isolates a namespace" {
     try std.testing.expectEqual(expected.len, idx);
 }
 
+test "scan merges a wide fan-in of uncompacted sstables with overlapping keys" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var db = try openTemp(&tmp, allocator, .{ .flushThreshold = 1 });
+    defer db.close();
+
+    const sstableCount = 14;
+    var round: usize = 0;
+    while (round < sstableCount) : (round += 1) {
+        var keyBuf: [16]u8 = undefined;
+        var valBuf: [24]u8 = undefined;
+        var i: usize = 0;
+        while (i < 5) : (i += 1) {
+            const key = try std.fmt.bufPrint(&keyBuf, "shared:{d:0>2}", .{i});
+            const value = try std.fmt.bufPrint(&valBuf, "round{d}", .{round});
+            try db.put(key, value);
+        }
+        try db.flush();
+    }
+    try db.delete("shared:02");
+    try db.flush();
+    try std.testing.expect(db.sstables.items.len >= sstableCount + 1);
+
+    var forward = try db.scan(allocator, null, null);
+    defer forward.deinit();
+    var seen: usize = 0;
+    while (try forward.next()) |entry| {
+        if (std.mem.eql(u8, entry.key, "shared:02")) {
+            try std.testing.expect(false);
+        }
+        try std.testing.expectEqualStrings("round13", entry.value);
+        seen += 1;
+    }
+    try std.testing.expectEqual(@as(usize, 4), seen);
+
+    var reverse = try db.scanReverse(allocator, .{});
+    defer reverse.deinit();
+    var revSeen: usize = 0;
+    var lastKey: ?[]const u8 = null;
+    while (try reverse.next()) |entry| {
+        if (lastKey) |prev| try std.testing.expect(order(entry.key, prev) == .lt);
+        lastKey = entry.key;
+        try std.testing.expectEqualStrings("round13", entry.value);
+        revSeen += 1;
+    }
+    try std.testing.expectEqual(@as(usize, 4), revSeen);
+}
+
 test "inclusive and exclusive bounds" {
     const allocator = std.testing.allocator;
     var tmp = std.testing.tmpDir(.{});
diff --git a/src/dump.zig b/src/dump.zig
new file mode 100644
index 0000000..c303864
--- /dev/null
+++ b/src/dump.zig
@@ -0,0 +1,596 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+const rowmod = @import("row.zig");
+const querymod = @import("query.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Value = rowmod.Value;
+const Field = rowmod.Field;
+const Table = querymod.Table;
+const pkField = querymod.pkField;
+
+/// Table export/import to CSV and JSON, the two data-interchange formats
+/// every other tool speaks. Rows are schema-less (`row.zig`'s `Row` is an
+/// ordered field list, not a fixed struct), so both formats use a shared
+/// "column set" step: scan once, then take the union of every field name
+/// seen across every row (first-seen order, primary key first) as the
+/// header/key set - a row missing a given column just omits that cell/key
+/// rather than writing an empty or null placeholder, which is what makes
+/// import's "cell absent" case unambiguous from "cell present but empty
+/// text" (`s:` with a zero-length payload is a real, distinct encoding).
+///
+/// Every cell/value is written as a type-tagged string (`i:`/`f:`/`b:`/
+/// `s:`/`x:`/`n:`, mirroring `Value.parseCli`'s prefixes plus `x:` for raw
+/// bytes and `n:` for `.none`) rather than native CSV numbers or JSON
+/// numbers/booleans - this is what lets both formats share one
+/// encode/decode pair and round-trip every `ValueTag` exactly, including
+/// floats (encoded as the exact bit pattern in hex, not a decimal that
+/// could lose precision on the way back in).
+fn encodeCell(allocator: Allocator, value: Value) ![]u8 {
+    return switch (value) {
+        .none => try allocator.dupe(u8, "n:"),
+        .boolean => |b| try allocator.dupe(u8, if (b) "b:true" else "b:false"),
+        .int => |v| try std.fmt.allocPrint(allocator, "i:{d}", .{v}),
+        .float => |v| try std.fmt.allocPrint(allocator, "f:{x}", .{@as(u64, @bitCast(v))}),
+        .text => |s| try std.fmt.allocPrint(allocator, "s:{s}", .{s}),
+        .bytes => |b| blk: {
+            var out = std.ArrayList(u8).init(allocator);
+            errdefer out.deinit();
+            try out.appendSlice("x:");
+            for (b) |byte| try out.writer().print("{x:0>2}", .{byte});
+            break :blk out.toOwnedSlice();
+        },
+    };
+}
+
+fn decodeCell(allocator: Allocator, text: []const u8) !Value {
+    if (text.len < 2 or text[1] != ':') return error.InvalidCell;
+    const payload = text[2..];
+    return switch (text[0]) {
+        'n' => .{ .none = {} },
+        'b' => if (std.mem.eql(u8, payload, "true"))
+            .{ .boolean = true }
+        else if (std.mem.eql(u8, payload, "false"))
+            .{ .boolean = false }
+        else
+            error.InvalidCell,
+        'i' => .{ .int = std.fmt.parseInt(i64, payload, 10) catch return error.InvalidCell },
+        'f' => blk: {
+            const bits = std.fmt.parseInt(u64, payload, 16) catch return error.InvalidCell;
+            break :blk .{ .float = @as(f64, @bitCast(bits)) };
+        },
+        's' => .{ .text = try allocator.dupe(u8, payload) },
+        'x' => blk: {
+            if (payload.len % 2 != 0) return error.InvalidCell;
+            const bytes = try allocator.alloc(u8, payload.len / 2);
+            errdefer allocator.free(bytes);
+            var i: usize = 0;
+            while (i < bytes.len) : (i += 1) {
+                bytes[i] = std.fmt.parseInt(u8, payload[i * 2 .. i * 2 + 2], 16) catch return error.InvalidCell;
+            }
+            break :blk .{ .bytes = bytes };
+        },
+        else => error.InvalidCell,
+    };
+}
+
+/// Union of every field name across `rows`, primary key first, everything
+/// else in first-seen order - the shared column list both CSV's header row
+/// and JSON's per-object keys iterate over.
+fn collectColumns(allocator: Allocator, rows: []const rowmod.Row) ![][]const u8 {
+    var columns = std.ArrayList([]const u8).init(allocator);
+    errdefer columns.deinit();
+    try columns.append(pkField);
+    for (rows) |r| {
+        for (r.fields.items) |f| {
+            if (std.mem.eql(u8, f.name, pkField)) continue;
+            var seen = false;
+            for (columns.items) |c| {
+                if (std.mem.eql(u8, c, f.name)) {
+                    seen = true;
+                    break;
+                }
+            }
+            if (!seen) try columns.append(f.name);
+        }
+    }
+    return columns.toOwnedSlice();
+}
+
+// ---------------------------------------------------------------- CSV -----
+
+fn writeCsvField(writer: anytype, field: []const u8) !void {
+    const needsQuote = std.mem.indexOfAny(u8, field, ",\"\r\n") != null;
+    if (!needsQuote) {
+        try writer.writeAll(field);
+        return;
+    }
+    try writer.writeByte('"');
+    for (field) |c| {
+        if (c == '"') try writer.writeByte('"');
+        try writer.writeByte(c);
+    }
+    try writer.writeByte('"');
+}
+
+pub fn exportCsvWriter(allocator: Allocator, table: *Table, writer: anytype) !usize {
+    const rows = try table.scanAll();
+    defer querymod.freeRows(allocator, rows);
+
+    const columns = try collectColumns(allocator, rows);
+    defer allocator.free(columns);
+
+    for (columns, 0..) |c, i| {
+        if (i > 0) try writer.writeByte(',');
+        try writeCsvField(writer, c);
+    }
+    try writer.writeByte('\n');
+
+    for (rows) |r| {
+        for (columns, 0..) |c, i| {
+            if (i > 0) try writer.writeByte(',');
+            if (r.get(c)) |v| {
+                const cell = try encodeCell(allocator, v);
+                defer allocator.free(cell);
+                try writeCsvField(writer, cell);
+            }
+        }
+        try writer.writeByte('\n');
+    }
+    return rows.len;
+}
+
+pub fn exportCsv(allocator: Allocator, table: *Table, path: []const u8) !usize {
+    const file = try std.fs.cwd().createFile(path, .{ .truncate = true });
+    defer file.close();
+    var buffered = std.io.bufferedWriter(file.writer());
+    const n = try exportCsvWriter(allocator, table, buffered.writer());
+    try buffered.flush();
+    return n;
+}
+
+/// A minimal RFC4180-shaped reader: comma-separated fields, `"..."`
+/// quoting with `""` as an escaped quote, records terminated by `\n` or
+/// `\r\n`. Fields are freshly allocated (never slices into `data`) so a
+/// quoted field's unescaped content can differ in length from its source
+/// bytes.
+const CsvReader = struct {
+    data: []const u8,
+    pos: usize = 0,
+
+    fn atEnd(self: *const CsvReader) bool {
+        return self.pos >= self.data.len;
+    }
+
+    fn readField(self: *CsvReader, allocator: Allocator) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        if (!self.atEnd() and self.data[self.pos] == '"') {
+            self.pos += 1;
+            while (true) {
+                if (self.atEnd()) return error.MalformedCsv;
+                const c = self.data[self.pos];
+                if (c == '"') {
+                    self.pos += 1;
+                    if (!self.atEnd() and self.data[self.pos] == '"') {
+                        try out.append('"');
+                        self.pos += 1;
+                    } else {
+                        break;
+                    }
+                } else {
+                    try out.append(c);
+                    self.pos += 1;
+                }
+            }
+        } else {
+            while (!self.atEnd()) {
+                const c = self.data[self.pos];
+                if (c == ',' or c == '\n' or c == '\r') break;
+                try out.append(c);
+                self.pos += 1;
+            }
+        }
+        return out.toOwnedSlice();
+    }
+
+    /// Returns the next record (list of owned field slices), or null at
+    /// end of input. Caller owns every field and the returned slice.
+    fn nextRecord(self: *CsvReader, allocator: Allocator) !?[][]u8 {
+        if (self.atEnd()) return null;
+        var fields = std.ArrayList([]u8).init(allocator);
+        errdefer {
+            for (fields.items) |f| allocator.free(f);
+            fields.deinit();
+        }
+
+        while (true) {
+            try fields.append(try self.readField(allocator));
+            if (self.atEnd()) break;
+            const c = self.data[self.pos];
+            if (c == ',') {
+                self.pos += 1;
+                continue;
+            } else if (c == '\n') {
+                self.pos += 1;
+                break;
+            } else if (c == '\r') {
+                self.pos += 1;
+                if (!self.atEnd() and self.data[self.pos] == '\n') self.pos += 1;
+                break;
+            }
+            return error.MalformedCsv;
+        }
+        return try fields.toOwnedSlice();
+    }
+};
+
+pub fn importCsvContent(allocator: Allocator, table: *Table, content: []const u8) !usize {
+    var csv = CsvReader{ .data = content };
+    const header = try csv.nextRecord(allocator) orelse return 0;
+    defer {
+        for (header) |h| allocator.free(h);
+        allocator.free(header);
+    }
+
+    var pkIndex: ?usize = null;
+    for (header, 0..) |h, i| {
+        if (std.mem.eql(u8, h, pkField)) {
+            pkIndex = i;
+            break;
+        }
+    }
+    const pkIdx = pkIndex orelse return error.MissingPrimaryKey;
+
+    var count: usize = 0;
+    while (try csv.nextRecord(allocator)) |record| {
+        defer {
+            for (record) |f| allocator.free(f);
+            allocator.free(record);
+        }
+        if (record.len != header.len) return error.MalformedCsv;
+
+        var pk: ?Value = null;
+        defer if (pk) |p| p.free(allocator);
+        var fields = std.ArrayList(Field).init(allocator);
+        defer {
+            for (fields.items) |f| f.value.free(allocator);
+            fields.deinit();
+        }
+
+        for (record, 0..) |cell, i| {
+            if (cell.len == 0) continue;
+            const value = try decodeCell(allocator, cell);
+            if (i == pkIdx) {
+                pk = value;
+            } else {
+                try fields.append(.{ .name = header[i], .value = value });
+            }
+        }
+        const pkValue = pk orelse return error.MissingPrimaryKey;
+        try table.put(pkValue, fields.items);
+        count += 1;
+    }
+    return count;
+}
+
+pub fn importCsv(allocator: Allocator, table: *Table, path: []const u8) !usize {
+    const content = try std.fs.cwd().readFileAlloc(allocator, path, 1 << 30);
+    defer allocator.free(content);
+    return importCsvContent(allocator, table, content);
+}
+
+// --------------------------------------------------------------- JSON -----
+
+pub fn exportJsonWriter(allocator: Allocator, table: *Table, writer: anytype) !usize {
+    const rows = try table.scanAll();
+    defer querymod.freeRows(allocator, rows);
+
+    const columns = try collectColumns(allocator, rows);
+    defer allocator.free(columns);
+
+    var arena = std.heap.ArenaAllocator.init(allocator);
+    defer arena.deinit();
+    const arenaAllocator = arena.allocator();
+
+    var array = std.json.Array.init(arenaAllocator);
+    for (rows) |r| {
+        var object = std.json.ObjectMap.init(arenaAllocator);
+        for (columns) |c| {
+            if (r.get(c)) |v| {
+                const cell = try encodeCell(arenaAllocator, v);
+                try object.put(c, .{ .string = cell });
+            }
+        }
+        try array.append(.{ .object = object });
+    }
+
+    try std.json.stringify(std.json.Value{ .array = array }, .{ .whitespace = .indent_2 }, writer);
+    try writer.writeByte('\n');
+    return rows.len;
+}
+
+pub fn exportJson(allocator: Allocator, table: *Table, path: []const u8) !usize {
+    const file = try std.fs.cwd().createFile(path, .{ .truncate = true });
+    defer file.close();
+    var buffered = std.io.bufferedWriter(file.writer());
+    const n = try exportJsonWriter(allocator, table, buffered.writer());
+    try buffered.flush();
+    return n;
+}
+
+pub fn importJsonContent(allocator: Allocator, table: *Table, content: []const u8) !usize {
+    var parsed = std.json.parseFromSlice(std.json.Value, allocator, content, .{}) catch return error.MalformedJson;
+    defer parsed.deinit();
+
+    const array = switch (parsed.value) {
+        .array => |a| a,
+        else => return error.MalformedJson,
+    };
+
+    var count: usize = 0;
+    for (array.items) |entry| {
+        const object = switch (entry) {
+            .object => |o| o,
+            else => return error.MalformedJson,
+        };
+
+        var pk: ?Value = null;
+        defer if (pk) |p| p.free(allocator);
+        var fields = std.ArrayList(Field).init(allocator);
+        defer {
+            for (fields.items) |f| f.value.free(allocator);
+            fields.deinit();
+        }
+
+        for (object.keys(), object.values()) |name, jv| {
+            const cell = switch (jv) {
+                .string => |s| s,
+                else => return error.MalformedJson,
+            };
+            const value = try decodeCell(allocator, cell);
+            if (std.mem.eql(u8, name, pkField)) {
+                pk = value;
+            } else {
+                try fields.append(.{ .name = name, .value = value });
+            }
+        }
+        const pkValue = pk orelse return error.MissingPrimaryKey;
+        try table.put(pkValue, fields.items);
+        count += 1;
+    }
+    return count;
+}
+
+pub fn importJson(allocator: Allocator, table: *Table, path: []const u8) !usize {
+    const content = try std.fs.cwd().readFileAlloc(allocator, path, 1 << 30);
+    defer allocator.free(content);
+    return importJsonContent(allocator, table, content);
+}
+
+// --------------------------------------------------------------- tests ----
+
+const testing = std.testing;
+
+test "encodeCell decodeCell round trip every value tag" {
+    const allocator = testing.allocator;
+    const values = [_]Value{
+        .{ .none = {} },
+        .{ .boolean = true },
+        .{ .boolean = false },
+        .{ .int = -42 },
+        .{ .int = 0 },
+        .{ .float = 3.5 },
+        .{ .float = -0.001 },
+        .{ .text = "hello, \"world\"\n" },
+        .{ .text = "" },
+        .{ .bytes = &.{ 0, 1, 2, 255 } },
+    };
+    for (values) |v| {
+        const cell = try encodeCell(allocator, v);
+        defer allocator.free(cell);
+        const decoded = try decodeCell(allocator, cell);
+        defer decoded.free(allocator);
+        try testing.expectEqual(@as(rowmod.ValueTag, v), @as(rowmod.ValueTag, decoded));
+        try testing.expect(Value.eql(v, decoded));
+    }
+}
+
+test "decodeCell rejects malformed cells" {
+    const allocator = testing.allocator;
+    try testing.expectError(error.InvalidCell, decodeCell(allocator, ""));
+    try testing.expectError(error.InvalidCell, decodeCell(allocator, "x"));
+    try testing.expectError(error.InvalidCell, decodeCell(allocator, "q:1"));
+    try testing.expectError(error.InvalidCell, decodeCell(allocator, "i:notanumber"));
+    try testing.expectError(error.InvalidCell, decodeCell(allocator, "b:maybe"));
+    try testing.expectError(error.InvalidCell, decodeCell(allocator, "x:abc"));
+    try testing.expectError(error.InvalidCell, decodeCell(allocator, "x:zz"));
+}
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+    return Db.open(allocator, dbPath, .{});
+}
+
+fn seedTable(table: *Table) !void {
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+        .{ .name = "active", .value = .{ .boolean = true } },
+    });
+    try table.put(.{ .int = 2 }, &.{
+        .{ .name = "city", .value = .{ .text = "krakow, poland \"old town\"\nsecond line" } },
+        .{ .name = "score", .value = .{ .float = -12.5 } },
+    });
+    try table.put(.{ .int = 3 }, &.{});
+}
+
+fn expectRoundTripped(table: *Table) !void {
+    var r1 = (try table.get(.{ .int = 1 })).?;
+    defer r1.deinit();
+    try testing.expectEqualStrings("warsaw", r1.get("city").?.text);
+    try testing.expectEqual(@as(i64, 30), r1.get("age").?.int);
+    try testing.expectEqual(true, r1.get("active").?.boolean);
+
+    var r2 = (try table.get(.{ .int = 2 })).?;
+    defer r2.deinit();
+    try testing.expectEqualStrings("krakow, poland \"old town\"\nsecond line", r2.get("city").?.text);
+    try testing.expectEqual(@as(f64, -12.5), r2.get("score").?.float);
+    try testing.expect(r2.get("age") == null);
+
+    // Row 3 was put with zero extra fields, so its only field is the
+    // primary key itself (`put` always stores that under `pkField`).
+    var r3 = (try table.get(.{ .int = 3 })).?;
+    defer r3.deinit();
+    try testing.expectEqual(@as(usize, 1), r3.count());
+    try testing.expectEqual(@as(i64, 3), r3.get(pkField).?.int);
+}
+
+test "csv export then import round trips every row and field exactly" {
+    const allocator = testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+    try seedTable(&table);
+
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const exported = try exportCsvWriter(allocator, &table, buf.writer());
+    try testing.expectEqual(@as(usize, 3), exported);
+
+    var dstTmp = std.testing.tmpDir(.{});
+    defer dstTmp.cleanup();
+    var dstDb = try openTemp(&dstTmp, allocator);
+    defer dstDb.close();
+    var dstTable = try Table.open(&dstDb, allocator, "people");
+    defer dstTable.deinit();
+
+    const imported = try importCsvContent(allocator, &dstTable, buf.items);
+    try testing.expectEqual(@as(usize, 3), imported);
+
+    try expectRoundTripped(&dstTable);
+}
+
+test "json export then import round trips every row and field exactly" {
+    const allocator = testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+    try seedTable(&table);
+
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const exported = try exportJsonWriter(allocator, &table, buf.writer());
+    try testing.expectEqual(@as(usize, 3), exported);
+
+    var dstTmp = std.testing.tmpDir(.{});
+    defer dstTmp.cleanup();
+    var dstDb = try openTemp(&dstTmp, allocator);
+    defer dstDb.close();
+    var dstTable = try Table.open(&dstDb, allocator, "people");
+    defer dstTable.deinit();
+
+    const imported = try importJsonContent(allocator, &dstTable, buf.items);
+    try testing.expectEqual(@as(usize, 3), imported);
+
+    try expectRoundTripped(&dstTable);
+}
+
+test "csv export of an empty table is just a header row and imports back to zero rows" {
+    const allocator = testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var table = try Table.open(&db, allocator, "empty");
+    defer table.deinit();
+
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const exported = try exportCsvWriter(allocator, &table, buf.writer());
+    try testing.expectEqual(@as(usize, 0), exported);
+    try testing.expectEqualStrings("__pk\n", buf.items);
+
+    const imported = try importCsvContent(allocator, &table, buf.items);
+    try testing.expectEqual(@as(usize, 0), imported);
+}
+
+test "csv import rejects a header without the primary key column" {
+    const allocator = testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+
+    try testing.expectError(error.MissingPrimaryKey, importCsvContent(allocator, &table, "city\ns:warsaw\n"));
+}
+
+test "csv import rejects a record whose field count does not match the header" {
+    const allocator = testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+
+    try testing.expectError(error.MalformedCsv, importCsvContent(allocator, &table, "__pk,city\ni:1,s:warsaw,s:extra\n"));
+}
+
+test "json import rejects a non-array root and a non-string cell value" {
+    const allocator = testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+
+    try testing.expectError(error.MalformedJson, importJsonContent(allocator, &table, "{}"));
+    try testing.expectError(error.MalformedJson, importJsonContent(allocator, &table, "[{\"__pk\": 1}]"));
+}
+
+test "export csv and json to real files then import from real files round trips" {
+    const allocator = testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+    try seedTable(&table);
+
+    const csvPath = "test-dump-people.csv";
+    const jsonPath = "test-dump-people.json";
+    defer std.fs.cwd().deleteFile(csvPath) catch {};
+    defer std.fs.cwd().deleteFile(jsonPath) catch {};
+
+    try testing.expectEqual(@as(usize, 3), try exportCsv(allocator, &table, csvPath));
+    try testing.expectEqual(@as(usize, 3), try exportJson(allocator, &table, jsonPath));
+
+    var dstTmp = std.testing.tmpDir(.{});
+    defer dstTmp.cleanup();
+    var dstDb = try openTemp(&dstTmp, allocator);
+    defer dstDb.close();
+    var csvTable = try Table.open(&dstDb, allocator, "from_csv");
+    defer csvTable.deinit();
+    var jsonTable = try Table.open(&dstDb, allocator, "from_json");
+    defer jsonTable.deinit();
+
+    try testing.expectEqual(@as(usize, 3), try importCsv(allocator, &csvTable, csvPath));
+    try testing.expectEqual(@as(usize, 3), try importJson(allocator, &jsonTable, jsonPath));
+    try expectRoundTripped(&csvTable);
+    try expectRoundTripped(&jsonTable);
+}
diff --git a/src/expr.zig b/src/expr.zig
new file mode 100644
index 0000000..06acd10
--- /dev/null
+++ b/src/expr.zig
@@ -0,0 +1,567 @@
+const std = @import("std");
+const rowmod = @import("row.zig");
+const idx = @import("index.zig");
+const querymod = @import("query.zig");
+const dbmod = @import("db.zig");
+
+const Allocator = std.mem.Allocator;
+const Predicate = querymod.Predicate;
+const Condition = querymod.Condition;
+
+/// Errors a caller can act on when a `table select` expression is rejected.
+/// Parsing never panics on malformed input - every failure mode a user can
+/// trigger from the CLI maps to one of these.
+pub const ParseError = error{
+    UnexpectedToken,
+    UnexpectedEnd,
+    InvalidIdentifier,
+    UnknownOperator,
+    InvalidValue,
+} || Allocator.Error;
+
+/// Owns every allocation a parsed Predicate tree depends on (field-name and
+/// text-value copies, and_/or_ slices, not_ boxes) in one arena, so freeing
+/// is a single `deinit()` regardless of how deep the tree is.
+pub const Parsed = struct {
+    arena: std.heap.ArenaAllocator,
+    predicate: Predicate,
+
+    pub fn deinit(self: *Parsed) void {
+        self.arena.deinit();
+    }
+};
+
+const TokenKind = enum { lparen, rparen, word, eof };
+
+const Token = struct {
+    kind: TokenKind,
+    text: []const u8,
+};
+
+const Lexer = struct {
+    src: []const u8,
+    pos: usize = 0,
+
+    fn next(self: *Lexer) Token {
+        while (self.pos < self.src.len and std.ascii.isWhitespace(self.src[self.pos])) : (self.pos += 1) {}
+        if (self.pos >= self.src.len) return .{ .kind = .eof, .text = "" };
+
+        const c = self.src[self.pos];
+        if (c == '(') {
+            self.pos += 1;
+            return .{ .kind = .lparen, .text = "(" };
+        }
+        if (c == ')') {
+            self.pos += 1;
+            return .{ .kind = .rparen, .text = ")" };
+        }
+
+        const start = self.pos;
+        while (self.pos < self.src.len) {
+            const ch = self.src[self.pos];
+            if (std.ascii.isWhitespace(ch) or ch == '(' or ch == ')') break;
+            self.pos += 1;
+        }
+        return .{ .kind = .word, .text = self.src[start..self.pos] };
+    }
+};
+
+fn isKeyword(tok: Token, kw: []const u8) bool {
+    return tok.kind == .word and std.mem.eql(u8, tok.text, kw);
+}
+
+/// Recursive-descent parser for the `table select` predicate language:
+///
+///   expr    := and ("or" and)*
+///   and     := unary ("and" unary)*
+///   unary   := "not" unary | primary
+///   primary := "(" expr ")" | field op value | field ("is_null" | "is_not_null")
+///   op      := eq | ne | lt | lte | gt | gte | like
+///
+/// Precedence (loosest to tightest) is or < and < not, matching every other
+/// C-family boolean expression language, so `a eq 1 or b eq 2 and not c eq 3`
+/// parses as `a eq 1 or (b eq 2 and (not (c eq 3)))`.
+const Parser = struct {
+    lexer: Lexer,
+    allocator: Allocator,
+    cur: Token,
+
+    fn advance(self: *Parser) void {
+        self.cur = self.lexer.next();
+    }
+
+    fn parseOr(self: *Parser) ParseError!Predicate {
+        var list = std.ArrayList(Predicate).init(self.allocator);
+        try list.append(try self.parseAnd());
+        while (isKeyword(self.cur, "or")) {
+            self.advance();
+            try list.append(try self.parseAnd());
+        }
+        if (list.items.len == 1) return list.items[0];
+        return .{ .or_ = try list.toOwnedSlice() };
+    }
+
+    fn parseAnd(self: *Parser) ParseError!Predicate {
+        var list = std.ArrayList(Predicate).init(self.allocator);
+        try list.append(try self.parseUnary());
+        while (isKeyword(self.cur, "and")) {
+            self.advance();
+            try list.append(try self.parseUnary());
+        }
+        if (list.items.len == 1) return list.items[0];
+        return .{ .and_ = try list.toOwnedSlice() };
+    }
+
+    fn parseUnary(self: *Parser) ParseError!Predicate {
+        if (isKeyword(self.cur, "not")) {
+            self.advance();
+            const inner = try self.parseUnary();
+            const boxed = try self.allocator.create(Predicate);
+            boxed.* = inner;
+            return .{ .not_ = boxed };
+        }
+        return self.parsePrimary();
+    }
+
+    fn parsePrimary(self: *Parser) ParseError!Predicate {
+        if (self.cur.kind == .lparen) {
+            self.advance();
+            const inner = try self.parseOr();
+            if (self.cur.kind != .rparen) return error.UnexpectedToken;
+            self.advance();
+            return inner;
+        }
+        return self.parseCondition();
+    }
+
+    fn parseCondition(self: *Parser) ParseError!Predicate {
+        if (self.cur.kind != .word) return if (self.cur.kind == .eof) error.UnexpectedEnd else error.UnexpectedToken;
+        const field = self.cur.text;
+        if (!idx.validIdentifier(field)) return error.InvalidIdentifier;
+        const fieldCopy = try self.allocator.dupe(u8, field);
+        self.advance();
+
+        if (self.cur.kind != .word) return error.UnexpectedEnd;
+        const op = self.cur.text;
+        self.advance();
+
+        if (std.mem.eql(u8, op, "in")) return self.parseIn(fieldCopy);
+        if (std.mem.eql(u8, op, "between")) return self.parseBetween(fieldCopy);
+        if (std.mem.eql(u8, op, "is_null")) return .{ .is_null = fieldCopy };
+        if (std.mem.eql(u8, op, "is_not_null")) return .{ .is_not_null = fieldCopy };
+
+        if (self.cur.kind != .word) return error.UnexpectedEnd;
+        const rawValue = rowmod.Value.parseCli(self.cur.text) catch return error.InvalidValue;
+        const value = try rawValue.dupe(self.allocator);
+        self.advance();
+
+        const cond = Condition{ .field = fieldCopy, .value = value };
+        if (std.mem.eql(u8, op, "eq")) return .{ .eq = cond };
+        if (std.mem.eql(u8, op, "ne")) return .{ .ne = cond };
+        if (std.mem.eql(u8, op, "lt")) return .{ .lt = cond };
+        if (std.mem.eql(u8, op, "lte")) return .{ .lte = cond };
+        if (std.mem.eql(u8, op, "gt")) return .{ .gt = cond };
+        if (std.mem.eql(u8, op, "gte")) return .{ .gte = cond };
+        if (std.mem.eql(u8, op, "like")) {
+            if (value != .text) return error.InvalidValue;
+            return .{ .like = cond };
+        }
+        return error.UnknownOperator;
+    }
+
+    /// `field in (v1 v2 ...)`: desugars to an `or_` of per-value `eq`
+    /// leaves against the same field, sharing the one field-name copy the
+    /// caller already made (Condition never owns `field`, so aliasing it
+    /// across every leaf is safe). A single value collapses to a bare `eq`
+    /// leaf, the same collapse `parseAnd`/`parseOr` already do for a
+    /// one-element and/or chain - lets a one-value `in` use an index like
+    /// `eq` does, since `findIndexableLeaf`/`findCompositeMatch` never look
+    /// inside `or_`. An empty list, `field in ()`, is not a syntax error:
+    /// it desugars to an `or_` over zero leaves, which `Predicate.evaluate`
+    /// already folds to `false` for an empty `preds` slice - matching SQL's
+    /// "IN () is always false" without a special case here.
+    fn parseIn(self: *Parser, field: []const u8) ParseError!Predicate {
+        if (self.cur.kind != .lparen) return if (self.cur.kind == .eof) error.UnexpectedEnd else error.UnexpectedToken;
+        self.advance();
+
+        var list = std.ArrayList(Predicate).init(self.allocator);
+        while (self.cur.kind != .rparen) {
+            if (self.cur.kind != .word) return if (self.cur.kind == .eof) error.UnexpectedEnd else error.UnexpectedToken;
+            const rawValue = rowmod.Value.parseCli(self.cur.text) catch return error.InvalidValue;
+            const value = try rawValue.dupe(self.allocator);
+            self.advance();
+            try list.append(.{ .eq = .{ .field = field, .value = value } });
+        }
+        self.advance();
+
+        if (list.items.len == 1) return list.items[0];
+        return .{ .or_ = try list.toOwnedSlice() };
+    }
+
+    /// `field between lo and hi`: desugars to `field gte lo and field lte
+    /// hi` (inclusive both ends, matching SQL BETWEEN). The `and` here is
+    /// consumed as part of this leaf's own grammar, not the outer
+    /// `parseAnd` binary connective, so it never nests a further `and_`
+    /// level - by the time control returns to the caller, `self.cur` is
+    /// whatever token follows `hi` (rparen/eof/"and"/"or"), decided purely
+    /// by having advanced past every token this leaf owns.
+    fn parseBetween(self: *Parser, field: []const u8) ParseError!Predicate {
+        if (self.cur.kind != .word) return error.UnexpectedEnd;
+        const rawLow = rowmod.Value.parseCli(self.cur.text) catch return error.InvalidValue;
+        const low = try rawLow.dupe(self.allocator);
+        self.advance();
+
+        if (!isKeyword(self.cur, "and")) return if (self.cur.kind == .eof) error.UnexpectedEnd else error.UnexpectedToken;
+        self.advance();
+
+        if (self.cur.kind != .word) return error.UnexpectedEnd;
+        const rawHigh = rowmod.Value.parseCli(self.cur.text) catch return error.InvalidValue;
+        const high = try rawHigh.dupe(self.allocator);
+        self.advance();
+
+        const bounds = try self.allocator.alloc(Predicate, 2);
+        bounds[0] = .{ .gte = .{ .field = field, .value = low } };
+        bounds[1] = .{ .lte = .{ .field = field, .value = high } };
+        return .{ .and_ = bounds };
+    }
+};
+
+/// Parses a full `table select` predicate expression, e.g.
+/// `city eq s:warsaw and (age gte i:30 or not age lt i:10)`. The returned
+/// Parsed owns every slice/pointer the Predicate tree references - `text`
+/// itself does not need to outlive the call.
+pub fn parse(backing: Allocator, text: []const u8) ParseError!Parsed {
+    var arena = std.heap.ArenaAllocator.init(backing);
+    errdefer arena.deinit();
+    const allocator = arena.allocator();
+
+    var p = Parser{ .lexer = .{ .src = text }, .allocator = allocator, .cur = undefined };
+    p.cur = p.lexer.next();
+
+    const pred = try p.parseOr();
+    if (p.cur.kind != .eof) return error.UnexpectedToken;
+
+    return .{ .arena = arena, .predicate = pred };
+}
+
+fn evalStr(allocator: Allocator, text: []const u8, row: *const rowmod.Row) !bool {
+    var parsed = try parse(allocator, text);
+    defer parsed.deinit();
+    return parsed.predicate.evaluate(row);
+}
+
+test "parses a single condition" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("city", .{ .text = "warsaw" });
+
+    try std.testing.expect(try evalStr(allocator, "city eq s:warsaw", &row));
+    try std.testing.expect(!try evalStr(allocator, "city eq s:krakow", &row));
+}
+
+test "and binds tighter than or" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("a", .{ .int = 1 });
+    try row.set("b", .{ .int = 2 });
+    try row.set("c", .{ .int = 99 });
+
+    // a eq 1 or b eq 2 and c eq 3  ==  (a eq 1) or ((b eq 2) and (c eq 3))
+    // b eq 2 is true but c eq 3 is false, so the and-branch is false; the
+    // overall result must still be true because of the leading `a eq 1`.
+    try std.testing.expect(try evalStr(allocator, "a eq i:1 or b eq i:2 and c eq i:3", &row));
+
+    var row2 = rowmod.Row.init(allocator);
+    defer row2.deinit();
+    try row2.set("a", .{ .int = 0 });
+    try row2.set("b", .{ .int = 2 });
+    try row2.set("c", .{ .int = 99 });
+    try std.testing.expect(!try evalStr(allocator, "a eq i:1 or b eq i:2 and c eq i:3", &row2));
+}
+
+test "parentheses override default precedence" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("a", .{ .int = 0 });
+    try row.set("b", .{ .int = 2 });
+    try row.set("c", .{ .int = 5 });
+
+    // (a eq 1 or b eq 2) and c eq 5 - forces the or to evaluate before and.
+    try std.testing.expect(try evalStr(allocator, "(a eq i:1 or b eq i:2) and c eq i:5", &row));
+    try std.testing.expect(!try evalStr(allocator, "(a eq i:1 or b eq i:2) and c eq i:6", &row));
+}
+
+test "not negates the following term" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("age", .{ .int = 20 });
+
+    try std.testing.expect(try evalStr(allocator, "not age eq i:10", &row));
+    try std.testing.expect(!try evalStr(allocator, "not age eq i:20", &row));
+    try std.testing.expect(!try evalStr(allocator, "not (age eq i:10 or age eq i:20)", &row));
+}
+
+test "nested parentheses and multiple not" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("x", .{ .int = 5 });
+
+    try std.testing.expect(try evalStr(allocator, "not not x eq i:5", &row));
+    try std.testing.expect(try evalStr(allocator, "((x eq i:5))", &row));
+}
+
+test "range and inequality operators parse and evaluate" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("score", .{ .int = 42 });
+
+    try std.testing.expect(try evalStr(allocator, "score gt i:10", &row));
+    try std.testing.expect(try evalStr(allocator, "score gte i:42", &row));
+    try std.testing.expect(try evalStr(allocator, "score lt i:100", &row));
+    try std.testing.expect(try evalStr(allocator, "score lte i:42", &row));
+    try std.testing.expect(try evalStr(allocator, "score ne i:0", &row));
+}
+
+test "like matches SQL-style wildcards and rejects non-text patterns" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("name", .{ .text = "Ada Lovelace" });
+    try row.set("age", .{ .int = 36 });
+
+    try std.testing.expect(try evalStr(allocator, "name like s:Ada%", &row));
+    try std.testing.expect(try evalStr(allocator, "name like s:%Lovelace", &row));
+    try std.testing.expect(try evalStr(allocator, "name like s:%Love%", &row));
+    try std.testing.expect(!try evalStr(allocator, "name like s:Boris%", &row));
+    // like against a non-text row field never matches, it does not error.
+    try std.testing.expect(!try evalStr(allocator, "age like s:3%", &row));
+    // like combines with and/or/not/parens exactly like every other operator.
+    try std.testing.expect(try evalStr(allocator, "name like s:Ada% and age eq i:36", &row));
+    try std.testing.expect(!try evalStr(allocator, "not name like s:Ada%", &row));
+
+    try std.testing.expectError(error.InvalidValue, parse(allocator, "name like i:5"));
+}
+
+test "is_null matches a row missing the field, is_not_null matches a row that has it" {
+    const allocator = std.testing.allocator;
+    var withCity = rowmod.Row.init(allocator);
+    defer withCity.deinit();
+    try withCity.set("city", .{ .text = "warsaw" });
+
+    var withoutCity = rowmod.Row.init(allocator);
+    defer withoutCity.deinit();
+    try withoutCity.set("age", .{ .int = 30 });
+
+    try std.testing.expect(!try evalStr(allocator, "city is_null", &withCity));
+    try std.testing.expect(try evalStr(allocator, "city is_not_null", &withCity));
+    try std.testing.expect(try evalStr(allocator, "city is_null", &withoutCity));
+    try std.testing.expect(!try evalStr(allocator, "city is_not_null", &withoutCity));
+}
+
+test "is_null treats an explicit Value.none the same as a missing field" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("nickname", .{ .none = {} });
+
+    try std.testing.expect(try evalStr(allocator, "nickname is_null", &row));
+    try std.testing.expect(!try evalStr(allocator, "nickname is_not_null", &row));
+}
+
+test "is_null and is_not_null take no trailing value and combine with and/or/not" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("age", .{ .int = 30 });
+
+    try std.testing.expect(try evalStr(allocator, "city is_null and age eq i:30", &row));
+    try std.testing.expect(!try evalStr(allocator, "city is_not_null or age eq i:99", &row));
+    try std.testing.expect(try evalStr(allocator, "not city is_not_null", &row));
+
+    var parsed = try parse(allocator, "city is_null");
+    defer parsed.deinit();
+    try std.testing.expect(parsed.predicate == .is_null);
+    try std.testing.expectEqualStrings("city", parsed.predicate.is_null);
+}
+
+test "field name copy and value copy outlive the source text" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("name", .{ .text = "ada" });
+
+    var buf: [64]u8 = undefined;
+    const src = try std.fmt.bufPrint(&buf, "name eq s:ada", .{});
+    var parsed = try parse(allocator, src);
+    // Overwrite the source buffer entirely: if the parser had kept slices
+    // into `src` instead of arena-owned copies, this would corrupt the
+    // predicate's field name/value in place.
+    @memset(&buf, 'X');
+    try std.testing.expect(parsed.predicate.evaluate(&row));
+    parsed.deinit();
+}
+
+test "rejects malformed expressions" {
+    const allocator = std.testing.allocator;
+    try std.testing.expectError(error.UnexpectedEnd, parse(allocator, "age eq"));
+    try std.testing.expectError(error.UnexpectedEnd, parse(allocator, "age"));
+    try std.testing.expectError(error.UnknownOperator, parse(allocator, "age foo i:1"));
+    try std.testing.expectError(error.InvalidValue, parse(allocator, "age eq i:notanumber"));
+    try std.testing.expectError(error.UnexpectedToken, parse(allocator, "(age eq i:1"));
+    try std.testing.expectError(error.UnexpectedToken, parse(allocator, "age eq i:1)"));
+    try std.testing.expectError(error.UnexpectedEnd, parse(allocator, ""));
+    try std.testing.expectError(error.UnexpectedToken, parse(allocator, "age eq i:1 age eq i:2"));
+}
+
+test "in matches any value in the list" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("city", .{ .text = "krakow" });
+
+    try std.testing.expect(try evalStr(allocator, "city in (s:warsaw s:krakow s:gdansk)", &row));
+    try std.testing.expect(!try evalStr(allocator, "city in (s:warsaw s:gdansk)", &row));
+    // Empty list is always false, mirroring SQL's `IN ()`.
+    try std.testing.expect(!try evalStr(allocator, "city in ()", &row));
+    // Combines with and/or/not/parens like every other operator.
+    try std.testing.expect(try evalStr(allocator, "city in (s:krakow) and not city eq s:warsaw", &row));
+    try std.testing.expect(!try evalStr(allocator, "not city in (s:warsaw s:krakow)", &row));
+}
+
+test "in with a single value collapses to a bare eq leaf" {
+    const allocator = std.testing.allocator;
+    var parsed = try parse(allocator, "city in (s:warsaw)");
+    defer parsed.deinit();
+    try std.testing.expect(parsed.predicate == .eq);
+    try std.testing.expectEqualStrings("city", parsed.predicate.eq.field);
+}
+
+test "between is inclusive on both ends" {
+    const allocator = std.testing.allocator;
+    var row = rowmod.Row.init(allocator);
+    defer row.deinit();
+    try row.set("age", .{ .int = 30 });
+
+    try std.testing.expect(try evalStr(allocator, "age between i:30 and i:40", &row));
+    try std.testing.expect(try evalStr(allocator, "age between i:20 and i:30", &row));
+    try std.testing.expect(!try evalStr(allocator, "age between i:31 and i:40", &row));
+    try std.testing.expect(!try evalStr(allocator, "age between i:10 and i:29", &row));
+    // Combines with and/or/not/parens, and the leaf's own "and" does not
+    // leak into the outer and/or grammar as a second top-level conjunct.
+    try std.testing.expect(try evalStr(allocator, "age between i:25 and i:35 and age ne i:0", &row));
+    try std.testing.expect(!try evalStr(allocator, "not age between i:25 and i:35", &row));
+}
+
+test "between desugars to a two-leaf and_ of gte/lte" {
+    const allocator = std.testing.allocator;
+    var parsed = try parse(allocator, "age between i:1 and i:2");
+    defer parsed.deinit();
+    try std.testing.expect(parsed.predicate == .and_);
+    try std.testing.expectEqual(@as(usize, 2), parsed.predicate.and_.len);
+    try std.testing.expect(parsed.predicate.and_[0] == .gte);
+    try std.testing.expect(parsed.predicate.and_[1] == .lte);
+}
+
+test "in and between reject malformed input" {
+    const allocator = std.testing.allocator;
+    try std.testing.expectError(error.UnexpectedToken, parse(allocator, "city in s:warsaw"));
+    try std.testing.expectError(error.UnexpectedEnd, parse(allocator, "city in (s:warsaw"));
+    try std.testing.expectError(error.InvalidValue, parse(allocator, "age in (i:notanumber)"));
+    try std.testing.expectError(error.UnexpectedEnd, parse(allocator, "age between i:1"));
+    try std.testing.expectError(error.UnexpectedToken, parse(allocator, "age between i:1 or i:2"));
+    try std.testing.expectError(error.InvalidValue, parse(allocator, "age between i:1 and i:notanumber"));
+}
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !dbmod.Db {
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+    return dbmod.Db.open(allocator, dbPath, .{});
+}
+
+test "a single-value in reaches Table.select through an index like eq does" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try querymod.Table.open(&db, allocator, "cities");
+    defer table.deinit();
+    try table.createIndex("city");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "oslo" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "bergen" } }});
+
+    var parsed = try parse(allocator, "city in (s:oslo)");
+    defer parsed.deinit();
+
+    var plan = try table.explain(allocator, parsed.predicate);
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.index_eq, plan.kind);
+    try std.testing.expectEqualStrings("city", plan.indexName.?);
+
+    const results = try table.select(parsed.predicate);
+    defer querymod.freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 1), results.len);
+    try std.testing.expectEqual(@as(i64, 1), results[0].get(querymod.pkField).?.int);
+}
+
+test "a multi-value in falls back to a full scan and still matches every listed value" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try querymod.Table.open(&db, allocator, "cities");
+    defer table.deinit();
+    try table.createIndex("city");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "oslo" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "bergen" } }});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "city", .value = .{ .text = "trondheim" } }});
+
+    var parsed = try parse(allocator, "city in (s:oslo s:trondheim)");
+    defer parsed.deinit();
+
+    var plan = try table.explain(allocator, parsed.predicate);
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.full_scan, plan.kind);
+
+    const results = try table.select(parsed.predicate);
+    defer querymod.freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 2), results.len);
+}
+
+test "between reaches Table.select through an index range like gte/lte does" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try querymod.Table.open(&db, allocator, "people");
+    defer table.deinit();
+    try table.createIndex("age");
+    var i: i64 = 0;
+    while (i < 10) : (i += 1) {
+        try table.put(.{ .int = i }, &.{.{ .name = "age", .value = .{ .int = i * 10 } }});
+    }
+
+    var parsed = try parse(allocator, "age between i:20 and i:50");
+    defer parsed.deinit();
+
+    var plan = try table.explain(allocator, parsed.predicate);
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.index_range, plan.kind);
+    try std.testing.expectEqualStrings("age", plan.indexName.?);
+
+    const results = try table.select(parsed.predicate);
+    defer querymod.freeRows(allocator, results);
+    // ages 20, 30, 40, 50 - inclusive both ends.
+    try std.testing.expectEqual(@as(usize, 4), results.len);
+}
diff --git a/src/heap.zig b/src/heap.zig
new file mode 100644
index 0000000..8a02873
--- /dev/null
+++ b/src/heap.zig
@@ -0,0 +1,265 @@
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+
+/// Binary heap ordered by `lessThan(context, a, b)`: parent never compares
+/// greater than either child under that relation. Pass a comparator that
+/// returns `a > b` to get a max-heap out of the same implementation.
+pub fn MinHeap(comptime T: type, comptime Context: type, comptime lessThan: fn (context: Context, a: T, b: T) bool) type {
+    return struct {
+        items: std.ArrayList(T),
+        context: Context,
+
+        const Self = @This();
+
+        pub fn init(allocator: Allocator, context: Context) Self {
+            return .{ .items = std.ArrayList(T).init(allocator), .context = context };
+        }
+
+        pub fn deinit(self: *Self) void {
+            self.items.deinit();
+        }
+
+        pub fn len(self: *const Self) usize {
+            return self.items.items.len;
+        }
+
+        pub fn peek(self: *const Self) ?T {
+            if (self.items.items.len == 0) return null;
+            return self.items.items[0];
+        }
+
+        pub fn push(self: *Self, item: T) !void {
+            try self.items.append(item);
+            self.siftUp(self.items.items.len - 1);
+        }
+
+        pub fn pop(self: *Self) ?T {
+            if (self.items.items.len == 0) return null;
+            const top = self.items.items[0];
+            const last = self.items.pop();
+            if (self.items.items.len > 0) {
+                self.items.items[0] = last;
+                self.siftDown(0);
+            }
+            return top;
+        }
+
+        /// Swap the root for `item` and restore the heap property in one
+        /// siftDown, instead of a pop() (siftDown) followed by a push()
+        /// (siftUp). Caller must ensure the heap is non-empty.
+        pub fn replaceTop(self: *Self, item: T) T {
+            const old = self.items.items[0];
+            self.items.items[0] = item;
+            self.siftDown(0);
+            return old;
+        }
+
+        fn siftUp(self: *Self, startIdx: usize) void {
+            var idx = startIdx;
+            while (idx > 0) {
+                const parent = (idx - 1) / 2;
+                if (!lessThan(self.context, self.items.items[idx], self.items.items[parent])) break;
+                std.mem.swap(T, &self.items.items[idx], &self.items.items[parent]);
+                idx = parent;
+            }
+        }
+
+        fn siftDown(self: *Self, startIdx: usize) void {
+            var idx = startIdx;
+            const n = self.items.items.len;
+            while (true) {
+                const left = idx * 2 + 1;
+                const right = idx * 2 + 2;
+                var smallest = idx;
+                if (left < n and lessThan(self.context, self.items.items[left], self.items.items[smallest])) smallest = left;
+                if (right < n and lessThan(self.context, self.items.items[right], self.items.items[smallest])) smallest = right;
+                if (smallest == idx) break;
+                std.mem.swap(T, &self.items.items[idx], &self.items.items[smallest]);
+                idx = smallest;
+            }
+        }
+
+        /// Debug helper: verifies the heap invariant holds at every node.
+        pub fn isValid(self: *const Self) bool {
+            const n = self.items.items.len;
+            var idx: usize = 0;
+            while (idx < n) : (idx += 1) {
+                const left = idx * 2 + 1;
+                const right = idx * 2 + 2;
+                if (left < n and lessThan(self.context, self.items.items[left], self.items.items[idx])) return false;
+                if (right < n and lessThan(self.context, self.items.items[right], self.items.items[idx])) return false;
+            }
+            return true;
+        }
+    };
+}
+
+fn u32Less(_: void, a: u32, b: u32) bool {
+    return a < b;
+}
+const U32Heap = MinHeap(u32, void, u32Less);
+
+test "heap: empty peek/pop return null" {
+    var heap = U32Heap.init(std.testing.allocator, {});
+    defer heap.deinit();
+    try std.testing.expectEqual(@as(?u32, null), heap.peek());
+    try std.testing.expectEqual(@as(?u32, null), heap.pop());
+    try std.testing.expectEqual(@as(usize, 0), heap.len());
+}
+
+test "heap: push/pop yields ascending order" {
+    var heap = U32Heap.init(std.testing.allocator, {});
+    defer heap.deinit();
+    const values = [_]u32{ 5, 1, 9, 3, 3, 7, 0, 42, 2 };
+    for (values) |v| try heap.push(v);
+    try std.testing.expectEqual(values.len, heap.len());
+
+    var sorted = values;
+    std.mem.sort(u32, &sorted, {}, std.sort.asc(u32));
+
+    for (sorted) |expected| {
+        try std.testing.expectEqual(@as(?u32, expected), heap.peek());
+        try std.testing.expectEqual(@as(?u32, expected), heap.pop());
+    }
+    try std.testing.expectEqual(@as(usize, 0), heap.len());
+}
+
+test "heap: peek does not remove" {
+    var heap = U32Heap.init(std.testing.allocator, {});
+    defer heap.deinit();
+    try heap.push(10);
+    try heap.push(4);
+    try std.testing.expectEqual(@as(?u32, 4), heap.peek());
+    try std.testing.expectEqual(@as(?u32, 4), heap.peek());
+    try std.testing.expectEqual(@as(usize, 2), heap.len());
+}
+
+test "heap: replaceTop matches pop-then-push" {
+    var a = U32Heap.init(std.testing.allocator, {});
+    defer a.deinit();
+    var b = U32Heap.init(std.testing.allocator, {});
+    defer b.deinit();
+    for ([_]u32{ 8, 2, 6, 1, 9 }) |v| {
+        try a.push(v);
+        try b.push(v);
+    }
+
+    const old = a.replaceTop(5);
+    try std.testing.expectEqual(@as(u32, 1), old);
+    _ = b.pop();
+    try b.push(5);
+
+    while (a.len() > 0) {
+        try std.testing.expectEqual(a.pop().?, b.pop().?);
+    }
+}
+
+test "heap: random stress matches sort reference and stays valid" {
+    var prng = std.Random.DefaultPrng.init(0xC0BA17);
+    const random = prng.random();
+    var heap = U32Heap.init(std.testing.allocator, {});
+    defer heap.deinit();
+
+    var reference = std.ArrayList(u32).init(std.testing.allocator);
+    defer reference.deinit();
+
+    var i: usize = 0;
+    while (i < 500) : (i += 1) {
+        const v = random.intRangeAtMost(u32, 0, 1000);
+        try heap.push(v);
+        try reference.append(v);
+        try std.testing.expect(heap.isValid());
+    }
+
+    std.mem.sort(u32, reference.items, {}, std.sort.asc(u32));
+    for (reference.items) |expected| {
+        try std.testing.expectEqual(@as(?u32, expected), heap.pop());
+        try std.testing.expect(heap.isValid());
+    }
+    try std.testing.expectEqual(@as(usize, 0), heap.len());
+}
+
+test "heap: interleaved push and pop stays valid" {
+    var prng = std.Random.DefaultPrng.init(0xFEED);
+    const random = prng.random();
+    var heap = U32Heap.init(std.testing.allocator, {});
+    defer heap.deinit();
+
+    var count: usize = 0;
+    var i: usize = 0;
+    while (i < 2000) : (i += 1) {
+        if (count == 0 or random.boolean()) {
+            try heap.push(random.intRangeAtMost(u32, 0, 100));
+            count += 1;
+        } else {
+            const popped = heap.pop();
+            try std.testing.expect(popped != null);
+            count -= 1;
+        }
+        try std.testing.expect(heap.isValid());
+        try std.testing.expectEqual(count, heap.len());
+    }
+}
+
+fn descU32(_: void, a: u32, b: u32) bool {
+    return a > b;
+}
+const MaxU32Heap = MinHeap(u32, void, descU32);
+
+test "heap: inverted comparator behaves as a max-heap" {
+    var heap = MaxU32Heap.init(std.testing.allocator, {});
+    defer heap.deinit();
+    for ([_]u32{ 3, 1, 4, 1, 5, 9, 2, 6 }) |v| try heap.push(v);
+
+    var sorted = [_]u32{ 3, 1, 4, 1, 5, 9, 2, 6 };
+    std.mem.sort(u32, &sorted, {}, std.sort.desc(u32));
+    for (sorted) |expected| try std.testing.expectEqual(@as(?u32, expected), heap.pop());
+}
+
+const Weighted = struct { key: []const u8, seq: u32 };
+
+fn keyLess(_: void, a: Weighted, b: Weighted) bool {
+    return std.mem.order(u8, a.key, b.key) == .lt;
+}
+const KeyHeap = MinHeap(Weighted, void, keyLess);
+
+test "heap: k-way merge of pre-sorted lists matches full sort" {
+    const allocator = std.testing.allocator;
+    const lists = [_][]const []const u8{
+        &[_][]const u8{ "apple", "cherry", "fig", "kiwi" },
+        &[_][]const u8{ "banana", "date", "eggplant" },
+        &[_][]const u8{"lemon"},
+        &[_][]const u8{},
+    };
+
+    const Cursor = struct { list: []const []const u8, idx: usize };
+    var cursors: [lists.len]Cursor = undefined;
+    for (lists, 0..) |list, i| cursors[i] = .{ .list = list, .idx = 0 };
+
+    var heap = KeyHeap.init(allocator, {});
+    defer heap.deinit();
+    for (cursors, 0..) |c, i| {
+        if (c.idx < c.list.len) try heap.push(.{ .key = c.list[c.idx], .seq = @intCast(i) });
+    }
+
+    var merged = std.ArrayList([]const u8).init(allocator);
+    defer merged.deinit();
+    while (heap.pop()) |top| {
+        try merged.append(top.key);
+        var c = &cursors[top.seq];
+        c.idx += 1;
+        if (c.idx < c.list.len) try heap.push(.{ .key = c.list[c.idx], .seq = top.seq });
+    }
+
+    var expected = std.ArrayList([]const u8).init(allocator);
+    defer expected.deinit();
+    for (lists) |list| try expected.appendSlice(list);
+    std.mem.sort([]const u8, expected.items, {}, struct {
+        fn lt(_: void, a: []const u8, b: []const u8) bool {
+            return std.mem.order(u8, a, b) == .lt;
+        }
+    }.lt);
+
+    try std.testing.expectEqual(expected.items.len, merged.items.len);
+    for (expected.items, merged.items) |e, m| try std.testing.expectEqualStrings(e, m);
+}
diff --git a/src/index.zig b/src/index.zig
new file mode 100644
index 0000000..13bac6d
--- /dev/null
+++ b/src/index.zig
@@ -0,0 +1,1937 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+const row = @import("row.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Value = row.Value;
+
+/// Keyspace layout shared by every table and index living inside a single
+/// Db instance:
+///   "R\x00" table "\x00" orderedPk                 -> encoded Row
+///   "I\x00" table "\x00" field "\x00" orderedValue orderedPk -> encoded pk Value
+///   "J\x00" table "\x00" indexName "\x00" orderedValue1 .. orderedValueN orderedPk -> encoded pk Value
+///   "M\x00INDEXES\x00" table                        -> encoded list of indexed field names
+///   "M\x00CINDEXES\x00" table                       -> encoded list of composite index specs
+///   "M\x00UNIQUE\x00" table                         -> encoded list of UNIQUE-constrained field names
+///   "M\x00FKEYS\x00" table                          -> encoded list of FOREIGN KEY specs (field, refTable, refField)
+///   "M\x00CHECKS\x00" table                         -> encoded list of CHECK constraint specs (name, expr source)
+///   "M\x00REFBY\x00" table                          -> encoded list of reverse FK specs (childTable, childField, refField),
+///                                                       one entry per OTHER table's FOREIGN KEY that names this table+refField
+///
+/// All namespaces share one flat LSM keyspace (there is only one Db), so the
+/// leading tag byte plus NUL separators keep tables, single-field indexes,
+/// composite indexes, and metadata from ever colliding or shadowing each
+/// other during a scan. A composite index entry's value columns are just N
+/// single-column `row.appendOrdered` encodings concatenated in the index's
+/// declared field order ahead of the primary key's - each encoding is
+/// already self-delimiting (fixed width for none/boolean/int/float, a
+/// 0x00 0x00 terminator for text/bytes with 0x00 bytes escaped), so the
+/// concatenation compares byte-for-byte in exactly the same order as
+/// comparing the value tuples component by component. That is what makes a
+/// prefix scan over the leading K of N components ("leftmost prefix" rule,
+/// same as a real multi-column B-tree index) a correct equality lookup on
+/// just those K columns, unconstrained on the rest.
+pub const rowTag: u8 = 'R';
+pub const indexTag: u8 = 'I';
+pub const compositeIndexTag: u8 = 'J';
+pub const metaTag: u8 = 'M';
+const sep: u8 = 0x00;
+
+fn appendSegment(out: *std.ArrayList(u8), segment: []const u8) !void {
+    try out.appendSlice(segment);
+    try out.append(sep);
+}
+
+pub fn rowPrefix(allocator: Allocator, table: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(rowTag);
+    try appendSegment(&out, table);
+    return out.toOwnedSlice();
+}
+
+pub fn rowKey(allocator: Allocator, table: []const u8, pk: Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(rowTag);
+    try appendSegment(&out, table);
+    try row.appendOrdered(&out, pk);
+    return out.toOwnedSlice();
+}
+
+pub fn indexPrefix(allocator: Allocator, table: []const u8, field: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(indexTag);
+    try appendSegment(&out, table);
+    try appendSegment(&out, field);
+    return out.toOwnedSlice();
+}
+
+pub fn indexEntryKey(allocator: Allocator, table: []const u8, field: []const u8, value: Value, pk: Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(indexTag);
+    try appendSegment(&out, table);
+    try appendSegment(&out, field);
+    try row.appendOrdered(&out, value);
+    try row.appendOrdered(&out, pk);
+    return out.toOwnedSlice();
+}
+
+pub fn indexValueBound(allocator: Allocator, table: []const u8, field: []const u8, value: Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(indexTag);
+    try appendSegment(&out, table);
+    try appendSegment(&out, field);
+    try row.appendOrdered(&out, value);
+    return out.toOwnedSlice();
+}
+
+fn metaKey(allocator: Allocator, table: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(metaTag);
+    try appendSegment(&out, "INDEXES");
+    try out.appendSlice(table);
+    return out.toOwnedSlice();
+}
+
+fn compositeMetaKey(allocator: Allocator, table: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(metaTag);
+    try appendSegment(&out, "CINDEXES");
+    try out.appendSlice(table);
+    return out.toOwnedSlice();
+}
+
+fn uniqueMetaKey(allocator: Allocator, table: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(metaTag);
+    try appendSegment(&out, "UNIQUE");
+    try out.appendSlice(table);
+    return out.toOwnedSlice();
+}
+
+fn foreignKeyMetaKey(allocator: Allocator, table: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(metaTag);
+    try appendSegment(&out, "FKEYS");
+    try out.appendSlice(table);
+    return out.toOwnedSlice();
+}
+
+fn checkMetaKey(allocator: Allocator, table: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(metaTag);
+    try appendSegment(&out, "CHECKS");
+    try out.appendSlice(table);
+    return out.toOwnedSlice();
+}
+
+fn referencedByMetaKey(allocator: Allocator, table: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(metaTag);
+    try appendSegment(&out, "REFBY");
+    try out.appendSlice(table);
+    return out.toOwnedSlice();
+}
+
+pub fn compositeIndexPrefix(allocator: Allocator, table: []const u8, indexName: []const u8) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(compositeIndexTag);
+    try appendSegment(&out, table);
+    try appendSegment(&out, indexName);
+    return out.toOwnedSlice();
+}
+
+pub fn compositeIndexEntryKey(allocator: Allocator, table: []const u8, indexName: []const u8, values: []const Value, pk: Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(compositeIndexTag);
+    try appendSegment(&out, table);
+    try appendSegment(&out, indexName);
+    for (values) |v| try row.appendOrdered(&out, v);
+    try row.appendOrdered(&out, pk);
+    return out.toOwnedSlice();
+}
+
+/// Bound for a leftmost-prefix scan of a composite index: `values.len` may
+/// be less than the index's full column count, in which case the scan
+/// matches every entry whose leading columns equal `values` regardless of
+/// what the remaining (unconstrained) columns hold - see the module-level
+/// keyspace comment for why the concatenation makes this a correct prefix.
+pub fn compositeIndexValueBound(allocator: Allocator, table: []const u8, indexName: []const u8, values: []const Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(compositeIndexTag);
+    try appendSegment(&out, table);
+    try appendSegment(&out, indexName);
+    for (values) |v| try row.appendOrdered(&out, v);
+    return out.toOwnedSlice();
+}
+
+/// Bound for a composite index scan that pins `eqValues` as the leading
+/// columns (leftmost prefix, same as `compositeIndexValueBound`) and then
+/// appends one more ordered value for a range condition on the very next
+/// column - the byte-extension argument from the module-level keyspace
+/// comment applies here exactly as it does for a bare `indexValueBound`, so
+/// `scanCompositeRangeCursor` can reuse the same inclusive/exclusive
+/// gap trick `scanRangeCursor` uses for single-field indexes.
+fn compositeIndexRangeBound(allocator: Allocator, table: []const u8, indexName: []const u8, eqValues: []const Value, extra: Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(compositeIndexTag);
+    try appendSegment(&out, table);
+    try appendSegment(&out, indexName);
+    for (eqValues) |v| try row.appendOrdered(&out, v);
+    try row.appendOrdered(&out, extra);
+    return out.toOwnedSlice();
+}
+
+/// Smallest byte string strictly greater than every string with `prefix` as
+/// a prefix, used as the exclusive upper bound of a prefix scan. Returns
+/// null when the prefix is all 0xFF bytes (unbounded above, e.g. empty
+/// table/field names never hit this in practice).
+pub fn prefixUpperBound(allocator: Allocator, prefix: []const u8) !?[]u8 {
+    var end = prefix.len;
+    while (end > 0 and prefix[end - 1] == 0xff) end -= 1;
+    if (end == 0) return null;
+    const upper = try allocator.alloc(u8, end);
+    @memcpy(upper, prefix[0..end]);
+    upper[end - 1] += 1;
+    return upper;
+}
+
+/// Whether a table name or field name is safe to embed as a NUL-delimited
+/// keyspace segment: table/field identifiers may not themselves contain
+/// NUL bytes or they would corrupt the segment boundaries above.
+pub fn validIdentifier(name: []const u8) bool {
+    if (name.len == 0) return false;
+    for (name) |c| {
+        if (c == sep) return false;
+    }
+    return true;
+}
+
+/// Persisted set of field names that have a secondary index on a table.
+/// Loaded once per Table.open and written back to the Db's metadata
+/// namespace whenever an index is created or dropped, so indexes survive
+/// process restarts without any external schema file.
+pub const IndexSet = struct {
+    allocator: Allocator,
+    fields: std.ArrayList([]u8),
+
+    pub fn load(allocator: Allocator, db: *Db, table: []const u8) !IndexSet {
+        const key = try metaKey(allocator, table);
+        defer allocator.free(key);
+
+        var set = IndexSet{ .allocator = allocator, .fields = std.ArrayList([]u8).init(allocator) };
+        errdefer set.deinit();
+
+        const raw = try db.get(allocator, key) orelse return set;
+        defer allocator.free(raw);
+
+        var pos: usize = 0;
+        if (pos + 4 > raw.len) return error.Malformed;
+        const count = std.mem.readInt(u32, raw[pos..][0..4], .little);
+        pos += 4;
+        var i: u32 = 0;
+        while (i < count) : (i += 1) {
+            if (pos + 4 > raw.len) return error.Malformed;
+            const len = std.mem.readInt(u32, raw[pos..][0..4], .little);
+            pos += 4;
+            if (pos + len > raw.len) return error.Malformed;
+            const name = try allocator.dupe(u8, raw[pos .. pos + len]);
+            pos += len;
+            try set.fields.append(name);
+        }
+        return set;
+    }
+
+    pub fn save(self: *const IndexSet, db: *Db, table: []const u8) !void {
+        const key = try metaKey(self.allocator, table);
+        defer self.allocator.free(key);
+
+        var out = std.ArrayList(u8).init(self.allocator);
+        defer out.deinit();
+        var countBuf: [4]u8 = undefined;
+        std.mem.writeInt(u32, &countBuf, @intCast(self.fields.items.len), .little);
+        try out.appendSlice(&countBuf);
+        for (self.fields.items) |name| {
+            var lenBuf: [4]u8 = undefined;
+            std.mem.writeInt(u32, &lenBuf, @intCast(name.len), .little);
+            try out.appendSlice(&lenBuf);
+            try out.appendSlice(name);
+        }
+        try db.put(key, out.items);
+    }
+
+    pub fn has(self: *const IndexSet, field: []const u8) bool {
+        for (self.fields.items) |f| {
+            if (std.mem.eql(u8, f, field)) return true;
+        }
+        return false;
+    }
+
+    pub fn add(self: *IndexSet, field: []const u8) !void {
+        if (self.has(field)) return;
+        const copy = try self.allocator.dupe(u8, field);
+        try self.fields.append(copy);
+    }
+
+    /// Returns true if the field was present and has been removed.
+    pub fn remove(self: *IndexSet, field: []const u8) bool {
+        for (self.fields.items, 0..) |f, i| {
+            if (std.mem.eql(u8, f, field)) {
+                self.allocator.free(f);
+                _ = self.fields.orderedRemove(i);
+                return true;
+            }
+        }
+        return false;
+    }
+
+    pub fn deinit(self: *IndexSet) void {
+        for (self.fields.items) |f| self.allocator.free(f);
+        self.fields.deinit();
+    }
+};
+
+/// Persisted set of field names carrying a UNIQUE constraint on a table -
+/// same on-disk shape as `IndexSet` (own meta key, own namespace), kept as
+/// a separate type because the two sets have different invariants: every
+/// member of `UniqueSet` is also required to be a member of the table's
+/// `IndexSet` (enforced by `Table.createUniqueIndex`/`Table.dropIndex`),
+/// since `Table.put` detects a colliding value by reusing the field's
+/// regular index entries via `scanEq` rather than a full table scan - a
+/// unique field with no backing index would make every write pay for a
+/// full scan just to check the constraint.
+pub const UniqueSet = struct {
+    allocator: Allocator,
+    fields: std.ArrayList([]u8),
+
+    pub fn load(allocator: Allocator, db: *Db, table: []const u8) !UniqueSet {
+        const key = try uniqueMetaKey(allocator, table);
+        defer allocator.free(key);
+
+        var set = UniqueSet{ .allocator = allocator, .fields = std.ArrayList([]u8).init(allocator) };
+        errdefer set.deinit();
+
+        const raw = try db.get(allocator, key) orelse return set;
+        defer allocator.free(raw);
+
+        var pos: usize = 0;
+        if (pos + 4 > raw.len) return error.Malformed;
+        const count = std.mem.readInt(u32, raw[pos..][0..4], .little);
+        pos += 4;
+        var i: u32 = 0;
+        while (i < count) : (i += 1) {
+            if (pos + 4 > raw.len) return error.Malformed;
+            const len = std.mem.readInt(u32, raw[pos..][0..4], .little);
+            pos += 4;
+            if (pos + len > raw.len) return error.Malformed;
+            const name = try allocator.dupe(u8, raw[pos .. pos + len]);
+            pos += len;
+            try set.fields.append(name);
+        }
+        return set;
+    }
+
+    pub fn save(self: *const UniqueSet, db: *Db, table: []const u8) !void {
+        const key = try uniqueMetaKey(self.allocator, table);
+        defer self.allocator.free(key);
+
+        var out = std.ArrayList(u8).init(self.allocator);
+        defer out.deinit();
+        var countBuf: [4]u8 = undefined;
+        std.mem.writeInt(u32, &countBuf, @intCast(self.fields.items.len), .little);
+        try out.appendSlice(&countBuf);
+        for (self.fields.items) |name| {
+            var lenBuf: [4]u8 = undefined;
+            std.mem.writeInt(u32, &lenBuf, @intCast(name.len), .little);
+            try out.appendSlice(&lenBuf);
+            try out.appendSlice(name);
+        }
+        try db.put(key, out.items);
+    }
+
+    pub fn has(self: *const UniqueSet, field: []const u8) bool {
+        for (self.fields.items) |f| {
+            if (std.mem.eql(u8, f, field)) return true;
+        }
+        return false;
+    }
+
+    pub fn add(self: *UniqueSet, field: []const u8) !void {
+        if (self.has(field)) return;
+        const copy = try self.allocator.dupe(u8, field);
+        try self.fields.append(copy);
+    }
+
+    /// Returns true if the field was present and has been removed.
+    pub fn remove(self: *UniqueSet, field: []const u8) bool {
+        for (self.fields.items, 0..) |f, i| {
+            if (std.mem.eql(u8, f, field)) {
+                self.allocator.free(f);
+                _ = self.fields.orderedRemove(i);
+                return true;
+            }
+        }
+        return false;
+    }
+
+    pub fn deinit(self: *UniqueSet) void {
+        for (self.fields.items) |f| self.allocator.free(f);
+        self.fields.deinit();
+    }
+};
+
+/// One FOREIGN KEY constraint: `field` on the owning table must, on every
+/// row where it is present and non-none, name a value that exists as
+/// `refField` on `refTable` (SQL's `FOREIGN KEY (field) REFERENCES
+/// refTable(refField)`). `refField` is either `query.pkField` (the
+/// referenced table's primary key, checked via a plain `get`) or a field
+/// carrying its own UNIQUE constraint on `refTable` (checked via `scanEq`) -
+/// `Table.createForeignKey` requires one of the two before installing,
+/// exactly like a real database refusing a foreign key against a column
+/// with no unique/primary-key backing, since otherwise "the value exists"
+/// would not pin down a single unambiguous parent row.
+/// SQL's `ON DELETE` clause: what a FOREIGN KEY does when the row it points
+/// at is deleted. `restrict` (the SQL default, and this codebase's only
+/// behavior before cascading deletes existed) refuses the delete outright
+/// while a referencing row still exists; `cascade` instead deletes every
+/// referencing row too, recursively (a cascaded child can itself have
+/// dependents), before the parent row itself is removed. Stored as a plain
+/// byte in `ForeignKeySpec`/`ReferencedBySpec` rather than a bare bool so a
+/// third mode (e.g. `set_null`) can be added later without another format
+/// bump.
+pub const OnDelete = enum(u8) {
+    restrict = 0,
+    cascade = 1,
+};
+
+fn onDeleteFromByte(b: u8) !OnDelete {
+    return switch (b) {
+        0 => .restrict,
+        1 => .cascade,
+        else => error.Malformed,
+    };
+}
+
+pub const ForeignKeySpec = struct {
+    field: []u8,
+    refTable: []u8,
+    refField: []u8,
+    onDelete: OnDelete,
+};
+
+/// Persisted set of FOREIGN KEY constraints on a table, at most one per
+/// owning field - same on-disk shape family as `IndexSet`/`UniqueSet` (own
+/// meta key, own namespace) but each entry carries two extra strings
+/// (`refTable`/`refField`) plus an `onDelete` mode byte instead of being a
+/// bare field name.
+pub const ForeignKeySet = struct {
+    allocator: Allocator,
+    specs: std.ArrayList(ForeignKeySpec),
+
+    pub fn load(allocator: Allocator, db: *Db, table: []const u8) !ForeignKeySet {
+        const key = try foreignKeyMetaKey(allocator, table);
+        defer allocator.free(key);
+
+        var set = ForeignKeySet{ .allocator = allocator, .specs = std.ArrayList(ForeignKeySpec).init(allocator) };
+        errdefer set.deinit();
+
+        const raw = try db.get(allocator, key) orelse return set;
+        defer allocator.free(raw);
+
+        var pos: usize = 0;
+        if (pos + 4 > raw.len) return error.Malformed;
+        const count = std.mem.readInt(u32, raw[pos..][0..4], .little);
+        pos += 4;
+        var i: u32 = 0;
+        while (i < count) : (i += 1) {
+            const field = try readLenPrefixed(allocator, raw, &pos);
+            errdefer allocator.free(field);
+            const refTable = try readLenPrefixed(allocator, raw, &pos);
+            errdefer allocator.free(refTable);
+            const refField = try readLenPrefixed(allocator, raw, &pos);
+            errdefer allocator.free(refField);
+            if (pos + 1 > raw.len) return error.Malformed;
+            const onDelete = try onDeleteFromByte(raw[pos]);
+            pos += 1;
+            try set.specs.append(.{ .field = field, .refTable = refTable, .refField = refField, .onDelete = onDelete });
+        }
+        return set;
+    }
+
+    pub fn save(self: *const ForeignKeySet, db: *Db, table: []const u8) !void {
+        const key = try foreignKeyMetaKey(self.allocator, table);
+        defer self.allocator.free(key);
+
+        var out = std.ArrayList(u8).init(self.allocator);
+        defer out.deinit();
+        var countBuf: [4]u8 = undefined;
+        std.mem.writeInt(u32, &countBuf, @intCast(self.specs.items.len), .little);
+        try out.appendSlice(&countBuf);
+        for (self.specs.items) |spec| {
+            try appendLenPrefixed(&out, spec.field);
+            try appendLenPrefixed(&out, spec.refTable);
+            try appendLenPrefixed(&out, spec.refField);
+            try out.append(@intFromEnum(spec.onDelete));
+        }
+        try db.put(key, out.items);
+    }
+
+    pub fn has(self: *const ForeignKeySet, field: []const u8) bool {
+        return self.find(field) != null;
+    }
+
+    pub fn find(self: *const ForeignKeySet, field: []const u8) ?ForeignKeySpec {
+        for (self.specs.items) |spec| {
+            if (std.mem.eql(u8, spec.field, field)) return spec;
+        }
+        return null;
+    }
+
+    pub fn add(self: *ForeignKeySet, field: []const u8, refTable: []const u8, refField: []const u8, onDelete: OnDelete) !void {
+        if (self.has(field)) return;
+        const spec = ForeignKeySpec{
+            .field = try self.allocator.dupe(u8, field),
+            .refTable = try self.allocator.dupe(u8, refTable),
+            .refField = try self.allocator.dupe(u8, refField),
+            .onDelete = onDelete,
+        };
+        try self.specs.append(spec);
+    }
+
+    /// Returns true if a constraint on `field` was present and has been
+    /// removed.
+    pub fn remove(self: *ForeignKeySet, field: []const u8) bool {
+        for (self.specs.items, 0..) |spec, i| {
+            if (std.mem.eql(u8, spec.field, field)) {
+                self.allocator.free(spec.field);
+                self.allocator.free(spec.refTable);
+                self.allocator.free(spec.refField);
+                _ = self.specs.orderedRemove(i);
+                return true;
+            }
+        }
+        return false;
+    }
+
+    pub fn deinit(self: *ForeignKeySet) void {
+        for (self.specs.items) |spec| {
+            self.allocator.free(spec.field);
+            self.allocator.free(spec.refTable);
+            self.allocator.free(spec.refField);
+        }
+        self.specs.deinit();
+    }
+};
+
+/// One named CHECK constraint: a caller-chosen `name` (used only as the key
+/// under which the constraint can be dropped again, not part of the
+/// keyspace layout - unlike `CompositeIndexSpec.name`, no index entries are
+/// ever written for a CHECK) paired with the raw `expr.zig` predicate source
+/// text it must evaluate true against. Stored as source rather than a parsed
+/// tree because `index.zig` sits below `query.zig`/`expr.zig` in the
+/// dependency graph and knows nothing about `Predicate` - parsing happens
+/// fresh in whichever layer enforces it (`query.zig`'s `Table.put`,
+/// `txn_table.zig`'s `TableTxn.put`), the same "reparse on every use" cost
+/// `table select`/`table join` already pay for their own expr text.
+pub const CheckConstraintSpec = struct {
+    name: []u8,
+    source: []u8,
+};
+
+/// Persisted set of CHECK constraints on a table, at most one per name -
+/// same on-disk shape family as `ForeignKeySet` (own meta key, own
+/// namespace, two length-prefixed strings per entry).
+pub const CheckConstraintSet = struct {
+    allocator: Allocator,
+    specs: std.ArrayList(CheckConstraintSpec),
+
+    pub fn load(allocator: Allocator, db: *Db, table: []const u8) !CheckConstraintSet {
+        const key = try checkMetaKey(allocator, table);
+        defer allocator.free(key);
+
+        var set = CheckConstraintSet{ .allocator = allocator, .specs = std.ArrayList(CheckConstraintSpec).init(allocator) };
+        errdefer set.deinit();
+
+        const raw = try db.get(allocator, key) orelse return set;
+        defer allocator.free(raw);
+
+        var pos: usize = 0;
+        if (pos + 4 > raw.len) return error.Malformed;
+        const count = std.mem.readInt(u32, raw[pos..][0..4], .little);
+        pos += 4;
+        var i: u32 = 0;
+        while (i < count) : (i += 1) {
+            const name = try readLenPrefixed(allocator, raw, &pos);
+            errdefer allocator.free(name);
+            const source = try readLenPrefixed(allocator, raw, &pos);
+            try set.specs.append(.{ .name = name, .source = source });
+        }
+        return set;
+    }
+
+    pub fn save(self: *const CheckConstraintSet, db: *Db, table: []const u8) !void {
+        const key = try checkMetaKey(self.allocator, table);
+        defer self.allocator.free(key);
+
+        var out = std.ArrayList(u8).init(self.allocator);
+        defer out.deinit();
+        var countBuf: [4]u8 = undefined;
+        std.mem.writeInt(u32, &countBuf, @intCast(self.specs.items.len), .little);
+        try out.appendSlice(&countBuf);
+        for (self.specs.items) |spec| {
+            try appendLenPrefixed(&out, spec.name);
+            try appendLenPrefixed(&out, spec.source);
+        }
+        try db.put(key, out.items);
+    }
+
+    pub fn has(self: *const CheckConstraintSet, name: []const u8) bool {
+        return self.find(name) != null;
+    }
+
+    pub fn find(self: *const CheckConstraintSet, name: []const u8) ?CheckConstraintSpec {
+        for (self.specs.items) |spec| {
+            if (std.mem.eql(u8, spec.name, name)) return spec;
+        }
+        return null;
+    }
+
+    pub fn add(self: *CheckConstraintSet, name: []const u8, source: []const u8) !void {
+        if (self.has(name)) return;
+        const spec = CheckConstraintSpec{
+            .name = try self.allocator.dupe(u8, name),
+            .source = try self.allocator.dupe(u8, source),
+        };
+        try self.specs.append(spec);
+    }
+
+    /// Returns true if a constraint named `name` was present and has been
+    /// removed.
+    pub fn remove(self: *CheckConstraintSet, name: []const u8) bool {
+        for (self.specs.items, 0..) |spec, i| {
+            if (std.mem.eql(u8, spec.name, name)) {
+                self.allocator.free(spec.name);
+                self.allocator.free(spec.source);
+                _ = self.specs.orderedRemove(i);
+                return true;
+            }
+        }
+        return false;
+    }
+
+    pub fn deinit(self: *CheckConstraintSet) void {
+        for (self.specs.items) |spec| {
+            self.allocator.free(spec.name);
+            self.allocator.free(spec.source);
+        }
+        self.specs.deinit();
+    }
+};
+
+/// One reverse FOREIGN KEY entry, recorded on the REFERENCED table rather
+/// than the referencing one: some other table `childTable` has a
+/// `FOREIGN KEY (childField) REFERENCES <this table>(refField)`. This is
+/// the registry `Table.createForeignKey`'s doc comment calls out as
+/// missing ("tables are opened ad hoc by name and never catalogued
+/// anywhere") - without it, deleting a parent row has no way to discover
+/// which other tables might still be pointing at it, since `ForeignKeySet`
+/// is only ever stored on the referencing (child) side.
+pub const ReferencedBySpec = struct {
+    childTable: []u8,
+    childField: []u8,
+    refField: []u8,
+    onDelete: OnDelete,
+};
+
+/// Persisted set of reverse FK entries on a table - same on-disk shape
+/// family as `ForeignKeySet` (own meta key, own namespace, three
+/// length-prefixed strings plus an `onDelete` mode byte per entry), but
+/// populated by a DIFFERENT table's `createForeignKey`/`dropForeignKey`
+/// call rather than by mutations against this table directly. `onDelete`
+/// is duplicated here rather than looked up from the child's own
+/// `ForeignKeySet` on every delete, so `Table.delete`'s cascade planner
+/// (see `query.zig`'s `planCascade`) can decide restrict-vs-cascade
+/// without opening and loading the child a second time just to answer
+/// that. `add` is keyed by the (childTable, childField) pair - a child
+/// field can only ever carry one FOREIGN KEY (enforced by
+/// `ForeignKeySet.has` at the child), so at most one reverse entry per
+/// pair can ever be correct; re-adding the same pair (only reachable by
+/// first dropping and recreating the child's constraint, possibly with a
+/// different `refField`/`onDelete`) replaces it in place instead of
+/// accumulating a stale duplicate.
+pub const ReferencedBySet = struct {
+    allocator: Allocator,
+    specs: std.ArrayList(ReferencedBySpec),
+
+    pub fn load(allocator: Allocator, db: *Db, table: []const u8) !ReferencedBySet {
+        const key = try referencedByMetaKey(allocator, table);
+        defer allocator.free(key);
+
+        var set = ReferencedBySet{ .allocator = allocator, .specs = std.ArrayList(ReferencedBySpec).init(allocator) };
+        errdefer set.deinit();
+
+        const raw = try db.get(allocator, key) orelse return set;
+        defer allocator.free(raw);
+
+        var pos: usize = 0;
+        if (pos + 4 > raw.len) return error.Malformed;
+        const count = std.mem.readInt(u32, raw[pos..][0..4], .little);
+        pos += 4;
+        var i: u32 = 0;
+        while (i < count) : (i += 1) {
+            const childTable = try readLenPrefixed(allocator, raw, &pos);
+            errdefer allocator.free(childTable);
+            const childField = try readLenPrefixed(allocator, raw, &pos);
+            errdefer allocator.free(childField);
+            const refField = try readLenPrefixed(allocator, raw, &pos);
+            errdefer allocator.free(refField);
+            if (pos + 1 > raw.len) return error.Malformed;
+            const onDelete = try onDeleteFromByte(raw[pos]);
+            pos += 1;
+            try set.specs.append(.{ .childTable = childTable, .childField = childField, .refField = refField, .onDelete = onDelete });
+        }
+        return set;
+    }
+
+    pub fn save(self: *const ReferencedBySet, db: *Db, table: []const u8) !void {
+        const key = try referencedByMetaKey(self.allocator, table);
+        defer self.allocator.free(key);
+
+        var out = std.ArrayList(u8).init(self.allocator);
+        defer out.deinit();
+        var countBuf: [4]u8 = undefined;
+        std.mem.writeInt(u32, &countBuf, @intCast(self.specs.items.len), .little);
+        try out.appendSlice(&countBuf);
+        for (self.specs.items) |spec| {
+            try appendLenPrefixed(&out, spec.childTable);
+            try appendLenPrefixed(&out, spec.childField);
+            try appendLenPrefixed(&out, spec.refField);
+            try out.append(@intFromEnum(spec.onDelete));
+        }
+        try db.put(key, out.items);
+    }
+
+    fn indexOf(self: *const ReferencedBySet, childTable: []const u8, childField: []const u8) ?usize {
+        for (self.specs.items, 0..) |spec, i| {
+            if (std.mem.eql(u8, spec.childTable, childTable) and std.mem.eql(u8, spec.childField, childField)) return i;
+        }
+        return null;
+    }
+
+    pub fn add(self: *ReferencedBySet, childTable: []const u8, childField: []const u8, refField: []const u8, onDelete: OnDelete) !void {
+        const refFieldCopy = try self.allocator.dupe(u8, refField);
+        errdefer self.allocator.free(refFieldCopy);
+        if (self.indexOf(childTable, childField)) |i| {
+            self.allocator.free(self.specs.items[i].refField);
+            self.specs.items[i].refField = refFieldCopy;
+            self.specs.items[i].onDelete = onDelete;
+            return;
+        }
+        const spec = ReferencedBySpec{
+            .childTable = try self.allocator.dupe(u8, childTable),
+            .childField = try self.allocator.dupe(u8, childField),
+            .refField = refFieldCopy,
+            .onDelete = onDelete,
+        };
+        try self.specs.append(spec);
+    }
+
+    /// Returns true if a reverse entry for (childTable, childField) was
+    /// present and has been removed.
+    pub fn remove(self: *ReferencedBySet, childTable: []const u8, childField: []const u8) bool {
+        const i = self.indexOf(childTable, childField) orelse return false;
+        const spec = self.specs.items[i];
+        self.allocator.free(spec.childTable);
+        self.allocator.free(spec.childField);
+        self.allocator.free(spec.refField);
+        _ = self.specs.orderedRemove(i);
+        return true;
+    }
+
+    pub fn deinit(self: *ReferencedBySet) void {
+        for (self.specs.items) |spec| {
+            self.allocator.free(spec.childTable);
+            self.allocator.free(spec.childField);
+            self.allocator.free(spec.refField);
+        }
+        self.specs.deinit();
+    }
+};
+
+fn readLenPrefixed(allocator: Allocator, raw: []const u8, pos: *usize) ![]u8 {
+    if (pos.* + 4 > raw.len) return error.Malformed;
+    const len = std.mem.readInt(u32, raw[pos.*..][0..4], .little);
+    pos.* += 4;
+    if (pos.* + len > raw.len) return error.Malformed;
+    const value = try allocator.dupe(u8, raw[pos.* .. pos.* + len]);
+    pos.* += len;
+    return value;
+}
+
+fn appendLenPrefixed(out: *std.ArrayList(u8), value: []const u8) !void {
+    var lenBuf: [4]u8 = undefined;
+    std.mem.writeInt(u32, &lenBuf, @intCast(value.len), .little);
+    try out.appendSlice(&lenBuf);
+    try out.appendSlice(value);
+}
+
+/// One multi-column ("composite") index: a caller-chosen name (used as the
+/// keyspace discriminator, so it must be a `validIdentifier` like a table or
+/// field name) plus the ordered list of fields it indexes. Field order is
+/// significant - it defines both the on-disk key layout and which leading
+/// ("leftmost") prefix of columns a query can use for a narrowed lookup.
+pub const CompositeIndexSpec = struct {
+    name: []u8,
+    fields: [][]u8,
+
+    fn free(self: *const CompositeIndexSpec, allocator: Allocator) void {
+        allocator.free(self.name);
+        for (self.fields) |f| allocator.free(f);
+        allocator.free(self.fields);
+    }
+};
+
+/// Persisted set of composite indexes on a table, the multi-column
+/// counterpart to `IndexSet`. Stored under a separate metadata key
+/// ("CINDEXES" vs "INDEXES") so single-field and composite indexes never
+/// share or shadow each other's schema record.
+pub const CompositeIndexSet = struct {
+    allocator: Allocator,
+    specs: std.ArrayList(CompositeIndexSpec),
+
+    pub fn load(allocator: Allocator, db: *Db, table: []const u8) !CompositeIndexSet {
+        const key = try compositeMetaKey(allocator, table);
+        defer allocator.free(key);
+
+        var set = CompositeIndexSet{ .allocator = allocator, .specs = std.ArrayList(CompositeIndexSpec).init(allocator) };
+        errdefer set.deinit();
+
+        const raw = try db.get(allocator, key) orelse return set;
+        defer allocator.free(raw);
+
+        var pos: usize = 0;
+        if (pos + 4 > raw.len) return error.Malformed;
+        const specCount = std.mem.readInt(u32, raw[pos..][0..4], .little);
+        pos += 4;
+        var i: u32 = 0;
+        while (i < specCount) : (i += 1) {
+            if (pos + 4 > raw.len) return error.Malformed;
+            const nameLen = std.mem.readInt(u32, raw[pos..][0..4], .little);
+            pos += 4;
+            if (pos + nameLen > raw.len) return error.Malformed;
+            const name = try allocator.dupe(u8, raw[pos .. pos + nameLen]);
+            errdefer allocator.free(name);
+            pos += nameLen;
+
+            if (pos + 4 > raw.len) return error.Malformed;
+            const fieldCount = std.mem.readInt(u32, raw[pos..][0..4], .little);
+            pos += 4;
+            const fields = try allocator.alloc([]u8, fieldCount);
+            var filled: usize = 0;
+            errdefer {
+                for (fields[0..filled]) |f| allocator.free(f);
+                allocator.free(fields);
+            }
+            var j: u32 = 0;
+            while (j < fieldCount) : (j += 1) {
+                if (pos + 4 > raw.len) return error.Malformed;
+                const len = std.mem.readInt(u32, raw[pos..][0..4], .little);
+                pos += 4;
+                if (pos + len > raw.len) return error.Malformed;
+                fields[j] = try allocator.dupe(u8, raw[pos .. pos + len]);
+                filled += 1;
+                pos += len;
+            }
+            try set.specs.append(.{ .name = name, .fields = fields });
+        }
+        return set;
+    }
+
+    pub fn save(self: *const CompositeIndexSet, db: *Db, table: []const u8) !void {
+        const key = try compositeMetaKey(self.allocator, table);
+        defer self.allocator.free(key);
+
+        var out = std.ArrayList(u8).init(self.allocator);
+        defer out.deinit();
+        var countBuf: [4]u8 = undefined;
+        std.mem.writeInt(u32, &countBuf, @intCast(self.specs.items.len), .little);
+        try out.appendSlice(&countBuf);
+        for (self.specs.items) |spec| {
+            var lenBuf: [4]u8 = undefined;
+            std.mem.writeInt(u32, &lenBuf, @intCast(spec.name.len), .little);
+            try out.appendSlice(&lenBuf);
+            try out.appendSlice(spec.name);
+
+            std.mem.writeInt(u32, &lenBuf, @intCast(spec.fields.len), .little);
+            try out.appendSlice(&lenBuf);
+            for (spec.fields) |f| {
+                std.mem.writeInt(u32, &lenBuf, @intCast(f.len), .little);
+                try out.appendSlice(&lenBuf);
+                try out.appendSlice(f);
+            }
+        }
+        try db.put(key, out.items);
+    }
+
+    pub fn find(self: *const CompositeIndexSet, name: []const u8) ?*const CompositeIndexSpec {
+        for (self.specs.items) |*s| {
+            if (std.mem.eql(u8, s.name, name)) return s;
+        }
+        return null;
+    }
+
+    pub fn has(self: *const CompositeIndexSet, name: []const u8) bool {
+        return self.find(name) != null;
+    }
+
+    pub fn add(self: *CompositeIndexSet, name: []const u8, fields: []const []const u8) !void {
+        if (self.has(name)) return;
+        const nameCopy = try self.allocator.dupe(u8, name);
+        errdefer self.allocator.free(nameCopy);
+
+        const fieldsCopy = try self.allocator.alloc([]u8, fields.len);
+        var filled: usize = 0;
+        errdefer {
+            for (fieldsCopy[0..filled]) |f| self.allocator.free(f);
+            self.allocator.free(fieldsCopy);
+        }
+        for (fields, 0..) |f, i| {
+            fieldsCopy[i] = try self.allocator.dupe(u8, f);
+            filled += 1;
+        }
+        try self.specs.append(.{ .name = nameCopy, .fields = fieldsCopy });
+    }
+
+    /// Returns true if a composite index by that name was present and has
+    /// been removed.
+    pub fn remove(self: *CompositeIndexSet, name: []const u8) bool {
+        for (self.specs.items, 0..) |*s, i| {
+            if (std.mem.eql(u8, s.name, name)) {
+                s.free(self.allocator);
+                _ = self.specs.orderedRemove(i);
+                return true;
+            }
+        }
+        return false;
+    }
+
+    pub fn deinit(self: *CompositeIndexSet) void {
+        for (self.specs.items) |*s| s.free(self.allocator);
+        self.specs.deinit();
+    }
+};
+
+/// Adds one index entry mapping `value` -> `pk` under `table.field`. The
+/// entry's stored value is the plain (non order-preserving) encoding of the
+/// primary key, so lookups can recover the exact original Value instead of
+/// re-parsing the escaped ordered key bytes.
+pub fn addEntry(db: *Db, allocator: Allocator, table: []const u8, field: []const u8, value: Value, pk: Value) !void {
+    const key = try indexEntryKey(allocator, table, field, value, pk);
+    defer allocator.free(key);
+    const pkBytes = try row.encodeValue(allocator, pk);
+    defer allocator.free(pkBytes);
+    try db.put(key, pkBytes);
+}
+
+pub fn removeEntry(db: *Db, allocator: Allocator, table: []const u8, field: []const u8, value: Value, pk: Value) !void {
+    const key = try indexEntryKey(allocator, table, field, value, pk);
+    defer allocator.free(key);
+    try db.delete(key);
+}
+
+/// Deletes every index entry for `table.field`, used when dropping an index.
+pub fn dropAllEntries(db: *Db, allocator: Allocator, table: []const u8, field: []const u8) !void {
+    const prefix = try indexPrefix(allocator, table, field);
+    defer allocator.free(prefix);
+
+    var keys = std.ArrayList([]u8).init(allocator);
+    defer {
+        for (keys.items) |k| allocator.free(k);
+        keys.deinit();
+    }
+
+    var it = try db.scanPrefix(allocator, prefix);
+    defer it.deinit();
+    while (try it.next()) |entry| {
+        try keys.append(try allocator.dupe(u8, entry.key));
+    }
+    for (keys.items) |k| try db.delete(k);
+}
+
+/// Adds one composite index entry mapping the full `values` tuple -> `pk`
+/// under `table`'s index `indexName`. Same stored-value convention as
+/// `addEntry`: the plain (non order-preserving) pk encoding.
+pub fn addCompositeEntry(db: *Db, allocator: Allocator, table: []const u8, indexName: []const u8, values: []const Value, pk: Value) !void {
+    const key = try compositeIndexEntryKey(allocator, table, indexName, values, pk);
+    defer allocator.free(key);
+    const pkBytes = try row.encodeValue(allocator, pk);
+    defer allocator.free(pkBytes);
+    try db.put(key, pkBytes);
+}
+
+pub fn removeCompositeEntry(db: *Db, allocator: Allocator, table: []const u8, indexName: []const u8, values: []const Value, pk: Value) !void {
+    const key = try compositeIndexEntryKey(allocator, table, indexName, values, pk);
+    defer allocator.free(key);
+    try db.delete(key);
+}
+
+/// Deletes every entry for a composite index, used when dropping it.
+pub fn dropAllCompositeEntries(db: *Db, allocator: Allocator, table: []const u8, indexName: []const u8) !void {
+    const prefix = try compositeIndexPrefix(allocator, table, indexName);
+    defer allocator.free(prefix);
+
+    var keys = std.ArrayList([]u8).init(allocator);
+    defer {
+        for (keys.items) |k| allocator.free(k);
+        keys.deinit();
+    }
+
+    var it = try db.scanPrefix(allocator, prefix);
+    defer it.deinit();
+    while (try it.next()) |entry| {
+        try keys.append(try allocator.dupe(u8, entry.key));
+    }
+    for (keys.items) |k| try db.delete(k);
+}
+
+/// Lazy cursor over a leftmost-prefix equality lookup on a composite index:
+/// `valuesPrefix` may cover all of the index's columns or just a leading
+/// subset of them. Streaming for the same reason as `EqCursor`.
+pub const CompositeEqCursor = struct {
+    it: dbmod.RangeIterator,
+
+    pub fn next(self: *CompositeEqCursor, allocator: Allocator) !?Value {
+        const entry = try self.it.next() orelse return null;
+        return try row.decodeValue(allocator, entry.value);
+    }
+
+    pub fn deinit(self: *CompositeEqCursor) void {
+        self.it.deinit();
+    }
+};
+
+pub fn scanCompositeEqCursor(db: *Db, allocator: Allocator, table: []const u8, indexName: []const u8, valuesPrefix: []const Value) !CompositeEqCursor {
+    const prefix = try compositeIndexValueBound(allocator, table, indexName, valuesPrefix);
+    defer allocator.free(prefix);
+    return .{ .it = try db.scanPrefix(allocator, prefix) };
+}
+
+/// Eager counterpart of `scanCompositeEqCursor`, all matching primary keys.
+pub fn scanCompositeEq(db: *Db, allocator: Allocator, table: []const u8, indexName: []const u8, valuesPrefix: []const Value) ![]Value {
+    var cursor = try scanCompositeEqCursor(db, allocator, table, indexName, valuesPrefix);
+    defer cursor.deinit();
+
+    var results = std.ArrayList(Value).init(allocator);
+    errdefer {
+        for (results.items) |v| v.free(allocator);
+        results.deinit();
+    }
+    while (try cursor.next(allocator)) |pk| try results.append(pk);
+    return results.toOwnedSlice();
+}
+
+/// Lazy cursor over a range lookup on the column immediately following a
+/// leftmost-prefix of equality columns on a composite index: `eqValues`
+/// pins the leading columns exactly like `CompositeEqCursor`, `low`/`high`
+/// bound the next column. Columns beyond that one are left unconstrained by
+/// the scan, same leftmost-prefix rule as the equality-only cursor.
+pub const CompositeRangeCursor = struct {
+    it: dbmod.RangeIterator,
+
+    pub fn next(self: *CompositeRangeCursor, allocator: Allocator) !?Value {
+        const entry = try self.it.next() orelse return null;
+        return try row.decodeValue(allocator, entry.value);
+    }
+
+    pub fn deinit(self: *CompositeRangeCursor) void {
+        self.it.deinit();
+    }
+};
+
+pub fn scanCompositeRangeCursor(
+    db: *Db,
+    allocator: Allocator,
+    table: []const u8,
+    indexName: []const u8,
+    eqValues: []const Value,
+    low: ?Bound,
+    high: ?Bound,
+) !CompositeRangeCursor {
+    const prefix = try compositeIndexValueBound(allocator, table, indexName, eqValues);
+    defer allocator.free(prefix);
+
+    var startBuf: ?[]u8 = null;
+    defer if (startBuf) |b| allocator.free(b);
+    var endBuf: ?[]u8 = null;
+    defer if (endBuf) |b| allocator.free(b);
+
+    // Same inclusive/exclusive gap trick as `scanRangeCursor`: a real entry
+    // key is always `compositeIndexRangeBound(eqValues, value) ++ orderedPk`,
+    // a strict byte-extension of the bare per-value bound (pk encodings are
+    // never empty), so a key with value == threshold always sorts after
+    // `compositeIndexRangeBound(eqValues, threshold)` itself.
+    const start = if (low) |b| blk: {
+        const bound = try compositeIndexRangeBound(allocator, table, indexName, eqValues, b.value);
+        if (b.inclusive) {
+            startBuf = bound;
+        } else {
+            defer allocator.free(bound);
+            startBuf = try prefixUpperBound(allocator, bound) orelse try allocator.dupe(u8, bound);
+        }
+        break :blk startBuf.?;
+    } else prefix;
+
+    const end = if (high) |b| blk: {
+        const bound = try compositeIndexRangeBound(allocator, table, indexName, eqValues, b.value);
+        if (b.inclusive) {
+            defer allocator.free(bound);
+            endBuf = try prefixUpperBound(allocator, bound) orelse try allocator.dupe(u8, bound);
+        } else {
+            endBuf = bound;
+        }
+        break :blk endBuf.?;
+    } else blk: {
+        endBuf = try prefixUpperBound(allocator, prefix) orelse try allocator.dupe(u8, prefix);
+        break :blk endBuf.?;
+    };
+
+    return .{ .it = try db.scanRange(allocator, .{
+        .start = start,
+        .end = end,
+        .startInclusive = true,
+        .endInclusive = false,
+    }) };
+}
+
+/// Lazy cursor over an equality index lookup: decodes one primary key at a
+/// time from the underlying `Db.RangeIterator` instead of materializing the
+/// whole match set up front. This is what lets `Table.selectPage` honour a
+/// small `limit` without reading and decoding every index entry for a value
+/// that may have thousands of matches.
+pub const EqCursor = struct {
+    it: dbmod.RangeIterator,
+
+    pub fn next(self: *EqCursor, allocator: Allocator) !?Value {
+        const entry = try self.it.next() orelse return null;
+        return try row.decodeValue(allocator, entry.value);
+    }
+
+    pub fn deinit(self: *EqCursor) void {
+        self.it.deinit();
+    }
+};
+
+/// Point lookup, streaming: opens the underlying scan but decodes nothing
+/// until `EqCursor.next` is called.
+pub fn scanEqCursor(db: *Db, allocator: Allocator, table: []const u8, field: []const u8, value: Value) !EqCursor {
+    const prefix = try indexValueBound(allocator, table, field, value);
+    defer allocator.free(prefix);
+    return .{ .it = try db.scanPrefix(allocator, prefix) };
+}
+
+/// Point lookup: all primary keys currently indexed under `value`.
+pub fn scanEq(db: *Db, allocator: Allocator, table: []const u8, field: []const u8, value: Value) ![]Value {
+    var cursor = try scanEqCursor(db, allocator, table, field, value);
+    defer cursor.deinit();
+
+    var results = std.ArrayList(Value).init(allocator);
+    errdefer {
+        for (results.items) |v| v.free(allocator);
+        results.deinit();
+    }
+    while (try cursor.next(allocator)) |pk| try results.append(pk);
+    return results.toOwnedSlice();
+}
+
+pub const Bound = struct {
+    value: Value,
+    inclusive: bool,
+};
+
+/// Lazy cursor over a range index lookup, same rationale as `EqCursor`.
+pub const RangeCursor = struct {
+    it: dbmod.RangeIterator,
+
+    pub fn next(self: *RangeCursor, allocator: Allocator) !?Value {
+        const entry = try self.it.next() orelse return null;
+        return try row.decodeValue(allocator, entry.value);
+    }
+
+    pub fn deinit(self: *RangeCursor) void {
+        self.it.deinit();
+    }
+};
+
+/// Range lookup over `table.field`'s index, streaming: primary keys whose
+/// indexed value falls within [low, high] (either side may be open/null),
+/// decoded one at a time as the caller consumes the cursor.
+pub fn scanRangeCursor(
+    db: *Db,
+    allocator: Allocator,
+    table: []const u8,
+    field: []const u8,
+    low: ?Bound,
+    high: ?Bound,
+) !RangeCursor {
+    const prefix = try indexPrefix(allocator, table, field);
+    defer allocator.free(prefix);
+
+    var startBuf: ?[]u8 = null;
+    defer if (startBuf) |b| allocator.free(b);
+    var endBuf: ?[]u8 = null;
+    defer if (endBuf) |b| allocator.free(b);
+
+    // Every real index-entry key is `indexValueBound(value) ++ orderedPk`, a
+    // strict byte-extension of the bare value bound (pk encodings are never
+    // empty). So a key with value == threshold always compares greater than
+    // `indexValueBound(threshold)` itself - inclusive/exclusive thresholds
+    // are therefore expressed by choosing which side of that gap to start
+    // or stop the scan at, not by the start/endInclusive flags.
+    const start = if (low) |b| blk: {
+        const bound = try indexValueBound(allocator, table, field, b.value);
+        if (b.inclusive) {
+            startBuf = bound;
+        } else {
+            defer allocator.free(bound);
+            startBuf = try prefixUpperBound(allocator, bound) orelse try allocator.dupe(u8, bound);
+        }
+        break :blk startBuf.?;
+    } else prefix;
+
+    const end = if (high) |b| blk: {
+        const bound = try indexValueBound(allocator, table, field, b.value);
+        if (b.inclusive) {
+            defer allocator.free(bound);
+            endBuf = try prefixUpperBound(allocator, bound) orelse try allocator.dupe(u8, bound);
+        } else {
+            endBuf = bound;
+        }
+        break :blk endBuf.?;
+    } else blk: {
+        endBuf = try prefixUpperBound(allocator, prefix) orelse try allocator.dupe(u8, prefix);
+        break :blk endBuf.?;
+    };
+
+    return .{ .it = try db.scanRange(allocator, .{
+        .start = start,
+        .end = end,
+        .startInclusive = true,
+        .endInclusive = false,
+    }) };
+}
+
+/// Range lookup over `table.field`'s index: all primary keys whose indexed
+/// value falls within [low, high] (either side may be open/null).
+pub fn scanRange(
+    db: *Db,
+    allocator: Allocator,
+    table: []const u8,
+    field: []const u8,
+    low: ?Bound,
+    high: ?Bound,
+) ![]Value {
+    var cursor = try scanRangeCursor(db, allocator, table, field, low, high);
+    defer cursor.deinit();
+
+    var results = std.ArrayList(Value).init(allocator);
+    errdefer {
+        for (results.items) |v| v.free(allocator);
+        results.deinit();
+    }
+    while (try cursor.next(allocator)) |pk| try results.append(pk);
+    return results.toOwnedSlice();
+}
+
+test "rowKey and indexEntryKey stay within their own namespace" {
+    const allocator = std.testing.allocator;
+    const rk = try rowKey(allocator, "users", .{ .int = 1 });
+    defer allocator.free(rk);
+    const ik = try indexEntryKey(allocator, "users", "email", .{ .text = "a@b.c" }, .{ .int = 1 });
+    defer allocator.free(ik);
+
+    try std.testing.expectEqual(@as(u8, 'R'), rk[0]);
+    try std.testing.expectEqual(@as(u8, 'I'), ik[0]);
+}
+
+test "prefixUpperBound bounds a prefix scan" {
+    const allocator = std.testing.allocator;
+    const upper = (try prefixUpperBound(allocator, "abc")).?;
+    defer allocator.free(upper);
+    try std.testing.expect(std.mem.order(u8, "abc", upper) == .lt);
+    try std.testing.expect(std.mem.order(u8, "abd", upper) != .lt);
+}
+
+test "IndexSet add remove save load round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var set = try IndexSet.load(allocator, &db, "users");
+    defer set.deinit();
+    try std.testing.expectEqual(@as(usize, 0), set.fields.items.len);
+
+    try set.add("email");
+    try set.add("age");
+    try set.add("email");
+    try std.testing.expectEqual(@as(usize, 2), set.fields.items.len);
+    try set.save(&db, "users");
+
+    var reloaded = try IndexSet.load(allocator, &db, "users");
+    defer reloaded.deinit();
+    try std.testing.expect(reloaded.has("email"));
+    try std.testing.expect(reloaded.has("age"));
+    try std.testing.expect(!reloaded.has("missing"));
+
+    try std.testing.expect(reloaded.remove("email"));
+    try std.testing.expect(!reloaded.remove("email"));
+    try reloaded.save(&db, "users");
+
+    var third = try IndexSet.load(allocator, &db, "users");
+    defer third.deinit();
+    try std.testing.expect(!third.has("email"));
+    try std.testing.expect(third.has("age"));
+}
+
+test "UniqueSet add remove save load round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var set = try UniqueSet.load(allocator, &db, "users");
+    defer set.deinit();
+    try std.testing.expectEqual(@as(usize, 0), set.fields.items.len);
+
+    try set.add("email");
+    try set.add("ssn");
+    try set.add("email");
+    try std.testing.expectEqual(@as(usize, 2), set.fields.items.len);
+    try set.save(&db, "users");
+
+    var reloaded = try UniqueSet.load(allocator, &db, "users");
+    defer reloaded.deinit();
+    try std.testing.expect(reloaded.has("email"));
+    try std.testing.expect(reloaded.has("ssn"));
+    try std.testing.expect(!reloaded.has("missing"));
+
+    try std.testing.expect(reloaded.remove("email"));
+    try std.testing.expect(!reloaded.remove("email"));
+    try reloaded.save(&db, "users");
+
+    var third = try UniqueSet.load(allocator, &db, "users");
+    defer third.deinit();
+    try std.testing.expect(!third.has("email"));
+    try std.testing.expect(third.has("ssn"));
+}
+
+test "UniqueSet and IndexSet on the same table never collide, each keeps its own membership" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var indexes = try IndexSet.load(allocator, &db, "users");
+    defer indexes.deinit();
+    try indexes.add("email");
+    try indexes.add("city");
+    try indexes.save(&db, "users");
+
+    var unique = try UniqueSet.load(allocator, &db, "users");
+    defer unique.deinit();
+    try unique.add("email");
+    try unique.save(&db, "users");
+
+    // "city" is indexed but not unique, "email" is both - the two sets
+    // must agree on "email" and disagree on "city" after an independent
+    // reload of each, proving neither save() overwrote the other's key.
+    var reloadedIndexes = try IndexSet.load(allocator, &db, "users");
+    defer reloadedIndexes.deinit();
+    var reloadedUnique = try UniqueSet.load(allocator, &db, "users");
+    defer reloadedUnique.deinit();
+
+    try std.testing.expect(reloadedIndexes.has("email"));
+    try std.testing.expect(reloadedIndexes.has("city"));
+    try std.testing.expect(reloadedUnique.has("email"));
+    try std.testing.expect(!reloadedUnique.has("city"));
+}
+
+test "ForeignKeySet add remove save load round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var set = try ForeignKeySet.load(allocator, &db, "orders");
+    defer set.deinit();
+    try std.testing.expectEqual(@as(usize, 0), set.specs.items.len);
+
+    try set.add("customer_id", "customers", "__pk", .cascade);
+    try set.add("customer_id", "customers", "some_other_field", .restrict);
+    try std.testing.expectEqual(@as(usize, 1), set.specs.items.len);
+    try set.save(&db, "orders");
+
+    var reloaded = try ForeignKeySet.load(allocator, &db, "orders");
+    defer reloaded.deinit();
+    try std.testing.expect(reloaded.has("customer_id"));
+    try std.testing.expect(!reloaded.has("missing"));
+    const spec = reloaded.find("customer_id").?;
+    try std.testing.expectEqualStrings("customers", spec.refTable);
+    try std.testing.expectEqualStrings("__pk", spec.refField);
+    // First `add` wins (mirrors `has` guard above) - `onDelete` survives the
+    // save/load round trip as the mode from that first call, not the
+    // no-op second one.
+    try std.testing.expectEqual(OnDelete.cascade, spec.onDelete);
+
+    try std.testing.expect(reloaded.remove("customer_id"));
+    try std.testing.expect(!reloaded.remove("customer_id"));
+    try reloaded.save(&db, "orders");
+
+    var third = try ForeignKeySet.load(allocator, &db, "orders");
+    defer third.deinit();
+    try std.testing.expect(!third.has("customer_id"));
+}
+
+test "ForeignKeySet.load rejects a corrupted onDelete byte instead of accepting garbage" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var set = try ForeignKeySet.load(allocator, &db, "orders");
+    defer set.deinit();
+    try set.add("customer_id", "customers", "__pk", .restrict);
+    try set.save(&db, "orders");
+
+    const key = try foreignKeyMetaKey(allocator, "orders");
+    defer allocator.free(key);
+    const raw = try db.get(allocator, key) orelse return error.TestUnexpectedResult;
+    defer allocator.free(raw);
+
+    // Flip the trailing onDelete byte to a value neither `restrict` (0)
+    // nor `cascade` (1) can ever legitimately be - same "malformed input
+    // is rejected, not silently coerced" contract every other decoder in
+    // this file already gives length-prefixed strings.
+    const corrupted = try allocator.dupe(u8, raw);
+    defer allocator.free(corrupted);
+    corrupted[corrupted.len - 1] = 0xFF;
+    try db.put(key, corrupted);
+
+    try std.testing.expectError(error.Malformed, ForeignKeySet.load(allocator, &db, "orders"));
+}
+
+test "ReferencedBySet add replaces an existing (childTable, childField) pair instead of duplicating it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var set = try ReferencedBySet.load(allocator, &db, "customers");
+    defer set.deinit();
+    try std.testing.expectEqual(@as(usize, 0), set.specs.items.len);
+
+    try set.add("orders", "customer_id", "__pk", .restrict);
+    try set.add("orders", "customer_id", "__pk", .restrict);
+    try std.testing.expectEqual(@as(usize, 1), set.specs.items.len);
+    try set.add("line_items", "customer_id", "__pk", .cascade);
+    try std.testing.expectEqual(@as(usize, 2), set.specs.items.len);
+    try set.save(&db, "customers");
+
+    var reloaded = try ReferencedBySet.load(allocator, &db, "customers");
+    defer reloaded.deinit();
+    try std.testing.expectEqual(@as(usize, 2), reloaded.specs.items.len);
+    for (reloaded.specs.items) |spec| {
+        if (std.mem.eql(u8, spec.childTable, "line_items")) {
+            try std.testing.expectEqual(OnDelete.cascade, spec.onDelete);
+        } else {
+            try std.testing.expectEqual(OnDelete.restrict, spec.onDelete);
+        }
+    }
+
+    // Re-adding the same pair under a different refField AND onDelete mode
+    // replaces both in place rather than accumulating a second, now-stale
+    // entry.
+    try reloaded.add("orders", "customer_id", "email", .cascade);
+    try std.testing.expectEqual(@as(usize, 2), reloaded.specs.items.len);
+    var sawOrders = false;
+    for (reloaded.specs.items) |spec| {
+        if (std.mem.eql(u8, spec.childTable, "orders")) {
+            sawOrders = true;
+            try std.testing.expectEqualStrings("email", spec.refField);
+            try std.testing.expectEqual(OnDelete.cascade, spec.onDelete);
+        }
+    }
+    try std.testing.expect(sawOrders);
+
+    try std.testing.expect(reloaded.remove("orders", "customer_id"));
+    try std.testing.expect(!reloaded.remove("orders", "customer_id"));
+    try reloaded.save(&db, "customers");
+
+    var third = try ReferencedBySet.load(allocator, &db, "customers");
+    defer third.deinit();
+    try std.testing.expectEqual(@as(usize, 1), third.specs.items.len);
+    try std.testing.expectEqualStrings("line_items", third.specs.items[0].childTable);
+}
+
+test "CheckConstraintSet add remove save load round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var set = try CheckConstraintSet.load(allocator, &db, "orders");
+    defer set.deinit();
+    try std.testing.expectEqual(@as(usize, 0), set.specs.items.len);
+
+    try set.add("qty_positive", "qty gt 0");
+    try set.add("qty_positive", "qty gt 100");
+    try std.testing.expectEqual(@as(usize, 1), set.specs.items.len);
+    try set.save(&db, "orders");
+
+    var reloaded = try CheckConstraintSet.load(allocator, &db, "orders");
+    defer reloaded.deinit();
+    try std.testing.expect(reloaded.has("qty_positive"));
+    try std.testing.expect(!reloaded.has("missing"));
+    const spec = reloaded.find("qty_positive").?;
+    try std.testing.expectEqualStrings("qty gt 0", spec.source);
+
+    try std.testing.expect(reloaded.remove("qty_positive"));
+    try std.testing.expect(!reloaded.remove("qty_positive"));
+    try reloaded.save(&db, "orders");
+
+    var third = try CheckConstraintSet.load(allocator, &db, "orders");
+    defer third.deinit();
+    try std.testing.expect(!third.has("qty_positive"));
+}
+
+test "ForeignKeySet, UniqueSet, and IndexSet on the same table never collide" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var indexes = try IndexSet.load(allocator, &db, "orders");
+    defer indexes.deinit();
+    try indexes.add("customer_id");
+    try indexes.save(&db, "orders");
+
+    var unique = try UniqueSet.load(allocator, &db, "orders");
+    defer unique.deinit();
+    try unique.add("order_number");
+    try unique.save(&db, "orders");
+
+    var fkeys = try ForeignKeySet.load(allocator, &db, "orders");
+    defer fkeys.deinit();
+    try fkeys.add("customer_id", "customers", "__pk", .restrict);
+    try fkeys.save(&db, "orders");
+
+    var checks = try CheckConstraintSet.load(allocator, &db, "orders");
+    defer checks.deinit();
+    try checks.add("qty_positive", "qty gt 0");
+    try checks.save(&db, "orders");
+
+    var reloadedIndexes = try IndexSet.load(allocator, &db, "orders");
+    defer reloadedIndexes.deinit();
+    var reloadedUnique = try UniqueSet.load(allocator, &db, "orders");
+    defer reloadedUnique.deinit();
+    var reloadedFkeys = try ForeignKeySet.load(allocator, &db, "orders");
+    defer reloadedFkeys.deinit();
+    var reloadedChecks = try CheckConstraintSet.load(allocator, &db, "orders");
+    defer reloadedChecks.deinit();
+
+    try std.testing.expect(reloadedIndexes.has("customer_id"));
+    try std.testing.expect(reloadedUnique.has("order_number"));
+    try std.testing.expect(!reloadedUnique.has("customer_id"));
+    try std.testing.expect(reloadedFkeys.has("customer_id"));
+    try std.testing.expect(!reloadedFkeys.has("order_number"));
+    try std.testing.expect(reloadedChecks.has("qty_positive"));
+    try std.testing.expect(!reloadedChecks.has("customer_id"));
+}
+
+test "addEntry scanEq removeEntry round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    try addEntry(&db, allocator, "users", "city", .{ .text = "warsaw" }, .{ .int = 1 });
+    try addEntry(&db, allocator, "users", "city", .{ .text = "warsaw" }, .{ .int = 2 });
+    try addEntry(&db, allocator, "users", "city", .{ .text = "krakow" }, .{ .int = 3 });
+
+    const warsawPks = try scanEq(&db, allocator, "users", "city", .{ .text = "warsaw" });
+    defer {
+        for (warsawPks) |v| v.free(allocator);
+        allocator.free(warsawPks);
+    }
+    try std.testing.expectEqual(@as(usize, 2), warsawPks.len);
+
+    try removeEntry(&db, allocator, "users", "city", .{ .text = "warsaw" }, .{ .int = 1 });
+    const afterRemove = try scanEq(&db, allocator, "users", "city", .{ .text = "warsaw" });
+    defer {
+        for (afterRemove) |v| v.free(allocator);
+        allocator.free(afterRemove);
+    }
+    try std.testing.expectEqual(@as(usize, 1), afterRemove.len);
+    try std.testing.expectEqual(@as(i64, 2), afterRemove[0].int);
+}
+
+test "EqCursor streams the same pks as eager scanEq and can stop early" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var i: i64 = 0;
+    while (i < 20) : (i += 1) {
+        try addEntry(&db, allocator, "users", "city", .{ .text = "warsaw" }, .{ .int = i });
+    }
+
+    const eager = try scanEq(&db, allocator, "users", "city", .{ .text = "warsaw" });
+    defer {
+        for (eager) |v| v.free(allocator);
+        allocator.free(eager);
+    }
+    try std.testing.expectEqual(@as(usize, 20), eager.len);
+
+    // Pull only the first three through the cursor, then drop it: this must
+    // neither read nor decode the remaining seventeen entries, and the
+    // testing allocator would flag a leak if the partially-consumed
+    // RangeIterator's resources were not released on an early deinit.
+    var cursor = try scanEqCursor(&db, allocator, "users", "city", .{ .text = "warsaw" });
+    defer cursor.deinit();
+    var pulled = std.ArrayList(Value).init(allocator);
+    defer {
+        for (pulled.items) |v| v.free(allocator);
+        pulled.deinit();
+    }
+    var n: usize = 0;
+    while (n < 3) : (n += 1) {
+        const pk = (try cursor.next(allocator)).?;
+        try pulled.append(pk);
+    }
+    try std.testing.expectEqual(@as(usize, 3), pulled.items.len);
+    for (pulled.items, 0..) |v, idx2| {
+        try std.testing.expectEqual(eager[idx2].int, v.int);
+    }
+}
+
+test "RangeCursor streams the same pks as eager scanRange and can stop early" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var i: i64 = 0;
+    while (i < 30) : (i += 1) {
+        try addEntry(&db, allocator, "events", "score", .{ .int = i }, .{ .int = i });
+    }
+
+    var cursor = try scanRangeCursor(&db, allocator, "events", "score", .{ .value = .{ .int = 5 }, .inclusive = true }, null);
+    defer cursor.deinit();
+    const first = (try cursor.next(allocator)).?;
+    defer first.free(allocator);
+    const second = (try cursor.next(allocator)).?;
+    defer second.free(allocator);
+    try std.testing.expectEqual(@as(i64, 5), first.int);
+    try std.testing.expectEqual(@as(i64, 6), second.int);
+    // cursor and its underlying iterator are dropped by `defer` here without
+    // consuming the other 23 matches.
+}
+
+test "scanRange respects bounds and inclusivity" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var i: i64 = 0;
+    while (i < 10) : (i += 1) {
+        try addEntry(&db, allocator, "events", "score", .{ .int = i }, .{ .int = i });
+    }
+
+    const all = try scanRange(&db, allocator, "events", "score", null, null);
+    defer {
+        for (all) |v| v.free(allocator);
+        allocator.free(all);
+    }
+    try std.testing.expectEqual(@as(usize, 10), all.len);
+
+    const midInclusive = try scanRange(&db, allocator, "events", "score", .{ .value = .{ .int = 3 }, .inclusive = true }, .{ .value = .{ .int = 6 }, .inclusive = true });
+    defer {
+        for (midInclusive) |v| v.free(allocator);
+        allocator.free(midInclusive);
+    }
+    try std.testing.expectEqual(@as(usize, 4), midInclusive.len);
+    try std.testing.expectEqual(@as(i64, 3), midInclusive[0].int);
+    try std.testing.expectEqual(@as(i64, 6), midInclusive[midInclusive.len - 1].int);
+
+    const midExclusive = try scanRange(&db, allocator, "events", "score", .{ .value = .{ .int = 3 }, .inclusive = false }, .{ .value = .{ .int = 6 }, .inclusive = false });
+    defer {
+        for (midExclusive) |v| v.free(allocator);
+        allocator.free(midExclusive);
+    }
+    try std.testing.expectEqual(@as(usize, 2), midExclusive.len);
+    try std.testing.expectEqual(@as(i64, 4), midExclusive[0].int);
+    try std.testing.expectEqual(@as(i64, 5), midExclusive[1].int);
+
+    const openAbove = try scanRange(&db, allocator, "events", "score", .{ .value = .{ .int = 8 }, .inclusive = true }, null);
+    defer {
+        for (openAbove) |v| v.free(allocator);
+        allocator.free(openAbove);
+    }
+    try std.testing.expectEqual(@as(usize, 2), openAbove.len);
+}
+
+test "CompositeIndexSet add remove save load round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var set = try CompositeIndexSet.load(allocator, &db, "users");
+    defer set.deinit();
+    try std.testing.expectEqual(@as(usize, 0), set.specs.items.len);
+
+    try set.add("city_age", &.{ "city", "age" });
+    try set.add("city_age", &.{ "city", "age" }); // no-op, already present
+    try std.testing.expectEqual(@as(usize, 1), set.specs.items.len);
+    try set.save(&db, "users");
+
+    var reloaded = try CompositeIndexSet.load(allocator, &db, "users");
+    defer reloaded.deinit();
+    try std.testing.expect(reloaded.has("city_age"));
+    const spec = reloaded.find("city_age").?;
+    try std.testing.expectEqual(@as(usize, 2), spec.fields.len);
+    try std.testing.expectEqualStrings("city", spec.fields[0]);
+    try std.testing.expectEqualStrings("age", spec.fields[1]);
+
+    try std.testing.expect(reloaded.remove("city_age"));
+    try std.testing.expect(!reloaded.remove("city_age"));
+    try reloaded.save(&db, "users");
+
+    var third = try CompositeIndexSet.load(allocator, &db, "users");
+    defer third.deinit();
+    try std.testing.expect(!third.has("city_age"));
+}
+
+test "single-field and composite index metadata never shadow each other" {
+    // Both live under the "M" tag with table-name-suffixed keys that differ
+    // only in "INDEXES" vs "CINDEXES" - this pins down that they stay two
+    // genuinely distinct Db keys, not one overwriting the other.
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    var single = try IndexSet.load(allocator, &db, "users");
+    defer single.deinit();
+    try single.add("email");
+    try single.save(&db, "users");
+
+    var composite = try CompositeIndexSet.load(allocator, &db, "users");
+    defer composite.deinit();
+    try composite.add("city_age", &.{ "city", "age" });
+    try composite.save(&db, "users");
+
+    var singleReloaded = try IndexSet.load(allocator, &db, "users");
+    defer singleReloaded.deinit();
+    try std.testing.expect(singleReloaded.has("email"));
+
+    var compositeReloaded = try CompositeIndexSet.load(allocator, &db, "users");
+    defer compositeReloaded.deinit();
+    try std.testing.expect(compositeReloaded.has("city_age"));
+}
+
+test "addCompositeEntry scanCompositeEq removeCompositeEntry round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    try addCompositeEntry(&db, allocator, "users", "city_age", &.{ .{ .text = "warsaw" }, .{ .int = 30 } }, .{ .int = 1 });
+    try addCompositeEntry(&db, allocator, "users", "city_age", &.{ .{ .text = "warsaw" }, .{ .int = 40 } }, .{ .int = 2 });
+    try addCompositeEntry(&db, allocator, "users", "city_age", &.{ .{ .text = "krakow" }, .{ .int = 30 } }, .{ .int = 3 });
+
+    // Full-tuple match: exactly one row.
+    const exact = try scanCompositeEq(&db, allocator, "users", "city_age", &.{ .{ .text = "warsaw" }, .{ .int = 30 } });
+    defer {
+        for (exact) |v| v.free(allocator);
+        allocator.free(exact);
+    }
+    try std.testing.expectEqual(@as(usize, 1), exact.len);
+    try std.testing.expectEqual(@as(i64, 1), exact[0].int);
+
+    // Leftmost-prefix match on just the first column: both warsaw rows,
+    // never the krakow one, even though it wasn't constrained on age at all.
+    const prefixMatch = try scanCompositeEq(&db, allocator, "users", "city_age", &.{.{ .text = "warsaw" }});
+    defer {
+        for (prefixMatch) |v| v.free(allocator);
+        allocator.free(prefixMatch);
+    }
+    try std.testing.expectEqual(@as(usize, 2), prefixMatch.len);
+
+    try removeCompositeEntry(&db, allocator, "users", "city_age", &.{ .{ .text = "warsaw" }, .{ .int = 30 } }, .{ .int = 1 });
+    const afterRemove = try scanCompositeEq(&db, allocator, "users", "city_age", &.{.{ .text = "warsaw" }});
+    defer {
+        for (afterRemove) |v| v.free(allocator);
+        allocator.free(afterRemove);
+    }
+    try std.testing.expectEqual(@as(usize, 1), afterRemove.len);
+    try std.testing.expectEqual(@as(i64, 2), afterRemove[0].int);
+}
+
+test "scanCompositeRangeCursor narrows on the column after the matched prefix" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    // Two cities, ages 20..29 in each - the composite index is (city, age).
+    var age: i64 = 20;
+    while (age < 30) : (age += 1) {
+        try addCompositeEntry(&db, allocator, "users", "city_age", &.{ .{ .text = "warsaw" }, .{ .int = age } }, .{ .int = age });
+        try addCompositeEntry(&db, allocator, "users", "city_age", &.{ .{ .text = "krakow" }, .{ .int = age } }, .{ .int = age + 100 });
+    }
+
+    // city == "warsaw" and 23 <= age <= 26: never crosses into krakow's
+    // bucket even though its ages overlap byte-for-byte with warsaw's.
+    var midCursor = try scanCompositeRangeCursor(&db, allocator, "users", "city_age", &.{.{ .text = "warsaw" }}, .{ .value = .{ .int = 23 }, .inclusive = true }, .{ .value = .{ .int = 26 }, .inclusive = true });
+    var midInclusive = std.ArrayList(Value).init(allocator);
+    defer midInclusive.deinit();
+    while (try midCursor.next(allocator)) |pk| try midInclusive.append(pk);
+    midCursor.deinit();
+    try std.testing.expectEqual(@as(usize, 4), midInclusive.items.len);
+    try std.testing.expectEqual(@as(i64, 23), midInclusive.items[0].int);
+    try std.testing.expectEqual(@as(i64, 26), midInclusive.items[midInclusive.items.len - 1].int);
+
+    // Exclusive both sides: drops the two endpoints.
+    var exclusive = try scanCompositeRangeCursor(&db, allocator, "users", "city_age", &.{.{ .text = "warsaw" }}, .{ .value = .{ .int = 23 }, .inclusive = false }, .{ .value = .{ .int = 26 }, .inclusive = false });
+    defer exclusive.deinit();
+    const first = (try exclusive.next(allocator)).?;
+    defer first.free(allocator);
+    const second = (try exclusive.next(allocator)).?;
+    defer second.free(allocator);
+    try std.testing.expectEqual(@as(i64, 24), first.int);
+    try std.testing.expectEqual(@as(i64, 25), second.int);
+    try std.testing.expectEqual(@as(?Value, null), try exclusive.next(allocator));
+
+    // Open above: age >= 28 within warsaw only, never touching krakow.
+    var openAbove = try scanCompositeRangeCursor(&db, allocator, "users", "city_age", &.{.{ .text = "warsaw" }}, .{ .value = .{ .int = 28 }, .inclusive = true }, null);
+    defer openAbove.deinit();
+    const a1 = (try openAbove.next(allocator)).?;
+    defer a1.free(allocator);
+    const a2 = (try openAbove.next(allocator)).?;
+    defer a2.free(allocator);
+    try std.testing.expectEqual(@as(i64, 28), a1.int);
+    try std.testing.expectEqual(@as(i64, 29), a2.int);
+    try std.testing.expectEqual(@as(?Value, null), try openAbove.next(allocator));
+}
+
+test "dropAllCompositeEntries clears an index without touching another one" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+
+    var db = try Db.open(allocator, dbPath, .{});
+    defer db.close();
+
+    try addCompositeEntry(&db, allocator, "users", "city_age", &.{ .{ .text = "warsaw" }, .{ .int = 30 } }, .{ .int = 1 });
+    try addCompositeEntry(&db, allocator, "users", "other_idx", &.{ .{ .int = 1 }, .{ .int = 2 } }, .{ .int = 1 });
+
+    try dropAllCompositeEntries(&db, allocator, "users", "city_age");
+
+    const cityAge = try scanCompositeEq(&db, allocator, "users", "city_age", &.{.{ .text = "warsaw" }});
+    defer {
+        for (cityAge) |v| v.free(allocator);
+        allocator.free(cityAge);
+    }
+    try std.testing.expectEqual(@as(usize, 0), cityAge.len);
+
+    const other = try scanCompositeEq(&db, allocator, "users", "other_idx", &.{.{ .int = 1 }});
+    defer {
+        for (other) |v| v.free(allocator);
+        allocator.free(other);
+    }
+    try std.testing.expectEqual(@as(usize, 1), other.len);
+}
diff --git a/src/join.zig b/src/join.zig
new file mode 100644
index 0000000..e7fc83d
--- /dev/null
+++ b/src/join.zig
@@ -0,0 +1,1158 @@
+const std = @import("std");
+const rowmod = @import("row.zig");
+const querymod = @import("query.zig");
+
+const Allocator = std.mem.Allocator;
+const Row = rowmod.Row;
+const Table = querymod.Table;
+const Predicate = querymod.Predicate;
+
+/// One matched pair produced by `innerJoin`: the left table's row and the
+/// right table's row that satisfied `leftRow.get(leftField) ==
+/// rightRow.get(rightField)`. Kept as two separate owned Rows rather than
+/// merged into one flat namespace, so join output never has to invent a
+/// collision rule for a field name that happens to exist on both sides.
+pub const JoinedRow = struct {
+    left: Row,
+    right: Row,
+
+    pub fn deinit(self: *JoinedRow) void {
+        self.left.deinit();
+        self.right.deinit();
+    }
+};
+
+pub fn freeJoined(allocator: Allocator, rows: []JoinedRow) void {
+    for (rows) |*r| r.deinit();
+    allocator.free(rows);
+}
+
+/// Independent copy of `row` via its own encode/decode round trip, so a
+/// join result can outlive (and be freed separately from) the pooled
+/// `Table.select` slice it was matched out of - the same row can appear in
+/// more than one output pair on a one-to-many join.
+fn dupeRow(allocator: Allocator, row: *const Row) !Row {
+    const buf = try row.encode(allocator);
+    defer allocator.free(buf);
+    return try Row.decode(allocator, buf);
+}
+
+/// Inner equi-join between `left` and `right` on
+/// `leftRow.get(leftField) == rightRow.get(rightField)` (compared with
+/// `row.compare`, so a mismatched type - e.g. an int on one side against a
+/// float on the other - never matches, exactly like `Predicate.eq`).
+/// `leftPred`/`rightPred` filter each side first, evaluated exactly like
+/// `Table.select` (including its own index usage). A row missing the join
+/// field entirely never matches anything, on either side.
+///
+/// Join strategy is chosen once, not per call site: if `right` already has
+/// a secondary index on `rightField`, this runs an index nested-loop join -
+/// one `right.select` per surviving left row, narrowed through that index
+/// exactly the way a plain `eq` query would be. Otherwise it builds an
+/// in-memory hash table over the (already `rightPred`-filtered) right rows
+/// keyed by the join value and probes it once per left row - a hash join,
+/// so an unindexed join over two large tables still costs
+/// O(leftRows + rightRows) rather than O(leftRows * rightRows).
+///
+/// Caller owns the returned slice and every `JoinedRow` in it; free with
+/// `freeJoined`.
+pub fn innerJoin(
+    allocator: Allocator,
+    left: *Table,
+    leftField: []const u8,
+    leftPred: ?Predicate,
+    right: *Table,
+    rightField: []const u8,
+    rightPred: ?Predicate,
+) ![]JoinedRow {
+    const leftRows = try left.select(leftPred);
+    defer querymod.freeRows(allocator, leftRows);
+
+    var results = std.ArrayList(JoinedRow).init(allocator);
+    errdefer {
+        for (results.items) |*r| r.deinit();
+        results.deinit();
+    }
+
+    if (right.hasIndex(rightField)) {
+        for (leftRows) |*lrow| {
+            const v = lrow.get(leftField) orelse continue;
+            const eqPred = Predicate{ .eq = .{ .field = rightField, .value = v } };
+            var combinedBuf: [2]Predicate = undefined;
+            const pred: Predicate = if (rightPred) |rp| blk: {
+                combinedBuf[0] = eqPred;
+                combinedBuf[1] = rp;
+                break :blk Predicate{ .and_ = combinedBuf[0..] };
+            } else eqPred;
+
+            const matches = try right.select(pred);
+            defer querymod.freeRows(allocator, matches);
+            for (matches) |*mrow| {
+                var lcopy = try dupeRow(allocator, lrow);
+                errdefer lcopy.deinit();
+                const rcopy = try dupeRow(allocator, mrow);
+                try results.append(.{ .left = lcopy, .right = rcopy });
+            }
+        }
+        return results.toOwnedSlice();
+    }
+
+    const rightRows = try right.select(rightPred);
+    defer querymod.freeRows(allocator, rightRows);
+
+    var buckets = std.StringHashMap(std.ArrayList(usize)).init(allocator);
+    defer {
+        var it = buckets.iterator();
+        while (it.next()) |entry| {
+            entry.value_ptr.deinit();
+            allocator.free(entry.key_ptr.*);
+        }
+        buckets.deinit();
+    }
+
+    for (rightRows, 0..) |*rrow, i| {
+        const v = rrow.get(rightField) orelse continue;
+        const key = try rowmod.encodeValue(allocator, v);
+        const gop = try buckets.getOrPut(key);
+        if (gop.found_existing) {
+            allocator.free(key);
+        } else {
+            gop.value_ptr.* = std.ArrayList(usize).init(allocator);
+        }
+        try gop.value_ptr.append(i);
+    }
+
+    for (leftRows) |*lrow| {
+        const v = lrow.get(leftField) orelse continue;
+        const key = try rowmod.encodeValue(allocator, v);
+        defer allocator.free(key);
+        const indices = buckets.get(key) orelse continue;
+        for (indices.items) |i| {
+            var lcopy = try dupeRow(allocator, lrow);
+            errdefer lcopy.deinit();
+            const rcopy = try dupeRow(allocator, &rightRows[i]);
+            try results.append(.{ .left = lcopy, .right = rcopy });
+        }
+    }
+
+    return results.toOwnedSlice();
+}
+
+/// One row produced by `leftOuterJoin`: every left row appears at least
+/// once, with `right` set to `null` when nothing on the right side matched
+/// (SQL LEFT OUTER JOIN semantics - the left side is never dropped, unlike
+/// `innerJoin` where an unmatched left row disappears entirely).
+pub const OuterJoinedRow = struct {
+    left: Row,
+    right: ?Row,
+
+    pub fn deinit(self: *OuterJoinedRow) void {
+        self.left.deinit();
+        if (self.right) |*r| r.deinit();
+    }
+};
+
+pub fn freeOuterJoined(allocator: Allocator, rows: []OuterJoinedRow) void {
+    for (rows) |*r| r.deinit();
+    allocator.free(rows);
+}
+
+/// Left outer equi-join: same matching rules, strategy selection (index
+/// nested-loop vs. hash join) and predicate semantics as `innerJoin`, but a
+/// left row with zero matches on the right (missing join field, filtered
+/// out by `rightPred`, or genuinely no equal value on the right) still
+/// produces exactly one `OuterJoinedRow` with `right = null` instead of
+/// vanishing from the output.
+///
+/// Caller owns the returned slice and every `OuterJoinedRow` in it; free
+/// with `freeOuterJoined`.
+pub fn leftOuterJoin(
+    allocator: Allocator,
+    left: *Table,
+    leftField: []const u8,
+    leftPred: ?Predicate,
+    right: *Table,
+    rightField: []const u8,
+    rightPred: ?Predicate,
+) ![]OuterJoinedRow {
+    const leftRows = try left.select(leftPred);
+    defer querymod.freeRows(allocator, leftRows);
+
+    var results = std.ArrayList(OuterJoinedRow).init(allocator);
+    errdefer {
+        for (results.items) |*r| r.deinit();
+        results.deinit();
+    }
+
+    if (right.hasIndex(rightField)) {
+        for (leftRows) |*lrow| {
+            const v = lrow.get(leftField) orelse {
+                var lcopy = try dupeRow(allocator, lrow);
+                errdefer lcopy.deinit();
+                try results.append(.{ .left = lcopy, .right = null });
+                continue;
+            };
+            const eqPred = Predicate{ .eq = .{ .field = rightField, .value = v } };
+            var combinedBuf: [2]Predicate = undefined;
+            const pred: Predicate = if (rightPred) |rp| blk: {
+                combinedBuf[0] = eqPred;
+                combinedBuf[1] = rp;
+                break :blk Predicate{ .and_ = combinedBuf[0..] };
+            } else eqPred;
+
+            const matches = try right.select(pred);
+            defer querymod.freeRows(allocator, matches);
+            if (matches.len == 0) {
+                var lcopy = try dupeRow(allocator, lrow);
+                errdefer lcopy.deinit();
+                try results.append(.{ .left = lcopy, .right = null });
+                continue;
+            }
+            for (matches) |*mrow| {
+                var lcopy = try dupeRow(allocator, lrow);
+                errdefer lcopy.deinit();
+                const rcopy = try dupeRow(allocator, mrow);
+                try results.append(.{ .left = lcopy, .right = rcopy });
+            }
+        }
+        return results.toOwnedSlice();
+    }
+
+    const rightRows = try right.select(rightPred);
+    defer querymod.freeRows(allocator, rightRows);
+
+    var buckets = std.StringHashMap(std.ArrayList(usize)).init(allocator);
+    defer {
+        var it = buckets.iterator();
+        while (it.next()) |entry| {
+            entry.value_ptr.deinit();
+            allocator.free(entry.key_ptr.*);
+        }
+        buckets.deinit();
+    }
+
+    for (rightRows, 0..) |*rrow, i| {
+        const v = rrow.get(rightField) orelse continue;
+        const key = try rowmod.encodeValue(allocator, v);
+        const gop = try buckets.getOrPut(key);
+        if (gop.found_existing) {
+            allocator.free(key);
+        } else {
+            gop.value_ptr.* = std.ArrayList(usize).init(allocator);
+        }
+        try gop.value_ptr.append(i);
+    }
+
+    for (leftRows) |*lrow| {
+        const v = lrow.get(leftField) orelse {
+            var lcopy = try dupeRow(allocator, lrow);
+            errdefer lcopy.deinit();
+            try results.append(.{ .left = lcopy, .right = null });
+            continue;
+        };
+        const key = try rowmod.encodeValue(allocator, v);
+        defer allocator.free(key);
+        const indices = buckets.get(key) orelse {
+            var lcopy = try dupeRow(allocator, lrow);
+            errdefer lcopy.deinit();
+            try results.append(.{ .left = lcopy, .right = null });
+            continue;
+        };
+        for (indices.items) |i| {
+            var lcopy = try dupeRow(allocator, lrow);
+            errdefer lcopy.deinit();
+            const rcopy = try dupeRow(allocator, &rightRows[i]);
+            try results.append(.{ .left = lcopy, .right = rcopy });
+        }
+    }
+
+    return results.toOwnedSlice();
+}
+
+/// One row produced by `rightOuterJoin`: every right row appears at least
+/// once, with `left` set to `null` when nothing on the left side matched
+/// (SQL RIGHT OUTER JOIN semantics - the mirror image of `OuterJoinedRow`,
+/// where it is the right side that is optional).
+pub const RightOuterJoinedRow = struct {
+    left: ?Row,
+    right: Row,
+
+    pub fn deinit(self: *RightOuterJoinedRow) void {
+        if (self.left) |*l| l.deinit();
+        self.right.deinit();
+    }
+};
+
+pub fn freeRightOuterJoined(allocator: Allocator, rows: []RightOuterJoinedRow) void {
+    for (rows) |*r| r.deinit();
+    allocator.free(rows);
+}
+
+/// Right outer equi-join: same matching rules and predicate semantics as
+/// `innerJoin`/`leftOuterJoin`, but every `right` row appears at least once,
+/// with `left = null` when nothing on the left side matched.
+///
+/// Implemented by delegating to `leftOuterJoin` with the two sides swapped
+/// and remapping the result, rather than re-deriving the index/hash-join
+/// strategy selection a third time - `leftOuterJoin(right, ..., left, ...)`
+/// already produces exactly "every row of `right`, paired with an optional
+/// match from `left`", which is right outer join semantics with the two
+/// output fields named the other way round.
+///
+/// Caller owns the returned slice and every `RightOuterJoinedRow` in it;
+/// free with `freeRightOuterJoined`.
+pub fn rightOuterJoin(
+    allocator: Allocator,
+    left: *Table,
+    leftField: []const u8,
+    leftPred: ?Predicate,
+    right: *Table,
+    rightField: []const u8,
+    rightPred: ?Predicate,
+) ![]RightOuterJoinedRow {
+    const swapped = try leftOuterJoin(allocator, right, rightField, rightPred, left, leftField, leftPred);
+    defer allocator.free(swapped);
+
+    const results = try allocator.alloc(RightOuterJoinedRow, swapped.len);
+    for (swapped, 0..) |pair, i| {
+        results[i] = .{ .left = pair.right, .right = pair.left };
+    }
+    return results;
+}
+
+/// One row produced by `fullOuterJoin`: both `left` and `right` are
+/// optional, and every row from either side that never matched on the other
+/// still appears exactly once (SQL FULL OUTER JOIN semantics - the union of
+/// what `leftOuterJoin` and `rightOuterJoin` each produce).
+pub const FullOuterJoinedRow = struct {
+    left: ?Row,
+    right: ?Row,
+
+    pub fn deinit(self: *FullOuterJoinedRow) void {
+        if (self.left) |*l| l.deinit();
+        if (self.right) |*r| r.deinit();
+    }
+};
+
+pub fn freeFullOuterJoined(allocator: Allocator, rows: []FullOuterJoinedRow) void {
+    for (rows) |*r| r.deinit();
+    allocator.free(rows);
+}
+
+/// Full outer equi-join: the union of `leftOuterJoin` (every left row,
+/// matched or not) and every right row `rightOuterJoin` reports as
+/// unmatched (`left == null`) - those are exactly the right-side rows a
+/// plain left outer join would never produce. Built from the two existing
+/// outer joins rather than a third independent matching pass, at the
+/// honest cost of computing the match twice (once per direction) - the
+/// same "correctness over a second matching pass" tradeoff already used by
+/// `rank`/`rangeByRank` in collections.zig.
+///
+/// Caller owns the returned slice and every `FullOuterJoinedRow` in it;
+/// free with `freeFullOuterJoined`.
+pub fn fullOuterJoin(
+    allocator: Allocator,
+    left: *Table,
+    leftField: []const u8,
+    leftPred: ?Predicate,
+    right: *Table,
+    rightField: []const u8,
+    rightPred: ?Predicate,
+) ![]FullOuterJoinedRow {
+    const leftSide = try leftOuterJoin(allocator, left, leftField, leftPred, right, rightField, rightPred);
+    errdefer freeOuterJoined(allocator, leftSide);
+
+    const rightSide = try rightOuterJoin(allocator, left, leftField, leftPred, right, rightField, rightPred);
+    errdefer freeRightOuterJoined(allocator, rightSide);
+
+    var unmatchedRightCount: usize = 0;
+    for (rightSide) |pair| {
+        if (pair.left == null) unmatchedRightCount += 1;
+    }
+
+    var results = try std.ArrayList(FullOuterJoinedRow).initCapacity(allocator, leftSide.len + unmatchedRightCount);
+    errdefer {
+        for (results.items) |*r| r.deinit();
+        results.deinit();
+    }
+
+    for (leftSide) |pair| {
+        results.appendAssumeCapacity(.{ .left = pair.left, .right = pair.right });
+    }
+    allocator.free(leftSide);
+
+    for (rightSide) |pair| {
+        if (pair.left) |l| {
+            var lm = l;
+            lm.deinit();
+            var rm = pair.right;
+            rm.deinit();
+        } else {
+            results.appendAssumeCapacity(.{ .left = null, .right = pair.right });
+        }
+    }
+    allocator.free(rightSide);
+
+    return results.toOwnedSlice();
+}
+
+/// Trims one of the four join result slices above to a `query.zig` `Page`
+/// window (0 = unlimited, the same convention `Table.selectPage` uses) -
+/// the join counterpart of pagination for `table_join`/`remote-join`.
+/// Unlike `Table.selectPage`, which narrows an index scan and can stop
+/// before materializing a row past the limit, a join has already had to
+/// produce a full pair to know it matched at all, so there is no cheaper
+/// way to honor `offset`/`limit` than windowing the already-complete
+/// result - this always runs after `innerJoin`/`leftOuterJoin`/
+/// `rightOuterJoin`/`fullOuterJoin` returns, never instead of it.
+///
+/// Takes ownership of `rows`: frees the backing slice, `.deinit()`s every
+/// pair that falls outside `[offset, offset+limit)`, and returns a freshly
+/// allocated slice holding only the kept pairs in their original order.
+/// Callers own the returned slice and the pairs in it exactly as they
+/// would have owned `rows` - free the pairs, then `allocator.free` the
+/// slice (or hand ownership onward, as `server.zig`'s `table_join` handler
+/// does by moving each kept pair into a `protocol.JoinPair`).
+pub fn applyPage(comptime T: type, allocator: Allocator, rows: []T, page: querymod.Page) ![]T {
+    const total = rows.len;
+    const start = @min(page.offset, total);
+    const end = if (page.limit == 0) total else @min(start + page.limit, total);
+
+    for (rows[0..start]) |*r| r.deinit();
+    for (rows[end..total]) |*r| r.deinit();
+
+    const kept = end - start;
+    const result = allocator.alloc(T, kept) catch |err| {
+        for (rows[start..end]) |*r| r.deinit();
+        allocator.free(rows);
+        return err;
+    };
+    @memcpy(result, rows[start..end]);
+    allocator.free(rows);
+    return result;
+}
+
+const testing = std.testing;
+const dbmod = @import("db.zig");
+
+fn openTestDb(tmp: *std.testing.TmpDir) !dbmod.Db {
+    const dbPath = try tmp.dir.realpathAlloc(testing.allocator, ".");
+    defer testing.allocator.free(dbPath);
+    return dbmod.Db.open(testing.allocator, dbPath, .{});
+}
+
+test "innerJoin: unindexed hash join matches on equal field value" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "alice" } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "bob" } }});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{ .{ .name = "customer_id", .value = .{ .int = 1 } }, .{ .name = "item", .value = .{ .text = "widget" } } });
+    try orders.put(.{ .int = 101 }, &.{ .{ .name = "customer_id", .value = .{ .int = 1 } }, .{ .name = "item", .value = .{ .text = "gadget" } } });
+    try orders.put(.{ .int = 102 }, &.{ .{ .name = "customer_id", .value = .{ .int = 2 } }, .{ .name = "item", .value = .{ .text = "gizmo" } } });
+    try orders.put(.{ .int = 103 }, &.{.{ .name = "customer_id", .value = .{ .int = 999 } }}); // no matching customer
+
+    const joined = try innerJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 3), joined.len);
+
+    var aliceItems = std.StringHashMap(void).init(testing.allocator);
+    defer aliceItems.deinit();
+    var seenBob = false;
+    for (joined) |pair| {
+        const name = pair.left.get("name").?.text;
+        const item = pair.right.get("item").?.text;
+        if (std.mem.eql(u8, name, "alice")) {
+            try aliceItems.put(item, {});
+        } else if (std.mem.eql(u8, name, "bob")) {
+            seenBob = true;
+            try testing.expectEqualStrings("gizmo", item);
+        } else {
+            try testing.expect(false); // unreachable: only alice/bob should ever match
+        }
+    }
+    try testing.expect(aliceItems.contains("widget"));
+    try testing.expect(aliceItems.contains("gadget"));
+    try testing.expect(seenBob);
+}
+
+test "innerJoin: index nested-loop join produces identical results to hash join" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "alice" } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "bob" } }});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.createIndex("customer_id");
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 101 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 102 }, &.{.{ .name = "customer_id", .value = .{ .int = 2 } }});
+
+    try testing.expect(orders.hasIndex("customer_id"));
+
+    const joined = try innerJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 3), joined.len);
+}
+
+test "innerJoin: rightPred filters matches out even when the join key matches" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{ .{ .name = "customer_id", .value = .{ .int = 1 } }, .{ .name = "status", .value = .{ .text = "shipped" } } });
+    try orders.put(.{ .int = 101 }, &.{ .{ .name = "customer_id", .value = .{ .int = 1 } }, .{ .name = "status", .value = .{ .text = "cancelled" } } });
+
+    const shippedOnly = Predicate{ .eq = .{ .field = "status", .value = .{ .text = "shipped" } } };
+    const joined = try innerJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", shippedOnly);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 1), joined.len);
+    try testing.expectEqualStrings("shipped", joined[0].right.get("status").?.text);
+}
+
+test "innerJoin: rightPred filters matches out even through an index nested-loop join" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.createIndex("customer_id");
+    try orders.put(.{ .int = 100 }, &.{ .{ .name = "customer_id", .value = .{ .int = 1 } }, .{ .name = "status", .value = .{ .text = "shipped" } } });
+    try orders.put(.{ .int = 101 }, &.{ .{ .name = "customer_id", .value = .{ .int = 1 } }, .{ .name = "status", .value = .{ .text = "cancelled" } } });
+
+    const shippedOnly = Predicate{ .eq = .{ .field = "status", .value = .{ .text = "shipped" } } };
+    const joined = try innerJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", shippedOnly);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 1), joined.len);
+    try testing.expectEqualStrings("shipped", joined[0].right.get("status").?.text);
+}
+
+test "innerJoin: leftPred narrows which left rows are even probed" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "vip", .value = .{ .boolean = true } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "vip", .value = .{ .boolean = false } }});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 101 }, &.{.{ .name = "customer_id", .value = .{ .int = 2 } }});
+
+    const vipOnly = Predicate{ .eq = .{ .field = "vip", .value = .{ .boolean = true } } };
+    const joined = try innerJoin(testing.allocator, &customers, "__pk", vipOnly, &orders, "customer_id", null);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 1), joined.len);
+}
+
+test "innerJoin: mismatched types never match even with equal-looking payloads" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 5 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    try right.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .float = 5.0 } }});
+
+    const joined = try innerJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 0), joined.len);
+}
+
+test "innerJoin: rows missing the join field on either side never match" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{}); // no "k" field at all
+    try left.put(.{ .int = 2 }, &.{.{ .name = "k", .value = .{ .int = 7 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    try right.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 7 } }});
+
+    const joined = try innerJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 1), joined.len);
+    try testing.expectEqual(@as(i64, 2), joined[0].left.get("__pk").?.int);
+}
+
+test "innerJoin: empty right table yields zero matches without touching left side output" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 1 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+
+    const joined = try innerJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 0), joined.len);
+}
+
+test "innerJoin: one-to-many fan-out duplicates the left row for each right match" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 42 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    var i: i64 = 0;
+    while (i < 5) : (i += 1) {
+        try right.put(.{ .int = i }, &.{.{ .name = "k", .value = .{ .int = 42 } }});
+    }
+
+    const joined = try innerJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 5), joined.len);
+    for (joined) |pair| {
+        try testing.expectEqual(@as(i64, 1), pair.left.get("__pk").?.int);
+    }
+}
+
+test "leftOuterJoin: unmatched left row survives with right=null instead of vanishing" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "alice" } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "bob" } }}); // never ordered
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    const joined = try leftOuterJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+    defer freeOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 2), joined.len);
+    var sawAliceMatched = false;
+    var sawBobUnmatched = false;
+    for (joined) |pair| {
+        const name = pair.left.get("name").?.text;
+        if (std.mem.eql(u8, name, "alice")) {
+            try testing.expect(pair.right != null);
+            sawAliceMatched = true;
+        } else if (std.mem.eql(u8, name, "bob")) {
+            try testing.expect(pair.right == null);
+            sawBobUnmatched = true;
+        }
+    }
+    try testing.expect(sawAliceMatched);
+    try testing.expect(sawBobUnmatched);
+}
+
+test "leftOuterJoin: index nested-loop join produces identical results to hash join" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{});
+    try customers.put(.{ .int = 2 }, &.{}); // no matching order either way
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.createIndex("customer_id");
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 101 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    try testing.expect(orders.hasIndex("customer_id"));
+
+    const joined = try leftOuterJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+    defer freeOuterJoined(testing.allocator, joined);
+
+    // customer 1 matches twice, customer 2 matches zero times but still appears once.
+    try testing.expectEqual(@as(usize, 3), joined.len);
+    var unmatchedCount: usize = 0;
+    for (joined) |pair| {
+        if (pair.right == null) unmatchedCount += 1;
+    }
+    try testing.expectEqual(@as(usize, 1), unmatchedCount);
+}
+
+test "leftOuterJoin: rightPred filtering out the only match still keeps the left row with right=null" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{ .{ .name = "customer_id", .value = .{ .int = 1 } }, .{ .name = "status", .value = .{ .text = "cancelled" } } });
+
+    const shippedOnly = Predicate{ .eq = .{ .field = "status", .value = .{ .text = "shipped" } } };
+    const joined = try leftOuterJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", shippedOnly);
+    defer freeOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 1), joined.len);
+    try testing.expect(joined[0].right == null);
+}
+
+test "leftOuterJoin: left row missing the join field entirely still appears once with right=null" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{}); // no "k" field at all
+    try left.put(.{ .int = 2 }, &.{.{ .name = "k", .value = .{ .int = 7 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    try right.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 7 } }});
+
+    const joined = try leftOuterJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 2), joined.len);
+    for (joined) |pair| {
+        if (pair.left.get("__pk").?.int == 1) {
+            try testing.expect(pair.right == null);
+        } else {
+            try testing.expect(pair.right != null);
+        }
+    }
+}
+
+test "leftOuterJoin: one-to-many fan-out on the matched side still produces one row per match" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 42 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    var i: i64 = 0;
+    while (i < 5) : (i += 1) {
+        try right.put(.{ .int = i }, &.{.{ .name = "k", .value = .{ .int = 42 } }});
+    }
+
+    const joined = try leftOuterJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 5), joined.len);
+    for (joined) |pair| {
+        try testing.expect(pair.right != null);
+    }
+}
+
+test "leftOuterJoin: empty right table yields exactly one unmatched row per left row" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 1 } }});
+    try left.put(.{ .int = 2 }, &.{.{ .name = "k", .value = .{ .int = 2 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+
+    const joined = try leftOuterJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 2), joined.len);
+    for (joined) |pair| {
+        try testing.expect(pair.right == null);
+    }
+}
+
+test "rightOuterJoin: unmatched right row survives with left=null instead of vanishing" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "alice" } }});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 101 }, &.{.{ .name = "customer_id", .value = .{ .int = 999 } }}); // no matching customer
+
+    const joined = try rightOuterJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+    defer freeRightOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 2), joined.len);
+    var sawMatched = false;
+    var sawUnmatched = false;
+    for (joined) |pair| {
+        const customerId = pair.right.get("customer_id").?.int;
+        if (customerId == 1) {
+            try testing.expect(pair.left != null);
+            try testing.expectEqualStrings("alice", pair.left.?.get("name").?.text);
+            sawMatched = true;
+        } else {
+            try testing.expect(pair.left == null);
+            sawUnmatched = true;
+        }
+    }
+    try testing.expect(sawMatched);
+    try testing.expect(sawUnmatched);
+}
+
+test "rightOuterJoin: index nested-loop join (index on left table) matches hash join results" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.createIndex("__pk");
+    try customers.put(.{ .int = 1 }, &.{});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 101 }, &.{.{ .name = "customer_id", .value = .{ .int = 2 } }}); // unmatched
+
+    const joined = try rightOuterJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+    defer freeRightOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 2), joined.len);
+    var unmatchedCount: usize = 0;
+    for (joined) |pair| {
+        if (pair.left == null) unmatchedCount += 1;
+    }
+    try testing.expectEqual(@as(usize, 1), unmatchedCount);
+}
+
+test "rightOuterJoin: leftPred filtering out the only match still keeps the right row with left=null" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "active", .value = .{ .boolean = false } }});
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    const activeOnly = Predicate{ .eq = .{ .field = "active", .value = .{ .boolean = true } } };
+    const joined = try rightOuterJoin(testing.allocator, &customers, "__pk", activeOnly, &orders, "customer_id", null);
+    defer freeRightOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 1), joined.len);
+    try testing.expect(joined[0].left == null);
+}
+
+test "rightOuterJoin: empty left table yields exactly one unmatched row per right row" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    try right.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 1 } }});
+    try right.put(.{ .int = 2 }, &.{.{ .name = "k", .value = .{ .int = 2 } }});
+
+    const joined = try rightOuterJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeRightOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 2), joined.len);
+    for (joined) |pair| {
+        try testing.expect(pair.left == null);
+    }
+}
+
+test "rightOuterJoin: one-to-many fan-out on the matched side still produces one row per match" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 42 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    var i: i64 = 0;
+    while (i < 5) : (i += 1) {
+        try right.put(.{ .int = i }, &.{.{ .name = "k", .value = .{ .int = 42 } }});
+    }
+
+    const joined = try rightOuterJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeRightOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 5), joined.len);
+    for (joined) |pair| {
+        try testing.expect(pair.left != null);
+    }
+}
+
+test "fullOuterJoin: rows unmatched on either side survive, matched pairs appear once" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var customers = try Table.open(&db, testing.allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "alice" } }}); // matches
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "bob" } }}); // never ordered
+
+    var orders = try Table.open(&db, testing.allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 101 }, &.{.{ .name = "customer_id", .value = .{ .int = 999 } }}); // orphan order
+
+    const joined = try fullOuterJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+    defer freeFullOuterJoined(testing.allocator, joined);
+
+    // alice+order100 (matched), bob+null (left-only), null+order101 (right-only).
+    try testing.expectEqual(@as(usize, 3), joined.len);
+    var sawMatched = false;
+    var sawLeftOnly = false;
+    var sawRightOnly = false;
+    for (joined) |pair| {
+        if (pair.left != null and pair.right != null) {
+            try testing.expectEqualStrings("alice", pair.left.?.get("name").?.text);
+            sawMatched = true;
+        } else if (pair.left != null and pair.right == null) {
+            try testing.expectEqualStrings("bob", pair.left.?.get("name").?.text);
+            sawLeftOnly = true;
+        } else if (pair.left == null and pair.right != null) {
+            try testing.expectEqual(@as(i64, 999), pair.right.?.get("customer_id").?.int);
+            sawRightOnly = true;
+        } else {
+            try testing.expect(false); // unreachable: both sides null never happens
+        }
+    }
+    try testing.expect(sawMatched);
+    try testing.expect(sawLeftOnly);
+    try testing.expect(sawRightOnly);
+}
+
+test "fullOuterJoin: fully disjoint tables yield exactly one unmatched row per side" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    try left.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 1 } }});
+
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+    try right.put(.{ .int = 1 }, &.{.{ .name = "k", .value = .{ .int = 2 } }});
+
+    const joined = try fullOuterJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeFullOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 2), joined.len);
+    var leftOnly: usize = 0;
+    var rightOnly: usize = 0;
+    for (joined) |pair| {
+        if (pair.left != null and pair.right == null) leftOnly += 1;
+        if (pair.left == null and pair.right != null) rightOnly += 1;
+    }
+    try testing.expectEqual(@as(usize, 1), leftOnly);
+    try testing.expectEqual(@as(usize, 1), rightOnly);
+}
+
+test "fullOuterJoin: both tables empty yields zero rows" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    var left = try Table.open(&db, testing.allocator, "left");
+    defer left.deinit();
+    var right = try Table.open(&db, testing.allocator, "right");
+    defer right.deinit();
+
+    const joined = try fullOuterJoin(testing.allocator, &left, "k", null, &right, "k", null);
+    defer freeFullOuterJoined(testing.allocator, joined);
+
+    try testing.expectEqual(@as(usize, 0), joined.len);
+}
+
+fn openFourPairJoin(tmp: *std.testing.TmpDir, db: *dbmod.Db) ![]JoinedRow {
+    var customers = try Table.open(db, testing.allocator, "customers");
+    defer customers.deinit();
+    var orders = try Table.open(db, testing.allocator, "orders");
+    defer orders.deinit();
+
+    var i: i64 = 1;
+    while (i <= 4) : (i += 1) {
+        try customers.put(.{ .int = i }, &.{.{ .name = "name", .value = .{ .int = i } }});
+        try orders.put(.{ .int = i * 100 }, &.{.{ .name = "customer_id", .value = .{ .int = i } }});
+    }
+    _ = tmp;
+    return innerJoin(testing.allocator, &customers, "__pk", null, &orders, "customer_id", null);
+}
+
+fn customerNames(pairs: []const JoinedRow) [4]i64 {
+    var out: [4]i64 = undefined;
+    for (pairs, 0..) |p, i| out[i] = p.left.get("name").?.int;
+    return out;
+}
+
+test "applyPage with offset and limit keeps a middle window in order" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    const joined = try openFourPairJoin(&tmp, &db);
+    try testing.expectEqual(@as(usize, 4), joined.len);
+
+    const paged = try applyPage(JoinedRow, testing.allocator, joined, .{ .offset = 1, .limit = 2 });
+    defer freeJoined(testing.allocator, paged);
+
+    try testing.expectEqual(@as(usize, 2), paged.len);
+    try testing.expectEqual(@as(i64, 2), paged[0].left.get("name").?.int);
+    try testing.expectEqual(@as(i64, 3), paged[1].left.get("name").?.int);
+}
+
+test "applyPage with limit 0 returns every row, matching unlimited select" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    const joined = try openFourPairJoin(&tmp, &db);
+    const paged = try applyPage(JoinedRow, testing.allocator, joined, .{});
+    defer freeJoined(testing.allocator, paged);
+
+    try testing.expectEqualSlices(i64, &.{ 1, 2, 3, 4 }, &customerNames(paged));
+}
+
+test "applyPage with offset past the end returns nothing" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    const joined = try openFourPairJoin(&tmp, &db);
+    const paged = try applyPage(JoinedRow, testing.allocator, joined, .{ .offset = 50 });
+    defer freeJoined(testing.allocator, paged);
+
+    try testing.expectEqual(@as(usize, 0), paged.len);
+}
+
+test "applyPage with limit larger than the remaining rows stops at the end" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    const joined = try openFourPairJoin(&tmp, &db);
+    const paged = try applyPage(JoinedRow, testing.allocator, joined, .{ .offset = 3, .limit = 100 });
+    defer freeJoined(testing.allocator, paged);
+
+    try testing.expectEqual(@as(usize, 1), paged.len);
+    try testing.expectEqual(@as(i64, 4), paged[0].left.get("name").?.int);
+}
+
+test "applyPage propagates OutOfMemory from its own result allocation without leaking any row" {
+    var tmp = testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTestDb(&tmp);
+    defer db.close();
+
+    // `joined` itself is built with the real `testing.allocator` - every
+    // `Row` inside stores that same allocator (see `row.zig`'s `Row.init`),
+    // so `applyPage`'s error path frees each one through it regardless of
+    // which allocator `applyPage` was asked to allocate its OWN result
+    // slice with below. Isolates the OOM path to exactly one call site:
+    // the `allocator.alloc(T, kept)` in `applyPage` itself, not the join
+    // that already succeeded.
+    const joined = try openFourPairJoin(&tmp, &db);
+    try testing.expectEqual(@as(usize, 4), joined.len);
+
+    var failing = testing.FailingAllocator.init(testing.allocator, .{ .fail_index = 0 });
+    try testing.expectError(error.OutOfMemory, applyPage(JoinedRow, failing.allocator(), joined, .{ .offset = 1, .limit = 2 }));
+    // No explicit assertion beyond this: `testing.allocator`'s leak
+    // detector at process exit is the real check - every one of the 4
+    // `JoinedRow`s (2 kept by the window, 2 trimmed outside it) must have
+    // been `.deinit()`-ed on the error path in `applyPage`, and the
+    // `rows` backing slice itself freed, or this test fails on leak.
+}
diff --git a/src/keyspace.zig b/src/keyspace.zig
new file mode 100644
index 0000000..4e8eada
--- /dev/null
+++ b/src/keyspace.zig
@@ -0,0 +1,96 @@
+const std = @import("std");
+const auth = @import("auth.zig");
+const index = @import("index.zig");
+const collections = @import("collections.zig");
+const collttl = @import("collttl.zig");
+const ttl = @import("ttl.zig");
+
+/// Single source of truth for every top-level byte tag a module uses to
+/// namespace its own keys in the flat `Db` keyspace (auth.zig/index.zig/
+/// collections.zig/collttl.zig/ttl.zig each own one plain byte as the
+/// first byte of every key they write, and rely on every OTHER module
+/// picking a different one - the entire scheme is "gentleman's agreement
+/// by comment" with nothing that actually enforces it).
+///
+/// Session #29 hit the failure mode this closes: collttl.zig originally
+/// reused ttl.zig's tag 'T' (only byte-disjoint via an extra marker byte,
+/// not prefix-disjoint), so ttl.zig's `sweepExpired` prefix-scan over "T"
+/// silently matched collttl.zig's markers too, corrupting sweep counts and
+/// leaving collections un-swept. It was caught by a flaky-looking test
+/// failure, not by anything structural - nothing stopped a *third* module
+/// from making the same mistake tomorrow.
+///
+/// Each entry below points at the module's own `pub const ...Tag`
+/// definition instead of retyping the byte, so this list is derived FROM
+/// the real definitions and cannot silently drift out of sync with them.
+/// `assertAllDistinct` runs at comptime (see the `comptime` block below,
+/// pulled in transitively by every build via root.zig) - a future module
+/// that picks an already-taken byte fails the BUILD, not a test someone
+/// has to remember to write.
+pub const Entry = struct { owner: []const u8, tag: u8 };
+
+pub const registry = [_]Entry{
+    .{ .owner = "auth", .tag = auth.nsTag },
+    .{ .owner = "index.row", .tag = index.rowTag },
+    .{ .owner = "index.index", .tag = index.indexTag },
+    .{ .owner = "index.compositeIndex", .tag = index.compositeIndexTag },
+    .{ .owner = "index.meta", .tag = index.metaTag },
+    .{ .owner = "collections", .tag = collections.nsTag },
+    .{ .owner = "collttl", .tag = collttl.nsTag },
+    .{ .owner = "ttl", .tag = ttl.nsTag },
+};
+
+fn assertAllDistinct() void {
+    @setEvalBranchQuota(10_000);
+    for (registry, 0..) |a, i| {
+        for (registry[i + 1 ..]) |b| {
+            if (a.tag == b.tag) {
+                @compileError("keyspace tag collision: '" ++ &[_]u8{a.tag} ++ "' claimed by both '" ++ a.owner ++ "' and '" ++ b.owner ++ "' - pick a different top-level byte for one of them");
+            }
+        }
+    }
+}
+
+comptime {
+    assertAllDistinct();
+}
+
+/// `true` iff no other registered owner already claims `tag` - the check a
+/// brand new module should run against its OWN candidate byte before
+/// wiring it into `registry` above, so the collision surfaces while
+/// picking the byte instead of after writing a whole module around it.
+pub fn isFree(tag: u8) bool {
+    for (registry) |e| {
+        if (e.tag == tag) return false;
+    }
+    return true;
+}
+
+test "registry has no duplicate top-level tags (runtime mirror of the comptime check)" {
+    for (registry, 0..) |a, i| {
+        for (registry[i + 1 ..]) |b| {
+            try std.testing.expect(a.tag != b.tag);
+        }
+    }
+}
+
+test "registry pins the exact set of tags currently in use" {
+    var seen = std.AutoHashMap(u8, void).init(std.testing.allocator);
+    defer seen.deinit();
+    for (registry) |e| try seen.put(e.tag, {});
+    // A change here (tag added, removed, or reassigned) must be a
+    // deliberate edit to this file's `registry` literal, not something
+    // that happened to fall out of touching an unrelated module.
+    try std.testing.expectEqual(@as(usize, 8), seen.count());
+    inline for (.{ 'A', 'R', 'I', 'J', 'M', 'X', 'Y', 'T' }) |expected| {
+        try std.testing.expect(seen.contains(expected));
+    }
+}
+
+test "isFree reports the registered tags as taken and an unused byte as free" {
+    try std.testing.expect(!isFree('A'));
+    try std.testing.expect(!isFree('T'));
+    try std.testing.expect(!isFree('Y'));
+    try std.testing.expect(isFree('Z'));
+    try std.testing.expect(isFree(0));
+}
diff --git a/src/main.zig b/src/main.zig
index b3d9650..aa8332f 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -1,21 +1,561 @@
 const std = @import("std");
 const cobalt = @import("root.zig");
 
+const Value = cobalt.row.Value;
+const Field = cobalt.row.Field;
+
 const usage =
     \\cobalt - LSM key/value store
     \\
     \\usage: cobalt <dir> <command> [args]
     \\
     \\commands:
-    \\  put <key> <value>        store a value
-    \\  get <key>                print a value or (nil)
+    \\  put <key> <value> [--ttl <seconds>]
+    \\                            store a value, optionally set to expire
+    \\  get <key>                print a value or (nil); a key past its ttl
+    \\                            reads as (nil) and is deleted lazily on this read
     \\  del <key>                delete a key
+    \\  expire <key> <seconds>   set/replace a key's ttl; error if the key does
+    \\                            not currently exist (nonexistent keys have no ttl to set)
+    \\  persist <key>            remove a key's ttl, making it immortal again
+    \\  ttl <key>                print seconds left, -1 if no ttl, -2 if no such key
+    \\  expire-sweep              actively delete every key whose ttl is due,
+    \\                            not just the next one someone happens to read;
+    \\                            prints how many were reaped
     \\  scan [start] [end]       forward range scan, start inclusive, end exclusive
     \\  rscan [start] [end]      reverse range scan
     \\  prefix <prefix>          scan every key under a prefix
     \\  compact                  run full leveled compaction
-    \\  stats                    print database statistics
+    \\  stats [--prom]           print database statistics (optionally as Prometheus text)
     \\  verify <n>               write n keys, reopen, check durability and scan order
+    \\  serve [host:port] [--rate-limit <capacity> <per-second>]
+    \\                     [--per-conn-rate-limit <capacity> <per-second>] [--auth]
+    \\                     [--session-ttl <seconds>] [--session-sweep-interval <seconds>]
+    \\                     [--ttl-sweep-interval <seconds>] [--coll-ttl-sweep-interval <seconds>]
+    \\                            run a TCP server (default 127.0.0.1:6380),
+    \\                            optionally capping requests with a shared
+    \\                            token bucket and/or a private one per
+    \\                            connection (both may be given together);
+    \\                            --auth requires an AUTH before any op but
+    \\                            ping, refuses to start if no admin user
+    \\                            exists yet (see `user add`); --session-ttl
+    \\                            (requires --auth) makes AUTH return a
+    \\                            token valid for that many seconds - a new
+    \\                            connection can present it via AUTH_TOKEN
+    \\                            instead of the password, and the role it
+    \\                            grants stops working once the ttl elapses
+    \\                            even on a connection that never disconnects;
+    \\                            --session-sweep-interval (requires
+    \\                            --session-ttl) periodically drops sessions
+    \\                            that expired but nobody ever presented again;
+    \\                            --ttl-sweep-interval periodically reaps every
+    \\                            key whose ttl is due, independent of --auth
+    \\                            (like local `expire-sweep`, but automatic);
+    \\                            --coll-ttl-sweep-interval does the same for
+    \\                            whole collections (like local
+    \\                            `coll expire-sweep`), independent of
+    \\                            --ttl-sweep-interval - either, both, or
+    \\                            neither may be given
+    \\
+    \\cobalt <host:port> remote-select <table> [expr...] [--limit N] [--offset N]
+    \\                                          [--order-by field[:desc][,field[:desc]...]]
+    \\                                          [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table select` there (same expr grammar as
+    \\                            local `table select`; empty expr selects
+    \\                            every row) - no local Db is opened;
+    \\                            --user/--pass authenticate first, needed
+    \\                            only if the server was started with --auth;
+    \\                            --token authenticates with a previously
+    \\                            issued session token instead of a password
+    \\                            (requires the server to have --session-ttl)
+    \\
+    \\cobalt <host:port> remote-explain <table> [expr...]
+    \\                                          [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table explain` there (same expr grammar as
+    \\                            local `table select`) - no local Db is opened;
+    \\                            --user/--pass or --token authenticate first,
+    \\                            same as `remote-select`
+    \\
+    \\cobalt <host:port> remote-update <table> --set field=value[,field=value...] [expr...]
+    \\                                          [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table update` there (same --set grammar and
+    \\                            expr grammar as local `table update`; empty
+    \\                            expr updates every row) - no local Db is
+    \\                            opened; prints the number of rows updated;
+    \\                            --user/--pass or --token authenticate first,
+    \\                            same as `remote-select`
+    \\
+    \\cobalt <host:port> remote-delete <table> [expr...]
+    \\                                          [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table delete` there (same expr grammar as
+    \\                            local `table delete`; empty expr deletes
+    \\                            every row) - no local Db is opened; prints
+    \\                            the number of rows deleted; --user/--pass or
+    \\                            --token authenticate first, same as
+    \\                            `remote-select`
+    \\
+    \\cobalt <host:port> remote-export <table> csv|json <path>
+    \\                                          [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table export` there (same output shape as
+    \\                            local `table export`), writing the result to
+    \\                            <path> on THIS machine - no local Db is
+    \\                            opened; prints the row count written;
+    \\                            --user/--pass or --token authenticate first,
+    \\                            same as `remote-select`
+    \\
+    \\cobalt <host:port> remote-import <table> csv|json <path>
+    \\                                          [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table import` there, reading <path> on THIS
+    \\                            machine and sending its bytes in one frame -
+    \\                            no local Db is opened; prints the row count
+    \\                            imported; --user/--pass or --token
+    \\                            authenticate first, same as `remote-select`
+    \\
+    \\cobalt <host:port> remote-join [--left|--right|--full] <leftTable> <leftField>
+    \\                                <rightTable> <rightField> [--left-expr E] [--right-expr E]
+    \\                                [--limit N] [--offset N]
+    \\                                [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table join` there (same 4 modes as local
+    \\                            `table join`; --left-expr/--right-expr are
+    \\                            the same expr grammar as `table select`,
+    \\                            filtering each side before the join runs;
+    \\                            --limit/--offset window the already-joined
+    \\                            result, same convention as `table select`) -
+    \\                            no local Db is opened; --user/--pass or
+    \\                            --token authenticate first, same as
+    \\                            `remote-select`
+    \\
+    \\cobalt <host:port> remote-aggregate <table> <groupField|*> <spec>[,<spec>...] [expr...]
+    \\                                     [having <expr>] [order <field[:desc]>[,field...]]
+    \\                                     [--limit N] [--offset N]
+    \\                                     [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table aggregate` there (same spec grammar
+    \\                            as local `table aggregate`: count |
+    \\                            count:field | sum:field | avg:field |
+    \\                            min:field | max:field | distinct:field,
+    \\                            comma-separated;
+    \\                            `*` as groupField means no GROUP BY, always
+    \\                            at most one result row and --limit/--offset
+    \\                            are ignored; expr filters rows before
+    \\                            aggregating, same grammar as `table
+    \\                            select`; an optional `having <expr>` after
+    \\                            expr filters the result groups after
+    \\                            aggregation, same as local `table
+    \\                            aggregate`; an optional `order
+    \\                            <field[:desc]>[,field...]` after having
+    \\                            sorts the result groups server-side before
+    \\                            --limit/--offset window them, same as
+    \\                            local `table aggregate`; --limit/--offset
+    \\                            window the result groups, same convention
+    \\                            as `table select`) - no local Db is opened;
+    \\                            --user/--pass or --token authenticate
+    \\                            first, same as `remote-select`
+    \\
+    \\cobalt <host:port> remote-window <table> <kind[:field]>[,<kind[:field]>...] [expr...]
+    \\                                  [partition <field>[,field...]]
+    \\                                  [order <field[:desc]>[,field...]]
+    \\                                  [--limit N] [--offset N] [--range]
+    \\                                  [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and run a
+    \\                            `table window` there (same spec-list
+    \\                            grammar as local `table window`: row_number |
+    \\                            rank | dense_rank | count | count:field |
+    \\                            count_distinct:field | sum:field | avg:field |
+    \\                            min:field | max:field | first_value:field |
+    \\                            last_value:field | nth_value:field:n[:default] |
+    \\                            lag:field[:offset[:default]] |
+    \\                            lead:field[:offset[:default]],
+    \\                            comma-separated for multiple
+    \\                            annotation columns sharing one partition/
+    \\                            order/frame; lag/lead read the field's value
+    \\                            `offset` rows before/after the current row
+    \\                            within the partition's order sequence
+    \\                            (default offset 1, default value SQL NULL
+    \\                            unless an `i:`/`f:`/`b:`/`s:`-prefixed
+    \\                            `default` literal is given); first_value/
+    \\                            last_value/nth_value read the current
+    \\                            frame's first/last/n-th row (n is 1-based,
+    \\                            required, no SQL default) - UNLIKE lag/lead,
+    \\                            these respect --range - see local `table
+    \\                            window`'s help for the full frame-end
+    \\                            semantics; expr
+    \\                            filters rows before annotation, same
+    \\                            grammar as `table select`;
+    \\                            an optional `partition <field>[,field...]`
+    \\                            after expr splits rows into independent
+    \\                            groups, same as local `table window`; an
+    \\                            optional `order <field[:desc]>[,field...]`
+    \\                            after partition orders rows within each
+    \\                            partition for ranking/running-aggregate
+    \\                            purposes; every matching row comes back
+    \\                            annotated (never collapsed, unlike `table
+    \\                            aggregate`); --limit/--offset window WHICH
+    \\                            rows are returned, walked in the same
+    \\                            partition-then-order sequence used to
+    \\                            compute them, not raw scan order; --range
+    \\                            switches sum/avg/count/min/max to a RANGE
+    \\                            frame (rows tied on `order` share the tie
+    \\                            group's combined value instead of each
+    \\                            accumulating its own, SQL's actual default;
+    \\                            rejected together with row_number/rank/
+    \\                            dense_rank, same as local `table window`)
+    \\                            - no local Db is opened; --user/--pass or
+    \\                            --token authenticate first, same as
+    \\                            `remote-select`
+    \\
+    \\cobalt <host:port> remote-publish <channel> <message...> [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and
+    \\                            deliver <message> (joined from every
+    \\                            trailing word) to every connection
+    \\                            currently subscribed to <channel>; prints
+    \\                            how many subscribers it reached (0 is a
+    \\                            normal outcome for a channel nobody is
+    \\                            listening to, not an error) - no local Db
+    \\                            is opened
+    \\
+    \\cobalt <host:port> remote-subscribe <channel>[,channel...] [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and
+    \\                            block, printing "subscribed as <id>" on the
+    \\                            first line, then "<channel>: <message>" for
+    \\                            every message published to any of the
+    \\                            listed channels, until the connection
+    \\                            closes (Ctrl+C, or the server shutting
+    \\                            down) - the connection becomes receive-only
+    \\                            once subscribed: to drop some of its
+    \\                            channels without closing it, run
+    \\                            `remote-unsubscribe <id> ...` from a
+    \\                            different terminal
+    \\
+    \\cobalt <host:port> remote-unsubscribe <subscriber-id> <channel>[,channel...] [--user NAME --pass PASS] [--token TOKEN]
+    \\                            connect to a running `cobalt serve` and
+    \\                            drop the listed channels from
+    \\                            <subscriber-id> (printed by
+    \\                            `remote-subscribe` when it started); prints
+    \\                            how many channels were actually removed
+    \\                            (naming one the subscriber was never on is
+    \\                            harmless and does not count, not an
+    \\                            error); an unknown or already-disconnected
+    \\                            <subscriber-id> is reported as an error,
+    \\                            not silently ignored; dropping every
+    \\                            channel the subscriber still has ends that
+    \\                            subscription outright, same as closing its
+    \\                            connection - no local Db is opened
+    \\
+    \\cobalt <host:port> remote-user add|passwd|role|del|list [args] [--user NAME --pass PASS] [--token TOKEN]
+    \\                            same operations as `user`, but against a
+    \\                            running `cobalt serve` over the network
+    \\                            instead of a local Db file - requires admin
+    \\                            role if the server was started with --auth
+    \\                            (--user/--pass or --token authenticate first)
+    \\
+    \\cobalt <host:port> remote-ttl expire <key> <seconds> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-ttl persist <key> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-ttl ttl <key> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-ttl sweep [--user NAME --pass PASS] [--token TOKEN]
+    \\                            same four operations as local `expire`/
+    \\                            `persist`/`ttl`/`expire-sweep`, but against a
+    \\                            running `cobalt serve` over the network -
+    \\                            `ttl` needs only readonly role, the other
+    \\                            three need readwrite, if the server was
+    \\                            started with --auth
+    \\
+    \\cobalt <host:port> remote-coll-ttl <kind> expire <name> <seconds> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll-ttl <kind> persist <name> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll-ttl <kind> ttl <name> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll-ttl sweep [--user NAME --pass PASS] [--token TOKEN]
+    \\                            same operations as local `coll <kind>
+    \\                            expire|ttl|persist`/`coll expire-sweep`, but
+    \\                            against a running `cobalt serve` over the
+    \\                            network - `ttl` needs only readonly role,
+    \\                            the other three need readwrite, if the
+    \\                            server was started with --auth
+    \\
+    \\cobalt <host:port> remote-coll counter get|set|incrby <name> [value|delta] [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll hash set|get|del <name> <field> [value] [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll hash len|getall <name> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll set add|rem|ismember <name> <member> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll set card|members <name> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll set inter|union <name> [name...] [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll set diff <name> <other> [other...] [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll list lpush|rpush <name> <value> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll list lpop|rpop|len <name> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll list range <name> <start> <stop> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll zset add <name> <member> <score> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll zset score|rank <name> <member> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll zset incrby <name> <member> <delta> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll zset rem <name> <member> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll zset card <name> [--user NAME --pass PASS] [--token TOKEN]
+    \\cobalt <host:port> remote-coll zset rangebyrank|rangebyscore <name> <lo> <hi> [--user NAME --pass PASS] [--token TOKEN]
+    \\                            same operations as local `coll <kind> <op>`,
+    \\                            against a running `cobalt serve` over the
+    \\                            network - read-only ops (get/len/getall/
+    \\                            ismember/card/members/inter/union/diff/
+    \\                            range/score/rank/rangebyrank/rangebyscore)
+    \\                            need only readonly role, every other op
+    \\                            needs readwrite, if the server was started
+    \\                            with --auth
+    \\
+    \\cobalt <host:port> remote-txn <script-file> [--user NAME --pass PASS] [--token TOKEN]
+    \\                            same script format as local `txn`, but
+    \\                            committed in one round trip against a
+    \\                            running `cobalt serve` over the network -
+    \\                            needs readwrite role if the server was
+    \\                            started with --auth
+    \\
+    \\cobalt <host:port> remote-stats [--user NAME --pass PASS] [--token TOKEN]
+    \\                            print a running `cobalt serve` instance's own
+    \\                            request/rate-limit/auth/session counters
+    \\                            together with its Db stats, as Prometheus
+    \\                            text - the network counterpart of local
+    \\                            `stats --prom`, since a server's own counters
+    \\                            (distinct from its Db's) were otherwise only
+    \\                            ever observable in-process
+    \\
+    \\  user add <username> <password> readonly|readwrite|admin
+    \\  user passwd <username> <newpassword>
+    \\  user role <username> readonly|readwrite|admin
+    \\  user del <username>
+    \\  user list                pre-requisite for `serve --auth`: create at
+    \\                            least one admin user first
+    \\  backup <file>            write a consistent point-in-time backup to <file>
+    \\  restore <file>           replay a backup file into this database
+    \\  backup-info <file>       validate a backup file and print its metadata
+    \\
+    \\  coll counter get|set|incrby <name> [value|delta]
+    \\  coll hash set|get|del <name> <field> [value]
+    \\  coll hash len|getall <name>
+    \\  coll set add|rem|ismember <name> <member>
+    \\  coll set card|members <name>
+    \\  coll set inter|union <name> [name...]
+    \\  coll set diff <name> <other> [other...]
+    \\  coll list lpush|rpush <name> <value>
+    \\  coll list lpop|rpop|len <name>
+    \\  coll list range <name> <start> <stop>
+    \\  coll zset add <name> <member> <score>
+    \\  coll zset score|rank <name> <member>
+    \\  coll zset incrby <name> <member> <delta>
+    \\  coll zset rem <name> <member>
+    \\  coll zset card <name>
+    \\  coll zset rangebyrank|rangebyscore <name> <lo> <hi>
+    \\  coll <kind> expire <name> <seconds>   whole collection expires as one unit
+    \\  coll <kind> ttl <name>                seconds left, -1 no expiry, -2 no such collection
+    \\  coll <kind> persist <name>            clears expiry, collection immortal again
+    \\  coll expire-sweep                     reaps every due collection now, across all kinds
+    \\
+    \\  table put <table> <pk> [field=value ...]
+    \\  table get <table> <pk>
+    \\  table del <table> <pk>
+    \\  table scan <table>
+    \\  table select <table> [expr...] [--limit N] [--offset N]
+    \\                        [--order-by field[:desc][,field[:desc]...]]
+    \\    expr is a predicate: <field> eq|ne|lt|lte|gt|gte|like <value>, composed
+    \\    with "and"/"or"/"not" and parentheses, e.g.
+    \\    city eq s:oslo and not (age lt i:18)
+    \\    like matches SQL-style wildcards against a text field: "%" is any run
+    \\    of characters, "_" is exactly one, e.g. name like s:A%; it never uses
+    \\    an index even when the field is indexed (always a value scan)
+    \\    in and between are sugar over the operators above, so they use an
+    \\    index exactly where the desugared form would:
+    \\    <field> in (<value> ...) is <field> eq v1 or <field> eq v2 or ...
+    \\    (a single value collapses to a bare eq, so it can use an index the
+    \\    same way eq does; two or more never do, same as any other "or")
+    \\    <field> between <lo> and <hi> is <field> gte <lo> and <field> lte
+    \\    <hi> (inclusive both ends), e.g. age between i:18 and i:65,
+    \\    city in (s:oslo s:bergen s:trondheim)
+    \\    <field> is_null / <field> is_not_null take no trailing value; is_null
+    \\    matches a row where the field was never set OR set to an explicit
+    \\    none, e.g. city is_null and age gte i:18 (never uses an index, a
+    \\    sparse row's absence is not something a B-tree entry can represent)
+    \\    (empty expr selects every row; --limit/--offset page the result,
+    \\    limit 0 or omitted means unlimited; --order-by sorts by one or more
+    \\    comma-separated fields, applied left to right (later fields only
+    \\    break ties left by earlier ones), ascending by default or ":desc"
+    \\    per field for descending - rows missing a sort field sort first
+    \\    on it)
+    \\  table explain <table> [expr...]
+    \\    reports which strategy `table select` would use for the same
+    \\    <table>/expr WITHOUT running the query: full scan, a single-field
+    \\    index (equality or range), or a composite index (equality or range,
+    \\    naming how many of its leading columns the expr actually pinned down)
+    \\  table update <table> --set field=value[,field=value...] [expr...]
+    \\    applies the --set field list to every row matched by expr (empty expr
+    \\    updates every row); each set field overrides an existing field of the
+    \\    same name or is added if the row does not have it; unmentioned fields
+    \\    are left as-is; secondary/composite indexes on a changed field are
+    \\    kept in sync exactly like `table put` would; prints the number of
+    \\    rows updated
+    \\  table delete <table> [expr...]
+    \\    removes every row matched by expr (empty expr deletes every row, same
+    \\    convention as `table select`/`table update`); secondary/composite
+    \\    indexes on the deleted rows are kept in sync exactly like `table del`
+    \\    would for a single row; prints the number of rows deleted
+    \\  table index create|drop <table> <field...>  (multiple fields = composite index)
+    \\    create --unique <table> <field>: single-field index that also enforces the
+    \\    field holds a distinct value across every row (SQL UNIQUE); refuses to
+    \\    install over data that already has a duplicate; dropping the index drops
+    \\    the constraint too. Not available for composite (multi-field) indexes.
+    \\  table fk create <table> <field> <refTable> <refField> [restrict|cascade]
+    \\    installs a FOREIGN KEY: every <table> row's (non-null) <field> value must
+    \\    name an existing <refField> on <refTable> (SQL FOREIGN KEY REFERENCES);
+    \\    <refField> must be either the special primary-key name "__pk" or a field
+    \\    already carrying its own --unique index on <refTable>, or the create is
+    \\    refused; refuses to install over a <table> row whose current value has
+    \\    no matching target; rows missing <field> entirely are exempt (nullable FK).
+    \\    Last argument picks ON DELETE behavior for a `table delete`/`table_delete`
+    \\    against <refTable>, default "restrict": restrict refuses the delete while
+    \\    a <table> row still points at it, cascade removes those rows too (and
+    \\    anything cascading from them, recursively). A `txn <script>` delete
+    \\    always restricts regardless of this setting - cascade only fires through
+    \\    the plain (non-transactional) delete path
+    \\  table fk drop <table> <field>
+    \\    removes the foreign key constraint on <field>, if any
+    \\  table check create <table> <name> <expr...>
+    \\    installs a named CHECK constraint (SQL CHECK): every row put into <table>
+    \\    from now on must evaluate <expr> (same predicate language as `table select`)
+    \\    to true, or the put is refused with CheckViolation; refuses to install over
+    \\    existing rows that already fail <expr>; a malformed <expr> is refused with
+    \\    InvalidCheckExpression before anything is persisted
+    \\  table check drop <table> <name>
+    \\    removes the named CHECK constraint, if any
+    \\  table join [--left|--right|--full] <leftTable> <leftField> <rightTable> <rightField>
+    \\    inner equi-join by default: prints "L <row>" / "R <row>" for every matched pair;
+    \\    --left makes it a left outer join: every left row still prints once, with
+    \\    "R (nil)" when it has no match on the right instead of being dropped;
+    \\    --right is the mirror image: every right row prints once, "L (nil)" when unmatched;
+    \\    --full is the union of both: every row on either side prints at least once;
+    \\    uses an index on <rightField> (or <leftField> for --right) when one exists,
+    \\    hash-joins otherwise; [--limit N] [--offset N] window the already-joined
+    \\    result, same convention as `table select` (limit 0 or omitted = unlimited)
+    \\    values/keys are typed: i:<int> f:<float> b:true|false s:<text>, bare text defaults to s:
+    \\  table aggregate <table> <groupField|*> <spec>[,<spec>...] [expr...] [having <expr>]
+    \\                   [order <field[:desc]>[,field...]] [--limit N] [--offset N]
+    \\    spec is count | count:<field> | sum:<field> | avg:<field> | min:<field> | max:<field> |
+    \\    distinct:<field> (COUNT DISTINCT), comma-separated for more than one in the same
+    \\    pass; groupField "*" means no
+    \\    grouping (a single result row over every row matching expr, same predicate
+    \\    grammar as `table select`, and having/order/--limit/--offset are all ignored);
+    \\    rows missing groupField are excluded from every group, rows missing a spec's
+    \\    field are excluded from just that spec; --limit/--offset window the result
+    \\    groups, same convention as `table select`;
+    \\    an optional literal `having <expr>` after the row-filtering expr filters the
+    \\    RESULT groups after aggregation (same expr grammar, evaluated before
+    \\    order/--limit/--offset); its fields are the printed result labels (bare kind
+    \\    name for count, else "<kind>_<field>" e.g. sum_score) plus groupField itself,
+    \\    so e.g. `table aggregate orders city sum:total having sum_total gt i:1000`;
+    \\    an optional literal `order <field[:desc]>[,field...]` after having (or right
+    \\    after the row-filtering expr if there is no having) sorts the result groups
+    \\    before --limit/--offset windows them, one or more comma-separated columns
+    \\    applied left to right same as `table select`'s --order-by, each field naming
+    \\    either groupField or a result label (same two names having's expr can use),
+    \\    e.g. `table aggregate orders city sum:total order sum_total:desc --limit 3`
+    \\    (top 3 cities by total, without needing having at all); without groupField
+    \\    among the sort fields, ties on every named field keep first-seen order
+    \\    (stable sort)
+    \\  table window <table> <kind[:field]>[,<kind[:field]>...] [expr...] [partition <field>[,field...]]
+    \\               [order <field[:desc]>[,field...]] [--limit N] [--offset N] [--range]
+    \\    annotates every matching row with one or more computed window-function
+    \\    columns instead of collapsing rows like `table aggregate` does; kind is
+    \\    row_number | rank | dense_rank (no :field) | sum:<field> | avg:<field> |
+    \\    count | count:<field> | count_distinct:<field> | min:<field> | max:<field> |
+    \\    first_value:<field> | last_value:<field> | nth_value:<field>:<n>[:<default>] |
+    \\    lag:<field>[:<offset>[:<default>]] | lead:<field>[:<offset>[:<default>]];
+    \\    a comma-separated list (e.g. `sum:total,avg:total,rank`) computes every
+    \\    column over the SAME partition/order/frame, printed in the same order
+    \\    after the row's own fields;
+    \\    an optional literal `partition <field>[,field...]` splits rows into
+    \\    independent groups (like GROUP BY, first-seen order; omitted = one
+    \\    partition covering every matching row) and an optional literal `order
+    \\    <field[:desc]>[,field...]` (same syntax as `table select`'s
+    \\    --order-by) decides the ranking/running-total walk within each
+    \\    partition - partition must come before order if both are given;
+    \\    without order, rank/dense_rank treat the whole partition as tied
+    \\    (every row gets 1) and sum/avg/count/count_distinct/min/max give every
+    \\    row the same whole-partition total; with order, sum/avg/count/
+    \\    count_distinct/min/max become a running total walked in that order
+    \\    instead, by default one physical
+    \\    ROW at a time - even a row tied with its predecessor on `order` gets
+    \\    its OWN individual running value; --range switches this to SQL's
+    \\    actual default RANGE frame instead, where rows tied on every `order`
+    \\    column share the LAST tied row's combined value rather than their own
+    \\    (e.g. two rows both on day 1 both show day 1's combined total, not a
+    \\    half/full split); --range has no effect without `order` (both frames
+    \\    already agree there) and is rejected outright together with
+    \\    row_number/rank/dense_rank (neither takes a frame clause in standard
+    \\    SQL either); --limit/--offset window the printed rows in the SAME
+    \\    partition-then-order walk the window computation itself uses (every
+    \\    partition's rows in `order`, first-seen partition order), not raw
+    \\    scan order - e.g. `table window orders row_number partition city
+    \\    order amount:desc --limit 3` prints (up to) the first 3 rows of the
+    \\    first-seen partition in that order, not an arbitrary scan-order slice;
+    \\    lag/lead read <field>'s value <offset> rows before/after the current
+    \\    row within the partition's `order` sequence (first-seen order if no
+    \\    `order` given), always as a DISTINCT physical position even when tied
+    \\    with a neighbor on `order` (unlike the RANGE running-aggregate frame,
+    \\    which collapses ties); a row whose target falls outside the partition
+    \\    gets <default> (an `i:`/`f:`/`b:`/`s:`-prefixed literal, same grammar
+    \\    as put's field=value) or SQL NULL if omitted; <offset> defaults to 1
+    \\    if omitted; --range is rejected outright with lag/lead, same as with
+    \\    row_number/rank/dense_rank (a frame clause has no meaning for either);
+    \\    first_value/last_value/nth_value read <field>'s value from the current
+    \\    frame's first/last/n-th row - UNLIKE lag/lead, these DO respect --range:
+    \\    first_value is always the partition's first row (same in both frames),
+    \\    but last_value's frame end follows the running-aggregate split - without
+    \\    --range (ROWS, ending at CURRENT ROW) last_value degenerates to the
+    \\    row's own field (SQL's well-known gotcha), with --range it is instead
+    \\    the LAST row of the current tie group on `order`; without `order` at
+    \\    all, both give every row the whole partition's first/last value;
+    \\    nth_value shares first_value/last_value's frame exactly (same start,
+    \\    same ROWS/RANGE/no-order end) but reads the <n>-th row (1-based,
+    \\    required - unlike lag/lead's <offset>, SQL's NTH_VALUE has no default
+    \\    position) counted from the frame's START; a row whose current frame is
+    \\    still smaller than <n> gets <default> (same grammar as lag/lead's, SQL
+    \\    NULL if omitted) - e.g. under ROWS, nth_value:total:2 is NULL on the
+    \\    first row of every partition (frame size 1) and 2nd-row's value from
+    \\    then on, once the frame has grown enough to contain it
+    \\  table export <table> csv|json <path>
+    \\    writes every row to <path>; the column/key set is the union of every
+    \\    field name across every row (primary key first, "__pk", then
+    \\    first-seen order), a row missing a column just omits that cell/key
+    \\    rather than writing empty/null; every value is written as a typed
+    \\    string (i:/f:/b:/s:/x:/n:, same prefixes as put's field=value, plus
+    \\    x: for raw bytes hex and n: for none) so re-importing reproduces the
+    \\    exact original type, including floats (encoded as exact bits, not a
+    \\    decimal that could round-trip lossy); prints the row count written
+    \\  table import <table> csv|json <path>
+    \\    reads rows written by `table export` (or any file in the same shape)
+    \\    back into <table> via `table put`, so existing rows sharing a
+    \\    primary key are overwritten and secondary/composite indexes stay in
+    \\    sync; the "__pk" column/key is required; prints the row count read
+    \\
+    \\  txn <script-file>        apply a script of `put|del <table> <pk> [field=value ...]`
+    \\                            lines as one atomic transaction (all-or-nothing, error.Conflict
+    \\                            aborts with nothing applied); blank lines and #comments skipped
+    \\
+    \\  repl [--script <file>]    interactive shell over this database: put/get/del/
+    \\                            scan/stats/flush/compact plus table put/get/del and
+    \\                            coll <kind> <op> [args...] (counter/hash/set/list/
+    \\                            zset), with begin/commit/rollback bracketing an
+    \\                            interactive transaction (get mid-transaction can
+    \\                            steer the next put, unlike a static `txn` script).
+    \\                            Reads stdin with a prompt by default, or a file
+    \\                            non-interactively with --script.
+    \\
+    \\  replicate <replica-dir> [--once] [--interval-ms <n>]
+    \\                            tail this database's WAL and apply new writes onto
+    \\                            <replica-dir> (opened/created fresh). Runs a bootstrap
+    \\                            fullResync first, then loops calling syncOnce every
+    \\                            interval-ms (default 200) until interrupted, or once
+    \\                            and exit if --once is given. Recovers automatically
+    \\                            from a fallen-behind tailer (primary flushed before
+    \\                            catching up) via another fullResync.
     \\
 ;
 
@@ -45,16 +585,150 @@ pub fn main() !void {
         return;
     }
 
+    if (std.mem.eql(u8, command, "remote-select")) {
+        // Reuses the <dir> slot as a host:port to connect to, exactly like
+        // `verify` reuses it as the directory under test - `remote-select`
+        // never opens a local Db at all.
+        try runRemoteSelect(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-join")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteJoin(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-aggregate")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteAggregate(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-window")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteWindow(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-publish")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemotePublish(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-subscribe")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteSubscribe(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-unsubscribe")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteUnsubscribe(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-explain")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteExplain(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-update")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteUpdate(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-delete")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteDelete(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-export")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteExport(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-import")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteImport(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-user")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select` - never opens a local Db.
+        try runRemoteUser(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-stats")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select`/`remote-user` - never opens a local Db.
+        try runRemoteStats(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-ttl")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-select`/`remote-user`/`remote-stats` - never opens a
+        // local Db.
+        try runRemoteTtl(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-coll-ttl")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-ttl` - never opens a local Db.
+        try runRemoteCollTtl(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-coll")) {
+        // Same "<dir> slot is really host:port" convention as
+        // `remote-coll-ttl` - never opens a local Db.
+        try runRemoteColl(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
+    if (std.mem.eql(u8, command, "remote-txn")) {
+        // Same "<dir> slot is really host:port" convention as every other
+        // remote-* command - never opens a local Db.
+        try runRemoteTxn(allocator, stdout, stderr, dir, rest);
+        return;
+    }
+
     var db = try cobalt.Db.open(allocator, dir, .{});
     defer db.close();
 
     if (std.mem.eql(u8, command, "put")) {
         if (rest.len < 2) return fail(stderr, "put needs <key> <value>");
         try db.put(rest[0], rest[1]);
+        if (rest.len >= 4 and std.mem.eql(u8, rest[2], "--ttl")) {
+            const seconds = std.fmt.parseInt(u64, rest[3], 10) catch return fail(stderr, "--ttl needs a whole number of seconds");
+            try cobalt.ttl.setExpireSeconds(&db, allocator, rest[0], std.time.nanoTimestamp(), seconds);
+        } else if (rest.len > 2) {
+            return fail(stderr, "put takes <key> <value> [--ttl <seconds>]");
+        }
         try db.maybeCompact();
     } else if (std.mem.eql(u8, command, "get")) {
         if (rest.len < 1) return fail(stderr, "get needs <key>");
-        if (try db.get(allocator, rest[0])) |value| {
+        if (try cobalt.ttl.getLive(&db, allocator, rest[0], std.time.nanoTimestamp())) |value| {
             defer allocator.free(value);
             try stdout.print("{s}\n", .{value});
         } else {
@@ -63,7 +737,27 @@ pub fn main() !void {
     } else if (std.mem.eql(u8, command, "del")) {
         if (rest.len < 1) return fail(stderr, "del needs <key>");
         try db.delete(rest[0]);
+        try cobalt.ttl.clearExpire(&db, allocator, rest[0]);
         try db.maybeCompact();
+    } else if (std.mem.eql(u8, command, "expire")) {
+        if (rest.len < 2) return fail(stderr, "expire needs <key> <seconds>");
+        const seconds = std.fmt.parseInt(u64, rest[1], 10) catch return fail(stderr, "expire needs a whole number of seconds");
+        const existing = try db.get(allocator, rest[0]) orelse return fail(stderr, "no such key");
+        allocator.free(existing);
+        try cobalt.ttl.setExpireSeconds(&db, allocator, rest[0], std.time.nanoTimestamp(), seconds);
+    } else if (std.mem.eql(u8, command, "persist")) {
+        if (rest.len < 1) return fail(stderr, "persist needs <key>");
+        try cobalt.ttl.clearExpire(&db, allocator, rest[0]);
+    } else if (std.mem.eql(u8, command, "ttl")) {
+        if (rest.len < 1) return fail(stderr, "ttl needs <key>");
+        switch (try cobalt.ttl.remaining(&db, allocator, rest[0], std.time.nanoTimestamp())) {
+            .noKey => try stdout.writeAll("-2\n"),
+            .noExpiry => try stdout.writeAll("-1\n"),
+            .seconds => |s| try stdout.print("{d}\n", .{s}),
+        }
+    } else if (std.mem.eql(u8, command, "expire-sweep")) {
+        const reaped = try cobalt.ttl.sweepExpired(&db, allocator, std.time.nanoTimestamp());
+        try stdout.print("reaped: {d}\n", .{reaped});
     } else if (std.mem.eql(u8, command, "scan")) {
         const start: ?[]const u8 = if (rest.len >= 1) rest[0] else null;
         const end: ?[]const u8 = if (rest.len >= 2) rest[1] else null;
@@ -85,7 +779,47 @@ pub fn main() !void {
         try db.compact();
         try stdout.print("sstables after compaction: {d}\n", .{db.sstables.items.len});
     } else if (std.mem.eql(u8, command, "stats")) {
-        try db.stats().print(stdout);
+        if (rest.len >= 1 and std.mem.eql(u8, rest[0], "--prom")) {
+            try cobalt.metrics.formatDbStats(stdout, "cobalt", db.stats());
+        } else {
+            try db.stats().print(stdout);
+        }
+    } else if (std.mem.eql(u8, command, "serve")) {
+        const bind = if (rest.len >= 1) rest[0] else "127.0.0.1:6380";
+        const serveRest = if (rest.len >= 1) rest[1..] else rest;
+        try runServe(allocator, stdout, &db, bind, serveRest);
+    } else if (std.mem.eql(u8, command, "backup")) {
+        if (rest.len < 1) return fail(stderr, "backup needs <file>");
+        const snap = try db.snapshot();
+        const count = try cobalt.backup.dumpToFile(allocator, snap, rest[0]);
+        try stdout.print("backup written: {d} entries, seq={d}, file={s}\n", .{ count, snap.seq, rest[0] });
+    } else if (std.mem.eql(u8, command, "restore")) {
+        if (rest.len < 1) return fail(stderr, "restore needs <file>");
+        const info = cobalt.backup.restoreFromFile(allocator, &db, rest[0], 500) catch |err| {
+            try stderr.print("restore failed: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("restore applied: {d} entries from seq={d}\n", .{ info.entryCount, info.seq });
+    } else if (std.mem.eql(u8, command, "coll")) {
+        try runColl(allocator, stdout, stderr, &db, rest);
+    } else if (std.mem.eql(u8, command, "table")) {
+        try runTable(allocator, stdout, stderr, &db, rest);
+    } else if (std.mem.eql(u8, command, "user")) {
+        try runUser(allocator, stdout, stderr, &db, rest);
+    } else if (std.mem.eql(u8, command, "txn")) {
+        try runTxn(allocator, stdout, stderr, &db, rest);
+    } else if (std.mem.eql(u8, command, "replicate")) {
+        if (rest.len < 1) return fail(stderr, "replicate needs <replica-dir>");
+        try runReplicate(allocator, stdout, &db, rest[0], rest[1..]);
+    } else if (std.mem.eql(u8, command, "repl")) {
+        try runRepl(allocator, stdout, stderr, &db, rest);
+    } else if (std.mem.eql(u8, command, "backup-info")) {
+        if (rest.len < 1) return fail(stderr, "backup-info needs <file>");
+        const info = cobalt.backup.inspectFile(allocator, rest[0]) catch |err| {
+            try stderr.print("invalid backup: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("entries={d} seq={d}\n", .{ info.entryCount, info.seq });
     } else {
         try stderr.print("unknown command: {s}\n", .{command});
         try stderr.writeAll(usage);
@@ -98,6 +832,2812 @@ fn fail(stderr: anytype, message: []const u8) !void {
     std.process.exit(2);
 }
 
+fn boolFlag(v: bool) u8 {
+    return if (v) 1 else 0;
+}
+
+/// Dispatches `coll <kind> <op> [args...]` onto the Redis-like typed
+/// collections in collections.zig (Counter/Hash/Set/List/ZSet), which until
+/// now were only reachable through the library API, never a CLI.
+fn runColl(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, db: *cobalt.Db, rest: []const []const u8) !void {
+    if (rest.len >= 1 and std.mem.eql(u8, rest[0], "expire-sweep")) {
+        const reaped = try cobalt.collttl.sweepExpired(db, allocator, std.time.nanoTimestamp());
+        try stdout.print("reaped: {d}\n", .{reaped});
+        return;
+    }
+    if (rest.len < 2) return fail(stderr, "coll needs <kind> <op> ...");
+    const kind = rest[0];
+    const op = rest[1];
+    const args = rest[2..];
+
+    if (std.mem.eql(u8, op, "expire") or std.mem.eql(u8, op, "ttl") or std.mem.eql(u8, op, "persist")) {
+        const k = cobalt.CollectionKind.parse(kind) orelse return fail(stderr, "unknown collection kind (expected counter/hash/set/list/zset)");
+        return runCollTtl(allocator, stdout, stderr, db, k, op, args);
+    }
+
+    // Lazy expiry on the read/write path: every remaining op below takes the
+    // collection name as args[0], so this is what keeps a bare
+    // `coll hash get <name> ...` from ever reading a collection that is
+    // logically already gone. `set inter|union|diff` accept further names
+    // past args[0] - those get their own expireIfDueMany call right before
+    // dispatch, so this single-name check only needs to cover args[0].
+    if (args.len >= 1) {
+        if (cobalt.CollectionKind.parse(kind)) |k| {
+            _ = try cobalt.collttl.expireIfDue(db, allocator, k, args[0], std.time.nanoTimestamp());
+        }
+    }
+
+    if (std.mem.eql(u8, kind, "counter")) {
+        if (std.mem.eql(u8, op, "get")) {
+            if (args.len < 1) return fail(stderr, "counter get needs <name>");
+            const v = try cobalt.Counter.get(db, allocator, args[0]);
+            try stdout.print("{d}\n", .{v});
+        } else if (std.mem.eql(u8, op, "set")) {
+            if (args.len < 2) return fail(stderr, "counter set needs <name> <value>");
+            const v = std.fmt.parseInt(i64, args[1], 10) catch return fail(stderr, "invalid integer value");
+            try cobalt.Counter.set(db, allocator, args[0], v);
+            try stdout.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "incrby")) {
+            if (args.len < 2) return fail(stderr, "counter incrby needs <name> <delta>");
+            const delta = std.fmt.parseInt(i64, args[1], 10) catch return fail(stderr, "invalid integer delta");
+            const v = try cobalt.Counter.incrBy(db, allocator, args[0], delta);
+            try stdout.print("{d}\n", .{v});
+        } else {
+            return fail(stderr, "unknown counter operation");
+        }
+    } else if (std.mem.eql(u8, kind, "hash")) {
+        if (std.mem.eql(u8, op, "set")) {
+            if (args.len < 3) return fail(stderr, "hash set needs <name> <field> <value>");
+            const created = try cobalt.Hash.set(db, allocator, args[0], args[1], args[2]);
+            try stdout.print("{s}\n", .{if (created) "created" else "updated"});
+        } else if (std.mem.eql(u8, op, "get")) {
+            if (args.len < 2) return fail(stderr, "hash get needs <name> <field>");
+            if (try cobalt.Hash.get(db, allocator, args[0], args[1])) |v| {
+                defer allocator.free(v);
+                try stdout.print("{s}\n", .{v});
+            } else {
+                try stdout.writeAll("(nil)\n");
+            }
+        } else if (std.mem.eql(u8, op, "del")) {
+            if (args.len < 2) return fail(stderr, "hash del needs <name> <field>");
+            const existed = try cobalt.Hash.del(db, allocator, args[0], args[1]);
+            try stdout.print("{d}\n", .{boolFlag(existed)});
+        } else if (std.mem.eql(u8, op, "len")) {
+            if (args.len < 1) return fail(stderr, "hash len needs <name>");
+            const n = try cobalt.Hash.len(db, allocator, args[0]);
+            try stdout.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "getall")) {
+            if (args.len < 1) return fail(stderr, "hash getall needs <name>");
+            const fields = try cobalt.Hash.getAll(db, allocator, args[0]);
+            defer {
+                for (fields) |f| f.free(allocator);
+                allocator.free(fields);
+            }
+            for (fields) |f| try stdout.print("{s}\t{s}\n", .{ f.field, f.value });
+        } else {
+            return fail(stderr, "unknown hash operation");
+        }
+    } else if (std.mem.eql(u8, kind, "set")) {
+        if (std.mem.eql(u8, op, "add")) {
+            if (args.len < 2) return fail(stderr, "set add needs <name> <member>");
+            const added = try cobalt.Set.add(db, allocator, args[0], args[1]);
+            try stdout.print("{d}\n", .{boolFlag(added)});
+        } else if (std.mem.eql(u8, op, "rem")) {
+            if (args.len < 2) return fail(stderr, "set rem needs <name> <member>");
+            const removed = try cobalt.Set.remove(db, allocator, args[0], args[1]);
+            try stdout.print("{d}\n", .{boolFlag(removed)});
+        } else if (std.mem.eql(u8, op, "ismember")) {
+            if (args.len < 2) return fail(stderr, "set ismember needs <name> <member>");
+            const is = try cobalt.Set.isMember(db, allocator, args[0], args[1]);
+            try stdout.print("{d}\n", .{boolFlag(is)});
+        } else if (std.mem.eql(u8, op, "card")) {
+            if (args.len < 1) return fail(stderr, "set card needs <name>");
+            const n = try cobalt.Set.card(db, allocator, args[0]);
+            try stdout.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "members")) {
+            if (args.len < 1) return fail(stderr, "set members needs <name>");
+            const ms = try cobalt.Set.members(db, allocator, args[0]);
+            defer {
+                for (ms) |m| allocator.free(m);
+                allocator.free(ms);
+            }
+            for (ms) |m| try stdout.print("{s}\n", .{m});
+        } else if (std.mem.eql(u8, op, "inter")) {
+            if (args.len < 1) return fail(stderr, "set inter needs at least one <name>");
+            // The blanket lazy check above only covered args[0]; args[1..]
+            // are additional set names this multi-set op reads directly.
+            _ = try cobalt.collttl.expireIfDueMany(db, allocator, .set, args[1..], std.time.nanoTimestamp());
+            const ms = try cobalt.Set.intersect(db, allocator, args);
+            defer {
+                for (ms) |m| allocator.free(m);
+                allocator.free(ms);
+            }
+            for (ms) |m| try stdout.print("{s}\n", .{m});
+        } else if (std.mem.eql(u8, op, "union")) {
+            if (args.len < 1) return fail(stderr, "set union needs at least one <name>");
+            _ = try cobalt.collttl.expireIfDueMany(db, allocator, .set, args[1..], std.time.nanoTimestamp());
+            const ms = try cobalt.Set.unionOf(db, allocator, args);
+            defer {
+                for (ms) |m| allocator.free(m);
+                allocator.free(ms);
+            }
+            for (ms) |m| try stdout.print("{s}\n", .{m});
+        } else if (std.mem.eql(u8, op, "diff")) {
+            if (args.len < 2) return fail(stderr, "set diff needs <name> <other...>");
+            _ = try cobalt.collttl.expireIfDueMany(db, allocator, .set, args[1..], std.time.nanoTimestamp());
+            const ms = try cobalt.Set.difference(db, allocator, args[0], args[1..]);
+            defer {
+                for (ms) |m| allocator.free(m);
+                allocator.free(ms);
+            }
+            for (ms) |m| try stdout.print("{s}\n", .{m});
+        } else {
+            return fail(stderr, "unknown set operation");
+        }
+    } else if (std.mem.eql(u8, kind, "list")) {
+        if (std.mem.eql(u8, op, "lpush")) {
+            if (args.len < 2) return fail(stderr, "list lpush needs <name> <value>");
+            try cobalt.List.pushLeft(db, allocator, args[0], args[1]);
+            try stdout.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "rpush")) {
+            if (args.len < 2) return fail(stderr, "list rpush needs <name> <value>");
+            try cobalt.List.pushRight(db, allocator, args[0], args[1]);
+            try stdout.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "lpop")) {
+            if (args.len < 1) return fail(stderr, "list lpop needs <name>");
+            if (try cobalt.List.popLeft(db, allocator, args[0])) |v| {
+                defer allocator.free(v);
+                try stdout.print("{s}\n", .{v});
+            } else {
+                try stdout.writeAll("(nil)\n");
+            }
+        } else if (std.mem.eql(u8, op, "rpop")) {
+            if (args.len < 1) return fail(stderr, "list rpop needs <name>");
+            if (try cobalt.List.popRight(db, allocator, args[0])) |v| {
+                defer allocator.free(v);
+                try stdout.print("{s}\n", .{v});
+            } else {
+                try stdout.writeAll("(nil)\n");
+            }
+        } else if (std.mem.eql(u8, op, "len")) {
+            if (args.len < 1) return fail(stderr, "list len needs <name>");
+            const n = try cobalt.List.len(db, allocator, args[0]);
+            try stdout.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "range")) {
+            if (args.len < 3) return fail(stderr, "list range needs <name> <start> <stop>");
+            const start = std.fmt.parseInt(i64, args[1], 10) catch return fail(stderr, "invalid start index");
+            const stop = std.fmt.parseInt(i64, args[2], 10) catch return fail(stderr, "invalid stop index");
+            const vals = try cobalt.List.range(db, allocator, args[0], start, stop);
+            defer {
+                for (vals) |v| allocator.free(v);
+                allocator.free(vals);
+            }
+            for (vals) |v| try stdout.print("{s}\n", .{v});
+        } else {
+            return fail(stderr, "unknown list operation");
+        }
+    } else if (std.mem.eql(u8, kind, "zset")) {
+        if (std.mem.eql(u8, op, "add")) {
+            if (args.len < 3) return fail(stderr, "zset add needs <name> <member> <score>");
+            const score = std.fmt.parseFloat(f64, args[2]) catch return fail(stderr, "invalid score");
+            try cobalt.ZSet.add(db, allocator, args[0], args[1], score);
+            try stdout.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "score")) {
+            if (args.len < 2) return fail(stderr, "zset score needs <name> <member>");
+            if (try cobalt.ZSet.score(db, allocator, args[0], args[1])) |s| {
+                try stdout.print("{d}\n", .{s});
+            } else {
+                try stdout.writeAll("(nil)\n");
+            }
+        } else if (std.mem.eql(u8, op, "incrby")) {
+            if (args.len < 3) return fail(stderr, "zset incrby needs <name> <member> <delta>");
+            const delta = std.fmt.parseFloat(f64, args[2]) catch return fail(stderr, "invalid delta");
+            const s = try cobalt.ZSet.incrBy(db, allocator, args[0], args[1], delta);
+            try stdout.print("{d}\n", .{s});
+        } else if (std.mem.eql(u8, op, "rem")) {
+            if (args.len < 2) return fail(stderr, "zset rem needs <name> <member>");
+            const removed = try cobalt.ZSet.remove(db, allocator, args[0], args[1]);
+            try stdout.print("{d}\n", .{boolFlag(removed)});
+        } else if (std.mem.eql(u8, op, "card")) {
+            if (args.len < 1) return fail(stderr, "zset card needs <name>");
+            const n = try cobalt.ZSet.card(db, allocator, args[0]);
+            try stdout.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "rangebyrank")) {
+            if (args.len < 3) return fail(stderr, "zset rangebyrank needs <name> <start> <stop>");
+            const start = std.fmt.parseInt(i64, args[1], 10) catch return fail(stderr, "invalid start rank");
+            const stop = std.fmt.parseInt(i64, args[2], 10) catch return fail(stderr, "invalid stop rank");
+            const zms = try cobalt.ZSet.rangeByRank(db, allocator, args[0], start, stop);
+            defer {
+                for (zms) |zm| zm.free(allocator);
+                allocator.free(zms);
+            }
+            for (zms) |zm| try stdout.print("{s}\t{d}\n", .{ zm.member, zm.score });
+        } else if (std.mem.eql(u8, op, "rangebyscore")) {
+            if (args.len < 3) return fail(stderr, "zset rangebyscore needs <name> <min> <max>");
+            const min = std.fmt.parseFloat(f64, args[1]) catch return fail(stderr, "invalid min score");
+            const max = std.fmt.parseFloat(f64, args[2]) catch return fail(stderr, "invalid max score");
+            const zms = try cobalt.ZSet.rangeByScore(db, allocator, args[0], min, max);
+            defer {
+                for (zms) |zm| zm.free(allocator);
+                allocator.free(zms);
+            }
+            for (zms) |zm| try stdout.print("{s}\t{d}\n", .{ zm.member, zm.score });
+        } else if (std.mem.eql(u8, op, "rank")) {
+            if (args.len < 2) return fail(stderr, "zset rank needs <name> <member>");
+            if (try cobalt.ZSet.rank(db, allocator, args[0], args[1])) |r| {
+                try stdout.print("{d}\n", .{r});
+            } else {
+                try stdout.writeAll("(nil)\n");
+            }
+        } else {
+            return fail(stderr, "unknown zset operation");
+        }
+    } else {
+        return fail(stderr, "unknown collection kind (expected counter/hash/set/list/zset)");
+    }
+}
+
+/// Dispatches `coll <kind> expire|ttl|persist <name> [seconds]` onto
+/// collttl.zig - the whole-collection counterpart of the flat-key
+/// `expire`/`ttl`/`persist` commands above. `expire` mirrors Redis-strict
+/// EXPIRE by checking the collection currently exists first (same shape as
+/// the flat-key `expire` handler checking db.get first).
+fn runCollTtl(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, db: *cobalt.Db, k: cobalt.CollectionKind, op: []const u8, args: []const []const u8) !void {
+    if (std.mem.eql(u8, op, "expire")) {
+        if (args.len < 2) return fail(stderr, "coll <kind> expire needs <name> <seconds>");
+        const seconds = std.fmt.parseInt(u64, args[1], 10) catch return fail(stderr, "expire needs a whole number of seconds");
+        if (!try cobalt.collections.collectionExists(db, allocator, k, args[0])) return fail(stderr, "no such collection");
+        try cobalt.collttl.setExpireSeconds(db, allocator, k, args[0], std.time.nanoTimestamp(), seconds);
+        try stdout.writeAll("OK\n");
+    } else if (std.mem.eql(u8, op, "persist")) {
+        if (args.len < 1) return fail(stderr, "coll <kind> persist needs <name>");
+        try cobalt.collttl.clearExpire(db, allocator, k, args[0]);
+        try stdout.writeAll("OK\n");
+    } else if (std.mem.eql(u8, op, "ttl")) {
+        if (args.len < 1) return fail(stderr, "coll <kind> ttl needs <name>");
+        switch (try cobalt.collttl.remaining(db, allocator, k, args[0], std.time.nanoTimestamp())) {
+            .noKey => try stdout.writeAll("-2\n"),
+            .noExpiry => try stdout.writeAll("-1\n"),
+            .seconds => |s| try stdout.print("{d}\n", .{s}),
+        }
+    } else {
+        return fail(stderr, "unknown coll ttl operation");
+    }
+}
+
+/// Parses a CLI-supplied scalar into a typed row Value. `i:`/`f:`/`b:`/`s:`
+/// prefixes pick int/float/bool/text explicitly; unprefixed text defaults to
+/// `.text`. The returned Value borrows `text` directly (no allocation), so it
+/// is only valid for as long as the argv slice (or script line) it came from.
+fn parseValue(text: []const u8) !Value {
+    return cobalt.row.Value.parseCli(text);
+}
+
+/// Splits `name=value` into a Field, validating the name with the same
+/// identifier rule tables and indexes already enforce.
+fn parseField(text: []const u8) !Field {
+    const eq = std.mem.indexOfScalar(u8, text, '=') orelse return error.InvalidField;
+    const name = text[0..eq];
+    if (!cobalt.index.validIdentifier(name)) return error.InvalidField;
+    const value = try parseValue(text[eq + 1 ..]);
+    return .{ .name = name, .value = value };
+}
+
+const PageFlags = struct { limit: u32 = 0, offset: u32 = 0 };
+
+/// Pulls `--limit N` / `--offset N` out of a `table select`/`remote-select`
+/// argument list wherever they appear, returning the remaining tokens
+/// (destined to be joined into the expr text) alongside the parsed page
+/// window. Caller owns and frees `rest`.
+fn extractPageFlags(allocator: std.mem.Allocator, args: []const []const u8) !struct { page: PageFlags, rest: [][]const u8 } {
+    var page = PageFlags{};
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        const isLimit = std.mem.eql(u8, args[i], "--limit");
+        const isOffset = std.mem.eql(u8, args[i], "--offset");
+        if (isLimit or isOffset) {
+            i += 1;
+            if (i >= args.len) return error.InvalidPageFlag;
+            const n = std.fmt.parseInt(u32, args[i], 10) catch return error.InvalidPageFlag;
+            if (isLimit) page.limit = n else page.offset = n;
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    return .{ .page = page, .rest = try rest.toOwnedSlice() };
+}
+
+/// Pulls a lone `--range` flag (no value) out of `table window`'s/
+/// `remote-window`'s trailing args, requesting `window.FrameMode.range`
+/// (SQL's actual `RANGE` frame default for running aggregates) instead of
+/// this CLI's `.rows` default - see `window.zig`'s `compute` doc comment
+/// for the semantic difference. Kept separate from `extractPageFlags`
+/// (same reason `extractSelectFlags`'s `--order-by` is kept separate:
+/// `extractPageFlags` is also shared by `table join`/`table aggregate`,
+/// neither of which has a frame concept to silently swallow the flag into).
+/// Caller owns and frees `rest`.
+fn extractRangeFlag(allocator: std.mem.Allocator, args: []const []const u8) !struct { range: bool, rest: [][]const u8 } {
+    var range = false;
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+    for (args) |a| {
+        if (std.mem.eql(u8, a, "--range")) {
+            range = true;
+        } else {
+            try rest.append(a);
+        }
+    }
+    return .{ .range = range, .rest = try rest.toOwnedSlice() };
+}
+
+const SelectFlags = struct { page: PageFlags = .{}, orderBy: []const cobalt.query.OrderBy = &.{} };
+
+/// `table select`/`remote-select`-only counterpart of `extractPageFlags`:
+/// same `--limit`/`--offset` handling plus `--order-by
+/// field[:desc][,field[:desc]...]` (one or more comma-separated columns,
+/// applied left to right - later columns only break ties left by earlier
+/// ones, same as SQL's `ORDER BY a, b`), kept as a SEPARATE function (not
+/// folded into `extractPageFlags` itself) because `extractPageFlags` is
+/// also shared by `table join`/`table aggregate` (and their remote
+/// mirrors) - if `--order-by` were recognized there too, it would be
+/// silently consumed and have no effect, since neither join nor aggregate
+/// sorts its result. Better a flag those two commands don't recognize at
+/// all than one they swallow without honoring. Caller owns and frees
+/// `rest` AND `flags.orderBy` (empty slice when the flag was never given,
+/// still safe to free).
+fn extractSelectFlags(allocator: std.mem.Allocator, args: []const []const u8) !struct { flags: SelectFlags, rest: [][]const u8 } {
+    var flags = SelectFlags{};
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        const isLimit = std.mem.eql(u8, args[i], "--limit");
+        const isOffset = std.mem.eql(u8, args[i], "--offset");
+        const isOrderBy = std.mem.eql(u8, args[i], "--order-by");
+        if (isLimit or isOffset) {
+            i += 1;
+            if (i >= args.len) return error.InvalidPageFlag;
+            const n = std.fmt.parseInt(u32, args[i], 10) catch return error.InvalidPageFlag;
+            if (isLimit) flags.page.limit = n else flags.page.offset = n;
+        } else if (isOrderBy) {
+            i += 1;
+            if (i >= args.len) return error.InvalidPageFlag;
+            allocator.free(flags.orderBy);
+            flags.orderBy = try parseOrderByList(allocator, args[i]);
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    return .{ .flags = flags, .rest = try rest.toOwnedSlice() };
+}
+
+/// Parses `--order-by`'s `field[:desc]` value, shared by `parseOrderByList`
+/// (both `table select` and `remote-select` route through it) and
+/// repl.zig's identically-shaped copy of the same flag. The suffix after
+/// the colon must be exactly `desc` or `asc` - anything else (a typo'd
+/// `:dsc`) is rejected rather than silently defaulting to ascending,
+/// matching the CLI's usual "malformed input is an error, not a guess"
+/// convention.
+fn parseOrderByFlag(text: []const u8) !cobalt.query.OrderBy {
+    if (std.mem.indexOfScalar(u8, text, ':')) |colon| {
+        const field = text[0..colon];
+        const dir = text[colon + 1 ..];
+        if (field.len == 0) return error.InvalidPageFlag;
+        if (std.mem.eql(u8, dir, "desc")) return .{ .field = field, .descending = true };
+        if (std.mem.eql(u8, dir, "asc")) return .{ .field = field, .descending = false };
+        return error.InvalidPageFlag;
+    }
+    if (text.len == 0) return error.InvalidPageFlag;
+    return .{ .field = text };
+}
+
+/// Splits `--order-by`'s comma-separated value into one or more columns,
+/// each parsed by `parseOrderByFlag` - `city,age:desc` sorts by `city`
+/// ascending, breaking ties by `age` descending. A leading, trailing, or
+/// doubled comma yields an empty segment, rejected the same way a
+/// malformed direction suffix is (not silently skipped), so `city,,age` is
+/// an error rather than a silently-collapsed two-column sort. Caller owns
+/// and frees the returned slice.
+fn parseOrderByList(allocator: std.mem.Allocator, text: []const u8) ![]cobalt.query.OrderBy {
+    var list = std.ArrayList(cobalt.query.OrderBy).init(allocator);
+    errdefer list.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |segment| {
+        try list.append(try parseOrderByFlag(segment));
+    }
+    return list.toOwnedSlice();
+}
+
+/// Splits `--set`'s comma-separated `name=value[,name=value...]` value into
+/// a list of Fields, each parsed by `parseField` - the `table update`/
+/// `remote-update` counterpart of `parseOrderByList`. A leading, trailing,
+/// or doubled comma yields an empty segment, which `parseField`'s missing
+/// `=` check rejects the same way a malformed order-by suffix is (not
+/// silently skipped). Caller owns and frees the returned slice.
+fn parseSetList(allocator: std.mem.Allocator, text: []const u8) ![]Field {
+    var list = std.ArrayList(Field).init(allocator);
+    errdefer list.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |segment| {
+        try list.append(try parseField(segment));
+    }
+    return list.toOwnedSlice();
+}
+
+/// Pulls a single required `--set name=value[,name=value...]` flag out of a
+/// `table update`/`remote-update` argument list, returning the parsed field
+/// list alongside the remaining tokens (destined to be joined into the expr
+/// text) - the update counterpart of `extractSelectFlags`. A missing
+/// `--set` is `error.MissingSetFlag`: unlike a `WHERE` predicate (optional,
+/// empty text means every row), a `SET`-less `UPDATE` names nothing to
+/// change and is rejected rather than silently accepted as a no-op. Caller
+/// owns and frees `rest` and the returned `sets` slice.
+fn extractSetFlag(allocator: std.mem.Allocator, args: []const []const u8) !struct { sets: []Field, rest: [][]const u8 } {
+    var sets: []Field = &.{};
+    errdefer allocator.free(sets);
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        if (std.mem.eql(u8, args[i], "--set")) {
+            i += 1;
+            if (i >= args.len) return error.InvalidSetFlag;
+            allocator.free(sets);
+            sets = parseSetList(allocator, args[i]) catch return error.InvalidSetFlag;
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    if (sets.len == 0) return error.MissingSetFlag;
+    return .{ .sets = sets, .rest = try rest.toOwnedSlice() };
+}
+
+fn printValue(stdout: anytype, value: Value) !void {
+    switch (value) {
+        .none => try stdout.writeAll("(none)"),
+        .boolean => |b| try stdout.print("{}", .{b}),
+        .int => |i| try stdout.print("{d}", .{i}),
+        .float => |f| try stdout.print("{d}", .{f}),
+        .text => |s| try stdout.writeAll(s),
+        .bytes => |b| for (b) |byte| try stdout.print("{x:0>2}", .{byte}),
+    }
+}
+
+fn printRow(stdout: anytype, row: cobalt.row.Row) !void {
+    for (row.fields.items, 0..) |f, i| {
+        if (i > 0) try stdout.writeAll("\t");
+        try stdout.print("{s}=", .{f.name});
+        try printValue(stdout, f.value);
+    }
+    try stdout.writeAll("\n");
+}
+
+/// Prints a `query.Plan` in the same human-readable shape for `table
+/// explain`, `remote-explain`, and the repl's `table explain` - one line
+/// naming the strategy `selectPage` would actually take, not a guess.
+fn printPlan(stdout: anytype, plan: cobalt.query.Plan) !void {
+    switch (plan.kind) {
+        .full_scan => try stdout.writeAll("full scan (no usable index)\n"),
+        .index_eq => try stdout.print("index '{s}' (equality)\n", .{plan.indexName.?}),
+        .index_range => try stdout.print("index '{s}' (range)\n", .{plan.indexName.?}),
+        .composite_eq => try stdout.print("composite index '{s}' (equality, {d}/{d} columns matched)\n", .{ plan.indexName.?, plan.matchedFields, plan.totalFields }),
+        .composite_range => try stdout.print("composite index '{s}' (range, {d}/{d} columns matched)\n", .{ plan.indexName.?, plan.matchedFields, plan.totalFields }),
+    }
+}
+
+fn parseAggKind(name: []const u8) ?cobalt.AggKind {
+    if (std.mem.eql(u8, name, "count")) return .count;
+    if (std.mem.eql(u8, name, "sum")) return .sum;
+    if (std.mem.eql(u8, name, "avg")) return .avg;
+    if (std.mem.eql(u8, name, "min")) return .min;
+    if (std.mem.eql(u8, name, "max")) return .max;
+    if (std.mem.eql(u8, name, "distinct")) return .count_distinct;
+    return null;
+}
+
+/// Parses a comma-separated `table aggregate` spec list (e.g.
+/// `count,sum:score,max:score,distinct:city`) into `AggSpec`s. Every kind
+/// but bare `count` (COUNT(*)) requires a `:field` suffix, validated with
+/// the same identifier rule tables/indexes already enforce. Returned
+/// `field` slices borrow from `text` (itself a CLI arg living for the
+/// process), so callers only need to free the returned slice itself, not
+/// each field.
+fn parseAggSpecs(allocator: std.mem.Allocator, text: []const u8) ![]cobalt.AggSpec {
+    var specs = std.ArrayList(cobalt.AggSpec).init(allocator);
+    errdefer specs.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |part| {
+        if (part.len == 0) return error.InvalidAggSpec;
+        if (std.mem.indexOfScalar(u8, part, ':')) |colon| {
+            const kind = parseAggKind(part[0..colon]) orelse return error.InvalidAggSpec;
+            const field = part[colon + 1 ..];
+            if (!cobalt.index.validIdentifier(field)) return error.InvalidAggSpec;
+            try specs.append(.{ .field = field, .kind = kind });
+        } else {
+            const kind = parseAggKind(part) orelse return error.InvalidAggSpec;
+            if (kind != .count) return error.InvalidAggSpec;
+            try specs.append(.{ .field = "", .kind = kind });
+        }
+    }
+    if (specs.items.len == 0) return error.InvalidAggSpec;
+    return specs.toOwnedSlice();
+}
+
+fn findLiteralToken(args: []const []const u8, token: []const u8) ?usize {
+    for (args, 0..) |a, i| {
+        if (std.mem.eql(u8, a, token)) return i;
+    }
+    return null;
+}
+
+/// Splits the trailing free-text args of `table aggregate`/`remote-aggregate`
+/// (after the spec list and any `--limit`/`--offset`/auth flags have already
+/// been pulled out) on literal `having` and `order` tokens, in that clause
+/// order (mirroring SQL's `WHERE ... GROUP BY ... HAVING ... ORDER BY ...`):
+/// everything before `having` (or `order`, if `having` is absent) is the
+/// WHERE-style expr filtering rows BEFORE aggregation (unchanged behavior);
+/// everything between `having` and `order` (or to the end, if `order` is
+/// absent) is the HAVING expr filtering result groups AFTER aggregation;
+/// everything after `order` is the ORDER BY field list - a single token like
+/// `--order-by`'s value (`parseOrderByList` splits it further), not a
+/// free-text expr, so unlike `havingArgs` a well-formed `orderArgs` is
+/// always exactly one element. Neither `having` nor `order` is a keyword
+/// `expr.zig` itself understands - they only have meaning as this
+/// CLI-level separator. Either or both tokens absent means "no HAVING"/"no
+/// ORDER BY", the same as before ORDER BY existed for `table aggregate`.
+fn splitAggFilterArgs(args: []const []const u8) struct { whereArgs: []const []const u8, havingArgs: ?[]const []const u8, orderArgs: ?[]const []const u8 } {
+    if (findLiteralToken(args, "having")) |hi| {
+        const whereArgs = args[0..hi];
+        const afterHaving = args[hi + 1 ..];
+        if (findLiteralToken(afterHaving, "order")) |oi| {
+            return .{ .whereArgs = whereArgs, .havingArgs = afterHaving[0..oi], .orderArgs = afterHaving[oi + 1 ..] };
+        }
+        return .{ .whereArgs = whereArgs, .havingArgs = afterHaving, .orderArgs = null };
+    }
+    if (findLiteralToken(args, "order")) |oi| {
+        return .{ .whereArgs = args[0..oi], .havingArgs = null, .orderArgs = args[oi + 1 ..] };
+    }
+    return .{ .whereArgs = args, .havingArgs = null, .orderArgs = null };
+}
+
+fn printAggLabel(stdout: anytype, spec: cobalt.AggSpec) !void {
+    if (spec.field.len == 0) {
+        try stdout.writeAll(@tagName(spec.kind));
+    } else {
+        try stdout.print("{s}_{s}", .{ @tagName(spec.kind), spec.field });
+    }
+}
+
+fn parseWindowKind(name: []const u8) ?cobalt.WindowKind {
+    if (std.mem.eql(u8, name, "row_number")) return .row_number;
+    if (std.mem.eql(u8, name, "rank")) return .rank;
+    if (std.mem.eql(u8, name, "dense_rank")) return .dense_rank;
+    if (std.mem.eql(u8, name, "sum")) return .sum;
+    if (std.mem.eql(u8, name, "avg")) return .avg;
+    if (std.mem.eql(u8, name, "count")) return .count;
+    if (std.mem.eql(u8, name, "count_distinct")) return .count_distinct;
+    if (std.mem.eql(u8, name, "min")) return .min;
+    if (std.mem.eql(u8, name, "max")) return .max;
+    if (std.mem.eql(u8, name, "lag")) return .lag;
+    if (std.mem.eql(u8, name, "lead")) return .lead;
+    if (std.mem.eql(u8, name, "first_value")) return .first_value;
+    if (std.mem.eql(u8, name, "last_value")) return .last_value;
+    if (std.mem.eql(u8, name, "nth_value")) return .nth_value;
+    return null;
+}
+
+/// Parses a single `table window` spec token: `<kind>`, `<kind>:<field>`,
+/// - `lag`/`lead` only - `<kind>:<field>[:<offset>[:<default>]]`, or -
+/// `nth_value` only - `<kind>:<field>:<n>[:<default>]`. `row_number`/
+/// `rank`/`dense_rank` never take a `:field` suffix (there is nothing to
+/// point them at); `count` may omit one (`COUNT(*)`) or take one;
+/// `sum`/`avg`/`min`/`max`/`first_value`/`last_value`/`count_distinct`
+/// always require exactly one - `count_distinct` has no `COUNT(*)`-style
+/// bare form since "distinct values of nothing" is not meaningful. `lag`/`lead`
+/// always require a field and additionally accept an optional integer
+/// `offset` (SQL's default of 1 if omitted) and, only alongside an
+/// explicit offset, an optional `default` literal in the same `i:`/`f:`/
+/// `b:`/`s:`-prefixed grammar `parseValue` already uses for `put`
+/// (`WindowSpec`'s SQL NULL default if omitted). `nth_value` always requires
+/// a field AND a positive integer `n` (unlike `lag`/`lead`'s offset, SQL's
+/// `NTH_VALUE` has no default position to fall back to) plus, optionally,
+/// the same `default` literal grammar for when `n` falls outside the
+/// current frame. Returned `field`/`default` text borrows from `text` (a
+/// CLI arg living for the process).
+fn parseWindowSpec(text: []const u8) !cobalt.WindowSpec {
+    var it = std.mem.splitScalar(u8, text, ':');
+    const kind = parseWindowKind(it.next().?) orelse return error.InvalidWindowSpec;
+
+    if (kind == .row_number or kind == .rank or kind == .dense_rank) {
+        if (it.next() != null) return error.InvalidWindowSpec;
+        return .{ .field = "", .kind = kind };
+    }
+    if (kind == .lag or kind == .lead) {
+        const field = it.next() orelse return error.InvalidWindowSpec;
+        if (!cobalt.index.validIdentifier(field)) return error.InvalidWindowSpec;
+        var spec = cobalt.WindowSpec{ .field = field, .kind = kind };
+        if (it.next()) |offsetText| {
+            spec.offset = std.fmt.parseInt(u64, offsetText, 10) catch return error.InvalidWindowSpec;
+            // `it.rest()`, NOT another `it.next()`: a typed default literal
+            // (`i:-1`, `s:foo:bar`) can itself contain colons, which would
+            // get wrongly re-split by a further `splitScalar` step.
+            const rest = it.rest();
+            if (rest.len > 0) spec.default = parseValue(rest) catch return error.InvalidWindowSpec;
+        }
+        return spec;
+    }
+    if (kind == .nth_value) {
+        const field = it.next() orelse return error.InvalidWindowSpec;
+        if (!cobalt.index.validIdentifier(field)) return error.InvalidWindowSpec;
+        const nText = it.next() orelse return error.InvalidWindowSpec;
+        const n = std.fmt.parseInt(u64, nText, 10) catch return error.InvalidWindowSpec;
+        if (n == 0) return error.InvalidWindowSpec;
+        var spec = cobalt.WindowSpec{ .field = field, .kind = kind, .offset = n };
+        const rest = it.rest();
+        if (rest.len > 0) spec.default = parseValue(rest) catch return error.InvalidWindowSpec;
+        return spec;
+    }
+
+    const field = it.next() orelse {
+        if (kind == .count) return .{ .field = "", .kind = kind };
+        return error.InvalidWindowSpec;
+    };
+    if (it.next() != null) return error.InvalidWindowSpec;
+    if (!cobalt.index.validIdentifier(field)) return error.InvalidWindowSpec;
+    return .{ .field = field, .kind = kind };
+}
+
+/// Parses `table window`'s comma-separated spec list (`sum:total,avg:total,
+/// row_number` - same comma-joined shape as `parseAggSpecs`, so a `table
+/// window` call can now annotate every matching row with MULTIPLE computed
+/// columns sharing one `PARTITION BY`/`ORDER BY`/frame, mirroring
+/// `window.computeMany`) into `WindowSpec`s via `parseWindowSpec` per token.
+/// Returned `field` slices borrow from `text`, same convention as
+/// `parseAggSpecs`; caller owns and frees the returned slice.
+fn parseWindowSpecs(allocator: std.mem.Allocator, text: []const u8) ![]cobalt.WindowSpec {
+    var specs = std.ArrayList(cobalt.WindowSpec).init(allocator);
+    errdefer specs.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |part| {
+        if (part.len == 0) return error.InvalidWindowSpec;
+        try specs.append(try parseWindowSpec(part));
+    }
+    if (specs.items.len == 0) return error.InvalidWindowSpec;
+    return specs.toOwnedSlice();
+}
+
+fn printWindowLabel(stdout: anytype, spec: cobalt.WindowSpec) !void {
+    if (spec.field.len == 0) {
+        try stdout.writeAll(@tagName(spec.kind));
+    } else {
+        try stdout.print("{s}_{s}", .{ @tagName(spec.kind), spec.field });
+    }
+}
+
+/// Splits the trailing free-text args of `table window` (after the spec
+/// token and any `--limit`/`--offset` flags have already been pulled out)
+/// on literal `partition` and `order` tokens, in that clause order
+/// (mirroring SQL's `OVER (PARTITION BY ... ORDER BY ...)`) - the `table
+/// window` counterpart of `splitAggFilterArgs`. Everything before
+/// `partition` (or `order`, if `partition` is absent) is the WHERE-style
+/// expr filtering rows before annotation; everything between `partition`
+/// and `order` (or to the end) is the partition field list (a single
+/// comma-separated token, parsed by the caller); everything after `order`
+/// is the ORDER BY field list, same shape as `splitAggFilterArgs`'s
+/// `orderArgs`. Either or both tokens absent means "one implicit partition"
+/// / "no ORDER BY".
+fn splitWindowArgs(args: []const []const u8) struct { whereArgs: []const []const u8, partitionArgs: ?[]const []const u8, orderArgs: ?[]const []const u8 } {
+    if (findLiteralToken(args, "partition")) |pi| {
+        const whereArgs = args[0..pi];
+        const afterPartition = args[pi + 1 ..];
+        if (findLiteralToken(afterPartition, "order")) |oi| {
+            return .{ .whereArgs = whereArgs, .partitionArgs = afterPartition[0..oi], .orderArgs = afterPartition[oi + 1 ..] };
+        }
+        return .{ .whereArgs = whereArgs, .partitionArgs = afterPartition, .orderArgs = null };
+    }
+    if (findLiteralToken(args, "order")) |oi| {
+        return .{ .whereArgs = args[0..oi], .partitionArgs = null, .orderArgs = args[oi + 1 ..] };
+    }
+    return .{ .whereArgs = args, .partitionArgs = null, .orderArgs = null };
+}
+
+/// Parses `table window`'s `partition <field>[,field...]` value into a
+/// borrowed field-name list (same non-owning convention `parseWindowSpec`
+/// uses) - a leading/trailing/doubled comma yields an empty segment,
+/// rejected by `index.validIdentifier` the same way a malformed order-by
+/// suffix is elsewhere, not silently skipped. Caller owns and frees the
+/// returned slice (not each field - they borrow from `text`).
+fn parsePartitionList(allocator: std.mem.Allocator, text: []const u8) ![][]const u8 {
+    var list = std.ArrayList([]const u8).init(allocator);
+    errdefer list.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |field| {
+        if (!cobalt.index.validIdentifier(field)) return error.InvalidPartitionField;
+        try list.append(field);
+    }
+    return list.toOwnedSlice();
+}
+
+/// Dispatches `user <op> ...` onto auth.zig's Store: username/password/role
+/// management for `serve --auth`, always operating on the local Db file
+/// directly (never over the wire - creating the first admin has to work
+/// even before any server is running, and there is no bootstrap way to
+/// AUTH your way into creating the first account).
+fn runUser(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, db: *cobalt.Db, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "user needs a subcommand (add/passwd/role/del/list)");
+    const op = rest[0];
+    const args = rest[1..];
+    const store = cobalt.AuthStore.init(db);
+
+    if (std.mem.eql(u8, op, "add")) {
+        if (args.len < 3) return fail(stderr, "user add needs <username> <password> readonly|readwrite|admin");
+        const role = cobalt.AuthRole.parse(args[2]) catch return fail(stderr, "role must be readonly, readwrite, or admin");
+        store.createUser(allocator, args[0], args[1], role, cobalt.auth.recommendedRounds) catch |err| {
+            return fail(stderr, @errorName(err));
+        };
+        try stdout.print("user '{s}' created with role {s}\n", .{ args[0], role.name() });
+    } else if (std.mem.eql(u8, op, "passwd")) {
+        if (args.len < 2) return fail(stderr, "user passwd needs <username> <newpassword>");
+        store.setPassword(allocator, args[0], args[1], cobalt.auth.recommendedRounds) catch |err| {
+            return fail(stderr, @errorName(err));
+        };
+        try stdout.print("password updated for '{s}'\n", .{args[0]});
+    } else if (std.mem.eql(u8, op, "role")) {
+        if (args.len < 2) return fail(stderr, "user role needs <username> readonly|readwrite|admin");
+        const role = cobalt.AuthRole.parse(args[1]) catch return fail(stderr, "role must be readonly, readwrite, or admin");
+        store.setRole(allocator, args[0], role) catch |err| {
+            return fail(stderr, @errorName(err));
+        };
+        try stdout.print("role for '{s}' set to {s}\n", .{ args[0], role.name() });
+    } else if (std.mem.eql(u8, op, "del")) {
+        if (args.len < 1) return fail(stderr, "user del needs <username>");
+        store.deleteUser(allocator, args[0]) catch |err| {
+            return fail(stderr, @errorName(err));
+        };
+        try stdout.print("user '{s}' deleted\n", .{args[0]});
+    } else if (std.mem.eql(u8, op, "list")) {
+        const users = try store.listUsers(allocator);
+        defer cobalt.auth.freeUserList(allocator, users);
+        for (users) |u| try stdout.print("{s}\t{s}\n", .{ u.username, u.role.name() });
+    } else {
+        return fail(stderr, "unknown user operation");
+    }
+}
+
+/// Dispatches `table <op> <table> ...` onto query.zig's Table: schemaless
+/// rows with secondary indexes, until now only reachable through the library
+/// API. Opens a fresh Table view per invocation (indexes are loaded from
+/// their persisted metadata, so this is consistent across process restarts).
+fn runTable(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, db: *cobalt.Db, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "table needs a subcommand (put/get/del/delete/scan/select/index/join/aggregate/export/import)");
+    const sub = rest[0];
+    const args = rest[1..];
+
+    if (std.mem.eql(u8, sub, "put")) {
+        if (args.len < 2) return fail(stderr, "table put needs <table> <pk> [field=value ...]");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+        const pk = parseValue(args[1]) catch return fail(stderr, "invalid primary key");
+
+        var fields = std.ArrayList(Field).init(allocator);
+        defer fields.deinit();
+        for (args[2..]) |raw| {
+            const f = parseField(raw) catch return fail(stderr, "invalid field, expected name=value");
+            try fields.append(f);
+        }
+        table.put(pk, fields.items) catch |err| return fail(stderr, @errorName(err));
+        try stdout.writeAll("OK\n");
+    } else if (std.mem.eql(u8, sub, "get")) {
+        if (args.len < 2) return fail(stderr, "table get needs <table> <pk>");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+        const pk = parseValue(args[1]) catch return fail(stderr, "invalid primary key");
+        var got = try table.get(pk);
+        if (got) |*row| {
+            defer row.deinit();
+            try printRow(stdout, row.*);
+        } else {
+            try stdout.writeAll("(nil)\n");
+        }
+    } else if (std.mem.eql(u8, sub, "del")) {
+        if (args.len < 2) return fail(stderr, "table del needs <table> <pk>");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+        const pk = parseValue(args[1]) catch return fail(stderr, "invalid primary key");
+        try table.delete(pk);
+        try stdout.writeAll("OK\n");
+    } else if (std.mem.eql(u8, sub, "scan")) {
+        if (args.len < 1) return fail(stderr, "table scan needs <table>");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+        const rows = try table.scanAll();
+        defer cobalt.query.freeRows(allocator, rows);
+        for (rows) |r| try printRow(stdout, r);
+    } else if (std.mem.eql(u8, sub, "select")) {
+        if (args.len < 1) return fail(stderr, "table select needs <table> [expr...] [--limit N] [--offset N] [--order-by field[:desc][,field[:desc]...]]");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+
+        const sel = extractSelectFlags(allocator, args[1..]) catch return fail(stderr, "invalid --limit/--offset/--order-by value");
+        defer allocator.free(sel.rest);
+        defer allocator.free(sel.flags.orderBy);
+
+        const exprText = try std.mem.join(allocator, " ", sel.rest);
+        defer allocator.free(exprText);
+
+        var parsed: ?cobalt.expr.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = cobalt.expr.parse(allocator, exprText) catch |err| return fail(stderr, @errorName(err));
+        }
+        const pred: ?cobalt.Predicate = if (parsed) |p| p.predicate else null;
+
+        const rows = try table.selectPageOrdered(pred, .{ .offset = sel.flags.page.offset, .limit = sel.flags.page.limit }, sel.flags.orderBy);
+        defer cobalt.query.freeRows(allocator, rows);
+        for (rows) |r| try printRow(stdout, r);
+    } else if (std.mem.eql(u8, sub, "explain")) {
+        if (args.len < 1) return fail(stderr, "table explain needs <table> [expr...]");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+
+        const exprText = try std.mem.join(allocator, " ", args[1..]);
+        defer allocator.free(exprText);
+
+        var parsed: ?cobalt.expr.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = cobalt.expr.parse(allocator, exprText) catch |err| return fail(stderr, @errorName(err));
+        }
+        const pred: ?cobalt.Predicate = if (parsed) |p| p.predicate else null;
+
+        var plan = try table.explain(allocator, pred);
+        defer plan.deinit(allocator);
+        try printPlan(stdout, plan);
+    } else if (std.mem.eql(u8, sub, "update")) {
+        if (args.len < 1) return fail(stderr, "table update needs <table> --set field=value[,field=value...] [expr...]");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+
+        const setf = extractSetFlag(allocator, args[1..]) catch |err| return fail(stderr, if (err == error.MissingSetFlag)
+            "table update requires --set field=value[,field=value...]"
+        else
+            "invalid --set value");
+        defer allocator.free(setf.sets);
+        defer allocator.free(setf.rest);
+
+        const exprText = try std.mem.join(allocator, " ", setf.rest);
+        defer allocator.free(exprText);
+
+        var parsed: ?cobalt.expr.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = cobalt.expr.parse(allocator, exprText) catch |err| return fail(stderr, @errorName(err));
+        }
+        const pred: ?cobalt.Predicate = if (parsed) |p| p.predicate else null;
+
+        const updated = table.updateWhere(pred, setf.sets) catch |err| return fail(stderr, @errorName(err));
+        try stdout.print("{d}\n", .{updated});
+    } else if (std.mem.eql(u8, sub, "delete")) {
+        if (args.len < 1) return fail(stderr, "table delete needs <table> [expr...]");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+
+        const exprText = try std.mem.join(allocator, " ", args[1..]);
+        defer allocator.free(exprText);
+
+        var parsed: ?cobalt.expr.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = cobalt.expr.parse(allocator, exprText) catch |err| return fail(stderr, @errorName(err));
+        }
+        const pred: ?cobalt.Predicate = if (parsed) |p| p.predicate else null;
+
+        const deleted = table.deleteWhere(pred) catch |err| return fail(stderr, @errorName(err));
+        try stdout.print("{d}\n", .{deleted});
+    } else if (std.mem.eql(u8, sub, "index")) {
+        if (args.len < 3) return fail(stderr, "table index needs create|drop <table> <field...>");
+        const action = args[0];
+        var positional = std.ArrayList([]const u8).init(allocator);
+        defer positional.deinit();
+        var unique = false;
+        for (args[1..]) |a| {
+            if (std.mem.eql(u8, a, "--unique")) {
+                unique = true;
+            } else {
+                try positional.append(a);
+            }
+        }
+        if (positional.items.len < 2) return fail(stderr, "table index needs create|drop <table> <field...>");
+        var table = try cobalt.Table.open(db, allocator, positional.items[0]);
+        defer table.deinit();
+        const fields = positional.items[1..];
+        if (std.mem.eql(u8, action, "create")) {
+            if (unique) {
+                if (fields.len != 1) return fail(stderr, "--unique only supports a single field, not a composite index");
+                table.createUniqueIndex(fields[0]) catch |err| return fail(stderr, @errorName(err));
+            } else if (fields.len == 1) {
+                table.createIndex(fields[0]) catch |err| return fail(stderr, @errorName(err));
+            } else {
+                const name = try std.mem.join(allocator, "+", fields);
+                defer allocator.free(name);
+                table.createCompositeIndex(name, fields) catch |err| return fail(stderr, @errorName(err));
+            }
+            try stdout.writeAll("OK\n");
+        } else if (std.mem.eql(u8, action, "drop")) {
+            if (fields.len == 1) {
+                try table.dropIndex(fields[0]);
+            } else {
+                const name = try std.mem.join(allocator, "+", fields);
+                defer allocator.free(name);
+                try table.dropCompositeIndex(name);
+            }
+            try stdout.writeAll("OK\n");
+        } else {
+            return fail(stderr, "unknown table index action (expected create/drop)");
+        }
+    } else if (std.mem.eql(u8, sub, "fk")) {
+        if (args.len < 2) return fail(stderr, "table fk needs create|drop <table> ...");
+        const action = args[0];
+        var table = try cobalt.Table.open(db, allocator, args[1]);
+        defer table.deinit();
+        if (std.mem.eql(u8, action, "create")) {
+            if (args.len < 5) return fail(stderr, "table fk create needs <table> <field> <refTable> <refField> [restrict|cascade]");
+            const onDelete: cobalt.index.OnDelete = if (args.len < 6 or std.mem.eql(u8, args[5], "restrict"))
+                .restrict
+            else if (std.mem.eql(u8, args[5], "cascade"))
+                .cascade
+            else
+                return fail(stderr, "table fk create: last argument must be restrict or cascade");
+            table.createForeignKey(args[2], args[3], args[4], onDelete) catch |err| return fail(stderr, @errorName(err));
+            try stdout.writeAll("OK\n");
+        } else if (std.mem.eql(u8, action, "drop")) {
+            if (args.len < 3) return fail(stderr, "table fk drop needs <table> <field>");
+            try table.dropForeignKey(args[2]);
+            try stdout.writeAll("OK\n");
+        } else {
+            return fail(stderr, "unknown table fk action (expected create/drop)");
+        }
+    } else if (std.mem.eql(u8, sub, "check")) {
+        if (args.len < 2) return fail(stderr, "table check needs create|drop <table> ...");
+        const action = args[0];
+        var table = try cobalt.Table.open(db, allocator, args[1]);
+        defer table.deinit();
+        if (std.mem.eql(u8, action, "create")) {
+            if (args.len < 4) return fail(stderr, "table check create needs <table> <name> <expr...>");
+            const source = try std.mem.join(allocator, " ", args[3..]);
+            defer allocator.free(source);
+            table.createCheckConstraint(args[2], source) catch |err| return fail(stderr, @errorName(err));
+            try stdout.writeAll("OK\n");
+        } else if (std.mem.eql(u8, action, "drop")) {
+            if (args.len < 3) return fail(stderr, "table check drop needs <table> <name>");
+            try table.dropCheckConstraint(args[2]);
+            try stdout.writeAll("OK\n");
+        } else {
+            return fail(stderr, "unknown table check action (expected create/drop)");
+        }
+    } else if (std.mem.eql(u8, sub, "join")) {
+        const JoinMode = enum { inner, left, right, full };
+        var mode: JoinMode = .inner;
+        var positional = std.ArrayList([]const u8).init(allocator);
+        defer positional.deinit();
+        for (args) |a| {
+            if (std.mem.eql(u8, a, "--left")) {
+                mode = .left;
+            } else if (std.mem.eql(u8, a, "--right")) {
+                mode = .right;
+            } else if (std.mem.eql(u8, a, "--full")) {
+                mode = .full;
+            } else {
+                try positional.append(a);
+            }
+        }
+        const pf = extractPageFlags(allocator, positional.items) catch return fail(stderr, "invalid --limit/--offset value");
+        defer allocator.free(pf.rest);
+        if (pf.rest.len < 4) return fail(stderr, "table join needs [--left|--right|--full] <leftTable> <leftField> <rightTable> <rightField> [--limit N] [--offset N]");
+        const jargs = pf.rest;
+        const page = cobalt.query.Page{ .offset = pf.page.offset, .limit = pf.page.limit };
+
+        var left = try cobalt.Table.open(db, allocator, jargs[0]);
+        defer left.deinit();
+        var right = try cobalt.Table.open(db, allocator, jargs[2]);
+        defer right.deinit();
+
+        switch (mode) {
+            .inner => {
+                const joined = cobalt.join.innerJoin(allocator, &left, jargs[1], null, &right, jargs[3], null) catch |err| return fail(stderr, @errorName(err));
+                const paged = cobalt.join.applyPage(cobalt.join.JoinedRow, allocator, joined, page) catch |err| return fail(stderr, @errorName(err));
+                defer cobalt.join.freeJoined(allocator, paged);
+                for (paged) |pair| {
+                    try stdout.writeAll("L ");
+                    try printRow(stdout, pair.left);
+                    try stdout.writeAll("R ");
+                    try printRow(stdout, pair.right);
+                }
+            },
+            .left => {
+                const joined = cobalt.join.leftOuterJoin(allocator, &left, jargs[1], null, &right, jargs[3], null) catch |err| return fail(stderr, @errorName(err));
+                const paged = cobalt.join.applyPage(cobalt.join.OuterJoinedRow, allocator, joined, page) catch |err| return fail(stderr, @errorName(err));
+                defer cobalt.join.freeOuterJoined(allocator, paged);
+                for (paged) |pair| {
+                    try stdout.writeAll("L ");
+                    try printRow(stdout, pair.left);
+                    if (pair.right) |r| {
+                        try stdout.writeAll("R ");
+                        try printRow(stdout, r);
+                    } else {
+                        try stdout.writeAll("R (nil)\n");
+                    }
+                }
+            },
+            .right => {
+                const joined = cobalt.join.rightOuterJoin(allocator, &left, jargs[1], null, &right, jargs[3], null) catch |err| return fail(stderr, @errorName(err));
+                const paged = cobalt.join.applyPage(cobalt.join.RightOuterJoinedRow, allocator, joined, page) catch |err| return fail(stderr, @errorName(err));
+                defer cobalt.join.freeRightOuterJoined(allocator, paged);
+                for (paged) |pair| {
+                    if (pair.left) |l| {
+                        try stdout.writeAll("L ");
+                        try printRow(stdout, l);
+                    } else {
+                        try stdout.writeAll("L (nil)\n");
+                    }
+                    try stdout.writeAll("R ");
+                    try printRow(stdout, pair.right);
+                }
+            },
+            .full => {
+                const joined = cobalt.join.fullOuterJoin(allocator, &left, jargs[1], null, &right, jargs[3], null) catch |err| return fail(stderr, @errorName(err));
+                const paged = cobalt.join.applyPage(cobalt.join.FullOuterJoinedRow, allocator, joined, page) catch |err| return fail(stderr, @errorName(err));
+                defer cobalt.join.freeFullOuterJoined(allocator, paged);
+                for (paged) |pair| {
+                    if (pair.left) |l| {
+                        try stdout.writeAll("L ");
+                        try printRow(stdout, l);
+                    } else {
+                        try stdout.writeAll("L (nil)\n");
+                    }
+                    if (pair.right) |r| {
+                        try stdout.writeAll("R ");
+                        try printRow(stdout, r);
+                    } else {
+                        try stdout.writeAll("R (nil)\n");
+                    }
+                }
+            },
+        }
+    } else if (std.mem.eql(u8, sub, "aggregate")) {
+        if (args.len < 3) return fail(stderr, "table aggregate needs <table> <groupField|*> <spec>[,<spec>...] [expr...] [having <expr>] [order <field[:desc]>[,field...]] [--limit N] [--offset N]");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+        const groupField = args[1];
+
+        const specs = parseAggSpecs(allocator, args[2]) catch return fail(stderr, "invalid aggregate spec (expected count | count:field | sum:field | avg:field | min:field | max:field | distinct:field, comma-separated)");
+        defer allocator.free(specs);
+
+        const flags = extractPageFlags(allocator, args[3..]) catch return fail(stderr, "invalid --limit/--offset value");
+        defer allocator.free(flags.rest);
+
+        const split = splitAggFilterArgs(flags.rest);
+
+        const exprText = try std.mem.join(allocator, " ", split.whereArgs);
+        defer allocator.free(exprText);
+        var parsed: ?cobalt.expr.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = cobalt.expr.parse(allocator, exprText) catch |err| return fail(stderr, @errorName(err));
+        }
+        const pred: ?cobalt.Predicate = if (parsed) |p| p.predicate else null;
+
+        var havingParsed: ?cobalt.expr.Parsed = null;
+        defer if (havingParsed) |*p| p.deinit();
+        var havingPred: ?cobalt.Predicate = null;
+        if (split.havingArgs) |havingArgs| {
+            const havingText = try std.mem.join(allocator, " ", havingArgs);
+            defer allocator.free(havingText);
+            if (havingText.len == 0) return fail(stderr, "having requires an expression");
+            havingParsed = cobalt.expr.parse(allocator, havingText) catch |err| return fail(stderr, @errorName(err));
+            havingPred = havingParsed.?.predicate;
+        }
+
+        var orderBy: []cobalt.query.OrderBy = &.{};
+        defer allocator.free(orderBy);
+        if (split.orderArgs) |orderArgs| {
+            if (orderArgs.len != 1) return fail(stderr, "order requires exactly one comma-separated field list");
+            orderBy = parseOrderByList(allocator, orderArgs[0]) catch return fail(stderr, "invalid order field list");
+        }
+
+        const rows = try table.select(pred);
+        defer cobalt.query.freeRows(allocator, rows);
+
+        if (std.mem.eql(u8, groupField, "*")) {
+            const values = cobalt.aggregate.runGlobal(allocator, rows, specs) catch |err| return fail(stderr, @errorName(err));
+            defer cobalt.aggregate.freeGlobalResult(allocator, values);
+            const matches = if (havingPred) |hp|
+                cobalt.aggregate.globalMatchesHaving(allocator, specs, values, hp) catch |err| return fail(stderr, @errorName(err))
+            else
+                true;
+            if (matches) {
+                for (specs, values, 0..) |spec, v, i| {
+                    if (i > 0) try stdout.writeAll("\t");
+                    try printAggLabel(stdout, spec);
+                    try stdout.writeAll("=");
+                    try printValue(stdout, v);
+                }
+                try stdout.writeAll("\n");
+            }
+        } else {
+            const unpaged = cobalt.aggregate.run(allocator, rows, groupField, specs) catch |err| return fail(stderr, @errorName(err));
+            const filtered = if (havingPred) |hp|
+                cobalt.aggregate.filterHaving(allocator, unpaged, groupField, specs, hp) catch |err| return fail(stderr, @errorName(err))
+            else
+                unpaged;
+            if (orderBy.len > 0) {
+                cobalt.aggregate.sortGroupsBy(allocator, filtered, groupField, specs, orderBy) catch |err| return fail(stderr, @errorName(err));
+            }
+            const groups = cobalt.aggregate.applyPageGroups(allocator, filtered, .{ .offset = flags.page.offset, .limit = flags.page.limit }) catch |err| return fail(stderr, @errorName(err));
+            defer {
+                for (groups) |*g| g.deinit(allocator);
+                allocator.free(groups);
+            }
+            for (groups) |g| {
+                try stdout.writeAll("group=");
+                try printValue(stdout, g.group);
+                for (specs, g.values) |spec, v| {
+                    try stdout.writeAll("\t");
+                    try printAggLabel(stdout, spec);
+                    try stdout.writeAll("=");
+                    try printValue(stdout, v);
+                }
+                try stdout.writeAll("\n");
+            }
+        }
+    } else if (std.mem.eql(u8, sub, "window")) {
+        if (args.len < 2) return fail(stderr, "table window needs <table> <kind[:field]>[,<kind[:field]>...] [expr...] [partition <field>[,field...]] [order <field[:desc]>[,field...]] [--limit N] [--offset N] [--range]");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+
+        const specs = parseWindowSpecs(allocator, args[1]) catch return fail(stderr, "invalid window spec (expected row_number | rank | dense_rank | sum:field | avg:field | count | count:field | count_distinct:field | min:field | max:field | first_value:field | last_value:field | nth_value:field:n[:default] | lag:field[:offset[:default]] | lead:field[:offset[:default]], comma-separated)");
+        defer allocator.free(specs);
+
+        const flags = extractPageFlags(allocator, args[2..]) catch return fail(stderr, "invalid --limit/--offset value");
+        defer allocator.free(flags.rest);
+
+        const rangeFlag = try extractRangeFlag(allocator, flags.rest);
+        defer allocator.free(rangeFlag.rest);
+        const frame: cobalt.window.FrameMode = if (rangeFlag.range) .range else .rows;
+
+        const split = splitWindowArgs(rangeFlag.rest);
+
+        const exprText = try std.mem.join(allocator, " ", split.whereArgs);
+        defer allocator.free(exprText);
+        var parsed: ?cobalt.expr.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = cobalt.expr.parse(allocator, exprText) catch |err| return fail(stderr, @errorName(err));
+        }
+        const pred: ?cobalt.Predicate = if (parsed) |p| p.predicate else null;
+
+        var partitionBy: [][]const u8 = &.{};
+        defer allocator.free(partitionBy);
+        if (split.partitionArgs) |partitionArgs| {
+            if (partitionArgs.len != 1) return fail(stderr, "partition requires exactly one comma-separated field list");
+            partitionBy = parsePartitionList(allocator, partitionArgs[0]) catch return fail(stderr, "invalid partition field list");
+        }
+
+        var orderBy: []cobalt.query.OrderBy = &.{};
+        defer allocator.free(orderBy);
+        if (split.orderArgs) |orderArgs| {
+            if (orderArgs.len != 1) return fail(stderr, "order requires exactly one comma-separated field list");
+            orderBy = parseOrderByList(allocator, orderArgs[0]) catch return fail(stderr, "invalid order field list");
+        }
+
+        const rows = try table.select(pred);
+        defer cobalt.query.freeRows(allocator, rows);
+
+        const results = cobalt.window.computeMany(allocator, rows, partitionBy, orderBy, specs, frame) catch |err| return fail(stderr, @errorName(err));
+        defer cobalt.window.freeManyResults(allocator, results);
+
+        // Display/page in the SAME partition-then-order walk `computeMany`
+        // used internally, not raw scan order - see `table window`'s help
+        // text and `window.orderedIndices`'s doc comment for why.
+        const displayOrder = cobalt.window.orderedIndices(allocator, rows, partitionBy, orderBy) catch |err| return fail(stderr, @errorName(err));
+        defer allocator.free(displayOrder);
+
+        const total = displayOrder.len;
+        const start = @min(flags.page.offset, total);
+        const end = if (flags.page.limit == 0) total else @min(start + flags.page.limit, total);
+        var i: usize = start;
+        while (i < end) : (i += 1) {
+            const idx = displayOrder[i];
+            for (rows[idx].fields.items, 0..) |f, j| {
+                if (j > 0) try stdout.writeAll("\t");
+                try stdout.print("{s}=", .{f.name});
+                try printValue(stdout, f.value);
+            }
+            if (rows[idx].fields.items.len > 0) try stdout.writeAll("\t");
+            for (specs, 0..) |spec, specIdx| {
+                if (specIdx > 0) try stdout.writeAll("\t");
+                try printWindowLabel(stdout, spec);
+                try stdout.writeAll("=");
+                try printValue(stdout, results[idx][specIdx]);
+            }
+            try stdout.writeAll("\n");
+        }
+    } else if (std.mem.eql(u8, sub, "export")) {
+        if (args.len < 3) return fail(stderr, "table export needs <table> csv|json <path>");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+        const n = if (std.mem.eql(u8, args[1], "csv"))
+            cobalt.dump.exportCsv(allocator, &table, args[2]) catch |err| return fail(stderr, @errorName(err))
+        else if (std.mem.eql(u8, args[1], "json"))
+            cobalt.dump.exportJson(allocator, &table, args[2]) catch |err| return fail(stderr, @errorName(err))
+        else
+            return fail(stderr, "table export format must be csv or json");
+        try stdout.print("{d}\n", .{n});
+    } else if (std.mem.eql(u8, sub, "import")) {
+        if (args.len < 3) return fail(stderr, "table import needs <table> csv|json <path>");
+        var table = try cobalt.Table.open(db, allocator, args[0]);
+        defer table.deinit();
+        const n = if (std.mem.eql(u8, args[1], "csv"))
+            cobalt.dump.importCsv(allocator, &table, args[2]) catch |err| return fail(stderr, @errorName(err))
+        else if (std.mem.eql(u8, args[1], "json"))
+            cobalt.dump.importJson(allocator, &table, args[2]) catch |err| return fail(stderr, @errorName(err))
+        else
+            return fail(stderr, "table import format must be csv or json");
+        try stdout.print("{d}\n", .{n});
+    } else {
+        return fail(stderr, "unknown table operation");
+    }
+}
+
+/// Runs a script of `put|del <table> <pk> [field=value ...]` lines as one
+/// atomic Transaction via TableTxn: every row/index mutation across every
+/// line becomes visible together on commit, or none of it does. This is the
+/// only place in the CLI multi-row atomicity is reachable at all - `table
+/// put` above writes one row directly to the Db per call, with no atomicity
+/// across rows.
+/// `repl [--script <file>]`: keeps `db` open across many commands instead
+/// of the usual one-process-per-command CLI shape, so `begin`/`commit`/
+/// `rollback` can bracket an interactive `cobalt.Repl` transaction - see
+/// `repl.zig` for the command grammar and why that is more than `txn
+/// <script-file>` with extra steps. With `--script <file>` reads from the
+/// file non-interactively (no prompt, same as `txn`); otherwise reads from
+/// stdin with a `cobalt>`/`cobalt(txn)>` prompt.
+fn runRepl(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, db: *cobalt.Db, rest: []const []const u8) !void {
+    var session = cobalt.Repl.init(allocator, db);
+    defer session.deinit();
+
+    if (rest.len >= 2 and std.mem.eql(u8, rest[0], "--script")) {
+        const contents = std.fs.cwd().readFileAlloc(allocator, rest[1], 16 * 1024 * 1024) catch |err| {
+            try stderr.print("failed to read script '{s}': {s}\n", .{ rest[1], @errorName(err) });
+            std.process.exit(1);
+        };
+        defer allocator.free(contents);
+        var stream = std.io.fixedBufferStream(contents);
+        try session.runFromReader(stream.reader(), stdout, false);
+        return;
+    }
+
+    const stdinReader = std.io.getStdIn().reader();
+    try session.runFromReader(stdinReader, stdout, true);
+}
+
+fn runTxn(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, db: *cobalt.Db, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "txn needs <script-file>");
+
+    const contents = std.fs.cwd().readFileAlloc(allocator, rest[0], 16 * 1024 * 1024) catch |err| {
+        try stderr.print("failed to read script '{s}': {s}\n", .{ rest[0], @errorName(err) });
+        std.process.exit(1);
+    };
+    defer allocator.free(contents);
+
+    var txn = cobalt.Transaction.begin(db);
+    defer txn.deinit();
+
+    var tables = std.StringHashMap(cobalt.TableTxn).init(allocator);
+    defer {
+        var it = tables.valueIterator();
+        while (it.next()) |t| t.deinit();
+        tables.deinit();
+    }
+
+    var applied: usize = 0;
+    var lineNo: usize = 0;
+    var lines = std.mem.splitScalar(u8, contents, '\n');
+    while (lines.next()) |rawLine| {
+        lineNo += 1;
+        const line = std.mem.trim(u8, rawLine, " \t\r");
+        if (line.len == 0 or line[0] == '#') continue;
+
+        var tok = std.mem.tokenizeScalar(u8, line, ' ');
+        const verb = tok.next() orelse continue;
+        const tableName = tok.next() orelse {
+            try stderr.print("line {d}: missing table name\n", .{lineNo});
+            std.process.exit(2);
+        };
+        const pkText = tok.next() orelse {
+            try stderr.print("line {d}: missing primary key\n", .{lineNo});
+            std.process.exit(2);
+        };
+        const pk = parseValue(pkText) catch {
+            try stderr.print("line {d}: invalid primary key '{s}'\n", .{ lineNo, pkText });
+            std.process.exit(2);
+        };
+
+        const gop = try tables.getOrPut(tableName);
+        if (!gop.found_existing) {
+            gop.key_ptr.* = tableName;
+            gop.value_ptr.* = cobalt.TableTxn.open(&txn, allocator, tableName) catch |err| {
+                try stderr.print("line {d}: cannot open table '{s}': {s}\n", .{ lineNo, tableName, @errorName(err) });
+                std.process.exit(2);
+            };
+        }
+        const table = gop.value_ptr;
+
+        if (std.mem.eql(u8, verb, "put")) {
+            var fields = std.ArrayList(Field).init(allocator);
+            defer fields.deinit();
+            while (tok.next()) |raw| {
+                const f = parseField(raw) catch {
+                    try stderr.print("line {d}: invalid field '{s}'\n", .{ lineNo, raw });
+                    std.process.exit(2);
+                };
+                try fields.append(f);
+            }
+            table.put(pk, fields.items) catch |err| {
+                try stderr.print("line {d}: put failed: {s}\n", .{ lineNo, @errorName(err) });
+                std.process.exit(1);
+            };
+        } else if (std.mem.eql(u8, verb, "del")) {
+            table.delete(pk) catch |err| {
+                try stderr.print("line {d}: del failed: {s}\n", .{ lineNo, @errorName(err) });
+                std.process.exit(1);
+            };
+        } else {
+            try stderr.print("line {d}: unknown verb '{s}' (expected put/del)\n", .{ lineNo, verb });
+            std.process.exit(2);
+        }
+        applied += 1;
+    }
+
+    if (applied == 0) return fail(stderr, "txn script had no operations");
+
+    txn.commit() catch |err| {
+        try stderr.print("transaction failed, nothing applied: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("OK: {d} operation(s) committed atomically\n", .{applied});
+}
+
+/// Dispatches `replicate <replica-dir> [--once] [--interval-ms <n>]`: opens
+/// (or creates) a second Db at <replica-dir> and keeps it mirroring `db` by
+/// physically tailing `db`'s wal.log (replicate.zig), recovering via a full
+/// snapshot resync whenever the tailer falls behind a primary flush.
+fn runReplicate(allocator: std.mem.Allocator, stdout: anytype, db: *cobalt.Db, replicaDir: []const u8, rest: []const []const u8) !void {
+    var once = false;
+    var intervalMs: u64 = 200;
+    var i: usize = 0;
+    while (i < rest.len) : (i += 1) {
+        if (std.mem.eql(u8, rest[i], "--once")) {
+            once = true;
+        } else if (std.mem.eql(u8, rest[i], "--interval-ms")) {
+            i += 1;
+            if (i >= rest.len) {
+                try stdout.writeAll("error: --interval-ms needs a value\n");
+                std.process.exit(2);
+            }
+            intervalMs = std.fmt.parseInt(u64, rest[i], 10) catch {
+                try stdout.writeAll("error: --interval-ms needs an integer\n");
+                std.process.exit(2);
+            };
+        } else {
+            try stdout.print("error: unknown replicate flag '{s}'\n", .{rest[i]});
+            std.process.exit(2);
+        }
+    }
+
+    var replica = try cobalt.Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    const resumeState = cobalt.replicate.loadOffset(allocator, replicaDir, db.dirPath) catch |err| switch (err) {
+        cobalt.replicate.StateError.PrimaryMismatch => {
+            try stdout.print("error: replica at '{s}' has persisted state for a different primary than '{s}' - refusing to resume against the wrong primary\n", .{ replicaDir, db.dirPath });
+            std.process.exit(1);
+        },
+        else => return err,
+    };
+
+    var rep = if (resumeState) |state|
+        try cobalt.Replicator.initFromOffset(allocator, db.dirPath, &replica, state.offset, state.generation)
+    else
+        try cobalt.Replicator.init(allocator, db.dirPath, &replica);
+    defer rep.deinit();
+
+    if (resumeState) |state| {
+        try stdout.print("resuming tail from persisted offset={d} generation={d}\n", .{ state.offset, state.generation });
+    } else {
+        const bootstrapped = try rep.fullResync(db, 500);
+        try stdout.print("bootstrap: {d} entries copied from snapshot\n", .{bootstrapped});
+        try cobalt.replicate.saveState(allocator, replicaDir, db.dirPath, rep.offset(), rep.generation());
+    }
+
+    while (true) {
+        const applied = rep.syncOnce() catch |err| switch (err) {
+            cobalt.ReplicateError.WalTruncatedAheadOfTailer, cobalt.ReplicateError.WalGenerationChanged => blk: {
+                const recovered = try rep.fullResync(db, 500);
+                try stdout.print("resync after truncation: {d} entries\n", .{recovered});
+                // fullResync always re-bases the tailer to offset 0 and the
+                // primary's current generation, which must be persisted
+                // immediately even if nothing new was applied afterwards -
+                // otherwise a later process would resume from the stale
+                // pre-truncation offset/generation instead of the fresh one.
+                try cobalt.replicate.saveState(allocator, replicaDir, db.dirPath, rep.offset(), rep.generation());
+                break :blk @as(usize, 0);
+            },
+            else => return err,
+        };
+        if (applied > 0) {
+            try stdout.print("applied {d} record(s), tail offset={d}\n", .{ applied, rep.offset() });
+            try cobalt.replicate.saveState(allocator, replicaDir, db.dirPath, rep.offset(), rep.generation());
+        }
+        if (once) break;
+        std.time.sleep(intervalMs * std.time.ns_per_ms);
+    }
+}
+
+/// Parses a `host:port` string as used by both `serve` (bind address) and
+/// `remote-select` (address to connect to). Exits with usage code 2 on a
+/// malformed address rather than propagating a parse error, matching every
+/// other CLI argument validation in this file.
+fn parseHostPort(stdout: anytype, spec: []const u8) !std.net.Address {
+    const colon = std.mem.lastIndexOfScalar(u8, spec, ':') orelse {
+        try stdout.print("error: address must be host:port, got '{s}'\n", .{spec});
+        std.process.exit(2);
+    };
+    const host = spec[0..colon];
+    const port = std.fmt.parseInt(u16, spec[colon + 1 ..], 10) catch {
+        try stdout.print("error: invalid port in '{s}'\n", .{spec});
+        std.process.exit(2);
+    };
+    return std.net.Address.parseIp(host, port);
+}
+
+const AuthFlags = struct { username: ?[]const u8 = null, password: ?[]const u8 = null, token: ?[]const u8 = null };
+
+/// Pulls `--user NAME` / `--pass PASS` / `--token TOKEN` out of a
+/// `remote-select`/`remote-user` argument list, same shape and same "strip
+/// recognized flags, keep the rest" idea as `extractPageFlags`. `--token`
+/// is the CLI counterpart of `client.authenticateWithToken` - a previously
+/// issued session token (see `serve --session-ttl`) used in place of a
+/// username/password pair. Caller owns and frees `rest`.
+fn extractAuthFlags(allocator: std.mem.Allocator, args: []const []const u8) !struct { auth: AuthFlags, rest: [][]const u8 } {
+    var authFlags = AuthFlags{};
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        const isUser = std.mem.eql(u8, args[i], "--user");
+        const isPass = std.mem.eql(u8, args[i], "--pass");
+        const isToken = std.mem.eql(u8, args[i], "--token");
+        if (isUser or isPass or isToken) {
+            i += 1;
+            if (i >= args.len) return error.InvalidAuthFlag;
+            if (isUser) authFlags.username = args[i] else if (isPass) authFlags.password = args[i] else authFlags.token = args[i];
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    return .{ .auth = authFlags, .rest = try rest.toOwnedSlice() };
+}
+
+/// Shared by `runRemoteSelect` and `runRemoteUser`: authenticates the
+/// just-connected `client` using whichever credential `authFlags` carried
+/// (a session token takes priority over a username/password pair - a
+/// caller passing both almost certainly means "use the token, the
+/// user/pass was left over from a script template"), or does nothing if
+/// neither was given (server has no --auth enabled, or the op needs none).
+/// A fresh password login against a server with sessions enabled gets a
+/// brand new token back (`client.sessionToken()`) - printed to stderr (kept
+/// out of stdout so scripts piping row/user output are not polluted) so the
+/// caller can pass it to a later invocation via `--token` instead of
+/// re-sending the password. Logging in with `--token` itself never mints a
+/// new one (see `server.zig`'s `handleAuthToken`), so nothing is printed
+/// in that branch.
+fn authenticateIfRequested(client: *cobalt.Client, stderr: anytype, authFlags: AuthFlags) !void {
+    if (authFlags.token) |token| {
+        client.authenticateWithToken(token) catch |err| {
+            try stderr.print("error: token authentication failed: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+    } else if (authFlags.username) |username| {
+        client.authenticate(username, authFlags.password orelse "") catch |err| {
+            try stderr.print("error: authentication failed: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        if (client.sessionToken()) |token| {
+            try stderr.print("session token (use with --token): {s}\n", .{token});
+        }
+    }
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table select`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_select` opcode, so a query engine that was
+/// previously CLI-local-only is now reachable over the wire with the exact
+/// same expression grammar as `table select`. `--user`/`--pass` authenticate
+/// first, needed only against a server started with `serve --auth`.
+fn runRemoteSelect(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-select needs <table> [expr...] [--limit N] [--offset N] [--order-by field[:desc][,field[:desc]...]]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const sel = extractSelectFlags(allocator, authFlags.rest) catch return fail(stderr, "invalid --limit/--offset/--order-by value");
+    defer allocator.free(sel.rest);
+    defer allocator.free(sel.flags.orderBy);
+
+    const exprText = try std.mem.join(allocator, " ", sel.rest);
+    defer allocator.free(exprText);
+
+    const rows = client.tableSelect(allocator, rest[0], exprText, sel.flags.page.offset, sel.flags.page.limit, sel.flags.orderBy) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer cobalt.protocol.freeRows(allocator, rows);
+    for (rows) |r| try printRow(stdout, r);
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table explain`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_explain` opcode, same shape as `runRemoteSelect`
+/// but reporting a `query.Plan` instead of rows. `--user`/`--pass`/
+/// `--token` authenticate first, needed only against a server started with
+/// `serve --auth`.
+fn runRemoteExplain(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-explain needs <table> [expr...]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const exprText = try std.mem.join(allocator, " ", authFlags.rest);
+    defer allocator.free(exprText);
+
+    var plan = client.tableExplain(allocator, rest[0], exprText) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer plan.deinit(allocator);
+    try printPlan(stdout, plan);
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table update`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_update` opcode, same shape as `runRemoteExplain`
+/// but taking a `--set` field list and printing the number of rows updated
+/// instead of a plan. `--user`/`--pass`/`--token` authenticate first,
+/// needed only against a server started with `serve --auth`.
+fn runRemoteUpdate(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-update needs <table> --set field=value[,field=value...] [expr...]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const setf = extractSetFlag(allocator, authFlags.rest) catch |err| return fail(stderr, if (err == error.MissingSetFlag)
+        "remote-update requires --set field=value[,field=value...]"
+    else
+        "invalid --set value");
+    defer allocator.free(setf.sets);
+    defer allocator.free(setf.rest);
+
+    const exprText = try std.mem.join(allocator, " ", setf.rest);
+    defer allocator.free(exprText);
+
+    const updated = client.tableUpdate(rest[0], setf.sets, exprText) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("{d}\n", .{updated});
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table delete`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_delete` opcode, same shape as `runRemoteExplain`
+/// (no `--set` flag, since a delete has no `SET` clause) but printing the
+/// number of rows deleted instead of a plan. `--user`/`--pass`/`--token`
+/// authenticate first, needed only against a server started with
+/// `serve --auth`.
+fn runRemoteDelete(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-delete needs <table> [expr...]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const exprText = try std.mem.join(allocator, " ", authFlags.rest);
+    defer allocator.free(exprText);
+
+    const deleted = client.tableDelete(rest[0], exprText) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("{d}\n", .{deleted});
+}
+
+fn parseDumpFormat(stderr: anytype, text: []const u8) !cobalt.protocol.DumpFormat {
+    if (std.mem.eql(u8, text, "csv")) return .csv;
+    if (std.mem.eql(u8, text, "json")) return .json;
+    try fail(stderr, "format must be csv or json");
+    unreachable;
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table export`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_export` opcode. Unlike every other remote-* op,
+/// the destination `<path>` names a file on THIS machine, not the server:
+/// the server renders the whole table into memory and sends the bytes
+/// back in one frame, and this function is the one that actually creates
+/// `<path>` and writes them - the local `table export` writes straight to
+/// disk itself since it already has a `*Db` handle in-process, but a
+/// remote client only ever gets bytes over the wire. `--user`/`--pass`/
+/// `--token` authenticate first, needed only against a server started
+/// with `serve --auth`.
+fn runRemoteExport(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-export needs <table> csv|json <path>");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const args = authFlags.rest;
+    if (args.len < 2) return fail(stderr, "remote-export needs <table> csv|json <path>");
+    const format = try parseDumpFormat(stderr, args[0]);
+
+    var result = client.tableExport(allocator, rest[0], format) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer result.deinit(allocator);
+
+    const file = std.fs.cwd().createFile(args[1], .{ .truncate = true }) catch |err| {
+        try stderr.print("failed to write '{s}': {s}\n", .{ args[1], @errorName(err) });
+        std.process.exit(1);
+    };
+    defer file.close();
+    try file.writeAll(result.content);
+
+    try stdout.print("{d}\n", .{result.rowCount});
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table import`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_import` opcode. Mirrors `runRemoteExport`: the
+/// source `<path>` is read from THIS machine (the same way `runTxn` reads
+/// a local script file), and its bytes are sent to the server in one
+/// frame. `--user`/`--pass`/`--token` authenticate first, needed only
+/// against a server started with `serve --auth`.
+fn runRemoteImport(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-import needs <table> csv|json <path>");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const args = authFlags.rest;
+    if (args.len < 2) return fail(stderr, "remote-import needs <table> csv|json <path>");
+    const format = try parseDumpFormat(stderr, args[0]);
+
+    const content = std.fs.cwd().readFileAlloc(allocator, args[1], 1 << 30) catch |err| {
+        try stderr.print("failed to read '{s}': {s}\n", .{ args[1], @errorName(err) });
+        std.process.exit(1);
+    };
+    defer allocator.free(content);
+
+    const imported = client.tableImport(rest[0], format, content) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("{d}\n", .{imported});
+}
+
+const JoinCliMode = enum { inner, left, right, full };
+
+/// Pulls `--left`/`--right`/`--full` (mutually exclusive, last one wins,
+/// same as local `table join`'s parsing loop) and `--left-expr E`/
+/// `--right-expr E` out of a `remote-join` argument list, same "strip
+/// recognized flags, keep the rest" shape as `extractPageFlags`/
+/// `extractAuthFlags`. An expr not given defaults to the empty string,
+/// meaning "select every row on that side" - the same convention
+/// `tableSelect`'s empty `exprText` already uses. Caller owns and frees
+/// `rest`.
+fn extractJoinFlags(allocator: std.mem.Allocator, args: []const []const u8) !struct {
+    mode: JoinCliMode,
+    leftExpr: []const u8,
+    rightExpr: []const u8,
+    rest: [][]const u8,
+} {
+    var mode: JoinCliMode = .inner;
+    var leftExpr: []const u8 = "";
+    var rightExpr: []const u8 = "";
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        if (std.mem.eql(u8, args[i], "--left")) {
+            mode = .left;
+        } else if (std.mem.eql(u8, args[i], "--right")) {
+            mode = .right;
+        } else if (std.mem.eql(u8, args[i], "--full")) {
+            mode = .full;
+        } else if (std.mem.eql(u8, args[i], "--left-expr")) {
+            i += 1;
+            if (i >= args.len) return error.InvalidJoinFlag;
+            leftExpr = args[i];
+        } else if (std.mem.eql(u8, args[i], "--right-expr")) {
+            i += 1;
+            if (i >= args.len) return error.InvalidJoinFlag;
+            rightExpr = args[i];
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    return .{ .mode = mode, .leftExpr = leftExpr, .rightExpr = rightExpr, .rest = try rest.toOwnedSlice() };
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table join`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_join` opcode, mirroring `runRemoteSelect`'s shape
+/// but for all four of `join.zig`'s equi-join variants instead of a plain
+/// select. `--user`/`--pass`/`--token` authenticate first, needed only
+/// against a server started with `serve --auth`; printing is identical to
+/// the local `table join` command (`L <row>` / `R <row>`, or `L (nil)` /
+/// `R (nil)` for the unmatched side of an outer join).
+fn runRemoteJoin(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const jf = extractJoinFlags(allocator, authFlags.rest) catch return fail(stderr, "invalid --left-expr/--right-expr value");
+    defer allocator.free(jf.rest);
+
+    const pf = extractPageFlags(allocator, jf.rest) catch return fail(stderr, "invalid --limit/--offset value");
+    defer allocator.free(pf.rest);
+
+    if (pf.rest.len < 4) return fail(stderr, "remote-join needs [--left|--right|--full] <leftTable> <leftField> <rightTable> <rightField> [--left-expr E] [--right-expr E] [--limit N] [--offset N]");
+
+    const mode: cobalt.protocol.JoinMode = switch (jf.mode) {
+        .inner => .inner,
+        .left => .left,
+        .right => .right,
+        .full => .full,
+    };
+
+    const pairs = client.tableJoin(allocator, mode, pf.rest[0], pf.rest[1], pf.rest[2], pf.rest[3], pf.page.offset, pf.page.limit, jf.leftExpr, jf.rightExpr) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer cobalt.protocol.freeJoinPairs(allocator, pairs);
+
+    for (pairs) |p| {
+        if (p.left) |l| {
+            try stdout.writeAll("L ");
+            try printRow(stdout, l);
+        } else {
+            try stdout.writeAll("L (nil)\n");
+        }
+        if (p.right) |r| {
+            try stdout.writeAll("R ");
+            try printRow(stdout, r);
+        } else {
+            try stdout.writeAll("R (nil)\n");
+        }
+    }
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table aggregate`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_aggregate` opcode, mirroring `runRemoteSelect`'s
+/// shape. Same `*` sentinel as local `table aggregate` for "no GROUP BY"
+/// (dispatches to `client.tableAggregateGlobal` instead of
+/// `tableAggregateGroups`), same comma-separated spec grammar
+/// (`parseAggSpecs`), and the same output format as the local command
+/// (`printAggLabel`/`printValue`). `--limit`/`--offset` window the result
+/// groups server-side (ignored for the `*` global path, same as local
+/// `table aggregate`), same convention as `remote-join`.
+/// `--user`/`--pass`/`--token` authenticate first, needed only against a
+/// server started with `serve --auth`. An optional literal `having <expr>`
+/// after the WHERE-style expr (split out by `splitAggFilterArgs`, the same
+/// helper the local `table aggregate` handler uses) filters the result
+/// groups server-side after aggregation, before `--limit`/`--offset` window
+/// them. An optional literal `order <field[:desc]>[,field...]` after that
+/// sorts the (HAVING-narrowed) result groups server-side before that same
+/// window, ignored for the `*` global path exactly like `--limit`/`--offset`
+/// already are - see `Client.tableAggregateGroups`/`tableAggregateGlobal`.
+fn runRemoteAggregate(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 3) return fail(stderr, "remote-aggregate needs <table> <groupField|*> <spec>[,<spec>...] [expr...] [having <expr>] [order <field[:desc]>[,field...]] [--limit N] [--offset N]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const table = rest[0];
+    const groupField = rest[1];
+    const specs = parseAggSpecs(allocator, rest[2]) catch return fail(stderr, "invalid aggregate spec (expected count | count:field | sum:field | avg:field | min:field | max:field | distinct:field, comma-separated)");
+    defer allocator.free(specs);
+
+    const authFlags = extractAuthFlags(allocator, rest[3..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const flags = extractPageFlags(allocator, authFlags.rest) catch return fail(stderr, "invalid --limit/--offset value");
+    defer allocator.free(flags.rest);
+
+    const split = splitAggFilterArgs(flags.rest);
+
+    const exprText = try std.mem.join(allocator, " ", split.whereArgs);
+    defer allocator.free(exprText);
+
+    const havingText = if (split.havingArgs) |ha| try std.mem.join(allocator, " ", ha) else try allocator.dupe(u8, "");
+    defer allocator.free(havingText);
+    if (split.havingArgs != null and havingText.len == 0) return fail(stderr, "having requires an expression");
+
+    var orderBy: []cobalt.query.OrderBy = &.{};
+    defer allocator.free(orderBy);
+    if (split.orderArgs) |orderArgs| {
+        if (orderArgs.len != 1) return fail(stderr, "order requires exactly one comma-separated field list");
+        orderBy = parseOrderByList(allocator, orderArgs[0]) catch return fail(stderr, "invalid order field list");
+    }
+
+    if (std.mem.eql(u8, groupField, "*")) {
+        const values = client.tableAggregateGlobal(allocator, table, specs, havingText, exprText) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        defer cobalt.protocol.freeAggValues(allocator, values);
+        // `values.len == 0` means the server's HAVING excluded the only
+        // global result (see `Client.tableAggregateGlobal`'s doc) - print
+        // nothing rather than indexing `specs` against a shorter `values`,
+        // which a naive `for (specs, values, ...)` would panic on.
+        if (values.len > 0) {
+            for (specs, values, 0..) |spec, v, i| {
+                if (i > 0) try stdout.writeAll("\t");
+                try printAggLabel(stdout, spec);
+                try stdout.writeAll("=");
+                try printValue(stdout, v);
+            }
+            try stdout.writeAll("\n");
+        }
+    } else {
+        const groups = client.tableAggregateGroups(allocator, table, groupField, specs, flags.page.offset, flags.page.limit, orderBy, havingText, exprText) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        defer cobalt.protocol.freeAggGroupRows(allocator, groups);
+        for (groups) |g| {
+            try stdout.writeAll("group=");
+            try printValue(stdout, g.group);
+            for (specs, g.values) |spec, v| {
+                try stdout.writeAll("\t");
+                try printAggLabel(stdout, spec);
+                try stdout.writeAll("=");
+                try printValue(stdout, v);
+            }
+            try stdout.writeAll("\n");
+        }
+    }
+}
+
+/// Connects to a remote `cobalt serve` instance and runs `table window`
+/// there instead of against a local Db - the client-side counterpart of
+/// `server.zig`'s `table_window` opcode, mirroring `runRemoteAggregate`'s
+/// shape. Same comma-separated spec-list grammar as local `table window`
+/// (`parseWindowSpecs`), same `partition <field>[,field...]`/`order
+/// <field[:desc]>[,field...]` clause split (`splitWindowArgs`), and the same
+/// per-row output format as the local command (row fields, then
+/// `<label>=<value>`). Unlike `runRemoteAggregate`, there is no `*`
+/// sentinel or global/grouped branch - a window annotation never collapses
+/// rows, so there is exactly one request/response shape
+/// (`Client.tableWindow`). `--limit`/`--offset` window which rows come back
+/// (server-side, in `window.orderedIndices`' partition-then-order display
+/// sequence, not raw scan order - see `Client.tableWindow`'s doc).
+/// `--user`/`--pass`/`--token` authenticate first, needed only against a
+/// server started with `serve --auth`.
+/// Splits `text` on commas into channel names for `remote-subscribe` - no
+/// identifier validation, unlike `parsePartitionList`, since a pub/sub
+/// channel is an arbitrary string (`pubsub.zig`'s `Hub` keys purely on
+/// byte equality), not a table field name.
+fn parseChannelList(allocator: std.mem.Allocator, text: []const u8) ![][]const u8 {
+    var list = std.ArrayList([]const u8).init(allocator);
+    errdefer list.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |ch| {
+        if (ch.len == 0) return error.EmptyChannelName;
+        try list.append(ch);
+    }
+    return list.toOwnedSlice();
+}
+
+/// Connects to a running `cobalt serve` and delivers a message to every
+/// connection currently subscribed to `<channel>` - the client-side
+/// counterpart of `server.zig`'s `publish` opcode. `<message...>` is every
+/// remaining non-flag argument joined with single spaces, the same
+/// "trailing free text" convention `runRemoteWindow`'s `exprText` uses, so a
+/// multi-word message does not need manual quoting tricks beyond the
+/// shell's own.
+fn runRemotePublish(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 2) return fail(stderr, "remote-publish needs <channel> <message...> [--user NAME --pass PASS] [--token TOKEN]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const channel = rest[0];
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    if (authFlags.rest.len == 0) return fail(stderr, "remote-publish needs a message");
+    const message = try std.mem.join(allocator, " ", authFlags.rest);
+    defer allocator.free(message);
+
+    const count = client.publish(channel, message) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("{d}\n", .{count});
+}
+
+/// Connects to a running `cobalt serve`, subscribes to every channel in the
+/// comma-separated `<channel>[,channel...]` list, and blocks printing
+/// `<channel>: <message>` for each message that arrives until the
+/// connection ends - the client-side counterpart of `server.zig`'s
+/// `subscribe` opcode and `Client.nextMessage`'s doc comment on why this
+/// connection never sends another request afterward. Prints "subscribed as
+/// <id>" first (the id `remote-unsubscribe`, run from a different terminal
+/// against a different connection, needs to ever name this subscription
+/// again) - closing this process (or the connection) still ends the whole
+/// subscription outright, same as before `remote-unsubscribe` existed.
+fn runRemoteSubscribe(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-subscribe needs <channel>[,channel...] [--user NAME --pass PASS] [--token TOKEN]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const channels = parseChannelList(allocator, rest[0]) catch return fail(stderr, "invalid channel list (empty channel name)");
+    defer allocator.free(channels);
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const subscriberId = client.subscribe(channels) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("subscribed as {d}\n", .{subscriberId});
+
+    while (try client.nextMessage(allocator)) |msg| {
+        defer msg.deinit(allocator);
+        try stdout.print("{s}: {s}\n", .{ msg.channel, msg.payload });
+    }
+}
+
+/// Connects to a running `cobalt serve` and drops the listed channels from
+/// an already-subscribed connection's set, identified by the
+/// `<subscriber-id>` its `remote-subscribe` printed - the client-side
+/// counterpart of `server.zig`'s `unsubscribe` opcode. Unlike
+/// `remote-subscribe`, this connection is an ordinary request/response
+/// round trip: it prints how many channels were actually removed and
+/// exits, never blocking. `<subscriber-id>` must parse as a `u64` - a
+/// malformed one is reported the same way a malformed `--limit` is
+/// elsewhere in this file, before ever reaching for the network.
+fn runRemoteUnsubscribe(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 2) return fail(stderr, "remote-unsubscribe needs <subscriber-id> <channel>[,channel...] [--user NAME --pass PASS] [--token TOKEN]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    const subscriberId = std.fmt.parseInt(u64, rest[0], 10) catch return fail(stderr, "invalid <subscriber-id> (expected a non-negative integer)");
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const channels = parseChannelList(allocator, rest[1]) catch return fail(stderr, "invalid channel list (empty channel name)");
+    defer allocator.free(channels);
+
+    const authFlags = extractAuthFlags(allocator, rest[2..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const removed = client.unsubscribe(subscriberId, channels) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("{d}\n", .{removed});
+}
+
+fn runRemoteWindow(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 2) return fail(stderr, "remote-window needs <table> <kind[:field]>[,<kind[:field]>...] [expr...] [partition <field>[,field...]] [order <field[:desc]>[,field...]] [--limit N] [--offset N] [--range]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const table = rest[0];
+    const specs = parseWindowSpecs(allocator, rest[1]) catch return fail(stderr, "invalid window spec (expected row_number | rank | dense_rank | sum:field | avg:field | count | count:field | count_distinct:field | min:field | max:field | first_value:field | last_value:field | nth_value:field:n[:default] | lag:field[:offset[:default]] | lead:field[:offset[:default]], comma-separated)");
+    defer allocator.free(specs);
+
+    const authFlags = extractAuthFlags(allocator, rest[2..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const flags = extractPageFlags(allocator, authFlags.rest) catch return fail(stderr, "invalid --limit/--offset value");
+    defer allocator.free(flags.rest);
+
+    const rangeFlag = try extractRangeFlag(allocator, flags.rest);
+    defer allocator.free(rangeFlag.rest);
+    const frame: cobalt.window.FrameMode = if (rangeFlag.range) .range else .rows;
+
+    const split = splitWindowArgs(rangeFlag.rest);
+
+    const exprText = try std.mem.join(allocator, " ", split.whereArgs);
+    defer allocator.free(exprText);
+
+    var partitionBy: [][]const u8 = &.{};
+    defer allocator.free(partitionBy);
+    if (split.partitionArgs) |partitionArgs| {
+        if (partitionArgs.len != 1) return fail(stderr, "partition requires exactly one comma-separated field list");
+        partitionBy = parsePartitionList(allocator, partitionArgs[0]) catch return fail(stderr, "invalid partition field list");
+    }
+
+    var orderBy: []cobalt.query.OrderBy = &.{};
+    defer allocator.free(orderBy);
+    if (split.orderArgs) |orderArgs| {
+        if (orderArgs.len != 1) return fail(stderr, "order requires exactly one comma-separated field list");
+        orderBy = parseOrderByList(allocator, orderArgs[0]) catch return fail(stderr, "invalid order field list");
+    }
+
+    const results = client.tableWindow(allocator, table, specs, partitionBy, orderBy, flags.page.offset, flags.page.limit, exprText, frame) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer cobalt.protocol.freeWindowRows(allocator, results);
+
+    for (results) |wr| {
+        for (wr.row.fields.items, 0..) |f, j| {
+            if (j > 0) try stdout.writeAll("\t");
+            try stdout.print("{s}=", .{f.name});
+            try printValue(stdout, f.value);
+        }
+        if (wr.row.fields.items.len > 0) try stdout.writeAll("\t");
+        for (specs, 0..) |spec, specIdx| {
+            if (specIdx > 0) try stdout.writeAll("\t");
+            try printWindowLabel(stdout, spec);
+            try stdout.writeAll("=");
+            try printValue(stdout, wr.values[specIdx]);
+        }
+        try stdout.writeAll("\n");
+    }
+}
+
+/// The network counterpart of `runTxn`: parses the exact same
+/// `put|del <table> <pk> [field=value ...]` script format as the local
+/// `txn <script-file>` command, but builds a list of
+/// `protocol.TxnOpEntry` and commits it in one round trip through
+/// `client.zig`'s `txnOp` (the `txn_op` opcode) instead of staging against
+/// a local `TableTxn` directly - so a script that used to require a
+/// process holding the `Db` can now run against a remote `cobalt serve`.
+fn runRemoteTxn(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-txn needs <script-file> [--user NAME --pass PASS] [--token TOKEN]");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    const contents = std.fs.cwd().readFileAlloc(allocator, rest[0], 16 * 1024 * 1024) catch |err| {
+        try stderr.print("failed to read script '{s}': {s}\n", .{ rest[0], @errorName(err) });
+        std.process.exit(1);
+    };
+    defer allocator.free(contents);
+
+    var entries = std.ArrayList(cobalt.protocol.TxnOpEntry).init(allocator);
+    defer {
+        for (entries.items) |e| allocator.free(e.fields);
+        entries.deinit();
+    }
+
+    var lineNo: usize = 0;
+    var lines = std.mem.splitScalar(u8, contents, '\n');
+    while (lines.next()) |rawLine| {
+        lineNo += 1;
+        const line = std.mem.trim(u8, rawLine, " \t\r");
+        if (line.len == 0 or line[0] == '#') continue;
+
+        var tok = std.mem.tokenizeScalar(u8, line, ' ');
+        const verb = tok.next() orelse continue;
+        const tableName = tok.next() orelse {
+            try stderr.print("line {d}: missing table name\n", .{lineNo});
+            std.process.exit(2);
+        };
+        const pkText = tok.next() orelse {
+            try stderr.print("line {d}: missing primary key\n", .{lineNo});
+            std.process.exit(2);
+        };
+        const pk = parseValue(pkText) catch {
+            try stderr.print("line {d}: invalid primary key '{s}'\n", .{ lineNo, pkText });
+            std.process.exit(2);
+        };
+
+        if (std.mem.eql(u8, verb, "put")) {
+            var fields = std.ArrayList(Field).init(allocator);
+            errdefer fields.deinit();
+            while (tok.next()) |raw| {
+                const f = parseField(raw) catch {
+                    try stderr.print("line {d}: invalid field '{s}'\n", .{ lineNo, raw });
+                    std.process.exit(2);
+                };
+                try fields.append(f);
+            }
+            try entries.append(.{ .verb = .put, .table = tableName, .pk = pk, .fields = try fields.toOwnedSlice() });
+        } else if (std.mem.eql(u8, verb, "del")) {
+            try entries.append(.{ .verb = .del, .table = tableName, .pk = pk, .fields = &.{} });
+        } else {
+            try stderr.print("line {d}: unknown verb '{s}' (expected put/del)\n", .{ lineNo, verb });
+            std.process.exit(2);
+        }
+    }
+
+    if (entries.items.len == 0) return fail(stderr, "txn script had no operations");
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const applied = client.txnOp(entries.items) catch |err| {
+        try stderr.print("transaction failed, nothing applied: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    try stdout.print("OK: {d} operation(s) committed atomically\n", .{applied});
+}
+
+/// The network counterpart of `runUser`: dispatches `remote-user <op> ...`
+/// onto `client.zig`'s `admin*` methods (which wire-encode the
+/// `user_admin` opcode) instead of a local `auth.Store`. Bootstrapping the
+/// very first admin account still has to happen locally via `user add`
+/// (see the module doc on `runUser`), but every subsequent user management
+/// operation can go over the wire once that first admin can authenticate.
+fn runRemoteUser(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-user needs a subcommand (add/passwd/role/del/list)");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const op = rest[0];
+    const args = authFlags.rest;
+
+    if (std.mem.eql(u8, op, "add")) {
+        if (args.len < 3) return fail(stderr, "remote-user add needs <username> <password> readonly|readwrite|admin");
+        const role = cobalt.AuthRole.parse(args[2]) catch return fail(stderr, "role must be readonly, readwrite, or admin");
+        client.adminCreateUser(args[0], args[1], role, cobalt.auth.recommendedRounds) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("user '{s}' created with role {s}\n", .{ args[0], role.name() });
+    } else if (std.mem.eql(u8, op, "passwd")) {
+        if (args.len < 2) return fail(stderr, "remote-user passwd needs <username> <newpassword>");
+        client.adminSetPassword(args[0], args[1], cobalt.auth.recommendedRounds) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("password updated for '{s}'\n", .{args[0]});
+    } else if (std.mem.eql(u8, op, "role")) {
+        if (args.len < 2) return fail(stderr, "remote-user role needs <username> readonly|readwrite|admin");
+        const role = cobalt.AuthRole.parse(args[1]) catch return fail(stderr, "role must be readonly, readwrite, or admin");
+        client.adminSetRole(args[0], role) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("role for '{s}' set to {s}\n", .{ args[0], role.name() });
+    } else if (std.mem.eql(u8, op, "del")) {
+        if (args.len < 1) return fail(stderr, "remote-user del needs <username>");
+        client.adminDeleteUser(args[0]) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("user '{s}' deleted\n", .{args[0]});
+    } else if (std.mem.eql(u8, op, "list")) {
+        const users = client.adminListUsers(allocator) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        defer cobalt.auth.freeUserList(allocator, users);
+        for (users) |u| try stdout.print("{s}\t{s}\n", .{ u.username, u.role.name() });
+    } else {
+        return fail(stderr, "unknown remote-user operation");
+    }
+}
+
+/// The network counterpart of `runTtl`-shaped local commands (`expire`,
+/// `persist`, `ttl`, `expire-sweep`): dispatches `remote-ttl <op> ...` onto
+/// `client.zig`'s `ttl*` methods (which wire-encode the `ttl_op` opcode)
+/// instead of calling `ttl.zig` directly against a local Db, the same
+/// "reuse client.zig, keep the arg parsing local" shape as `runRemoteUser`.
+fn runRemoteTtl(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-ttl needs a subcommand (expire/persist/ttl/sweep)");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const op = rest[0];
+    const args = authFlags.rest;
+
+    if (std.mem.eql(u8, op, "expire")) {
+        if (args.len < 2) return fail(stderr, "remote-ttl expire needs <key> <seconds>");
+        const seconds = std.fmt.parseInt(u64, args[1], 10) catch return fail(stderr, "expire needs a whole number of seconds");
+        client.ttlExpire(args[0], seconds) catch |err| {
+            if (err == error.ServerKeyNotFound) return fail(stderr, "no such key");
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+    } else if (std.mem.eql(u8, op, "persist")) {
+        if (args.len < 1) return fail(stderr, "remote-ttl persist needs <key>");
+        client.ttlPersist(args[0]) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+    } else if (std.mem.eql(u8, op, "ttl")) {
+        if (args.len < 1) return fail(stderr, "remote-ttl ttl needs <key>");
+        const result = client.ttlQuery(args[0]) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        switch (result) {
+            .noKey => try stdout.writeAll("-2\n"),
+            .noExpiry => try stdout.writeAll("-1\n"),
+            .seconds => |s| try stdout.print("{d}\n", .{s}),
+        }
+    } else if (std.mem.eql(u8, op, "sweep")) {
+        const reaped = client.ttlSweep() catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("reaped: {d}\n", .{reaped});
+    } else {
+        return fail(stderr, "unknown remote-ttl operation");
+    }
+}
+
+/// The network counterpart of `runCollTtl`-shaped local commands (`coll
+/// <kind> expire|ttl|persist`, `coll expire-sweep`): dispatches
+/// `remote-coll-ttl sweep` or `remote-coll-ttl <kind> <op> ...` onto
+/// `client.zig`'s `collTtl*` methods (which wire-encode the `coll_ttl_op`
+/// opcode), same "reuse client.zig, keep the arg parsing local" shape as
+/// `runRemoteTtl`. `sweep` has no `<kind>` (it reaps every kind at once,
+/// same as local `coll expire-sweep`), so it is checked before trying to
+/// parse `rest[0]` as a kind.
+fn runRemoteCollTtl(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 1) return fail(stderr, "remote-coll-ttl needs sweep or <kind> expire|ttl|persist <name>");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    if (std.mem.eql(u8, rest[0], "sweep")) {
+        const authFlags = extractAuthFlags(allocator, rest[1..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+        defer allocator.free(authFlags.rest);
+        try authenticateIfRequested(&client, stderr, authFlags.auth);
+        const reaped = client.collTtlSweep() catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        try stdout.print("reaped: {d}\n", .{reaped});
+        return;
+    }
+
+    const kind = cobalt.CollectionKind.parse(rest[0]) orelse
+        return fail(stderr, "unknown collection kind (expected counter/hash/set/list/zset)");
+    if (rest.len < 2) return fail(stderr, "remote-coll-ttl <kind> needs expire|ttl|persist <name>");
+
+    const authFlags = extractAuthFlags(allocator, rest[2..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const op = rest[1];
+    const args = authFlags.rest;
+
+    if (std.mem.eql(u8, op, "expire")) {
+        if (args.len < 2) return fail(stderr, "remote-coll-ttl <kind> expire needs <name> <seconds>");
+        const seconds = std.fmt.parseInt(u64, args[1], 10) catch return fail(stderr, "expire needs a whole number of seconds");
+        client.collTtlExpire(kind, args[0], seconds) catch |err| {
+            if (err == error.ServerCollectionNotFound) return fail(stderr, "no such collection");
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+    } else if (std.mem.eql(u8, op, "persist")) {
+        if (args.len < 1) return fail(stderr, "remote-coll-ttl <kind> persist needs <name>");
+        client.collTtlPersist(kind, args[0]) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+    } else if (std.mem.eql(u8, op, "ttl")) {
+        if (args.len < 1) return fail(stderr, "remote-coll-ttl <kind> ttl needs <name>");
+        const result = client.collTtlQuery(kind, args[0]) catch |err| {
+            try stderr.print("error: {s}\n", .{@errorName(err)});
+            std.process.exit(1);
+        };
+        switch (result) {
+            .noKey => try stdout.writeAll("-2\n"),
+            .noExpiry => try stdout.writeAll("-1\n"),
+            .seconds => |s| try stdout.print("{d}\n", .{s}),
+        }
+    } else {
+        return fail(stderr, "unknown remote-coll-ttl operation");
+    }
+}
+
+/// Prints an `OwnedCollReply` the same way `runColl`'s local dispatch
+/// prints each op's own return value - one shape per reply variant, not
+/// one shape per op, since `client.collOp`'s reply already carries enough
+/// structure to tell them apart (an int reply from `set_ismember` prints
+/// exactly like one from `hash_del`, both booleans-as-0/1, matching
+/// `runColl`'s own `boolFlag` convention).
+fn printCollReply(stdout: anytype, reply: cobalt.protocol.OwnedCollReply) !void {
+    switch (reply) {
+        .nil => try stdout.writeAll("(nil)\n"),
+        .ok => try stdout.writeAll("OK\n"),
+        .int => |v| try stdout.print("{d}\n", .{v}),
+        .real => |v| try stdout.print("{d}\n", .{v}),
+        .bytes => |v| try stdout.print("{s}\n", .{v}),
+        .stringList => |items| for (items) |it| try stdout.print("{s}\n", .{it}),
+        .pairList => |items| for (items) |p| try stdout.print("{s}\t{s}\n", .{ p.field, p.value }),
+        .scorePairList => |items| for (items) |p| try stdout.print("{s}\t{d}\n", .{ p.member, p.score }),
+    }
+}
+
+/// The network counterpart of `runColl`'s local `coll <kind> <op> ...`
+/// (backed by `collections.zig`): parses the exact same
+/// `<kind> <op> [args...]` shape `runColl` does, translates it to a
+/// `protocol.CollAction` plus a name and string-arg list, and sends it
+/// through `client.collOp` instead of calling `collections.zig` directly -
+/// the network counterpart `remote-coll-ttl` already is for `coll <kind>
+/// expire|ttl|persist`. There is no `remote-coll expire-sweep` counterpart:
+/// unlike TTL sweeping (a background maintenance action against the whole
+/// store), the read/write collection operations here always target one
+/// named collection, so there is nothing store-wide to bundle behind this
+/// opcode the way `coll_ttl_op`'s `sweep` action does.
+fn runRemoteColl(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    if (rest.len < 2) return fail(stderr, "remote-coll needs <kind> <op> ...");
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest[2..]) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const kind = rest[0];
+    const op = rest[1];
+    const args = authFlags.rest;
+
+    const Call = struct { action: cobalt.protocol.CollAction, name: []const u8, callArgs: []const []const u8 };
+
+    const call: Call = blk: {
+        if (std.mem.eql(u8, kind, "counter")) {
+            if (std.mem.eql(u8, op, "get")) {
+                if (args.len < 1) return fail(stderr, "counter get needs <name>");
+                break :blk .{ .action = .counter_get, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "set")) {
+                if (args.len < 2) return fail(stderr, "counter set needs <name> <value>");
+                break :blk .{ .action = .counter_set, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "incrby")) {
+                if (args.len < 2) return fail(stderr, "counter incrby needs <name> <delta>");
+                break :blk .{ .action = .counter_incrby, .name = args[0], .callArgs = args[1..2] };
+            }
+            return fail(stderr, "unknown counter operation");
+        } else if (std.mem.eql(u8, kind, "hash")) {
+            if (std.mem.eql(u8, op, "set")) {
+                if (args.len < 3) return fail(stderr, "hash set needs <name> <field> <value>");
+                break :blk .{ .action = .hash_set, .name = args[0], .callArgs = args[1..3] };
+            } else if (std.mem.eql(u8, op, "get")) {
+                if (args.len < 2) return fail(stderr, "hash get needs <name> <field>");
+                break :blk .{ .action = .hash_get, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "del")) {
+                if (args.len < 2) return fail(stderr, "hash del needs <name> <field>");
+                break :blk .{ .action = .hash_del, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "len")) {
+                if (args.len < 1) return fail(stderr, "hash len needs <name>");
+                break :blk .{ .action = .hash_len, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "getall")) {
+                if (args.len < 1) return fail(stderr, "hash getall needs <name>");
+                break :blk .{ .action = .hash_getall, .name = args[0], .callArgs = &.{} };
+            }
+            return fail(stderr, "unknown hash operation");
+        } else if (std.mem.eql(u8, kind, "set")) {
+            if (std.mem.eql(u8, op, "add")) {
+                if (args.len < 2) return fail(stderr, "set add needs <name> <member>");
+                break :blk .{ .action = .set_add, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "rem")) {
+                if (args.len < 2) return fail(stderr, "set rem needs <name> <member>");
+                break :blk .{ .action = .set_rem, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "ismember")) {
+                if (args.len < 2) return fail(stderr, "set ismember needs <name> <member>");
+                break :blk .{ .action = .set_ismember, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "card")) {
+                if (args.len < 1) return fail(stderr, "set card needs <name>");
+                break :blk .{ .action = .set_card, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "members")) {
+                if (args.len < 1) return fail(stderr, "set members needs <name>");
+                break :blk .{ .action = .set_members, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "inter")) {
+                if (args.len < 1) return fail(stderr, "set inter needs at least one <name>");
+                break :blk .{ .action = .set_inter, .name = args[0], .callArgs = args[1..] };
+            } else if (std.mem.eql(u8, op, "union")) {
+                if (args.len < 1) return fail(stderr, "set union needs at least one <name>");
+                break :blk .{ .action = .set_union, .name = args[0], .callArgs = args[1..] };
+            } else if (std.mem.eql(u8, op, "diff")) {
+                if (args.len < 2) return fail(stderr, "set diff needs <name> <other...>");
+                break :blk .{ .action = .set_diff, .name = args[0], .callArgs = args[1..] };
+            }
+            return fail(stderr, "unknown set operation");
+        } else if (std.mem.eql(u8, kind, "list")) {
+            if (std.mem.eql(u8, op, "lpush")) {
+                if (args.len < 2) return fail(stderr, "list lpush needs <name> <value>");
+                break :blk .{ .action = .list_lpush, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "rpush")) {
+                if (args.len < 2) return fail(stderr, "list rpush needs <name> <value>");
+                break :blk .{ .action = .list_rpush, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "lpop")) {
+                if (args.len < 1) return fail(stderr, "list lpop needs <name>");
+                break :blk .{ .action = .list_lpop, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "rpop")) {
+                if (args.len < 1) return fail(stderr, "list rpop needs <name>");
+                break :blk .{ .action = .list_rpop, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "len")) {
+                if (args.len < 1) return fail(stderr, "list len needs <name>");
+                break :blk .{ .action = .list_len, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "range")) {
+                if (args.len < 3) return fail(stderr, "list range needs <name> <start> <stop>");
+                break :blk .{ .action = .list_range, .name = args[0], .callArgs = args[1..3] };
+            }
+            return fail(stderr, "unknown list operation");
+        } else if (std.mem.eql(u8, kind, "zset")) {
+            if (std.mem.eql(u8, op, "add")) {
+                if (args.len < 3) return fail(stderr, "zset add needs <name> <member> <score>");
+                break :blk .{ .action = .zset_add, .name = args[0], .callArgs = args[1..3] };
+            } else if (std.mem.eql(u8, op, "score")) {
+                if (args.len < 2) return fail(stderr, "zset score needs <name> <member>");
+                break :blk .{ .action = .zset_score, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "incrby")) {
+                if (args.len < 3) return fail(stderr, "zset incrby needs <name> <member> <delta>");
+                break :blk .{ .action = .zset_incrby, .name = args[0], .callArgs = args[1..3] };
+            } else if (std.mem.eql(u8, op, "rem")) {
+                if (args.len < 2) return fail(stderr, "zset rem needs <name> <member>");
+                break :blk .{ .action = .zset_rem, .name = args[0], .callArgs = args[1..2] };
+            } else if (std.mem.eql(u8, op, "card")) {
+                if (args.len < 1) return fail(stderr, "zset card needs <name>");
+                break :blk .{ .action = .zset_card, .name = args[0], .callArgs = &.{} };
+            } else if (std.mem.eql(u8, op, "rangebyrank")) {
+                if (args.len < 3) return fail(stderr, "zset rangebyrank needs <name> <start> <stop>");
+                break :blk .{ .action = .zset_rangebyrank, .name = args[0], .callArgs = args[1..3] };
+            } else if (std.mem.eql(u8, op, "rangebyscore")) {
+                if (args.len < 3) return fail(stderr, "zset rangebyscore needs <name> <min> <max>");
+                break :blk .{ .action = .zset_rangebyscore, .name = args[0], .callArgs = args[1..3] };
+            } else if (std.mem.eql(u8, op, "rank")) {
+                if (args.len < 2) return fail(stderr, "zset rank needs <name> <member>");
+                break :blk .{ .action = .zset_rank, .name = args[0], .callArgs = args[1..2] };
+            }
+            return fail(stderr, "unknown zset operation");
+        }
+        return fail(stderr, "unknown collection kind (expected counter/hash/set/list/zset)");
+    };
+
+    var reply = client.collOp(allocator, call.action, call.name, call.callArgs) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer reply.deinit(allocator);
+    try printCollReply(stdout, reply);
+}
+
+/// The network counterpart of local `stats --prom`: connects to a running
+/// `cobalt serve`, authenticates if credentials were given (same
+/// `--user`/`--pass`/`--token` convention as `remote-select`/`remote-user`),
+/// and prints `client.metricsText` verbatim. Unlike `stats --prom` locally
+/// (which only ever has a `Db` to render, never a `*Server`), this also
+/// carries the server's own request/rate-limit/auth/session counters from
+/// `Server.registerMetrics` - the only way to observe those from outside
+/// the serving process at all.
+fn runRemoteStats(allocator: std.mem.Allocator, stdout: anytype, stderr: anytype, addressSpec: []const u8, rest: []const []const u8) !void {
+    const address = try parseHostPort(stdout, addressSpec);
+
+    var client = cobalt.Client.connect(allocator, address) catch |err| {
+        try stderr.print("error: could not connect to {s}: {s}\n", .{ addressSpec, @errorName(err) });
+        std.process.exit(1);
+    };
+    defer client.close();
+
+    const authFlags = extractAuthFlags(allocator, rest) catch return fail(stderr, "invalid --user/--pass/--token value");
+    defer allocator.free(authFlags.rest);
+
+    try authenticateIfRequested(&client, stderr, authFlags.auth);
+
+    const text = client.metricsText(allocator) catch |err| {
+        try stderr.print("error: {s}\n", .{@errorName(err)});
+        std.process.exit(1);
+    };
+    defer allocator.free(text);
+    try stdout.writeAll(text);
+}
+
+fn runServe(allocator: std.mem.Allocator, stdout: anytype, db: *cobalt.Db, bind: []const u8, rest: []const []const u8) !void {
+    const address = try parseHostPort(stdout, bind);
+
+    var server = try cobalt.Server.init(allocator, db, address);
+
+    var sessionTtlSeconds: ?f64 = null;
+    var sessionSweepSeconds: ?f64 = null;
+    var ttlSweepSeconds: ?f64 = null;
+    var collTtlSweepSeconds: ?f64 = null;
+    var i: usize = 0;
+    while (i < rest.len) : (i += 1) {
+        if (std.mem.eql(u8, rest[i], "--rate-limit")) {
+            if (i + 2 >= rest.len) {
+                try stdout.writeAll("error: --rate-limit needs <capacity> <per-second>\n");
+                std.process.exit(2);
+            }
+            const capacity = std.fmt.parseFloat(f64, rest[i + 1]) catch {
+                try stdout.print("error: invalid rate-limit capacity '{s}'\n", .{rest[i + 1]});
+                std.process.exit(2);
+            };
+            const refill = std.fmt.parseFloat(f64, rest[i + 2]) catch {
+                try stdout.print("error: invalid rate-limit per-second '{s}'\n", .{rest[i + 2]});
+                std.process.exit(2);
+            };
+            server.enableRateLimit(capacity, refill);
+            try stdout.print("rate limit enabled: {d} capacity, {d}/sec refill\n", .{ capacity, refill });
+            i += 2;
+        } else if (std.mem.eql(u8, rest[i], "--per-conn-rate-limit")) {
+            if (i + 2 >= rest.len) {
+                try stdout.writeAll("error: --per-conn-rate-limit needs <capacity> <per-second>\n");
+                std.process.exit(2);
+            }
+            const capacity = std.fmt.parseFloat(f64, rest[i + 1]) catch {
+                try stdout.print("error: invalid per-conn-rate-limit capacity '{s}'\n", .{rest[i + 1]});
+                std.process.exit(2);
+            };
+            const refill = std.fmt.parseFloat(f64, rest[i + 2]) catch {
+                try stdout.print("error: invalid per-conn-rate-limit per-second '{s}'\n", .{rest[i + 2]});
+                std.process.exit(2);
+            };
+            server.enablePerConnectionRateLimit(capacity, refill);
+            try stdout.print("per-connection rate limit enabled: {d} capacity, {d}/sec refill\n", .{ capacity, refill });
+            i += 2;
+        } else if (std.mem.eql(u8, rest[i], "--auth")) {
+            const store = cobalt.AuthStore.init(db);
+            if (!(try store.hasAnyAdmin(allocator))) {
+                try stdout.writeAll("error: --auth requires at least one admin user; create one first with `user add <name> <password> admin`\n");
+                std.process.exit(2);
+            }
+            server.enableAuth(store);
+            try stdout.writeAll("auth enabled: every op but ping now requires a prior AUTH\n");
+        } else if (std.mem.eql(u8, rest[i], "--session-ttl")) {
+            if (i + 1 >= rest.len) {
+                try stdout.writeAll("error: --session-ttl needs <seconds>\n");
+                std.process.exit(2);
+            }
+            sessionTtlSeconds = std.fmt.parseFloat(f64, rest[i + 1]) catch {
+                try stdout.print("error: invalid session-ttl '{s}'\n", .{rest[i + 1]});
+                std.process.exit(2);
+            };
+            i += 1;
+        } else if (std.mem.eql(u8, rest[i], "--session-sweep-interval")) {
+            if (i + 1 >= rest.len) {
+                try stdout.writeAll("error: --session-sweep-interval needs <seconds>\n");
+                std.process.exit(2);
+            }
+            sessionSweepSeconds = std.fmt.parseFloat(f64, rest[i + 1]) catch {
+                try stdout.print("error: invalid session-sweep-interval '{s}'\n", .{rest[i + 1]});
+                std.process.exit(2);
+            };
+            i += 1;
+        } else if (std.mem.eql(u8, rest[i], "--ttl-sweep-interval")) {
+            if (i + 1 >= rest.len) {
+                try stdout.writeAll("error: --ttl-sweep-interval needs <seconds>\n");
+                std.process.exit(2);
+            }
+            ttlSweepSeconds = std.fmt.parseFloat(f64, rest[i + 1]) catch {
+                try stdout.print("error: invalid ttl-sweep-interval '{s}'\n", .{rest[i + 1]});
+                std.process.exit(2);
+            };
+            i += 1;
+        } else if (std.mem.eql(u8, rest[i], "--coll-ttl-sweep-interval")) {
+            if (i + 1 >= rest.len) {
+                try stdout.writeAll("error: --coll-ttl-sweep-interval needs <seconds>\n");
+                std.process.exit(2);
+            }
+            collTtlSweepSeconds = std.fmt.parseFloat(f64, rest[i + 1]) catch {
+                try stdout.print("error: invalid coll-ttl-sweep-interval '{s}'\n", .{rest[i + 1]});
+                std.process.exit(2);
+            };
+            i += 1;
+        } else {
+            try stdout.print("error: unknown serve flag '{s}'\n", .{rest[i]});
+            std.process.exit(2);
+        }
+    }
+
+    if (sessionSweepSeconds != null and sessionTtlSeconds == null) {
+        try stdout.writeAll("error: --session-sweep-interval requires --session-ttl\n");
+        std.process.exit(2);
+    }
+
+    var sessionStore: cobalt.SessionStore = undefined;
+    if (sessionTtlSeconds) |seconds| {
+        if (seconds <= 0) {
+            try stdout.writeAll("error: --session-ttl must be a positive number of seconds\n");
+            std.process.exit(2);
+        }
+        if (server.authStore == null) {
+            try stdout.writeAll("error: --session-ttl requires --auth\n");
+            std.process.exit(2);
+        }
+        sessionStore = cobalt.SessionStore.init(allocator);
+        const ttlNanos: i128 = @intFromFloat(seconds * @as(f64, @floatFromInt(std.time.ns_per_s)));
+        server.enableSessions(&sessionStore, ttlNanos);
+        try stdout.print("sessions enabled: AUTH issues a token valid for {d}s\n", .{seconds});
+
+        if (sessionSweepSeconds) |sweepSeconds| {
+            if (sweepSeconds <= 0) {
+                try stdout.writeAll("error: --session-sweep-interval must be a positive number of seconds\n");
+                std.process.exit(2);
+            }
+            const sweepNanos: u64 = @intFromFloat(sweepSeconds * @as(f64, @floatFromInt(std.time.ns_per_s)));
+            server.enableSessionSweep(sweepNanos);
+            try stdout.print("session sweeper enabled: expired sessions dropped every {d}s\n", .{sweepSeconds});
+        }
+    }
+    defer if (sessionTtlSeconds != null) sessionStore.deinit();
+
+    if (ttlSweepSeconds) |seconds| {
+        if (seconds <= 0) {
+            try stdout.writeAll("error: --ttl-sweep-interval must be a positive number of seconds\n");
+            std.process.exit(2);
+        }
+        const nanos: u64 = @intFromFloat(seconds * @as(f64, @floatFromInt(std.time.ns_per_s)));
+        server.enableTtlSweep(nanos);
+        try stdout.print("ttl sweeper enabled: due keys reaped every {d}s\n", .{seconds});
+    }
+
+    if (collTtlSweepSeconds) |seconds| {
+        if (seconds <= 0) {
+            try stdout.writeAll("error: --coll-ttl-sweep-interval must be a positive number of seconds\n");
+            std.process.exit(2);
+        }
+        const nanos: u64 = @intFromFloat(seconds * @as(f64, @floatFromInt(std.time.ns_per_s)));
+        server.enableCollTtlSweep(nanos);
+        try stdout.print("collection ttl sweeper enabled: due collections reaped every {d}s\n", .{seconds});
+    }
+
+    try stdout.print("cobalt server listening on {}\n", .{server.boundAddress()});
+    try server.start();
+    server.wait();
+}
+
 fn runVerify(allocator: std.mem.Allocator, stdout: anytype, dir: []const u8, count: usize) !void {
     std.fs.cwd().deleteTree(dir) catch {};
 
diff --git a/src/metrics.zig b/src/metrics.zig
new file mode 100644
index 0000000..1be570c
--- /dev/null
+++ b/src/metrics.zig
@@ -0,0 +1,600 @@
+const std = @import("std");
+const stats_mod = @import("stats.zig");
+
+// Metrics primitives (counter/gauge/histogram), two independent rate-limiter
+// algorithms (token bucket, sliding window counter), and a text-exposition
+// registry. Fully additive module: does not touch Db/txn/storage internals,
+// only depends on stats.zig's public Stats type for the export helper.
+
+pub const MetricCounter = struct {
+    value: std.atomic.Value(u64) = std.atomic.Value(u64).init(0),
+
+    pub fn incr(self: *MetricCounter) void {
+        self.incrBy(1);
+    }
+
+    pub fn incrBy(self: *MetricCounter, delta: u64) void {
+        _ = self.value.fetchAdd(delta, .monotonic);
+    }
+
+    pub fn get(self: *const MetricCounter) u64 {
+        return self.value.load(.monotonic);
+    }
+
+    pub fn reset(self: *MetricCounter) void {
+        self.value.store(0, .monotonic);
+    }
+};
+
+pub const Gauge = struct {
+    bits: std.atomic.Value(u64) = std.atomic.Value(u64).init(0),
+
+    pub fn set(self: *Gauge, v: f64) void {
+        self.bits.store(@bitCast(v), .monotonic);
+    }
+
+    pub fn get(self: *const Gauge) f64 {
+        const raw = self.bits.load(.monotonic);
+        return @bitCast(raw);
+    }
+
+    pub fn add(self: *Gauge, delta: f64) void {
+        while (true) {
+            const cur = self.bits.load(.monotonic);
+            const curF: f64 = @bitCast(cur);
+            const newBits: u64 = @bitCast(curF + delta);
+            if (self.bits.cmpxchgWeak(cur, newBits, .monotonic, .monotonic) == null) return;
+        }
+    }
+};
+
+pub const HistogramError = error{EmptyBounds};
+
+/// Fixed-bucket histogram with Prometheus-style cumulative-bucket quantile
+/// estimation. `bounds` must be strictly increasing and is borrowed (caller
+/// keeps it alive for the histogram's lifetime); values greater than the
+/// last bound land in an implicit +Inf bucket.
+pub const Histogram = struct {
+    bounds: []const f64,
+    counts: []u64,
+    sum: f64 = 0,
+    total: u64 = 0,
+    mutex: std.Thread.Mutex = .{},
+    allocator: std.mem.Allocator,
+
+    pub fn init(allocator: std.mem.Allocator, bounds: []const f64) !Histogram {
+        if (bounds.len == 0) return HistogramError.EmptyBounds;
+        var i: usize = 1;
+        while (i < bounds.len) : (i += 1) {
+            std.debug.assert(bounds[i] > bounds[i - 1]);
+        }
+        const counts = try allocator.alloc(u64, bounds.len + 1);
+        @memset(counts, 0);
+        return .{ .bounds = bounds, .counts = counts, .allocator = allocator };
+    }
+
+    pub fn deinit(self: *Histogram) void {
+        self.allocator.free(self.counts);
+        self.* = undefined;
+    }
+
+    pub fn observe(self: *Histogram, value: f64) void {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        var idx: usize = self.bounds.len;
+        for (self.bounds, 0..) |bound, i| {
+            if (value <= bound) {
+                idx = i;
+                break;
+            }
+        }
+        self.counts[idx] += 1;
+        self.sum += value;
+        self.total += 1;
+    }
+
+    pub fn count(self: *const Histogram) u64 {
+        return self.total;
+    }
+
+    pub fn mean(self: *const Histogram) f64 {
+        if (self.total == 0) return 0;
+        return self.sum / @as(f64, @floatFromInt(self.total));
+    }
+
+    /// Linear-interpolation quantile estimate over cumulative bucket counts,
+    /// same algorithm Prometheus uses for `histogram_quantile`. q in [0, 1].
+    pub fn quantile(self: *Histogram, q: f64) f64 {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        if (self.total == 0 or self.bounds.len == 0) return 0;
+        const clamped = std.math.clamp(q, 0, 1);
+        const target = clamped * @as(f64, @floatFromInt(self.total));
+
+        var cumulative: u64 = 0;
+        var i: usize = 0;
+        while (i < self.counts.len) : (i += 1) {
+            const prevCumulative = cumulative;
+            cumulative += self.counts[i];
+            if (@as(f64, @floatFromInt(cumulative)) >= target) {
+                if (i == 0) return self.bounds[0];
+                if (i == self.bounds.len) return self.bounds[self.bounds.len - 1];
+                const lower = self.bounds[i - 1];
+                const upper = self.bounds[i];
+                const countInBucket = cumulative - prevCumulative;
+                if (countInBucket == 0) return upper;
+                const fraction = (target - @as(f64, @floatFromInt(prevCumulative))) / @as(f64, @floatFromInt(countInBucket));
+                return lower + fraction * (upper - lower);
+            }
+        }
+        return self.bounds[self.bounds.len - 1];
+    }
+
+    pub fn bucketCount(self: *Histogram, idx: usize) u64 {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        return self.counts[idx];
+    }
+};
+
+pub fn linearBuckets(allocator: std.mem.Allocator, start: f64, width: f64, n: usize) ![]f64 {
+    std.debug.assert(n > 0);
+    std.debug.assert(width > 0);
+    const out = try allocator.alloc(f64, n);
+    var i: usize = 0;
+    while (i < n) : (i += 1) out[i] = start + width * @as(f64, @floatFromInt(i));
+    return out;
+}
+
+pub fn exponentialBuckets(allocator: std.mem.Allocator, start: f64, factor: f64, n: usize) ![]f64 {
+    std.debug.assert(n > 0);
+    std.debug.assert(start > 0);
+    std.debug.assert(factor > 1);
+    const out = try allocator.alloc(f64, n);
+    var cur = start;
+    var i: usize = 0;
+    while (i < n) : (i += 1) {
+        out[i] = cur;
+        cur *= factor;
+    }
+    return out;
+}
+
+/// Classic token-bucket rate limiter. Time is passed in explicitly as
+/// nanoseconds so the algorithm is deterministic and testable; `tryAcquireNow`
+/// wraps it with the wall clock for real use.
+pub const TokenBucket = struct {
+    capacity: f64,
+    refillPerSecond: f64,
+    tokens: f64,
+    lastRefillNanos: u64,
+    mutex: std.Thread.Mutex = .{},
+
+    pub fn init(capacity: f64, refillPerSecond: f64, nowNanos: u64) TokenBucket {
+        std.debug.assert(capacity > 0);
+        std.debug.assert(refillPerSecond > 0);
+        return .{
+            .capacity = capacity,
+            .refillPerSecond = refillPerSecond,
+            .tokens = capacity,
+            .lastRefillNanos = nowNanos,
+        };
+    }
+
+    fn refillLocked(self: *TokenBucket, nowNanos: u64) void {
+        if (nowNanos <= self.lastRefillNanos) return;
+        const elapsedNanos = nowNanos - self.lastRefillNanos;
+        const elapsedSeconds = @as(f64, @floatFromInt(elapsedNanos)) / std.time.ns_per_s;
+        self.tokens = @min(self.capacity, self.tokens + elapsedSeconds * self.refillPerSecond);
+        self.lastRefillNanos = nowNanos;
+    }
+
+    /// Attempts to consume `n` tokens at time `nowNanos`. All-or-nothing:
+    /// never partially consumes on failure.
+    pub fn tryAcquireAt(self: *TokenBucket, n: f64, nowNanos: u64) bool {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        self.refillLocked(nowNanos);
+        if (self.tokens >= n) {
+            self.tokens -= n;
+            return true;
+        }
+        return false;
+    }
+
+    pub fn tryAcquireNow(self: *TokenBucket, n: f64) bool {
+        return self.tryAcquireAt(n, @intCast(std.time.nanoTimestamp()));
+    }
+
+    pub fn availableAt(self: *TokenBucket, nowNanos: u64) f64 {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        self.refillLocked(nowNanos);
+        return self.tokens;
+    }
+};
+
+/// Sliding-window-counter rate limiter (the "Cloudflare" approximation):
+/// tracks a count for the current fixed window and the previous one, and
+/// weights the previous window's count by how much of it still overlaps the
+/// trailing `windowNanos` interval. O(1) memory unlike a sliding log, more
+/// accurate at window boundaries than a plain fixed window.
+pub const SlidingWindowLimiter = struct {
+    limit: u64,
+    windowNanos: u64,
+    currentWindowStart: u64,
+    currentCount: u64 = 0,
+    previousCount: u64 = 0,
+    mutex: std.Thread.Mutex = .{},
+
+    pub fn init(limit: u64, windowNanos: u64, nowNanos: u64) SlidingWindowLimiter {
+        std.debug.assert(limit > 0);
+        std.debug.assert(windowNanos > 0);
+        return .{
+            .limit = limit,
+            .windowNanos = windowNanos,
+            .currentWindowStart = alignedWindowStart(nowNanos, windowNanos),
+        };
+    }
+
+    fn alignedWindowStart(nowNanos: u64, windowNanos: u64) u64 {
+        return (nowNanos / windowNanos) * windowNanos;
+    }
+
+    fn rotateLocked(self: *SlidingWindowLimiter, nowNanos: u64) void {
+        const windowStart = alignedWindowStart(nowNanos, self.windowNanos);
+        if (windowStart == self.currentWindowStart) return;
+        const windowsElapsed = (windowStart - self.currentWindowStart) / self.windowNanos;
+        if (windowsElapsed == 1) {
+            self.previousCount = self.currentCount;
+        } else {
+            self.previousCount = 0;
+        }
+        self.currentCount = 0;
+        self.currentWindowStart = windowStart;
+    }
+
+    pub fn allowAt(self: *SlidingWindowLimiter, nowNanos: u64) bool {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        self.rotateLocked(nowNanos);
+        const elapsedInWindow = nowNanos - self.currentWindowStart;
+        const overlap = 1.0 - @as(f64, @floatFromInt(elapsedInWindow)) / @as(f64, @floatFromInt(self.windowNanos));
+        const clampedOverlap = std.math.clamp(overlap, 0, 1);
+        const weighted = @as(f64, @floatFromInt(self.previousCount)) * clampedOverlap + @as(f64, @floatFromInt(self.currentCount));
+        if (weighted >= @as(f64, @floatFromInt(self.limit))) return false;
+        self.currentCount += 1;
+        return true;
+    }
+
+    pub fn allowNow(self: *SlidingWindowLimiter) bool {
+        return self.allowAt(@intCast(std.time.nanoTimestamp()));
+    }
+};
+
+const MetricKind = enum { counter, gauge, histogram };
+
+const MetricRef = union(MetricKind) {
+    counter: *const MetricCounter,
+    gauge: *const Gauge,
+    histogram: *Histogram,
+};
+
+/// Named-metric registry with a Prometheus-style text exporter. Stores only
+/// borrowed pointers (owned name copies) - callers keep the metrics alive.
+pub const Registry = struct {
+    allocator: std.mem.Allocator,
+    entries: std.StringHashMapUnmanaged(MetricRef) = .{},
+
+    pub fn init(allocator: std.mem.Allocator) Registry {
+        return .{ .allocator = allocator };
+    }
+
+    pub fn deinit(self: *Registry) void {
+        var it = self.entries.keyIterator();
+        while (it.next()) |key| self.allocator.free(key.*);
+        self.entries.deinit(self.allocator);
+        self.* = undefined;
+    }
+
+    fn put(self: *Registry, name: []const u8, ref: MetricRef) !void {
+        if (self.entries.getPtr(name)) |existing| {
+            existing.* = ref;
+            return;
+        }
+        const owned = try self.allocator.dupe(u8, name);
+        errdefer self.allocator.free(owned);
+        try self.entries.put(self.allocator, owned, ref);
+    }
+
+    pub fn registerCounter(self: *Registry, name: []const u8, c: *const MetricCounter) !void {
+        try self.put(name, .{ .counter = c });
+    }
+
+    pub fn registerGauge(self: *Registry, name: []const u8, g: *const Gauge) !void {
+        try self.put(name, .{ .gauge = g });
+    }
+
+    pub fn registerHistogram(self: *Registry, name: []const u8, h: *Histogram) !void {
+        try self.put(name, .{ .histogram = h });
+    }
+
+    pub fn count(self: *const Registry) usize {
+        return self.entries.count();
+    }
+
+    /// Writes every registered metric in Prometheus exposition format.
+    /// Output is sorted by name so it is deterministic (and diffable).
+    pub fn exportText(self: *Registry, allocator: std.mem.Allocator, writer: anytype) !void {
+        var names = try allocator.alloc([]const u8, self.entries.count());
+        defer allocator.free(names);
+        var it = self.entries.keyIterator();
+        var i: usize = 0;
+        while (it.next()) |key| : (i += 1) names[i] = key.*;
+        std.mem.sort([]const u8, names, {}, lessThanStr);
+
+        for (names) |name| {
+            const ref = self.entries.get(name).?;
+            switch (ref) {
+                .counter => |c| try writer.print("{s} {d}\n", .{ name, c.get() }),
+                .gauge => |g| try writer.print("{s} {d}\n", .{ name, g.get() }),
+                .histogram => |h| {
+                    var cumulative: u64 = 0;
+                    for (h.bounds, 0..) |bound, idx| {
+                        cumulative += h.counts[idx];
+                        try writer.print("{s}_bucket{{le=\"{d}\"}} {d}\n", .{ name, bound, cumulative });
+                    }
+                    cumulative += h.counts[h.bounds.len];
+                    try writer.print("{s}_bucket{{le=\"+Inf\"}} {d}\n", .{ name, cumulative });
+                    try writer.print("{s}_sum {d}\n", .{ name, h.sum });
+                    try writer.print("{s}_count {d}\n", .{ name, h.total });
+                },
+            }
+        }
+    }
+};
+
+fn lessThanStr(_: void, a: []const u8, b: []const u8) bool {
+    return std.mem.order(u8, a, b) == .lt;
+}
+
+/// Renders a Db Stats snapshot in the same Prometheus text format used by
+/// Registry.exportText, so `stats` output and ad-hoc registry metrics can be
+/// scraped through one shared shape.
+pub fn formatDbStats(writer: anytype, prefix: []const u8, s: stats_mod.Stats) !void {
+    try writer.print("{s}_memtable_entries {d}\n", .{ prefix, s.memtableEntries });
+    try writer.print("{s}_memtable_bytes {d}\n", .{ prefix, s.memtableBytes });
+    try writer.print("{s}_sstable_count {d}\n", .{ prefix, s.sstableCount });
+    try writer.print("{s}_live_entries {d}\n", .{ prefix, s.liveEntries });
+    try writer.print("{s}_physical_bytes {d}\n", .{ prefix, s.physicalBytes });
+    try writer.print("{s}_cache_hits {d}\n", .{ prefix, s.cacheHits });
+    try writer.print("{s}_cache_misses {d}\n", .{ prefix, s.cacheMisses });
+    try writer.print("{s}_cache_hit_rate {d:.6}\n", .{ prefix, s.cacheHitRate() });
+    try writer.print("{s}_next_seq {d}\n", .{ prefix, s.nextSeq });
+    const deepest = s.deepestLevel();
+    var i: usize = 0;
+    while (i <= deepest) : (i += 1) {
+        const level = s.levels[i];
+        try writer.print("{s}_level_tables{{level=\"{d}\"}} {d}\n", .{ prefix, i, level.tables });
+        try writer.print("{s}_level_entries{{level=\"{d}\"}} {d}\n", .{ prefix, i, level.entries });
+    }
+}
+
+test "counter incr and incrBy accumulate" {
+    var c = MetricCounter{};
+    c.incr();
+    c.incrBy(41);
+    try std.testing.expectEqual(@as(u64, 42), c.get());
+    c.reset();
+    try std.testing.expectEqual(@as(u64, 0), c.get());
+}
+
+test "gauge set/add round trip through bit reinterpretation" {
+    var g = Gauge{};
+    g.set(3.5);
+    try std.testing.expectApproxEqAbs(@as(f64, 3.5), g.get(), 1e-12);
+    g.add(-1.25);
+    try std.testing.expectApproxEqAbs(@as(f64, 2.25), g.get(), 1e-12);
+}
+
+test "histogram observe buckets and mean" {
+    const bounds = [_]f64{ 10, 50, 100 };
+    var h = try Histogram.init(std.testing.allocator, &bounds);
+    defer h.deinit();
+
+    h.observe(5);
+    h.observe(20);
+    h.observe(20);
+    h.observe(75);
+    h.observe(1000);
+
+    try std.testing.expectEqual(@as(u64, 1), h.bucketCount(0));
+    try std.testing.expectEqual(@as(u64, 2), h.bucketCount(1));
+    try std.testing.expectEqual(@as(u64, 1), h.bucketCount(2));
+    try std.testing.expectEqual(@as(u64, 1), h.bucketCount(3));
+    try std.testing.expectEqual(@as(u64, 5), h.count());
+    try std.testing.expectApproxEqAbs(@as(f64, (5 + 20 + 20 + 75 + 1000) / 5.0), h.mean(), 1e-9);
+}
+
+test "histogram quantile interpolates within a bucket" {
+    const bounds = [_]f64{ 100, 200 };
+    var h = try Histogram.init(std.testing.allocator, &bounds);
+    defer h.deinit();
+
+    // 4 values land in the (0,100] bucket, evenly spread by construction;
+    // linear interpolation only sees prev/cur cumulative counts, so the
+    // median of an all-in-one-bucket histogram is the bucket's own bound.
+    var i: usize = 0;
+    while (i < 4) : (i += 1) h.observe(50);
+    try std.testing.expectApproxEqAbs(@as(f64, 100), h.quantile(0.5), 1e-9);
+
+    // Now spread evenly across both finite buckets: p50 should land exactly
+    // on the boundary between them.
+    h.observe(150);
+    h.observe(150);
+    h.observe(150);
+    h.observe(150);
+    // counts: bucket0=4 (<=100), bucket1=4 (<=200) => cumulative [4,8], total 8
+    const q50 = h.quantile(0.5);
+    try std.testing.expectApproxEqAbs(@as(f64, 100), q50, 1e-9);
+}
+
+test "histogram quantile falls back to last bound for the +Inf bucket" {
+    const bounds = [_]f64{ 10, 20 };
+    var h = try Histogram.init(std.testing.allocator, &bounds);
+    defer h.deinit();
+    h.observe(5);
+    h.observe(9999);
+    try std.testing.expectApproxEqAbs(@as(f64, 20), h.quantile(1.0), 1e-9);
+}
+
+test "linearBuckets and exponentialBuckets produce expected boundaries" {
+    const lin = try linearBuckets(std.testing.allocator, 0, 10, 5);
+    defer std.testing.allocator.free(lin);
+    try std.testing.expectEqualSlices(f64, &[_]f64{ 0, 10, 20, 30, 40 }, lin);
+
+    const exp = try exponentialBuckets(std.testing.allocator, 1, 2, 5);
+    defer std.testing.allocator.free(exp);
+    try std.testing.expectEqualSlices(f64, &[_]f64{ 1, 2, 4, 8, 16 }, exp);
+}
+
+test "token bucket refills over time and denies when empty" {
+    var b = TokenBucket.init(10, 5, 0); // 10 capacity, 5 tokens/sec
+    try std.testing.expect(b.tryAcquireAt(10, 0));
+    try std.testing.expect(!b.tryAcquireAt(1, 0));
+
+    // half a second later: +2.5 tokens
+    try std.testing.expect(!b.tryAcquireAt(3, std.time.ns_per_s / 2));
+    try std.testing.expectApproxEqAbs(@as(f64, 2.5), b.availableAt(std.time.ns_per_s / 2), 1e-9);
+
+    // two full seconds later than that: refill caps at capacity
+    const later = std.time.ns_per_s / 2 + 2 * std.time.ns_per_s;
+    try std.testing.expect(b.tryAcquireAt(10, later));
+    try std.testing.expect(!b.tryAcquireAt(1, later));
+}
+
+test "token bucket never partially consumes on a failed acquire" {
+    var b = TokenBucket.init(5, 1, 0);
+    try std.testing.expect(!b.tryAcquireAt(6, 0));
+    try std.testing.expectApproxEqAbs(@as(f64, 5), b.availableAt(0), 1e-9);
+}
+
+test "sliding window limiter smooths across a window boundary" {
+    const windowNs: u64 = std.time.ns_per_s;
+    var lim = SlidingWindowLimiter.init(10, windowNs, 0);
+
+    var i: usize = 0;
+    while (i < 10) : (i += 1) try std.testing.expect(lim.allowAt(0));
+    try std.testing.expect(!lim.allowAt(0)); // exhausted current window
+
+    // Halfway into the next window: previous window's 10 requests are
+    // weighted at 50% overlap (5), so only 5 more should be allowed before
+    // the weighted total reaches the limit of 10.
+    const halfwayNextWindow = windowNs + windowNs / 2;
+    var allowed: usize = 0;
+    i = 0;
+    while (i < 20) : (i += 1) {
+        if (lim.allowAt(halfwayNextWindow)) allowed += 1;
+    }
+    try std.testing.expectEqual(@as(usize, 5), allowed);
+}
+
+test "sliding window limiter resets fully after a gap of more than one window" {
+    const windowNs: u64 = std.time.ns_per_s;
+    var lim = SlidingWindowLimiter.init(3, windowNs, 0);
+    try std.testing.expect(lim.allowAt(0));
+    try std.testing.expect(lim.allowAt(0));
+    try std.testing.expect(lim.allowAt(0));
+    try std.testing.expect(!lim.allowAt(0));
+
+    // Jump 10 windows ahead: previous window count must not leak in.
+    const farFuture = 10 * windowNs;
+    try std.testing.expect(lim.allowAt(farFuture));
+    try std.testing.expect(lim.allowAt(farFuture));
+    try std.testing.expect(lim.allowAt(farFuture));
+    try std.testing.expect(!lim.allowAt(farFuture));
+}
+
+test "registry exports counters gauges and histograms as sorted prometheus text" {
+    var c = MetricCounter{};
+    c.incrBy(7);
+    var g = Gauge{};
+    g.set(2.5);
+    const bounds = [_]f64{ 5, 10 };
+    var h = try Histogram.init(std.testing.allocator, &bounds);
+    defer h.deinit();
+    h.observe(3);
+    h.observe(8);
+
+    var reg = Registry.init(std.testing.allocator);
+    defer reg.deinit();
+    try reg.registerCounter("requests_total", &c);
+    try reg.registerGauge("temperature", &g);
+    try reg.registerHistogram("latency", &h);
+    try std.testing.expectEqual(@as(usize, 3), reg.count());
+
+    var buf = std.ArrayList(u8).init(std.testing.allocator);
+    defer buf.deinit();
+    try reg.exportText(std.testing.allocator, buf.writer());
+
+    const text = buf.items;
+    // sorted alphabetically: latency < requests_total < temperature
+    try std.testing.expect(std.mem.indexOf(u8, text, "latency_bucket{le=\"5\"} 1\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "latency_bucket{le=\"10\"} 2\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "latency_bucket{le=\"+Inf\"} 2\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "latency_sum 11") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "latency_count 2\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "requests_total 7\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "temperature 2.5\n") != null);
+
+    const latencyPos = std.mem.indexOf(u8, text, "latency_bucket").?;
+    const requestsPos = std.mem.indexOf(u8, text, "requests_total").?;
+    const temperaturePos = std.mem.indexOf(u8, text, "temperature").?;
+    try std.testing.expect(latencyPos < requestsPos);
+    try std.testing.expect(requestsPos < temperaturePos);
+}
+
+test "registry re-registering the same name overwrites rather than duplicating" {
+    var c1 = MetricCounter{};
+    c1.incrBy(1);
+    var c2 = MetricCounter{};
+    c2.incrBy(99);
+
+    var reg = Registry.init(std.testing.allocator);
+    defer reg.deinit();
+    try reg.registerCounter("x", &c1);
+    try reg.registerCounter("x", &c2);
+    try std.testing.expectEqual(@as(usize, 1), reg.count());
+
+    var buf = std.ArrayList(u8).init(std.testing.allocator);
+    defer buf.deinit();
+    try reg.exportText(std.testing.allocator, buf.writer());
+    try std.testing.expectEqualStrings("x 99\n", buf.items);
+}
+
+test "formatDbStats renders levels up to the deepest populated one" {
+    var s = stats_mod.Stats{};
+    s.memtableEntries = 3;
+    s.memtableBytes = 128;
+    s.sstableCount = 2;
+    s.cacheHits = 9;
+    s.cacheMisses = 1;
+    s.levels[0].tables = 1;
+    s.levels[0].entries = 10;
+    s.levels[2].tables = 4;
+    s.levels[2].entries = 40;
+
+    var buf = std.ArrayList(u8).init(std.testing.allocator);
+    defer buf.deinit();
+    try formatDbStats(buf.writer(), "cobalt", s);
+
+    const text = buf.items;
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_memtable_entries 3\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_cache_hit_rate 0.900000\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_level_tables{level=\"0\"} 1\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_level_tables{level=\"2\"} 4\n") != null);
+    // level 1 is empty but must still appear since deepestLevel is 2
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_level_tables{level=\"1\"} 0\n") != null);
+    // level 3+ must not appear at all
+    try std.testing.expect(std.mem.indexOf(u8, text, "level=\"3\"") == null);
+}
diff --git a/src/protocol.zig b/src/protocol.zig
new file mode 100644
index 0000000..a565fad
--- /dev/null
+++ b/src/protocol.zig
@@ -0,0 +1,3998 @@
+const std = @import("std");
+const encode = @import("encode.zig");
+const dbmod = @import("db.zig");
+const rowmod = @import("row.zig");
+const authmod = @import("auth.zig");
+const ttlmod = @import("ttl.zig");
+const collmod = @import("collections.zig");
+const aggregatemod = @import("aggregate.zig");
+const windowmod = @import("window.zig");
+const querymod = @import("query.zig");
+
+const Allocator = std.mem.Allocator;
+
+/// Guard against a corrupt or hostile length prefix causing an unbounded
+/// allocation before a single byte of the frame body has been validated.
+pub const maxFrameBytes: u32 = 64 * 1024 * 1024;
+
+pub const Op = enum(u8) {
+    ping = 0,
+    get = 1,
+    set = 2,
+    del = 3,
+    scan = 4,
+    prefix = 5,
+    stats = 6,
+    flush = 7,
+    compact = 8,
+    batch = 9,
+    table_select = 10,
+    auth = 11,
+    user_admin = 12,
+    auth_token = 13,
+    metrics = 14,
+    ttl_op = 15,
+    coll_ttl_op = 16,
+    coll_op = 17,
+    txn_op = 18,
+    table_join = 19,
+    table_aggregate = 20,
+    table_explain = 21,
+    table_update = 22,
+    table_delete = 23,
+    table_export = 24,
+    table_import = 25,
+    table_window = 26,
+    subscribe = 27,
+    publish = 28,
+    unsubscribe = 29,
+
+    pub fn fromByte(b: u8) !Op {
+        return std.meta.intToEnum(Op, b) catch error.UnknownOp;
+    }
+};
+
+pub const Status = enum(u8) {
+    ok = 0,
+    not_found = 1,
+    bad_request = 2,
+    io_error = 3,
+    conflict = 4,
+    internal = 5,
+    rate_limited = 6,
+    unauthorized = 7,
+    forbidden = 8,
+
+    pub fn fromByte(b: u8) !Status {
+        return std.meta.intToEnum(Status, b) catch error.UnknownStatus;
+    }
+};
+
+pub const ProtoError = error{
+    UnknownOp,
+    UnknownStatus,
+    FrameTooLarge,
+    Malformed,
+};
+
+/// A frame is the unit exchanged over the wire in both directions: a
+/// single tag byte (an `Op` on the request side, a `Status` on the
+/// response side) followed by a little-endian u32 payload length and the
+/// payload itself.
+pub const Frame = struct {
+    tag: u8,
+    payload: []u8,
+    allocator: Allocator,
+
+    pub fn deinit(self: *Frame) void {
+        self.allocator.free(self.payload);
+        self.* = undefined;
+    }
+};
+
+pub fn writeFrame(writer: anytype, tag: u8, payload: []const u8) !void {
+    if (payload.len > maxFrameBytes) return error.FrameTooLarge;
+    var header: [5]u8 = undefined;
+    header[0] = tag;
+    std.mem.writeInt(u32, header[1..5], @intCast(payload.len), encode.endian);
+    try writer.writeAll(&header);
+    if (payload.len > 0) try writer.writeAll(payload);
+}
+
+pub fn readFrame(allocator: Allocator, reader: anytype) !Frame {
+    var header: [5]u8 = undefined;
+    try reader.readNoEof(&header);
+    const tag = header[0];
+    const len = std.mem.readInt(u32, header[1..5], encode.endian);
+    if (len > maxFrameBytes) return error.FrameTooLarge;
+    const payload = try allocator.alloc(u8, len);
+    errdefer allocator.free(payload);
+    if (len > 0) try reader.readNoEof(payload);
+    return .{ .tag = tag, .payload = payload, .allocator = allocator };
+}
+
+/// Bounds-checked cursor over a decoded payload. Every read returns
+/// `error.Malformed` instead of panicking when the peer sent a short or
+/// truncated buffer, since payload bytes come from an untrusted socket.
+pub const Cursor = struct {
+    data: []const u8,
+    pos: usize = 0,
+
+    pub fn takeByte(self: *Cursor) !u8 {
+        if (self.pos + 1 > self.data.len) return error.Malformed;
+        const v = self.data[self.pos];
+        self.pos += 1;
+        return v;
+    }
+
+    pub fn takeU32(self: *Cursor) !u32 {
+        if (self.pos + 4 > self.data.len) return error.Malformed;
+        const v = encode.readU32(self.data, self.pos);
+        self.pos += 4;
+        return v;
+    }
+
+    pub fn takeU64(self: *Cursor) !u64 {
+        if (self.pos + 8 > self.data.len) return error.Malformed;
+        const v = encode.readU64(self.data, self.pos);
+        self.pos += 8;
+        return v;
+    }
+
+    pub fn takeBytes(self: *Cursor, n: usize) ![]const u8 {
+        if (self.pos + n > self.data.len) return error.Malformed;
+        const v = self.data[self.pos .. self.pos + n];
+        self.pos += n;
+        return v;
+    }
+
+    pub fn takeLenPrefixed(self: *Cursor) ![]const u8 {
+        const n = try self.takeU32();
+        return self.takeBytes(n);
+    }
+
+    pub fn atEnd(self: *Cursor) bool {
+        return self.pos == self.data.len;
+    }
+};
+
+fn putLenPrefixed(writer: encode.ByteWriter, v: []const u8) !void {
+    try writer.putU32(@intCast(v.len));
+    try writer.slice(v);
+}
+
+// --- set ---
+
+pub fn encodeSet(allocator: Allocator, key: []const u8, value: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, key);
+    try w.slice(value);
+    return buf.toOwnedSlice();
+}
+
+pub const SetArgs = struct { key: []const u8, value: []const u8 };
+
+pub fn decodeSet(payload: []const u8) !SetArgs {
+    var c = Cursor{ .data = payload };
+    const key = try c.takeLenPrefixed();
+    const value = c.data[c.pos..];
+    return .{ .key = key, .value = value };
+}
+
+// --- auth ---
+
+pub fn encodeAuth(allocator: Allocator, username: []const u8, password: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, username);
+    try w.slice(password);
+    return buf.toOwnedSlice();
+}
+
+pub const AuthArgs = struct { username: []const u8, password: []const u8 };
+
+pub fn decodeAuth(payload: []const u8) !AuthArgs {
+    var c = Cursor{ .data = payload };
+    const username = try c.takeLenPrefixed();
+    const password = c.data[c.pos..];
+    return .{ .username = username, .password = password };
+}
+
+/// A successful `auth` response's payload: empty when the server has no
+/// session store wired up (see server.zig's `enableSessions`), or the raw
+/// session token bytes when it does. There is no separate decode function
+/// on the client side - `frame.payload` itself IS the token (or empty),
+/// no framing needed for a single opaque blob.
+pub fn encodeAuthOk(allocator: Allocator, token: ?[]const u8) ![]u8 {
+    return allocator.dupe(u8, token orelse "");
+}
+
+// --- auth_token ---
+
+/// Reconnects a fresh connection to a role without presenting the
+/// password again, by presenting a token previously handed out in an
+/// `auth` response (see `session.zig`'s `SessionStore.issue`). The
+/// payload is nothing but the opaque token bytes - no framing needed for
+/// a single blob, exactly like `encodeAuthOk`.
+pub fn encodeAuthToken(allocator: Allocator, token: []const u8) ![]u8 {
+    return allocator.dupe(u8, token);
+}
+
+pub fn decodeAuthToken(payload: []const u8) []const u8 {
+    return payload;
+}
+
+// --- user_admin ---
+
+/// Remote counterpart of the CLI's local `user add|passwd|role|del|list`,
+/// carried as one opcode so `server.zig`'s `requiredRole` can gate all five
+/// actions behind a single `admin`-only check instead of five separate
+/// opcodes. `role`/`rounds` are only meaningful for the actions that use
+/// them (`create` reads both, `set_role` reads only `role`, `set_password`
+/// reads only `rounds`); callers send 0 for the fields an action ignores.
+pub const UserAdminAction = enum(u8) {
+    create = 0,
+    set_password = 1,
+    set_role = 2,
+    delete = 3,
+    list = 4,
+
+    pub fn fromByte(b: u8) !UserAdminAction {
+        return std.meta.intToEnum(UserAdminAction, b) catch error.Malformed;
+    }
+};
+
+pub fn encodeUserAdmin(allocator: Allocator, action: UserAdminAction, username: []const u8, password: []const u8, role: authmod.Role, rounds: u32) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(@intFromEnum(action));
+    try w.byte(@intFromEnum(role));
+    try w.putU32(rounds);
+    try putLenPrefixed(w, username);
+    try w.slice(password);
+    return buf.toOwnedSlice();
+}
+
+pub const UserAdminArgs = struct {
+    action: UserAdminAction,
+    roleByte: u8,
+    rounds: u32,
+    username: []const u8,
+    password: []const u8,
+};
+
+pub fn decodeUserAdmin(payload: []const u8) !UserAdminArgs {
+    var c = Cursor{ .data = payload };
+    const action = try UserAdminAction.fromByte(try c.takeByte());
+    const roleByte = try c.takeByte();
+    const rounds = try c.takeU32();
+    const username = try c.takeLenPrefixed();
+    const password = c.data[c.pos..];
+    return .{ .action = action, .roleByte = roleByte, .rounds = rounds, .username = username, .password = password };
+}
+
+/// Encodes the response of a `list` user_admin request: every username
+/// paired with its role byte. Reuses `authmod.UserInfo`/`freeUserList`
+/// rather than inventing a parallel type, the same way `encodeStats` reuses
+/// `dbmod.Stats` and `encodeRows` reuses `rowmod.Row`.
+pub fn encodeUserList(allocator: Allocator, users: []const authmod.UserInfo) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(users.len));
+    for (users) |u| {
+        try putLenPrefixed(w, u.username);
+        try w.byte(@intFromEnum(u.role));
+    }
+    return buf.toOwnedSlice();
+}
+
+/// Decodes a user list response into independently owned entries - free
+/// with `authmod.freeUserList`.
+pub fn decodeUserList(allocator: Allocator, payload: []const u8) ![]authmod.UserInfo {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(authmod.UserInfo).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |u| u.deinit(allocator);
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const uname = try c.takeLenPrefixed();
+        const role = authmod.Role.fromByte(try c.takeByte()) catch return error.Malformed;
+        const owned = try allocator.dupe(u8, uname);
+        list.appendAssumeCapacity(.{ .username = owned, .role = role });
+    }
+    return list.toOwnedSlice();
+}
+
+// --- ttl_op ---
+
+/// Remote counterpart of the CLI's local `expire`/`persist`/`ttl`/
+/// `expire-sweep` (main.zig, backed by `ttl.zig`), carried as one opcode the
+/// same way `user_admin` bundles five user-management actions under one
+/// opcode - see server.zig's `requiredRole`, which (unlike `user_admin`'s
+/// blanket `admin` gate) inspects this action byte: `query` is read-only
+/// and needs only `readonly`; `expire`/`persist`/`sweep` all mutate (sweep
+/// deletes every due key) and need `readwrite`, matching every other write
+/// opcode.
+pub const TtlAction = enum(u8) {
+    expire = 0,
+    persist = 1,
+    query = 2,
+    sweep = 3,
+
+    pub fn fromByte(b: u8) !TtlAction {
+        return std.meta.intToEnum(TtlAction, b) catch error.Malformed;
+    }
+};
+
+/// `seconds` is only meaningful for `expire` - callers send 0 for the other
+/// three actions, same "unused fields carry a zero" convention as
+/// `encodeUserAdmin`'s `role`/`rounds`. `key` is empty for `sweep`, which
+/// operates on every due key in the store rather than one specific key.
+pub fn encodeTtlOp(allocator: Allocator, action: TtlAction, key: []const u8, seconds: u64) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(@intFromEnum(action));
+    try w.putU64(seconds);
+    try w.slice(key);
+    return buf.toOwnedSlice();
+}
+
+pub const TtlOpArgs = struct { action: TtlAction, seconds: u64, key: []const u8 };
+
+pub fn decodeTtlOp(payload: []const u8) !TtlOpArgs {
+    var c = Cursor{ .data = payload };
+    const action = try TtlAction.fromByte(try c.takeByte());
+    const seconds = try c.takeU64();
+    const key = c.data[c.pos..];
+    return .{ .action = action, .seconds = seconds, .key = key };
+}
+
+/// Encodes the response to a `query` ttl_op: reuses `ttlmod.TtlResult`
+/// rather than inventing a parallel type, the same way `encodeStats` reuses
+/// `dbmod.Stats` and `encodeUserList` reuses `authmod.UserInfo`.
+pub fn encodeTtlResult(allocator: Allocator, result: ttlmod.TtlResult) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    switch (result) {
+        .noKey => try w.byte(0),
+        .noExpiry => try w.byte(1),
+        .seconds => |s| {
+            try w.byte(2);
+            try w.putU64(s);
+        },
+    }
+    return buf.toOwnedSlice();
+}
+
+pub fn decodeTtlResult(payload: []const u8) !ttlmod.TtlResult {
+    var c = Cursor{ .data = payload };
+    const kind = try c.takeByte();
+    return switch (kind) {
+        0 => .noKey,
+        1 => .noExpiry,
+        2 => .{ .seconds = try c.takeU64() },
+        else => error.Malformed,
+    };
+}
+
+/// Encodes the response to a `sweep` ttl_op: how many due keys were reaped.
+pub fn encodeTtlSweepCount(allocator: Allocator, count: u64) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU64(count);
+    return buf.toOwnedSlice();
+}
+
+pub fn decodeTtlSweepCount(payload: []const u8) !u64 {
+    var c = Cursor{ .data = payload };
+    return c.takeU64();
+}
+
+// --- coll_ttl_op ---
+
+/// Remote counterpart of the CLI's local `coll <kind> expire|ttl|persist
+/// <name>`/`coll expire-sweep` (main.zig, backed by `collttl.zig`), same
+/// bundling shape as `ttl_op` above but for a whole typed collection
+/// (Counter/Hash/Set/List/ZSet) instead of one flat key - so the payload
+/// carries an extra `Kind` tag byte the flat version does not need.
+/// Reuses `TtlAction` directly rather than a parallel enum: the four
+/// actions (expire/persist/query/sweep) mean exactly the same thing here,
+/// just against `collttl.zig` instead of `ttl.zig`.
+pub fn encodeCollTtlOp(allocator: Allocator, action: TtlAction, kind: collmod.Kind, name: []const u8, seconds: u64) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(@intFromEnum(action));
+    // `sweep` operates across every kind at once (collttl.sweepExpired
+    // scans the whole marker namespace, not one kind's slice of it), so
+    // the kind byte is meaningless for that action - callers pass any
+    // valid `Kind` and `decodeCollTtlOp` still decodes it, but
+    // `handleCollTtlOp` never reads it for `.sweep`. Same "unused field
+    // still round-trips" convention as `encodeTtlOp`'s zeroed `seconds`
+    // on non-`expire` actions.
+    try w.byte(kind.tagByte());
+    try w.putU64(seconds);
+    try w.slice(name);
+    return buf.toOwnedSlice();
+}
+
+pub const CollTtlOpArgs = struct { action: TtlAction, kind: collmod.Kind, seconds: u64, name: []const u8 };
+
+pub fn decodeCollTtlOp(payload: []const u8) !CollTtlOpArgs {
+    var c = Cursor{ .data = payload };
+    const action = try TtlAction.fromByte(try c.takeByte());
+    const kind = collmod.Kind.fromTagByte(try c.takeByte()) orelse return error.Malformed;
+    const seconds = try c.takeU64();
+    const name = c.data[c.pos..];
+    return .{ .action = action, .kind = kind, .seconds = seconds, .name = name };
+}
+
+// --- coll_op ---
+
+/// Remote counterpart of the CLI's local `coll <kind> <op> ...` (main.zig's
+/// `runColl`, backed by `collections.zig`) - until now the Redis-like
+/// collections (Counter/Hash/Set/List/ZSet) were reachable only from a
+/// process that had the `Db` open directly, the same gap `ttl_op`/
+/// `coll_ttl_op` already closed for TTL management. One opcode bundles
+/// every collection operation (the same "one opcode, many actions" shape
+/// as `user_admin` and `ttl_op`) rather than one opcode per op, since the
+/// five kinds share almost nothing about their argument count or type.
+/// The payload carries only the action tag, the collection name, and a
+/// variable list of string arguments in the exact CLI text form `runColl`
+/// already parses locally (values/members/indices/scores) - so
+/// `handleCollOp` (server.zig) can reuse the very same
+/// `std.fmt.parseInt`/`parseFloat` calls instead of inventing a second
+/// binary number encoding just for this opcode.
+pub const CollAction = enum(u8) {
+    counter_get = 0,
+    counter_set = 1,
+    counter_incrby = 2,
+    hash_set = 3,
+    hash_get = 4,
+    hash_del = 5,
+    hash_len = 6,
+    hash_getall = 7,
+    set_add = 8,
+    set_rem = 9,
+    set_ismember = 10,
+    set_card = 11,
+    set_members = 12,
+    // `set_inter`/`set_union`/`set_diff`: `name` is the first set, `args`
+    // are every remaining set name - the same split `runColl` already uses
+    // (`args[0]` vs `args[1..]`) for these three multi-set operations.
+    set_inter = 13,
+    set_union = 14,
+    set_diff = 15,
+    list_lpush = 16,
+    list_rpush = 17,
+    list_lpop = 18,
+    list_rpop = 19,
+    list_len = 20,
+    list_range = 21,
+    zset_add = 22,
+    zset_score = 23,
+    zset_incrby = 24,
+    zset_rem = 25,
+    zset_card = 26,
+    zset_rangebyrank = 27,
+    zset_rangebyscore = 28,
+    zset_rank = 29,
+
+    pub fn fromByte(b: u8) !CollAction {
+        return std.meta.intToEnum(CollAction, b) catch error.Malformed;
+    }
+
+    /// Which `collections.Kind` namespace this action's lazy TTL check
+    /// (`collttl.expireIfDue`, called on `name` before every dispatch in
+    /// `handleCollOp`) and `requiredRole` gating both need - grouped by the
+    /// action's numeric range rather than a second explicit table, since
+    /// the enum above is itself laid out kind-by-kind.
+    pub fn kind(self: CollAction) collmod.Kind {
+        return switch (self) {
+            .counter_get, .counter_set, .counter_incrby => .counter,
+            .hash_set, .hash_get, .hash_del, .hash_len, .hash_getall => .hash,
+            .set_add, .set_rem, .set_ismember, .set_card, .set_members, .set_inter, .set_union, .set_diff => .set,
+            .list_lpush, .list_rpush, .list_lpop, .list_rpop, .list_len, .list_range => .list,
+            .zset_add, .zset_score, .zset_incrby, .zset_rem, .zset_card, .zset_rangebyrank, .zset_rangebyscore, .zset_rank => .zset,
+        };
+    }
+
+    /// True for actions that only read - see `server.zig`'s `requiredRole`,
+    /// which needs this to decide `readonly` vs `readwrite` from the action
+    /// byte alone, the same action-byte peek `ttl_op`/`coll_ttl_op` already
+    /// use for their own bundled actions.
+    pub fn isReadOnly(self: CollAction) bool {
+        return switch (self) {
+            .counter_get, .hash_get, .hash_len, .hash_getall, .set_ismember, .set_card, .set_members, .set_inter, .set_union, .set_diff, .list_len, .list_range, .zset_score, .zset_card, .zset_rangebyrank, .zset_rangebyscore, .zset_rank => true,
+            else => false,
+        };
+    }
+};
+
+pub fn encodeCollOp(allocator: Allocator, action: CollAction, name: []const u8, args: []const []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(@intFromEnum(action));
+    try putLenPrefixed(w, name);
+    try w.putU32(@intCast(args.len));
+    for (args) |a| try putLenPrefixed(w, a);
+    return buf.toOwnedSlice();
+}
+
+pub const CollOpArgs = struct {
+    action: CollAction,
+    name: []const u8,
+    args: [][]const u8,
+};
+
+/// `name` and every entry of `args` are borrowed slices into `payload`,
+/// valid only as long as the frame that carried them is alive - the same
+/// convention `decodeBatch`/`decodeTableSelect` use. Only the `args`
+/// pointer array itself is owned by the caller (free with
+/// `allocator.free`); never its contents.
+pub fn decodeCollOp(allocator: Allocator, payload: []const u8) !CollOpArgs {
+    var c = Cursor{ .data = payload };
+    const action = try CollAction.fromByte(try c.takeByte());
+    const name = try c.takeLenPrefixed();
+    const count = try c.takeU32();
+    var list = try std.ArrayList([]const u8).initCapacity(allocator, count);
+    errdefer list.deinit();
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        list.appendAssumeCapacity(try c.takeLenPrefixed());
+    }
+    return .{ .action = action, .name = name, .args = try list.toOwnedSlice() };
+}
+
+/// One reply shape covers every `coll_op` action, tagged by the first byte -
+/// the response-side counterpart of the request-side `CollAction`. `.nil`
+/// is the wire form of the CLI's `(nil)` (a hash field/list pop/zset score
+/// that does not exist); `.ok` is a bare acknowledgement (counter set,
+/// hash set/del as a flag would double up with `.int`, so those still use
+/// `.int` with 0/1 - see `encodeCollReply`).
+pub const CollReplyTag = enum(u8) {
+    nil = 0,
+    ok = 1,
+    int = 2,
+    real = 3,
+    bytes = 4,
+    stringList = 5,
+    pairList = 6,
+    scorePairList = 7,
+};
+
+pub const CollPair = struct { field: []const u8, value: []const u8 };
+pub const CollScorePair = struct { member: []const u8, score: f64 };
+
+pub const CollReply = union(enum) {
+    nil,
+    ok,
+    int: i64,
+    real: f64,
+    bytes: []const u8,
+    stringList: []const []const u8,
+    pairList: []const CollPair,
+    scorePairList: []const CollScorePair,
+};
+
+pub fn encodeCollReply(allocator: Allocator, reply: CollReply) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    switch (reply) {
+        .nil => try w.byte(@intFromEnum(CollReplyTag.nil)),
+        .ok => try w.byte(@intFromEnum(CollReplyTag.ok)),
+        .int => |v| {
+            try w.byte(@intFromEnum(CollReplyTag.int));
+            try w.putU64(@bitCast(v));
+        },
+        .real => |v| {
+            try w.byte(@intFromEnum(CollReplyTag.real));
+            try w.putU64(@bitCast(v));
+        },
+        .bytes => |v| {
+            try w.byte(@intFromEnum(CollReplyTag.bytes));
+            try w.slice(v);
+        },
+        .stringList => |items| {
+            try w.byte(@intFromEnum(CollReplyTag.stringList));
+            try w.putU32(@intCast(items.len));
+            for (items) |it| try putLenPrefixed(w, it);
+        },
+        .pairList => |items| {
+            try w.byte(@intFromEnum(CollReplyTag.pairList));
+            try w.putU32(@intCast(items.len));
+            for (items) |p| {
+                try putLenPrefixed(w, p.field);
+                try putLenPrefixed(w, p.value);
+            }
+        },
+        .scorePairList => |items| {
+            try w.byte(@intFromEnum(CollReplyTag.scorePairList));
+            try w.putU32(@intCast(items.len));
+            for (items) |p| {
+                try putLenPrefixed(w, p.member);
+                try w.putU64(@bitCast(p.score));
+            }
+        },
+    }
+    return buf.toOwnedSlice();
+}
+
+pub const OwnedCollPair = struct { field: []u8, value: []u8 };
+pub const OwnedCollScorePair = struct { member: []u8, score: f64 };
+
+/// Decoded, independently owned counterpart of `CollReply` - every byte
+/// slice is a fresh allocation the caller must free via `deinit`, unlike
+/// `CollOpArgs` above which stays borrowed (that side is consumed
+/// immediately inside `dispatch` before the frame is freed; this side
+/// crosses back out to a `Client` caller that keeps it around).
+pub const OwnedCollReply = union(enum) {
+    nil,
+    ok,
+    int: i64,
+    real: f64,
+    bytes: []u8,
+    stringList: [][]u8,
+    pairList: []OwnedCollPair,
+    scorePairList: []OwnedCollScorePair,
+
+    pub fn deinit(self: *OwnedCollReply, allocator: Allocator) void {
+        switch (self.*) {
+            .bytes => |b| allocator.free(b),
+            .stringList => |items| {
+                for (items) |it| allocator.free(it);
+                allocator.free(items);
+            },
+            .pairList => |items| {
+                for (items) |p| {
+                    allocator.free(p.field);
+                    allocator.free(p.value);
+                }
+                allocator.free(items);
+            },
+            .scorePairList => |items| {
+                for (items) |p| allocator.free(p.member);
+                allocator.free(items);
+            },
+            .nil, .ok, .int, .real => {},
+        }
+        self.* = undefined;
+    }
+};
+
+pub fn decodeCollReply(allocator: Allocator, payload: []const u8) !OwnedCollReply {
+    var c = Cursor{ .data = payload };
+    const tag = std.meta.intToEnum(CollReplyTag, try c.takeByte()) catch return error.Malformed;
+    return switch (tag) {
+        .nil => .nil,
+        .ok => .ok,
+        .int => .{ .int = @bitCast(try c.takeU64()) },
+        .real => .{ .real = @bitCast(try c.takeU64()) },
+        .bytes => .{ .bytes = try allocator.dupe(u8, c.data[c.pos..]) },
+        .stringList => blk: {
+            const count = try c.takeU32();
+            var list = try std.ArrayList([]u8).initCapacity(allocator, count);
+            errdefer {
+                for (list.items) |it| allocator.free(it);
+                list.deinit();
+            }
+            var i: u32 = 0;
+            while (i < count) : (i += 1) {
+                const raw = try c.takeLenPrefixed();
+                list.appendAssumeCapacity(try allocator.dupe(u8, raw));
+            }
+            break :blk .{ .stringList = try list.toOwnedSlice() };
+        },
+        .pairList => blk: {
+            const count = try c.takeU32();
+            var list = try std.ArrayList(OwnedCollPair).initCapacity(allocator, count);
+            errdefer {
+                for (list.items) |p| {
+                    allocator.free(p.field);
+                    allocator.free(p.value);
+                }
+                list.deinit();
+            }
+            var i: u32 = 0;
+            while (i < count) : (i += 1) {
+                const field = try c.takeLenPrefixed();
+                const value = try c.takeLenPrefixed();
+                list.appendAssumeCapacity(.{ .field = try allocator.dupe(u8, field), .value = try allocator.dupe(u8, value) });
+            }
+            break :blk .{ .pairList = try list.toOwnedSlice() };
+        },
+        .scorePairList => blk: {
+            const count = try c.takeU32();
+            var list = try std.ArrayList(OwnedCollScorePair).initCapacity(allocator, count);
+            errdefer {
+                for (list.items) |p| allocator.free(p.member);
+                list.deinit();
+            }
+            var i: u32 = 0;
+            while (i < count) : (i += 1) {
+                const member = try c.takeLenPrefixed();
+                const score: f64 = @bitCast(try c.takeU64());
+                list.appendAssumeCapacity(.{ .member = try allocator.dupe(u8, member), .score = score });
+            }
+            break :blk .{ .scorePairList = try list.toOwnedSlice() };
+        },
+    };
+}
+
+// --- txn_op ---
+
+/// Remote counterpart of the CLI's local `txn <script-file>` (main.zig's
+/// `runTxn`, backed by `txn.zig`/`txn_table.zig`): a batch of put/delete row
+/// operations, possibly spanning several tables, applied as one atomic
+/// `Transaction` commit - the same "every op succeeds together or none of
+/// them do" guarantee the local CLI gives, now reachable from a process that
+/// only has a `Client`, not a `*Db`. Unlike `coll_op`/`ttl_op` (one action
+/// against one key/collection per request) this opcode carries a LIST of
+/// entries, since a transaction script is inherently a batch.
+pub const TxnVerb = enum(u8) {
+    put = 0,
+    del = 1,
+
+    pub fn fromByte(b: u8) !TxnVerb {
+        return std.meta.intToEnum(TxnVerb, b) catch error.Malformed;
+    }
+};
+
+/// One staged operation as the caller supplies it. `fields` is ignored for
+/// `.del` (callers pass `&.{}`) - same "unused argument still there, just
+/// empty" convention as `encodeUserAdmin`'s zeroed `role`/`rounds` on
+/// actions that do not need them.
+pub const TxnOpEntry = struct {
+    verb: TxnVerb,
+    table: []const u8,
+    pk: rowmod.Value,
+    fields: []const rowmod.Field = &.{},
+};
+
+pub fn encodeTxnOp(allocator: Allocator, entries: []const TxnOpEntry) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(entries.len));
+    for (entries) |e| {
+        try w.byte(@intFromEnum(e.verb));
+        try putLenPrefixed(w, e.table);
+
+        const pkBytes = try rowmod.encodeValue(allocator, e.pk);
+        defer allocator.free(pkBytes);
+        try putLenPrefixed(w, pkBytes);
+
+        // Reuses `Row.encode` for the field list exactly the way
+        // `encodeRows` does for a whole result set, instead of inventing a
+        // second name+value framing just for this opcode.
+        var fieldsRow = rowmod.Row.init(allocator);
+        defer fieldsRow.deinit();
+        for (e.fields) |f| try fieldsRow.set(f.name, f.value);
+        const fieldsBytes = try fieldsRow.encode(allocator);
+        defer allocator.free(fieldsBytes);
+        try putLenPrefixed(w, fieldsBytes);
+    }
+    return buf.toOwnedSlice();
+}
+
+/// Decoded entry with every slice borrowed from the frame `payload` that
+/// carried it - same convention as `decodeCollOp`/`decodeTableSelect`, valid
+/// only as long as that payload is alive. `pkBytes`/`fieldsBytes` still need
+/// `rowmod.decodeValue`/`rowmod.Row.decode` to become a real `Value`/field
+/// list; kept undecoded here so a malformed table name or verb byte fails
+/// fast without touching row-decoding at all.
+pub const DecodedTxnOpEntry = struct {
+    verb: TxnVerb,
+    table: []const u8,
+    pkBytes: []const u8,
+    fieldsBytes: []const u8,
+};
+
+pub fn decodeTxnOp(allocator: Allocator, payload: []const u8) ![]DecodedTxnOpEntry {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(DecodedTxnOpEntry).initCapacity(allocator, count);
+    errdefer list.deinit();
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const verb = try TxnVerb.fromByte(try c.takeByte());
+        const table = try c.takeLenPrefixed();
+        const pkBytes = try c.takeLenPrefixed();
+        const fieldsBytes = try c.takeLenPrefixed();
+        list.appendAssumeCapacity(.{ .verb = verb, .table = table, .pkBytes = pkBytes, .fieldsBytes = fieldsBytes });
+    }
+    return list.toOwnedSlice();
+}
+
+/// Encodes the response to a successful `txn_op`: how many operations were
+/// committed - always every entry in the request, since a partial commit is
+/// impossible (`error.Conflict` aborts the whole transaction instead, and
+/// surfaces as `Status.conflict` with no payload, the same shape as
+/// `user_admin`'s `UserExists` conflict).
+pub fn encodeTxnResult(allocator: Allocator, applied: u32) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(applied);
+    return buf.toOwnedSlice();
+}
+
+pub fn decodeTxnResult(payload: []const u8) !u32 {
+    var c = Cursor{ .data = payload };
+    return c.takeU32();
+}
+
+// --- scan / prefix ---
+
+pub const ScanArgs = struct {
+    start: ?[]const u8 = null,
+    end: ?[]const u8 = null,
+    limit: u32 = 0,
+    reverse: bool = false,
+};
+
+const scanFlagHasStart: u8 = 1 << 0;
+const scanFlagHasEnd: u8 = 1 << 1;
+const scanFlagReverse: u8 = 1 << 2;
+
+pub fn encodeScan(allocator: Allocator, args: ScanArgs) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    var flags: u8 = 0;
+    if (args.start != null) flags |= scanFlagHasStart;
+    if (args.end != null) flags |= scanFlagHasEnd;
+    if (args.reverse) flags |= scanFlagReverse;
+    try w.byte(flags);
+    if (args.start) |s| try putLenPrefixed(w, s);
+    if (args.end) |e| try putLenPrefixed(w, e);
+    try w.putU32(args.limit);
+    return buf.toOwnedSlice();
+}
+
+pub fn decodeScan(payload: []const u8) !ScanArgs {
+    var c = Cursor{ .data = payload };
+    const flags = try c.takeByte();
+    var args = ScanArgs{};
+    if (flags & scanFlagHasStart != 0) args.start = try c.takeLenPrefixed();
+    if (flags & scanFlagHasEnd != 0) args.end = try c.takeLenPrefixed();
+    args.reverse = flags & scanFlagReverse != 0;
+    args.limit = try c.takeU32();
+    return args;
+}
+
+pub fn encodePrefix(allocator: Allocator, prefix: []const u8, limit: u32) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(limit);
+    try w.slice(prefix);
+    return buf.toOwnedSlice();
+}
+
+pub const PrefixArgs = struct { prefix: []const u8, limit: u32 };
+
+pub fn decodePrefix(payload: []const u8) !PrefixArgs {
+    var c = Cursor{ .data = payload };
+    const limit = try c.takeU32();
+    const prefix = c.data[c.pos..];
+    return .{ .prefix = prefix, .limit = limit };
+}
+
+// --- entry lists (scan / prefix responses) ---
+
+pub fn encodeEntries(allocator: Allocator, entries: []const dbmod.Entry) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(entries.len));
+    for (entries) |e| {
+        try putLenPrefixed(w, e.key);
+        try putLenPrefixed(w, e.value);
+    }
+    return buf.toOwnedSlice();
+}
+
+pub const OwnedEntry = struct {
+    key: []u8,
+    value: []u8,
+
+    pub fn deinit(self: *OwnedEntry, allocator: Allocator) void {
+        allocator.free(self.key);
+        allocator.free(self.value);
+    }
+};
+
+/// Copies every key and value out of `payload` so the caller can free
+/// the frame that carried them and keep the entries alive independently.
+pub fn decodeEntries(allocator: Allocator, payload: []const u8) ![]OwnedEntry {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(OwnedEntry).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |*e| e.deinit(allocator);
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const key = try c.takeLenPrefixed();
+        const value = try c.takeLenPrefixed();
+        const ownedKey = try allocator.dupe(u8, key);
+        errdefer allocator.free(ownedKey);
+        const ownedValue = try allocator.dupe(u8, value);
+        list.appendAssumeCapacity(.{ .key = ownedKey, .value = ownedValue });
+    }
+    return list.toOwnedSlice();
+}
+
+pub fn freeOwnedEntries(allocator: Allocator, entries: []OwnedEntry) void {
+    for (entries) |*e| e.deinit(allocator);
+    allocator.free(entries);
+}
+
+// --- batch ---
+
+pub const BatchOp = union(enum) {
+    put: struct { key: []const u8, value: []const u8 },
+    del: []const u8,
+};
+
+const batchKindPut: u8 = 0;
+const batchKindDel: u8 = 1;
+
+pub fn encodeBatch(allocator: Allocator, ops: []const BatchOp) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(ops.len));
+    for (ops) |op| {
+        switch (op) {
+            .put => |kv| {
+                try w.byte(batchKindPut);
+                try putLenPrefixed(w, kv.key);
+                try putLenPrefixed(w, kv.value);
+            },
+            .del => |key| {
+                try w.byte(batchKindDel);
+                try putLenPrefixed(w, key);
+            },
+        }
+    }
+    return buf.toOwnedSlice();
+}
+
+pub const DecodedBatchOp = union(enum) {
+    put: struct { key: []const u8, value: []const u8 },
+    del: []const u8,
+};
+
+pub fn decodeBatch(allocator: Allocator, payload: []const u8) ![]DecodedBatchOp {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(DecodedBatchOp).initCapacity(allocator, count);
+    errdefer list.deinit();
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const kind = try c.takeByte();
+        switch (kind) {
+            batchKindPut => {
+                const key = try c.takeLenPrefixed();
+                const value = try c.takeLenPrefixed();
+                list.appendAssumeCapacity(.{ .put = .{ .key = key, .value = value } });
+            },
+            batchKindDel => {
+                const key = try c.takeLenPrefixed();
+                list.appendAssumeCapacity(.{ .del = key });
+            },
+            else => return error.Malformed,
+        }
+    }
+    return list.toOwnedSlice();
+}
+
+// --- table select ---
+
+/// Wire request for a remote `table select`: a table name, the raw text of
+/// an `expr.zig` predicate expression (empty text selects every row, the
+/// same convention `query.Table.select(null)` uses locally), an
+/// offset/limit page window using the same "0 = unlimited" convention as
+/// `ScanArgs.limit` above - so a large remote result can be paged instead
+/// of always coming back in one frame bounded only by `maxFrameBytes` - and
+/// a `query.OrderBy` sort key list (possibly empty) applied server-side via
+/// `Table.selectPageOrdered` before that page window. The order-by count
+/// byte (and each field name/direction pair behind it) sit BEFORE
+/// `exprText` rather than after it, because `exprText` is decoded as
+/// "everything left in the payload" - anything meant to survive decoding
+/// has to come first. A single byte bounds the count to 255 columns, far
+/// more than any real query needs.
+pub fn encodeTableSelect(allocator: Allocator, table: []const u8, exprText: []const u8, offset: u32, limit: u32, orderBy: []const querymod.OrderBy) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+    try w.putU32(offset);
+    try w.putU32(limit);
+    try w.byte(@intCast(orderBy.len));
+    for (orderBy) |ob| {
+        try w.byte(if (ob.descending) 1 else 0);
+        try putLenPrefixed(w, ob.field);
+    }
+    try w.slice(exprText);
+    return buf.toOwnedSlice();
+}
+
+pub const TableSelectArgs = struct {
+    table: []const u8,
+    exprText: []const u8,
+    offset: u32 = 0,
+    limit: u32 = 0,
+    orderBy: []const querymod.OrderBy = &.{},
+};
+
+/// `table`, `exprText`, and every `orderBy[i].field` are borrowed slices
+/// into `payload` - the same convention `decodeCollOp` uses. Only the
+/// `orderBy` array itself is owned by the caller (free with
+/// `allocator.free`); never its contents.
+pub fn decodeTableSelect(allocator: Allocator, payload: []const u8) !TableSelectArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const offset = try c.takeU32();
+    const limit = try c.takeU32();
+    const count = try c.takeByte();
+    var list = try std.ArrayList(querymod.OrderBy).initCapacity(allocator, count);
+    errdefer list.deinit();
+    var i: u8 = 0;
+    while (i < count) : (i += 1) {
+        const descending = try c.takeByte();
+        const field = try c.takeLenPrefixed();
+        list.appendAssumeCapacity(.{ .field = field, .descending = descending != 0 });
+    }
+    const exprText = c.data[c.pos..];
+    return .{ .table = table, .exprText = exprText, .offset = offset, .limit = limit, .orderBy = try list.toOwnedSlice() };
+}
+
+/// Encodes a `table select` result set as a length-prefixed list of rows,
+/// each row itself encoded with `Row.encode` (the same self-describing
+/// field format a Table stores on disk).
+pub fn encodeRows(allocator: Allocator, rows: []const rowmod.Row) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(rows.len));
+    for (rows) |*r| {
+        const encoded = try r.encode(allocator);
+        defer allocator.free(encoded);
+        try putLenPrefixed(w, encoded);
+    }
+    return buf.toOwnedSlice();
+}
+
+/// Decodes a `table select` result set into independently owned Rows -
+/// callers must free each with `Row.deinit` (see `freeRows` below).
+pub fn decodeRows(allocator: Allocator, payload: []const u8) ![]rowmod.Row {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(rowmod.Row).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |*r| r.deinit();
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const raw = try c.takeLenPrefixed();
+        const row = rowmod.Row.decode(allocator, raw) catch return error.Malformed;
+        list.appendAssumeCapacity(row);
+    }
+    return list.toOwnedSlice();
+}
+
+pub fn freeRows(allocator: Allocator, rows: []rowmod.Row) void {
+    for (rows) |*r| r.deinit();
+    allocator.free(rows);
+}
+
+// --- table join ---
+
+/// Which of `join.zig`'s four equi-join variants a `table_join` request
+/// wants - the wire counterpart of the CLI's `table join`
+/// `[--left|--right|--full]` flags (no flag means `.inner`).
+pub const JoinMode = enum(u8) {
+    inner = 0,
+    left = 1,
+    right = 2,
+    full = 3,
+
+    pub fn fromByte(b: u8) !JoinMode {
+        return std.meta.intToEnum(JoinMode, b) catch error.UnknownJoinMode;
+    }
+};
+
+/// Wire request for a remote `table join`: which variant (`mode`), the two
+/// tables and the fields they are joined on, and an optional `expr.zig`
+/// predicate text for each side - the same `leftPred`/`rightPred` filter
+/// `join.innerJoin` and its outer variants already take, evaluated exactly
+/// like `table_select`'s `exprText` (empty selects every row on that side).
+pub fn encodeTableJoin(
+    allocator: Allocator,
+    mode: JoinMode,
+    leftTable: []const u8,
+    leftField: []const u8,
+    rightTable: []const u8,
+    rightField: []const u8,
+    offset: u32,
+    limit: u32,
+    leftExprText: []const u8,
+    rightExprText: []const u8,
+) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(@intFromEnum(mode));
+    try putLenPrefixed(w, leftTable);
+    try putLenPrefixed(w, leftField);
+    try putLenPrefixed(w, rightTable);
+    try putLenPrefixed(w, rightField);
+    try w.putU32(offset);
+    try w.putU32(limit);
+    try putLenPrefixed(w, leftExprText);
+    try w.slice(rightExprText);
+    return buf.toOwnedSlice();
+}
+
+pub const TableJoinArgs = struct {
+    mode: JoinMode,
+    leftTable: []const u8,
+    leftField: []const u8,
+    rightTable: []const u8,
+    rightField: []const u8,
+    offset: u32 = 0,
+    limit: u32 = 0,
+    leftExprText: []const u8,
+    rightExprText: []const u8,
+};
+
+pub fn decodeTableJoin(payload: []const u8) !TableJoinArgs {
+    var c = Cursor{ .data = payload };
+    const mode = try JoinMode.fromByte(try c.takeByte());
+    const leftTable = try c.takeLenPrefixed();
+    const leftField = try c.takeLenPrefixed();
+    const rightTable = try c.takeLenPrefixed();
+    const rightField = try c.takeLenPrefixed();
+    const offset = try c.takeU32();
+    const limit = try c.takeU32();
+    const leftExprText = try c.takeLenPrefixed();
+    const rightExprText = c.data[c.pos..];
+    return .{
+        .mode = mode,
+        .leftTable = leftTable,
+        .leftField = leftField,
+        .rightTable = rightTable,
+        .rightField = rightField,
+        .offset = offset,
+        .limit = limit,
+        .leftExprText = leftExprText,
+        .rightExprText = rightExprText,
+    };
+}
+
+/// One row pair from any of `join.zig`'s four variants, flattened to a
+/// single wire shape: `innerJoin` never leaves either side null,
+/// `leftOuterJoin`/`rightOuterJoin` leave exactly one side nullable, and
+/// `fullOuterJoin` allows either - rather than four near-identical wire
+/// encodings, every variant's result is converted to this one shape before
+/// `encodeJoinedRows`, and the CLI decides what "(nil)" means from which
+/// `--left`/`--right`/`--full` flag it sent, exactly like the local `table
+/// join` printer already does per `JoinMode`.
+pub const JoinPair = struct { left: ?rowmod.Row, right: ?rowmod.Row };
+
+fn putOptionalRow(allocator: Allocator, w: encode.ByteWriter, row: ?rowmod.Row) !void {
+    if (row) |*r| {
+        try w.byte(1);
+        const encoded = try r.encode(allocator);
+        defer allocator.free(encoded);
+        try putLenPrefixed(w, encoded);
+    } else {
+        try w.byte(0);
+    }
+}
+
+pub fn encodeJoinedRows(allocator: Allocator, pairs: []const JoinPair) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(pairs.len));
+    for (pairs) |p| {
+        try putOptionalRow(allocator, w, p.left);
+        try putOptionalRow(allocator, w, p.right);
+    }
+    return buf.toOwnedSlice();
+}
+
+fn takeOptionalRow(allocator: Allocator, c: *Cursor) !?rowmod.Row {
+    const present = try c.takeByte();
+    if (present == 0) return null;
+    const raw = try c.takeLenPrefixed();
+    return rowmod.Row.decode(allocator, raw) catch return error.Malformed;
+}
+
+/// Decodes a `table_join` result set into independently owned `JoinPair`s -
+/// callers must free each present side with `Row.deinit` (see
+/// `freeJoinPairs` below).
+pub fn decodeJoinedRows(allocator: Allocator, payload: []const u8) ![]JoinPair {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(JoinPair).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |*p| {
+            if (p.left) |*l| l.deinit();
+            if (p.right) |*r| r.deinit();
+        }
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const left = try takeOptionalRow(allocator, &c);
+        const right = try takeOptionalRow(allocator, &c);
+        list.appendAssumeCapacity(.{ .left = left, .right = right });
+    }
+    return list.toOwnedSlice();
+}
+
+pub fn freeJoinPairs(allocator: Allocator, pairs: []JoinPair) void {
+    for (pairs) |*p| {
+        if (p.left) |*l| l.deinit();
+        if (p.right) |*r| r.deinit();
+    }
+    allocator.free(pairs);
+}
+
+// --- table aggregate ---
+
+/// Wire request for a remote `table aggregate`: a table name, an optional
+/// GROUP BY field (empty means no grouping - the network counterpart of the
+/// CLI's `*` sentinel for `table aggregate <table> *`, chosen client-side so
+/// the wire itself needs no separate mode byte), the list of
+/// `aggregate.zig` specs to compute, and an `expr.zig` predicate text
+/// filtering rows BEFORE aggregation runs - the same empty-means-every-row
+/// convention `table_select`'s `exprText` already uses.
+/// `offset`/`limit` window the result GROUPS (not the input rows) when
+/// `groupField` is non-empty, the same `join.applyPage`/`Table.selectPage`
+/// convention as `table_join`'s wire format - 0/0 means unlimited. Ignored
+/// server-side when `groupField` is empty (`runGlobal` always produces
+/// exactly one result row, nothing to page).
+/// `orderBy` is a `query.OrderBy` sort key list (possibly empty) applied
+/// server-side to the result GROUPS via `aggregate.sortGroupsBy`, after
+/// HAVING narrows them and before `offset`/`limit` window them - same
+/// convention and wire shape (count byte + descending byte + length-prefixed
+/// field name, per column) as `encodeTableSelect`'s `orderBy`. Each
+/// `orderBy[i].field` must name either `groupField` or one of `specs`'
+/// `specLabel`s (validated server-side by `sortGroupsBy`, not here).
+/// Meaningless (and ignored server-side) for the ungrouped `groupField.len
+/// == 0` path, same as `offset`/`limit` already are - `runGlobal` always
+/// produces exactly one result row, nothing to order.
+///
+/// `havingText` is a second, independent `expr.zig` predicate text
+/// (empty means no HAVING) filtering the result GROUPS AFTER aggregation,
+/// evaluated server-side before `offset`/`limit` window them - the wire
+/// counterpart of the CLI's `having <expr>` suffix. Encoded length-prefixed
+/// (not "rest of payload" like `exprText`) precisely because `exprText`
+/// still needs to occupy that final slot.
+pub fn encodeTableAggregate(allocator: Allocator, table: []const u8, groupField: []const u8, specs: []const aggregatemod.AggSpec, offset: u32, limit: u32, orderBy: []const querymod.OrderBy, havingText: []const u8, exprText: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+    try putLenPrefixed(w, groupField);
+    try w.putU32(@intCast(specs.len));
+    for (specs) |spec| {
+        try w.byte(@intFromEnum(spec.kind));
+        try putLenPrefixed(w, spec.field);
+    }
+    try w.putU32(offset);
+    try w.putU32(limit);
+    try w.byte(@intCast(orderBy.len));
+    for (orderBy) |ob| {
+        try w.byte(if (ob.descending) 1 else 0);
+        try putLenPrefixed(w, ob.field);
+    }
+    try putLenPrefixed(w, havingText);
+    try w.slice(exprText);
+    return buf.toOwnedSlice();
+}
+
+pub const TableAggregateArgs = struct {
+    table: []const u8,
+    groupField: []const u8,
+    /// Borrows `field` slices from the decoded payload but owns the slice
+    /// itself - caller frees with `allocator.free(args.specs)`, same shape
+    /// as `decodeBatch`'s returned list.
+    specs: []aggregatemod.AggSpec,
+    offset: u32 = 0,
+    limit: u32 = 0,
+    /// Empty means no ORDER BY - see `encodeTableAggregate`'s doc. Borrows
+    /// `field` slices from the decoded payload but owns the slice itself,
+    /// same convention as `specs`/`TableSelectArgs.orderBy`.
+    orderBy: []const querymod.OrderBy = &.{},
+    /// Empty means no HAVING clause - see `encodeTableAggregate`'s doc.
+    havingText: []const u8,
+    exprText: []const u8,
+};
+
+pub fn decodeTableAggregate(allocator: Allocator, payload: []const u8) !TableAggregateArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const groupField = try c.takeLenPrefixed();
+    const count = try c.takeU32();
+    var specs = try std.ArrayList(aggregatemod.AggSpec).initCapacity(allocator, count);
+    errdefer specs.deinit();
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const kindByte = try c.takeByte();
+        const kind = std.meta.intToEnum(aggregatemod.AggKind, kindByte) catch return error.Malformed;
+        const field = try c.takeLenPrefixed();
+        specs.appendAssumeCapacity(.{ .kind = kind, .field = field });
+    }
+    const offset = try c.takeU32();
+    const limit = try c.takeU32();
+    const orderCount = try c.takeByte();
+    var orderBy = try std.ArrayList(querymod.OrderBy).initCapacity(allocator, orderCount);
+    errdefer orderBy.deinit();
+    var j: u8 = 0;
+    while (j < orderCount) : (j += 1) {
+        const descending = try c.takeByte();
+        const field = try c.takeLenPrefixed();
+        orderBy.appendAssumeCapacity(.{ .field = field, .descending = descending != 0 });
+    }
+    const havingText = try c.takeLenPrefixed();
+    const exprText = c.data[c.pos..];
+    return .{ .table = table, .groupField = groupField, .specs = try specs.toOwnedSlice(), .offset = offset, .limit = limit, .orderBy = try orderBy.toOwnedSlice(), .havingText = havingText, .exprText = exprText };
+}
+
+fn putEncodedValue(allocator: Allocator, w: encode.ByteWriter, value: rowmod.Value) !void {
+    const encoded = try rowmod.encodeValue(allocator, value);
+    defer allocator.free(encoded);
+    try putLenPrefixed(w, encoded);
+}
+
+fn takeDecodedValue(allocator: Allocator, c: *Cursor) !rowmod.Value {
+    const raw = try c.takeLenPrefixed();
+    return rowmod.decodeValue(allocator, raw) catch return error.Malformed;
+}
+
+/// Encodes a `runGlobal` (no `GROUP BY`) result: exactly `specs.len` values,
+/// same order as the request's specs.
+pub fn encodeAggGlobalResult(allocator: Allocator, values: []const rowmod.Value) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(values.len));
+    for (values) |v| try putEncodedValue(allocator, w, v);
+    return buf.toOwnedSlice();
+}
+
+/// Decodes a `runGlobal` result into independently owned `Value`s - callers
+/// must free with `freeAggValues`.
+pub fn decodeAggGlobalResult(allocator: Allocator, payload: []const u8) ![]rowmod.Value {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(rowmod.Value).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |v| v.free(allocator);
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) list.appendAssumeCapacity(try takeDecodedValue(allocator, &c));
+    return list.toOwnedSlice();
+}
+
+pub fn freeAggValues(allocator: Allocator, values: []rowmod.Value) void {
+    for (values) |v| v.free(allocator);
+    allocator.free(values);
+}
+
+/// Encodes a grouped `run` result: one entry per `GroupRow` (the group-key
+/// value, then exactly `specs.len` result values), in the same first-seen
+/// order `GroupBy.finish()` produced them.
+pub fn encodeAggGroupRows(allocator: Allocator, groups: []const aggregatemod.GroupRow) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(groups.len));
+    for (groups) |g| {
+        try putEncodedValue(allocator, w, g.group);
+        try w.putU32(@intCast(g.values.len));
+        for (g.values) |v| try putEncodedValue(allocator, w, v);
+    }
+    return buf.toOwnedSlice();
+}
+
+/// Decodes a grouped `run` result into independently owned `GroupRow`s -
+/// callers must free each with `GroupRow.deinit`, then the slice itself
+/// (see `freeAggGroupRows`).
+pub fn decodeAggGroupRows(allocator: Allocator, payload: []const u8) ![]aggregatemod.GroupRow {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(aggregatemod.GroupRow).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |*g| g.deinit(allocator);
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const group = try takeDecodedValue(allocator, &c);
+        // Armed for the rest of THIS iteration's block only - Zig disarms an
+        // errdefer once the block it was declared in exits normally, and
+        // `appendAssumeCapacity` below is that block's last statement, so a
+        // later iteration's failure can never reach back and double-free an
+        // already-appended `group` (the exact class of bug `aggregate.zig`'s
+        // `GroupBy.observe` hit and fixed - see its comment for the details).
+        errdefer group.free(allocator);
+        const valueCount = try c.takeU32();
+        var values = try allocator.alloc(rowmod.Value, valueCount);
+        errdefer allocator.free(values);
+        var filled: u32 = 0;
+        errdefer for (values[0..filled]) |v| v.free(allocator);
+        var j: u32 = 0;
+        while (j < valueCount) : (j += 1) {
+            values[j] = try takeDecodedValue(allocator, &c);
+            filled += 1;
+        }
+        list.appendAssumeCapacity(.{ .group = group, .values = values });
+    }
+    return list.toOwnedSlice();
+}
+
+pub fn freeAggGroupRows(allocator: Allocator, groups: []aggregatemod.GroupRow) void {
+    for (groups) |*g| g.deinit(allocator);
+    allocator.free(groups);
+}
+
+// --- table window ---
+
+/// Wire request for a remote `table window`: a table name, the LIST of
+/// `window.zig` `WindowSpec`s to compute (one or more columns sharing the
+/// same `PARTITION BY`/`ORDER BY`/`frame` - `window.computeMany`'s shape,
+/// mirroring `table_aggregate`'s `specs` list), the `PARTITION BY`/`ORDER
+/// BY` field lists (either possibly empty, same "no partition"/"no order"
+/// meaning as local `table window`'s `partitionBy`/`orderBy`), `offset`/
+/// `limit` windowing the PRINTED rows in the same partition-then-order walk
+/// `window.orderedIndices` produces (not raw scan order, not `computeMany`'s
+/// per-row results, which stay aligned 1:1 with every matching row
+/// regardless of paging - see `handleTableWindow`'s doc), and an `expr.zig`
+/// predicate text filtering rows BEFORE annotation (same
+/// empty-means-every-row convention every other `table_*` opcode's
+/// `exprText` already uses). `orderBy` reuses `querymod.OrderBy`'s wire
+/// shape (descending byte + length-prefixed field name) exactly like
+/// `encodeTableAggregate`'s. `specs` is a byte count followed by
+/// `(kind byte, length-prefixed field)` pairs, same shape `partitionBy`
+/// already uses for its own count-prefixed field list. `frame` is a single
+/// byte (`@intFromEnum(windowmod.FrameMode)`) written right before
+/// `exprText` - after every other fixed-size field but before the
+/// unbounded, unprefixed trailing text, same placement
+/// `encodeTableAggregate`'s `havingText` uses relative to ITS trailing
+/// `exprText`.
+/// Writes a `WindowSpec`'s `offset`/`default` fields, shared by `lag`/`lead`
+/// (offset = rows back/forward from the current row) and `nth_value`
+/// (offset = 1-based position within the frame) - both pairs share the same
+/// wire shape, so one writer covers all three `WindowKind`s. `default` uses
+/// the tag+payload shape `row.zig`'s `encodeValue` does, but written
+/// directly (not through `putEncodedValue`, which allocates a throwaway
+/// buffer via `rowmod.encodeValue` only to copy it right back out) since a
+/// `WindowSpec.default` is always a small scalar or short borrowed string,
+/// never worth a heap round trip.
+fn putLagLeadExtra(w: encode.ByteWriter, offset: u64, default: rowmod.Value) !void {
+    try w.putU64(offset);
+    try w.byte(@intFromEnum(@as(rowmod.ValueTag, default)));
+    switch (default) {
+        .none => {},
+        .boolean => |v| try w.byte(if (v) 1 else 0),
+        .int => |v| try w.putU64(@bitCast(v)),
+        .float => |v| try w.putU64(@bitCast(v)),
+        .text, .bytes => |s| try putLenPrefixed(w, s),
+    }
+}
+
+/// Reads back what `putLagLeadExtra` wrote. `.text`/`.bytes` are returned as
+/// slices BORROWED from `c`'s backing payload (never allocated) - the same
+/// convention `WindowSpec.field`/`TableWindowArgs.partitionBy` already use,
+/// safe because the payload buffer outlives the whole request handler.
+fn takeLagLeadExtra(c: *Cursor) !struct { offset: u64, default: rowmod.Value } {
+    const offset = try c.takeU64();
+    const tagByte = try c.takeByte();
+    const tag = std.meta.intToEnum(rowmod.ValueTag, tagByte) catch return error.Malformed;
+    const default: rowmod.Value = switch (tag) {
+        .none => .{ .none = {} },
+        .boolean => .{ .boolean = (try c.takeByte()) != 0 },
+        .int => .{ .int = @bitCast(try c.takeU64()) },
+        .float => .{ .float = @bitCast(try c.takeU64()) },
+        .text => .{ .text = try c.takeLenPrefixed() },
+        .bytes => .{ .bytes = try c.takeLenPrefixed() },
+    };
+    return .{ .offset = offset, .default = default };
+}
+
+pub fn encodeTableWindow(allocator: Allocator, table: []const u8, specs: []const windowmod.WindowSpec, partitionBy: []const []const u8, orderBy: []const querymod.OrderBy, offset: u32, limit: u32, exprText: []const u8, frame: windowmod.FrameMode) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+    try w.byte(@intCast(specs.len));
+    for (specs) |spec| {
+        try w.byte(@intFromEnum(spec.kind));
+        try putLenPrefixed(w, spec.field);
+        if (spec.kind == .lag or spec.kind == .lead or spec.kind == .nth_value) try putLagLeadExtra(w, spec.offset, spec.default);
+    }
+    try w.byte(@intCast(partitionBy.len));
+    for (partitionBy) |field| try putLenPrefixed(w, field);
+    try w.byte(@intCast(orderBy.len));
+    for (orderBy) |ob| {
+        try w.byte(if (ob.descending) 1 else 0);
+        try putLenPrefixed(w, ob.field);
+    }
+    try w.putU32(offset);
+    try w.putU32(limit);
+    try w.byte(@intFromEnum(frame));
+    try w.slice(exprText);
+    return buf.toOwnedSlice();
+}
+
+pub const TableWindowArgs = struct {
+    table: []const u8,
+    /// Borrows field-name slices from the decoded payload but owns the
+    /// slice itself, same convention as `partitionBy`/`orderBy` below.
+    /// Always non-empty for a well-formed request (`decodeTableWindow`
+    /// itself does not enforce this - `handleTableWindow` rejects an empty
+    /// list as `bad_request`, same as `table_aggregate`'s empty-specs
+    /// check).
+    specs: []const windowmod.WindowSpec = &.{},
+    /// Borrows field-name slices from the decoded payload but owns the
+    /// slice itself, same convention as `TableAggregateArgs.orderBy`. Empty
+    /// means "one implicit partition" (the whole result set), same as local
+    /// `table window`'s default.
+    partitionBy: []const []const u8 = &.{},
+    orderBy: []const querymod.OrderBy = &.{},
+    offset: u32 = 0,
+    limit: u32 = 0,
+    frame: windowmod.FrameMode = .rows,
+    exprText: []const u8,
+};
+
+pub fn decodeTableWindow(allocator: Allocator, payload: []const u8) !TableWindowArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const specCount = try c.takeByte();
+    var specs = try std.ArrayList(windowmod.WindowSpec).initCapacity(allocator, specCount);
+    errdefer specs.deinit();
+    var s: u8 = 0;
+    while (s < specCount) : (s += 1) {
+        const kindByte = try c.takeByte();
+        const kind = std.meta.intToEnum(windowmod.WindowKind, kindByte) catch return error.Malformed;
+        const field = try c.takeLenPrefixed();
+        if (kind == .lag or kind == .lead or kind == .nth_value) {
+            const extra = try takeLagLeadExtra(&c);
+            specs.appendAssumeCapacity(.{ .kind = kind, .field = field, .offset = extra.offset, .default = extra.default });
+        } else {
+            specs.appendAssumeCapacity(.{ .kind = kind, .field = field });
+        }
+    }
+    const partitionCount = try c.takeByte();
+    var partitionBy = try std.ArrayList([]const u8).initCapacity(allocator, partitionCount);
+    errdefer partitionBy.deinit();
+    var i: u8 = 0;
+    while (i < partitionCount) : (i += 1) partitionBy.appendAssumeCapacity(try c.takeLenPrefixed());
+    const orderCount = try c.takeByte();
+    var orderBy = try std.ArrayList(querymod.OrderBy).initCapacity(allocator, orderCount);
+    errdefer orderBy.deinit();
+    var j: u8 = 0;
+    while (j < orderCount) : (j += 1) {
+        const descending = try c.takeByte();
+        const obField = try c.takeLenPrefixed();
+        orderBy.appendAssumeCapacity(.{ .field = obField, .descending = descending != 0 });
+    }
+    const offset = try c.takeU32();
+    const limit = try c.takeU32();
+    const frameByte = try c.takeByte();
+    const frame = std.meta.intToEnum(windowmod.FrameMode, frameByte) catch return error.Malformed;
+    const exprText = c.data[c.pos..];
+    return .{
+        .table = table,
+        .specs = try specs.toOwnedSlice(),
+        .partitionBy = try partitionBy.toOwnedSlice(),
+        .orderBy = try orderBy.toOwnedSlice(),
+        .offset = offset,
+        .limit = limit,
+        .frame = frame,
+        .exprText = exprText,
+    };
+}
+
+/// One annotated row from a `table_window` result: the original row
+/// (unmodified, same fields the request matched) paired with one computed
+/// window value PER requested spec, in the same order as the request's
+/// `specs` list - the network shape of what local `table window` prints per
+/// row (`printRow` fields, then `<label>=<value>` per spec). Already in the
+/// server-paginated partition-then-order display order (see
+/// `handleTableWindow`), so the client prints these in order with no
+/// further sorting.
+pub const WindowRow = struct { row: rowmod.Row, values: []rowmod.Value };
+
+pub fn encodeWindowRows(allocator: Allocator, rows: []const WindowRow) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(rows.len));
+    for (rows) |wr| {
+        const encoded = try wr.row.encode(allocator);
+        defer allocator.free(encoded);
+        try putLenPrefixed(w, encoded);
+        try w.putU32(@intCast(wr.values.len));
+        for (wr.values) |v| try putEncodedValue(allocator, w, v);
+    }
+    return buf.toOwnedSlice();
+}
+
+/// Decodes a `table_window` result into independently owned `WindowRow`s -
+/// callers must free each (`.row.deinit()`, each `.values[i].free(allocator)`
+/// then `allocator.free(.values)`), then the slice itself (see
+/// `freeWindowRows`).
+pub fn decodeWindowRows(allocator: Allocator, payload: []const u8) ![]WindowRow {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList(WindowRow).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |*wr| {
+            wr.row.deinit();
+            for (wr.values) |v| v.free(allocator);
+            allocator.free(wr.values);
+        }
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const raw = try c.takeLenPrefixed();
+        var row = rowmod.Row.decode(allocator, raw) catch return error.Malformed;
+        errdefer row.deinit();
+        const valueCount = try c.takeU32();
+        var values = try allocator.alloc(rowmod.Value, valueCount);
+        errdefer allocator.free(values);
+        var filled: u32 = 0;
+        errdefer for (values[0..filled]) |v| v.free(allocator);
+        var j: u32 = 0;
+        while (j < valueCount) : (j += 1) {
+            values[j] = try takeDecodedValue(allocator, &c);
+            filled += 1;
+        }
+        list.appendAssumeCapacity(.{ .row = row, .values = values });
+    }
+    return list.toOwnedSlice();
+}
+
+pub fn freeWindowRows(allocator: Allocator, rows: []WindowRow) void {
+    for (rows) |*wr| {
+        wr.row.deinit();
+        for (wr.values) |v| v.free(allocator);
+        allocator.free(wr.values);
+    }
+    allocator.free(rows);
+}
+
+// --- pubsub ---
+
+/// Wire request for `subscribe`: the list of channel names to listen on (at
+/// least one - `server.zig`'s `handleSubscribe` rejects an empty list as
+/// malformed rather than opening a subscription that can never receive
+/// anything). Unlike every other opcode in this file, a `subscribe` request
+/// does not get a single reply frame back: after the initial acknowledgment
+/// (see `encodeSubscribeAck`), the connection becomes a one-way stream of
+/// `encodePubSubMessage` frames until it closes - see `pubsub.zig`'s doc
+/// comment on `Hub` and `server.zig`'s `handleSubscribe`.
+pub fn encodeSubscribe(allocator: Allocator, channels: []const []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(@intCast(channels.len));
+    for (channels) |c| try putLenPrefixed(w, c);
+    return buf.toOwnedSlice();
+}
+
+pub const SubscribeArgs = struct {
+    channels: [][]u8,
+
+    pub fn deinit(self: SubscribeArgs, allocator: Allocator) void {
+        for (self.channels) |c| allocator.free(c);
+        allocator.free(self.channels);
+    }
+};
+
+/// Decodes a `subscribe` request into independently owned channel-name
+/// copies - free with `SubscribeArgs.deinit`. Owned (rather than borrowed
+/// slices into `payload`, as most other decoders here return) because
+/// `handleSubscribe` hands these straight to `pubsub.Hub.subscribe`, which
+/// keeps its own copies anyway - decoding once into memory that outlives
+/// the request frame avoids a second, redundant copy inside the hub for
+/// every subscribe call.
+pub fn decodeSubscribe(allocator: Allocator, payload: []const u8) !SubscribeArgs {
+    var c = Cursor{ .data = payload };
+    const count = try c.takeU32();
+    var list = try std.ArrayList([]u8).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |ch| allocator.free(ch);
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const name = try c.takeLenPrefixed();
+        const owned = try allocator.dupe(u8, name);
+        list.appendAssumeCapacity(owned);
+    }
+    return .{ .channels = try list.toOwnedSlice() };
+}
+
+/// A `subscribe` request's one and only reply frame (status `.ok`, this as
+/// its payload) - sent once the connection is actually registered in the
+/// `pubsub.Hub`, so a client that has received this ack is guaranteed not
+/// to miss a message published right after it returns. Carries the
+/// (deduplicated) channel count purely as a sanity-checkable echo, the same
+/// spirit as `encodeAuthOk` echoing a token back - plus the `pubsub.Hub`-
+/// assigned subscriber id, the only way a later `unsubscribe` request (on a
+/// SEPARATE connection - this one is receive-only from here on, see
+/// `server.zig`'s `handleSubscribe`) can ever name this subscription again.
+pub fn encodeSubscribeAck(allocator: Allocator, subscriberId: u64, channelCount: u32) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU64(subscriberId);
+    try w.putU32(channelCount);
+    return buf.toOwnedSlice();
+}
+
+pub const SubscribeAck = struct { subscriberId: u64, channelCount: u32 };
+
+pub fn decodeSubscribeAck(payload: []const u8) !SubscribeAck {
+    var c = Cursor{ .data = payload };
+    const subscriberId = try c.takeU64();
+    const channelCount = try c.takeU32();
+    return .{ .subscriberId = subscriberId, .channelCount = channelCount };
+}
+
+/// Wire request for `publish`: a channel name and the message bytes (binary
+/// safe, "rest of the payload" like `encodeSet`'s value). Any connection
+/// may publish regardless of whether it has ever subscribed to anything -
+/// publishing and subscribing are independent roles on the same opcode
+/// family, exactly like a `Db` writer and a `Db` reader are independent
+/// roles over the same store.
+pub fn encodePublish(allocator: Allocator, channel: []const u8, message: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, channel);
+    try w.slice(message);
+    return buf.toOwnedSlice();
+}
+
+pub const PublishArgs = struct { channel: []const u8, message: []const u8 };
+
+pub fn decodePublish(payload: []const u8) !PublishArgs {
+    var c = Cursor{ .data = payload };
+    const channel = try c.takeLenPrefixed();
+    const message = c.data[c.pos..];
+    return .{ .channel = channel, .message = message };
+}
+
+/// A `publish` request's reply payload: how many subscribers `pubsub.Hub`
+/// handed the message to (see `Hub.publish`'s doc comment - 0 is a normal,
+/// non-error outcome for a channel nobody is listening to).
+pub fn encodePublishResult(allocator: Allocator, subscriberCount: u64) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU64(subscriberCount);
+    return buf.toOwnedSlice();
+}
+
+pub fn decodePublishResult(payload: []const u8) !u64 {
+    var c = Cursor{ .data = payload };
+    return c.takeU64();
+}
+
+/// Wire request for `unsubscribe`: the `pubsub.Hub`-assigned subscriber id
+/// (from `encodeSubscribeAck`) plus the list of channel names to drop from
+/// that subscription - the same channel-list shape `encodeSubscribe` uses,
+/// with the id prefixed. Unlike `subscribe`, this is an ordinary
+/// request/response opcode (see `server.zig`'s `handleUnsubscribe`): it is
+/// always sent on a DIFFERENT connection than the one that subscribed,
+/// since that connection became receive-only the moment its subscribe ack
+/// arrived and can never send another request on itself again.
+pub fn encodeUnsubscribe(allocator: Allocator, subscriberId: u64, channels: []const []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU64(subscriberId);
+    try w.putU32(@intCast(channels.len));
+    for (channels) |c| try putLenPrefixed(w, c);
+    return buf.toOwnedSlice();
+}
+
+pub const UnsubscribeArgs = struct {
+    subscriberId: u64,
+    channels: [][]u8,
+
+    pub fn deinit(self: UnsubscribeArgs, allocator: Allocator) void {
+        for (self.channels) |c| allocator.free(c);
+        allocator.free(self.channels);
+    }
+};
+
+/// Decodes an `unsubscribe` request - same owned-copy rationale as
+/// `decodeSubscribe`: `handleUnsubscribe` hands the channel names straight
+/// to `pubsub.Hub.unsubscribe`, which only ever borrows them for the
+/// duration of that call, so decoding into memory this function's caller
+/// frees (via `UnsubscribeArgs.deinit`) avoids a redundant second copy.
+pub fn decodeUnsubscribe(allocator: Allocator, payload: []const u8) !UnsubscribeArgs {
+    var c = Cursor{ .data = payload };
+    const subscriberId = try c.takeU64();
+    const count = try c.takeU32();
+    var list = try std.ArrayList([]u8).initCapacity(allocator, count);
+    errdefer {
+        for (list.items) |ch| allocator.free(ch);
+        list.deinit();
+    }
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        const name = try c.takeLenPrefixed();
+        const owned = try allocator.dupe(u8, name);
+        list.appendAssumeCapacity(owned);
+    }
+    return .{ .subscriberId = subscriberId, .channels = try list.toOwnedSlice() };
+}
+
+/// An `unsubscribe` request's reply payload: how many of the requested
+/// channel names were actually removed from the named subscriber's set (see
+/// `pubsub.Hub.unsubscribe`'s doc comment on why naming a channel it was
+/// never on is a harmless no-op that simply does not count here, not an
+/// error).
+pub fn encodeUnsubscribeResult(allocator: Allocator, removedCount: u32) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(removedCount);
+    return buf.toOwnedSlice();
+}
+
+pub fn decodeUnsubscribeResult(payload: []const u8) !u32 {
+    var c = Cursor{ .data = payload };
+    return c.takeU32();
+}
+
+/// One pushed message on an already-open `subscribe` connection: which
+/// channel it arrived on (a client can subscribe to several at once, so the
+/// tag travels with every message) plus the payload bytes. Every frame a
+/// subscribed connection receives after its initial ack uses this shape,
+/// always with status `.ok` - there is no separate framing marker, because
+/// once a client has sent `subscribe` it never sends another request on
+/// that connection and so never has to disambiguate a push from a reply to
+/// something else it asked (see `server.zig`'s `handleSubscribe`).
+pub const PubSubMessage = struct {
+    channel: []u8,
+    payload: []u8,
+
+    pub fn deinit(self: PubSubMessage, allocator: Allocator) void {
+        allocator.free(self.channel);
+        allocator.free(self.payload);
+    }
+};
+
+pub fn encodePubSubMessage(allocator: Allocator, channel: []const u8, payload: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, channel);
+    try w.slice(payload);
+    return buf.toOwnedSlice();
+}
+
+/// Decodes a pushed message into independently owned copies (the frame
+/// they arrived in is freed right after decoding, in `Client.nextMessage` -
+/// see its doc comment) - free with `PubSubMessage.deinit`.
+pub fn decodePubSubMessage(allocator: Allocator, payload: []const u8) !PubSubMessage {
+    var c = Cursor{ .data = payload };
+    const channel = try c.takeLenPrefixed();
+    const message = c.data[c.pos..];
+    const channelCopy = try allocator.dupe(u8, channel);
+    errdefer allocator.free(channelCopy);
+    const payloadCopy = try allocator.dupe(u8, message);
+    return .{ .channel = channelCopy, .payload = payloadCopy };
+}
+
+// --- table explain ---
+
+/// Wire request for a remote `table explain`: a table name and the raw text
+/// of an `expr.zig` predicate expression (empty text means "no predicate",
+/// the same convention `encodeTableSelect`'s `exprText` uses). No
+/// offset/limit - explain reports a plan, not rows, so there is nothing to
+/// page.
+pub fn encodeTableExplain(allocator: Allocator, table: []const u8, exprText: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+    try w.slice(exprText);
+    return buf.toOwnedSlice();
+}
+
+pub const TableExplainArgs = struct { table: []const u8, exprText: []const u8 };
+
+pub fn decodeTableExplain(payload: []const u8) !TableExplainArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const exprText = c.data[c.pos..];
+    return .{ .table = table, .exprText = exprText };
+}
+
+/// Encodes a `query.Plan`. `indexName` uses the empty string as its "null"
+/// sentinel (an index or field name can never itself be empty - `query.zig`
+/// rejects that at `createIndex`/`createCompositeIndex` time) instead of a
+/// separate presence byte, the same economy `exprText`'s "empty means no
+/// predicate" convention already relies on elsewhere in this file.
+pub fn encodePlan(allocator: Allocator, plan: querymod.Plan) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(@intFromEnum(plan.kind));
+    try putLenPrefixed(w, plan.indexName orelse "");
+    try w.putU32(@intCast(plan.matchedFields));
+    try w.putU32(@intCast(plan.totalFields));
+    return buf.toOwnedSlice();
+}
+
+/// Decodes a `query.Plan` - `indexName`, when present, is an owned copy the
+/// caller must free with `Plan.deinit` (see `encodePlan`'s doc comment for
+/// why an empty string decodes back to `null` instead of `""`).
+pub fn decodePlan(allocator: Allocator, payload: []const u8) !querymod.Plan {
+    var c = Cursor{ .data = payload };
+    const kindByte = try c.takeByte();
+    const kind = std.meta.intToEnum(querymod.PlanKind, kindByte) catch return error.Malformed;
+    const rawName = try c.takeLenPrefixed();
+    const indexName = if (rawName.len == 0) null else try allocator.dupe(u8, rawName);
+    errdefer if (indexName) |n| allocator.free(n);
+    const matchedFields = try c.takeU32();
+    const totalFields = try c.takeU32();
+    return .{ .kind = kind, .indexName = indexName, .matchedFields = matchedFields, .totalFields = totalFields };
+}
+
+// --- table update ---
+
+/// Wire request for a remote `table update`: a table name, the `SET`
+/// clause's field list, and the raw text of an `expr.zig` predicate
+/// expression (empty text updates every row, the same convention
+/// `encodeTableSelect`'s `exprText` uses). The field list reuses
+/// `Row.encode` exactly like `encodeTxnOp`'s per-entry `fields` does,
+/// instead of inventing a second name+value framing just for this opcode -
+/// and, like `encodeTableSelect`'s `orderBy`, sits BEFORE `exprText`
+/// because `exprText` is decoded as "everything left in the payload",
+/// so anything meant to survive decoding has to come first.
+pub fn encodeTableUpdate(allocator: Allocator, table: []const u8, sets: []const rowmod.Field, exprText: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+
+    var setsRow = rowmod.Row.init(allocator);
+    defer setsRow.deinit();
+    for (sets) |f| try setsRow.set(f.name, f.value);
+    const setsBytes = try setsRow.encode(allocator);
+    defer allocator.free(setsBytes);
+    try putLenPrefixed(w, setsBytes);
+
+    try w.slice(exprText);
+    return buf.toOwnedSlice();
+}
+
+pub const TableUpdateArgs = struct { table: []const u8, setsBytes: []const u8, exprText: []const u8 };
+
+/// `table` and `exprText` are borrowed slices into `payload`, the same
+/// convention `decodeTableExplain` uses. `setsBytes` is also borrowed and
+/// still needs `rowmod.Row.decode` to become a real field list - kept
+/// undecoded here so a malformed table name fails fast without touching
+/// row-decoding at all, the same ownership split `DecodedTxnOpEntry` uses
+/// for its own `fieldsBytes`.
+pub fn decodeTableUpdate(payload: []const u8) !TableUpdateArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const setsBytes = try c.takeLenPrefixed();
+    const exprText = c.data[c.pos..];
+    return .{ .table = table, .setsBytes = setsBytes, .exprText = exprText };
+}
+
+// --- table delete ---
+
+/// Wire request for a remote `table delete`: a table name and the raw text
+/// of an `expr.zig` predicate expression (empty text deletes every row, the
+/// same convention `encodeTableSelect`/`encodeTableExplain`'s `exprText`
+/// uses). Identical wire shape to `encodeTableExplain` - both are just
+/// "table + predicate", no `SET` clause like `encodeTableUpdate` needs - but
+/// kept as its own named pair rather than reused directly, the same
+/// per-opcode-gets-its-own-function precedent every other opcode here
+/// follows even when two shapes coincide.
+pub fn encodeTableDelete(allocator: Allocator, table: []const u8, exprText: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+    try w.slice(exprText);
+    return buf.toOwnedSlice();
+}
+
+pub const TableDeleteArgs = struct { table: []const u8, exprText: []const u8 };
+
+/// `table` and `exprText` are borrowed slices into `payload`, the same
+/// convention `decodeTableExplain`/`decodeTableUpdate` use.
+pub fn decodeTableDelete(payload: []const u8) !TableDeleteArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const exprText = c.data[c.pos..];
+    return .{ .table = table, .exprText = exprText };
+}
+
+// --- table export / table import ---
+
+/// Which interchange format a `table_export`/`table_import` request uses -
+/// the wire counterpart of the CLI's `csv`/`json` string argument (see
+/// `main.zig`'s local `table export`/`table import`), carried as one byte
+/// instead of a length-prefixed string since there are only ever two.
+pub const DumpFormat = enum(u8) {
+    csv = 0,
+    json = 1,
+};
+
+/// Wire request for a remote `table export`: a table name and which format
+/// (`dump.zig`'s `exportCsvWriter`/`exportJsonWriter`) to render it in. No
+/// predicate/paging - export always dumps the whole table, matching the
+/// local CLI's `table export <table> csv|json <path>`.
+pub fn encodeTableExport(allocator: Allocator, table: []const u8, format: DumpFormat) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+    try w.byte(@intFromEnum(format));
+    return buf.toOwnedSlice();
+}
+
+pub const TableExportArgs = struct { table: []const u8, format: DumpFormat };
+
+pub fn decodeTableExport(payload: []const u8) !TableExportArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const formatByte = try c.takeByte();
+    const format = std.meta.intToEnum(DumpFormat, formatByte) catch return error.Malformed;
+    return .{ .table = table, .format = format };
+}
+
+/// Wire response for `table_export`: the row count `dump.zig`'s exporter
+/// reported (so the CLI can print the same count the local `table export`
+/// prints) followed by the rendered content bytes verbatim - a "count then
+/// rest of the payload" shape, the same idea `exprText` fields elsewhere in
+/// this file use for their own trailing variable-length piece.
+pub fn encodeExportResult(allocator: Allocator, rowCount: u64, content: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU64(rowCount);
+    try w.slice(content);
+    return buf.toOwnedSlice();
+}
+
+pub const ExportResult = struct { rowCount: u64, content: []const u8 };
+
+/// `content` is a borrowed slice into `payload`, the same convention
+/// `decodeTableExplain`'s `exprText` uses - the caller decides whether to
+/// copy it (`client.zig`'s `tableExport` dupes it into an allocation the
+/// caller owns once the response frame itself is about to be freed).
+pub fn decodeExportResult(payload: []const u8) !ExportResult {
+    var c = Cursor{ .data = payload };
+    const rowCount = try c.takeU64();
+    const content = payload[c.pos..];
+    return .{ .rowCount = rowCount, .content = content };
+}
+
+/// Wire request for a remote `table import`: a table name, which format the
+/// following `content` bytes are encoded in, and the content itself.
+/// `content` comes last (decoded as "everything left in the payload", the
+/// same convention every `exprText` field in this file relies on) since it
+/// is arbitrary-length and, unlike `table`, needs no length prefix of its
+/// own.
+pub fn encodeTableImport(allocator: Allocator, table: []const u8, format: DumpFormat, content: []const u8) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, table);
+    try w.byte(@intFromEnum(format));
+    try w.slice(content);
+    return buf.toOwnedSlice();
+}
+
+pub const TableImportArgs = struct { table: []const u8, format: DumpFormat, content: []const u8 };
+
+/// `table` and `content` are borrowed slices into `payload`, the same
+/// convention every other decode function in this file uses.
+pub fn decodeTableImport(payload: []const u8) !TableImportArgs {
+    var c = Cursor{ .data = payload };
+    const table = try c.takeLenPrefixed();
+    const formatByte = try c.takeByte();
+    const format = std.meta.intToEnum(DumpFormat, formatByte) catch return error.Malformed;
+    const content = payload[c.pos..];
+    return .{ .table = table, .format = format, .content = content };
+}
+
+// --- stats ---
+
+pub fn encodeStats(allocator: Allocator, stats: dbmod.Stats) ![]u8 {
+    var buf = std.ArrayList(u8).init(allocator);
+    errdefer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU64(@intCast(stats.memtableEntries));
+    try w.putU64(@intCast(stats.memtableBytes));
+    try w.putU64(@intCast(stats.sstableCount));
+    try w.putU64(stats.liveEntries);
+    try w.putU64(stats.physicalBytes);
+    try w.putU64(stats.cacheHits);
+    try w.putU64(stats.cacheMisses);
+    try w.putU64(stats.nextSeq);
+    for (stats.levels) |level| {
+        try w.putU64(@intCast(level.tables));
+        try w.putU64(level.entries);
+        try w.putU64(level.physicalBytes);
+    }
+    return buf.toOwnedSlice();
+}
+
+pub fn decodeStats(payload: []const u8) !dbmod.Stats {
+    var c = Cursor{ .data = payload };
+    var stats = dbmod.Stats{};
+    stats.memtableEntries = @intCast(try c.takeU64());
+    stats.memtableBytes = @intCast(try c.takeU64());
+    stats.sstableCount = @intCast(try c.takeU64());
+    stats.liveEntries = try c.takeU64();
+    stats.physicalBytes = try c.takeU64();
+    stats.cacheHits = try c.takeU64();
+    stats.cacheMisses = try c.takeU64();
+    stats.nextSeq = try c.takeU64();
+    var i: usize = 0;
+    while (i < stats.levels.len) : (i += 1) {
+        stats.levels[i] = .{
+            .tables = @intCast(try c.takeU64()),
+            .entries = try c.takeU64(),
+            .physicalBytes = try c.takeU64(),
+        };
+    }
+    return stats;
+}
+
+test "frame round trip through an in-memory buffer" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+
+    try writeFrame(buf.writer(), @intFromEnum(Op.get), "hello");
+    var stream = std.io.fixedBufferStream(buf.items);
+    var frame = try readFrame(allocator, stream.reader());
+    defer frame.deinit();
+
+    try std.testing.expectEqual(@intFromEnum(Op.get), frame.tag);
+    try std.testing.expectEqualStrings("hello", frame.payload);
+}
+
+test "frame with empty payload round trips" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+
+    try writeFrame(buf.writer(), @intFromEnum(Op.ping), "");
+    var stream = std.io.fixedBufferStream(buf.items);
+    var frame = try readFrame(allocator, stream.reader());
+    defer frame.deinit();
+
+    try std.testing.expectEqual(@as(usize, 0), frame.payload.len);
+}
+
+test "readFrame rejects a length prefix beyond the frame guard" {
+    const allocator = std.testing.allocator;
+    var header: [5]u8 = undefined;
+    header[0] = 0;
+    std.mem.writeInt(u32, header[1..5], maxFrameBytes + 1, encode.endian);
+    var stream = std.io.fixedBufferStream(&header);
+    try std.testing.expectError(error.FrameTooLarge, readFrame(allocator, stream.reader()));
+}
+
+test "readFrame rejects a truncated body" {
+    const allocator = std.testing.allocator;
+    var header: [5]u8 = undefined;
+    header[0] = 0;
+    std.mem.writeInt(u32, header[1..5], 10, encode.endian);
+    var stream = std.io.fixedBufferStream(&header);
+    try std.testing.expectError(error.EndOfStream, readFrame(allocator, stream.reader()));
+}
+
+test "Op.fromByte rejects unknown opcodes" {
+    try std.testing.expectError(error.UnknownOp, Op.fromByte(200));
+    try std.testing.expectEqual(Op.batch, try Op.fromByte(9));
+    try std.testing.expectEqual(Op.table_select, try Op.fromByte(10));
+    try std.testing.expectEqual(Op.auth, try Op.fromByte(11));
+    try std.testing.expectEqual(Op.user_admin, try Op.fromByte(12));
+    try std.testing.expectEqual(Op.auth_token, try Op.fromByte(13));
+    try std.testing.expectEqual(Op.metrics, try Op.fromByte(14));
+    try std.testing.expectEqual(Op.ttl_op, try Op.fromByte(15));
+    try std.testing.expectEqual(Op.coll_ttl_op, try Op.fromByte(16));
+    try std.testing.expectEqual(Op.coll_op, try Op.fromByte(17));
+    try std.testing.expectEqual(Op.txn_op, try Op.fromByte(18));
+    try std.testing.expectEqual(Op.table_join, try Op.fromByte(19));
+    try std.testing.expectEqual(Op.table_aggregate, try Op.fromByte(20));
+    try std.testing.expectEqual(Op.table_explain, try Op.fromByte(21));
+    try std.testing.expectEqual(Op.table_update, try Op.fromByte(22));
+    try std.testing.expectEqual(Op.table_delete, try Op.fromByte(23));
+    try std.testing.expectEqual(Op.table_export, try Op.fromByte(24));
+    try std.testing.expectEqual(Op.table_import, try Op.fromByte(25));
+    try std.testing.expectEqual(Op.table_window, try Op.fromByte(26));
+    try std.testing.expectEqual(Op.subscribe, try Op.fromByte(27));
+    try std.testing.expectEqual(Op.publish, try Op.fromByte(28));
+    try std.testing.expectEqual(Op.unsubscribe, try Op.fromByte(29));
+}
+
+test "Status.fromByte rejects unknown status codes" {
+    try std.testing.expectError(error.UnknownStatus, Status.fromByte(200));
+    try std.testing.expectEqual(Status.internal, try Status.fromByte(5));
+    try std.testing.expectEqual(Status.rate_limited, try Status.fromByte(6));
+    try std.testing.expectEqual(Status.unauthorized, try Status.fromByte(7));
+    try std.testing.expectEqual(Status.forbidden, try Status.fromByte(8));
+}
+
+test "auth payload encodes and decodes username and password" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeAuth(allocator, "alice", "hunter2");
+    defer allocator.free(payload);
+    const args = try decodeAuth(payload);
+    try std.testing.expectEqualStrings("alice", args.username);
+    try std.testing.expectEqualStrings("hunter2", args.password);
+}
+
+test "auth payload handles an empty password" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeAuth(allocator, "alice", "");
+    defer allocator.free(payload);
+    const args = try decodeAuth(payload);
+    try std.testing.expectEqualStrings("alice", args.username);
+    try std.testing.expectEqualStrings("", args.password);
+}
+
+test "encodeAuthOk with no token round trips to an empty payload" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeAuthOk(allocator, null);
+    defer allocator.free(payload);
+    try std.testing.expectEqual(@as(usize, 0), payload.len);
+}
+
+test "encodeAuthOk with a token round trips exactly" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeAuthOk(allocator, "deadbeef");
+    defer allocator.free(payload);
+    try std.testing.expectEqualStrings("deadbeef", payload);
+}
+
+test "auth_token payload round trips the opaque token bytes" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeAuthToken(allocator, "abc123token");
+    defer allocator.free(payload);
+    try std.testing.expectEqualStrings("abc123token", decodeAuthToken(payload));
+}
+
+test "set payload encodes and decodes key and value" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeSet(allocator, "k", "value-bytes");
+    defer allocator.free(payload);
+    const args = try decodeSet(payload);
+    try std.testing.expectEqualStrings("k", args.key);
+    try std.testing.expectEqualStrings("value-bytes", args.value);
+}
+
+test "set payload handles an empty value" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeSet(allocator, "k", "");
+    defer allocator.free(payload);
+    const args = try decodeSet(payload);
+    try std.testing.expectEqualStrings("k", args.key);
+    try std.testing.expectEqualStrings("", args.value);
+}
+
+test "scan args round trip with both bounds" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeScan(allocator, .{ .start = "a", .end = "z", .limit = 42, .reverse = true });
+    defer allocator.free(payload);
+    const args = try decodeScan(payload);
+    try std.testing.expectEqualStrings("a", args.start.?);
+    try std.testing.expectEqualStrings("z", args.end.?);
+    try std.testing.expectEqual(@as(u32, 42), args.limit);
+    try std.testing.expect(args.reverse);
+}
+
+test "scan args round trip with no bounds" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeScan(allocator, .{});
+    defer allocator.free(payload);
+    const args = try decodeScan(payload);
+    try std.testing.expect(args.start == null);
+    try std.testing.expect(args.end == null);
+    try std.testing.expect(!args.reverse);
+}
+
+test "prefix args round trip" {
+    const allocator = std.testing.allocator;
+    const payload = try encodePrefix(allocator, "user:", 7);
+    defer allocator.free(payload);
+    const args = try decodePrefix(payload);
+    try std.testing.expectEqualStrings("user:", args.prefix);
+    try std.testing.expectEqual(@as(u32, 7), args.limit);
+}
+
+test "entries round trip and are independently owned" {
+    const allocator = std.testing.allocator;
+    const entries = [_]dbmod.Entry{
+        .{ .key = "a", .value = "1" },
+        .{ .key = "b", .value = "2" },
+    };
+    const payload = try encodeEntries(allocator, &entries);
+    defer allocator.free(payload);
+
+    const owned = try decodeEntries(allocator, payload);
+    defer freeOwnedEntries(allocator, owned);
+
+    try std.testing.expectEqual(@as(usize, 2), owned.len);
+    try std.testing.expectEqualStrings("a", owned[0].key);
+    try std.testing.expectEqualStrings("1", owned[0].value);
+    try std.testing.expectEqualStrings("b", owned[1].key);
+    try std.testing.expectEqualStrings("2", owned[1].value);
+}
+
+test "empty entry list round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeEntries(allocator, &[_]dbmod.Entry{});
+    defer allocator.free(payload);
+    const owned = try decodeEntries(allocator, payload);
+    defer freeOwnedEntries(allocator, owned);
+    try std.testing.expectEqual(@as(usize, 0), owned.len);
+}
+
+test "batch ops round trip put and delete" {
+    const allocator = std.testing.allocator;
+    const ops = [_]BatchOp{
+        .{ .put = .{ .key = "a", .value = "1" } },
+        .{ .del = "b" },
+    };
+    const payload = try encodeBatch(allocator, &ops);
+    defer allocator.free(payload);
+
+    const decoded = try decodeBatch(allocator, payload);
+    defer allocator.free(decoded);
+
+    try std.testing.expectEqual(@as(usize, 2), decoded.len);
+    try std.testing.expectEqualStrings("a", decoded[0].put.key);
+    try std.testing.expectEqualStrings("1", decoded[0].put.value);
+    try std.testing.expectEqualStrings("b", decoded[1].del);
+}
+
+test "decodeBatch rejects an unknown op kind" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(1);
+    try w.byte(9);
+    try std.testing.expectError(error.Malformed, decodeBatch(allocator, buf.items));
+}
+
+test "stats round trip preserves all fields including per-level detail" {
+    const allocator = std.testing.allocator;
+    var stats = dbmod.Stats{};
+    stats.memtableEntries = 3;
+    stats.memtableBytes = 128;
+    stats.sstableCount = 2;
+    stats.liveEntries = 100;
+    stats.physicalBytes = 4096;
+    stats.cacheHits = 10;
+    stats.cacheMisses = 4;
+    stats.nextSeq = 55;
+    stats.levels[0] = .{ .tables = 1, .entries = 50, .physicalBytes = 2048 };
+    stats.levels[3] = .{ .tables = 2, .entries = 50, .physicalBytes = 2048 };
+
+    const payload = try encodeStats(allocator, stats);
+    defer allocator.free(payload);
+    const decoded = try decodeStats(payload);
+
+    try std.testing.expectEqual(stats.memtableEntries, decoded.memtableEntries);
+    try std.testing.expectEqual(stats.nextSeq, decoded.nextSeq);
+    try std.testing.expectEqual(stats.levels[0].tables, decoded.levels[0].tables);
+    try std.testing.expectEqual(stats.levels[3].entries, decoded.levels[3].entries);
+    try std.testing.expectEqual(@as(f64, decoded.cacheHitRate()), decoded.cacheHitRate());
+}
+
+test "table select args round trip with a non-empty expr" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableSelect(allocator, "users", "city eq s:warsaw", 0, 0, &.{});
+    defer allocator.free(payload);
+    const args = try decodeTableSelect(allocator, payload);
+    defer allocator.free(args.orderBy);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("city eq s:warsaw", args.exprText);
+    try std.testing.expectEqual(@as(u32, 0), args.offset);
+    try std.testing.expectEqual(@as(u32, 0), args.limit);
+    try std.testing.expectEqual(@as(usize, 0), args.orderBy.len);
+}
+
+test "table select args round trip with an empty expr means select all" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableSelect(allocator, "users", "", 0, 0, &.{});
+    defer allocator.free(payload);
+    const args = try decodeTableSelect(allocator, payload);
+    defer allocator.free(args.orderBy);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("", args.exprText);
+}
+
+test "table select args round trip with a page window" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableSelect(allocator, "users", "age gt i:10", 5, 3, &.{});
+    defer allocator.free(payload);
+    const args = try decodeTableSelect(allocator, payload);
+    defer allocator.free(args.orderBy);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("age gt i:10", args.exprText);
+    try std.testing.expectEqual(@as(u32, 5), args.offset);
+    try std.testing.expectEqual(@as(u32, 3), args.limit);
+}
+
+test "table select args round trip with an ascending order-by" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableSelect(allocator, "users", "", 0, 0, &.{.{ .field = "age" }});
+    defer allocator.free(payload);
+    const args = try decodeTableSelect(allocator, payload);
+    defer allocator.free(args.orderBy);
+    try std.testing.expectEqual(@as(usize, 1), args.orderBy.len);
+    try std.testing.expectEqualStrings("age", args.orderBy[0].field);
+    try std.testing.expectEqual(false, args.orderBy[0].descending);
+}
+
+test "table select args round trip with a descending order-by, page, and expr all together" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableSelect(allocator, "users", "city eq s:warsaw", 2, 5, &.{.{ .field = "score", .descending = true }});
+    defer allocator.free(payload);
+    const args = try decodeTableSelect(allocator, payload);
+    defer allocator.free(args.orderBy);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("city eq s:warsaw", args.exprText);
+    try std.testing.expectEqual(@as(u32, 2), args.offset);
+    try std.testing.expectEqual(@as(u32, 5), args.limit);
+    try std.testing.expectEqualStrings("score", args.orderBy[0].field);
+    try std.testing.expectEqual(true, args.orderBy[0].descending);
+}
+
+test "table select args round trip with two order-by columns in given order" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableSelect(allocator, "users", "", 0, 0, &.{ .{ .field = "city" }, .{ .field = "score", .descending = true } });
+    defer allocator.free(payload);
+    const args = try decodeTableSelect(allocator, payload);
+    defer allocator.free(args.orderBy);
+    try std.testing.expectEqual(@as(usize, 2), args.orderBy.len);
+    try std.testing.expectEqualStrings("city", args.orderBy[0].field);
+    try std.testing.expectEqual(false, args.orderBy[0].descending);
+    try std.testing.expectEqualStrings("score", args.orderBy[1].field);
+    try std.testing.expectEqual(true, args.orderBy[1].descending);
+}
+
+test "decodeTableSelect rejects an order-by count claiming more columns than were actually encoded" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableSelect(allocator, "users", "", 0, 0, &.{.{ .field = "age" }});
+    defer allocator.free(payload);
+    // The count byte sits right after the two u32 page fields: 4 (table
+    // len prefix) + 5 ("users") + 4 (offset) + 4 (limit).
+    const countBytePos = 4 + 5 + 4 + 4;
+    try std.testing.expectEqual(@as(u8, 1), payload[countBytePos]);
+    var corrupted = try allocator.dupe(u8, payload);
+    defer allocator.free(corrupted);
+    corrupted[countBytePos] = 200;
+    try std.testing.expectError(error.Malformed, decodeTableSelect(allocator, corrupted));
+}
+
+test "rows round trip through encode and decode" {
+    const allocator = std.testing.allocator;
+    var rows = [_]rowmod.Row{ rowmod.Row.init(allocator), rowmod.Row.init(allocator) };
+    defer for (&rows) |*r| r.deinit();
+    try rows[0].set("name", .{ .text = "ada" });
+    try rows[0].set("age", .{ .int = 36 });
+    try rows[1].set("name", .{ .text = "bob" });
+    try rows[1].set("age", .{ .int = 24 });
+
+    const payload = try encodeRows(allocator, &rows);
+    defer allocator.free(payload);
+
+    const decoded = try decodeRows(allocator, payload);
+    defer freeRows(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 2), decoded.len);
+    try std.testing.expectEqualStrings("ada", decoded[0].get("name").?.text);
+    try std.testing.expectEqual(@as(i64, 36), decoded[0].get("age").?.int);
+    try std.testing.expectEqualStrings("bob", decoded[1].get("name").?.text);
+    try std.testing.expectEqual(@as(i64, 24), decoded[1].get("age").?.int);
+}
+
+test "empty row list round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeRows(allocator, &[_]rowmod.Row{});
+    defer allocator.free(payload);
+    const decoded = try decodeRows(allocator, payload);
+    defer freeRows(allocator, decoded);
+    try std.testing.expectEqual(@as(usize, 0), decoded.len);
+}
+
+test "JoinMode.fromByte rejects an unknown mode" {
+    try std.testing.expectError(error.UnknownJoinMode, JoinMode.fromByte(9));
+}
+
+test "table_join args round trip mode, tables, fields, and both expr texts" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableJoin(allocator, .left, "customers", "__pk", "orders", "customer_id", 0, 0, "age gt i:10", "total gt i:0");
+    defer allocator.free(payload);
+    const args = try decodeTableJoin(payload);
+    try std.testing.expectEqual(JoinMode.left, args.mode);
+    try std.testing.expectEqualStrings("customers", args.leftTable);
+    try std.testing.expectEqualStrings("__pk", args.leftField);
+    try std.testing.expectEqualStrings("orders", args.rightTable);
+    try std.testing.expectEqualStrings("customer_id", args.rightField);
+    try std.testing.expectEqual(@as(u32, 0), args.offset);
+    try std.testing.expectEqual(@as(u32, 0), args.limit);
+    try std.testing.expectEqualStrings("age gt i:10", args.leftExprText);
+    try std.testing.expectEqualStrings("total gt i:0", args.rightExprText);
+}
+
+test "table_join args round trip with both expr texts empty" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableJoin(allocator, .inner, "a", "x", "b", "y", 0, 0, "", "");
+    defer allocator.free(payload);
+    const args = try decodeTableJoin(payload);
+    try std.testing.expectEqual(JoinMode.inner, args.mode);
+    try std.testing.expectEqualStrings("", args.leftExprText);
+    try std.testing.expectEqualStrings("", args.rightExprText);
+}
+
+test "table_join args round trip a nonzero offset and limit" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableJoin(allocator, .full, "a", "x", "b", "y", 3, 7, "", "");
+    defer allocator.free(payload);
+    const args = try decodeTableJoin(payload);
+    try std.testing.expectEqual(@as(u32, 3), args.offset);
+    try std.testing.expectEqual(@as(u32, 7), args.limit);
+}
+
+test "join pairs round trip a fully matched pair (inner-join shape)" {
+    const allocator = std.testing.allocator;
+    var left = rowmod.Row.init(allocator);
+    defer left.deinit();
+    try left.set("name", .{ .text = "ada" });
+    var right = rowmod.Row.init(allocator);
+    defer right.deinit();
+    try right.set("total", .{ .int = 42 });
+
+    const pairs = [_]JoinPair{.{ .left = left, .right = right }};
+    const payload = try encodeJoinedRows(allocator, &pairs);
+    defer allocator.free(payload);
+
+    const decoded = try decodeJoinedRows(allocator, payload);
+    defer freeJoinPairs(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 1), decoded.len);
+    try std.testing.expectEqualStrings("ada", decoded[0].left.?.get("name").?.text);
+    try std.testing.expectEqual(@as(i64, 42), decoded[0].right.?.get("total").?.int);
+}
+
+test "join pairs round trip a nil left side and a nil right side" {
+    const allocator = std.testing.allocator;
+    var right = rowmod.Row.init(allocator);
+    defer right.deinit();
+    try right.set("total", .{ .int = 7 });
+    var left = rowmod.Row.init(allocator);
+    defer left.deinit();
+    try left.set("name", .{ .text = "carol" });
+
+    const pairs = [_]JoinPair{
+        .{ .left = null, .right = right },
+        .{ .left = left, .right = null },
+    };
+    const payload = try encodeJoinedRows(allocator, &pairs);
+    defer allocator.free(payload);
+
+    const decoded = try decodeJoinedRows(allocator, payload);
+    defer freeJoinPairs(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 2), decoded.len);
+    try std.testing.expect(decoded[0].left == null);
+    try std.testing.expectEqual(@as(i64, 7), decoded[0].right.?.get("total").?.int);
+    try std.testing.expectEqualStrings("carol", decoded[1].left.?.get("name").?.text);
+    try std.testing.expect(decoded[1].right == null);
+}
+
+test "empty join pair list round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeJoinedRows(allocator, &[_]JoinPair{});
+    defer allocator.free(payload);
+    const decoded = try decodeJoinedRows(allocator, payload);
+    defer freeJoinPairs(allocator, decoded);
+    try std.testing.expectEqual(@as(usize, 0), decoded.len);
+}
+
+test "table_aggregate args round trip a groupField, several specs, and an expr" {
+    const allocator = std.testing.allocator;
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+        .{ .field = "total", .kind = .max },
+        .{ .field = "city", .kind = .count_distinct },
+    };
+    const payload = try encodeTableAggregate(allocator, "orders", "city", &specs, 0, 0, &.{}, "", "total gt i:10");
+    defer allocator.free(payload);
+    const args = try decodeTableAggregate(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqualStrings("orders", args.table);
+    try std.testing.expectEqualStrings("city", args.groupField);
+    try std.testing.expectEqual(@as(u32, 0), args.offset);
+    try std.testing.expectEqual(@as(u32, 0), args.limit);
+    try std.testing.expectEqualStrings("", args.havingText);
+    try std.testing.expectEqualStrings("total gt i:10", args.exprText);
+    try std.testing.expectEqual(@as(usize, 4), args.specs.len);
+    try std.testing.expectEqual(aggregatemod.AggKind.count, args.specs[0].kind);
+    try std.testing.expectEqualStrings("", args.specs[0].field);
+    try std.testing.expectEqual(aggregatemod.AggKind.sum, args.specs[1].kind);
+    try std.testing.expectEqualStrings("total", args.specs[1].field);
+    try std.testing.expectEqual(aggregatemod.AggKind.max, args.specs[2].kind);
+    try std.testing.expectEqual(aggregatemod.AggKind.count_distinct, args.specs[3].kind);
+    try std.testing.expectEqualStrings("city", args.specs[3].field);
+}
+
+test "table_aggregate args round trip an empty groupField (global, no grouping) and empty expr" {
+    const allocator = std.testing.allocator;
+    const specs = [_]aggregatemod.AggSpec{.{ .field = "", .kind = .count }};
+    const payload = try encodeTableAggregate(allocator, "orders", "", &specs, 0, 0, &.{}, "", "");
+    defer allocator.free(payload);
+    const args = try decodeTableAggregate(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqualStrings("", args.groupField);
+    try std.testing.expectEqualStrings("", args.exprText);
+    try std.testing.expectEqual(@as(usize, 1), args.specs.len);
+}
+
+test "table_aggregate args round trip a nonzero offset and limit" {
+    const allocator = std.testing.allocator;
+    const specs = [_]aggregatemod.AggSpec{.{ .field = "", .kind = .count }};
+    const payload = try encodeTableAggregate(allocator, "orders", "city", &specs, 2, 5, &.{}, "", "");
+    defer allocator.free(payload);
+    const args = try decodeTableAggregate(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(u32, 2), args.offset);
+    try std.testing.expectEqual(@as(u32, 5), args.limit);
+}
+
+test "table_aggregate args round trip a non-empty havingText alongside a non-empty exprText" {
+    const allocator = std.testing.allocator;
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+    };
+    const payload = try encodeTableAggregate(allocator, "orders", "city", &specs, 0, 0, &.{}, "sum_total gt i:1000", "total gt i:10");
+    defer allocator.free(payload);
+    const args = try decodeTableAggregate(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqualStrings("sum_total gt i:1000", args.havingText);
+    try std.testing.expectEqualStrings("total gt i:10", args.exprText);
+}
+
+test "table_aggregate args round trip a multi-column orderBy alongside havingText and exprText" {
+    const allocator = std.testing.allocator;
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+    };
+    const orderBy = [_]querymod.OrderBy{
+        .{ .field = "sum_total", .descending = true },
+        .{ .field = "city" },
+    };
+    const payload = try encodeTableAggregate(allocator, "orders", "city", &specs, 0, 0, &orderBy, "sum_total gt i:100", "total gt i:10");
+    defer allocator.free(payload);
+    const args = try decodeTableAggregate(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 2), args.orderBy.len);
+    try std.testing.expectEqualStrings("sum_total", args.orderBy[0].field);
+    try std.testing.expect(args.orderBy[0].descending);
+    try std.testing.expectEqualStrings("city", args.orderBy[1].field);
+    try std.testing.expect(!args.orderBy[1].descending);
+    try std.testing.expectEqualStrings("sum_total gt i:100", args.havingText);
+    try std.testing.expectEqualStrings("total gt i:10", args.exprText);
+}
+
+test "table_aggregate args round trip an empty orderBy the same as before this feature existed" {
+    const allocator = std.testing.allocator;
+    const specs = [_]aggregatemod.AggSpec{.{ .field = "", .kind = .count }};
+    const payload = try encodeTableAggregate(allocator, "orders", "city", &specs, 0, 0, &.{}, "", "");
+    defer allocator.free(payload);
+    const args = try decodeTableAggregate(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 0), args.orderBy.len);
+}
+
+test "decodeTableAggregate rejects an unknown agg kind byte instead of corrupting a spec" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, "orders");
+    try putLenPrefixed(w, "city");
+    try w.putU32(1);
+    try w.byte(200); // not a valid AggKind tag
+    try putLenPrefixed(w, "total");
+
+    try std.testing.expectError(error.Malformed, decodeTableAggregate(allocator, buf.items));
+}
+
+test "agg global result round trips count/sum/max values, including a none from an empty avg" {
+    const allocator = std.testing.allocator;
+    const values = [_]rowmod.Value{
+        .{ .int = 4 },
+        .{ .float = 10.5 },
+        .{ .none = {} },
+        .{ .text = "warsaw" },
+    };
+    const payload = try encodeAggGlobalResult(allocator, &values);
+    defer allocator.free(payload);
+
+    const decoded = try decodeAggGlobalResult(allocator, payload);
+    defer freeAggValues(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 4), decoded.len);
+    try std.testing.expectEqual(@as(i64, 4), decoded[0].int);
+    try std.testing.expectApproxEqAbs(@as(f64, 10.5), decoded[1].float, 1e-9);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, decoded[2]));
+    try std.testing.expectEqualStrings("warsaw", decoded[3].text);
+}
+
+test "empty agg global result round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeAggGlobalResult(allocator, &[_]rowmod.Value{});
+    defer allocator.free(payload);
+    const decoded = try decodeAggGlobalResult(allocator, payload);
+    defer freeAggValues(allocator, decoded);
+    try std.testing.expectEqual(@as(usize, 0), decoded.len);
+}
+
+test "agg group rows round trip several groups with several values each" {
+    const allocator = std.testing.allocator;
+    const groups = [_]aggregatemod.GroupRow{
+        .{ .group = .{ .text = "warsaw" }, .values = @constCast(&[_]rowmod.Value{ .{ .int = 2 }, .{ .int = 350 } }) },
+        .{ .group = .{ .text = "krakow" }, .values = @constCast(&[_]rowmod.Value{ .{ .int = 1 }, .{ .int = 40 } }) },
+    };
+    const payload = try encodeAggGroupRows(allocator, &groups);
+    defer allocator.free(payload);
+
+    const decoded = try decodeAggGroupRows(allocator, payload);
+    defer freeAggGroupRows(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 2), decoded.len);
+    try std.testing.expectEqualStrings("warsaw", decoded[0].group.text);
+    try std.testing.expectEqual(@as(i64, 2), decoded[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, 350), decoded[0].values[1].int);
+    try std.testing.expectEqualStrings("krakow", decoded[1].group.text);
+    try std.testing.expectEqual(@as(i64, 40), decoded[1].values[1].int);
+}
+
+test "empty agg group rows list round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeAggGroupRows(allocator, &[_]aggregatemod.GroupRow{});
+    defer allocator.free(payload);
+    const decoded = try decodeAggGroupRows(allocator, payload);
+    defer freeAggGroupRows(allocator, decoded);
+    try std.testing.expectEqual(@as(usize, 0), decoded.len);
+}
+
+test "decodeAggGroupRows rejects a corrupted second group without leaking the first" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+
+    var goodGroup = rowmod.Row.init(allocator);
+    defer goodGroup.deinit();
+    // Use rowmod.encodeValue directly for a real, well-formed first group so
+    // the corruption below is unambiguously in the SECOND group only.
+    const goodGroupValue = try rowmod.encodeValue(allocator, .{ .text = "warsaw" });
+    defer allocator.free(goodGroupValue);
+    const goodMemberValue = try rowmod.encodeValue(allocator, .{ .int = 1 });
+    defer allocator.free(goodMemberValue);
+
+    try w.putU32(2); // claims two groups, only one is well-formed
+    try putLenPrefixed(w, goodGroupValue);
+    try w.putU32(1);
+    try putLenPrefixed(w, goodMemberValue);
+    // Second group: a length-prefixed blob whose declared value tag is
+    // invalid - `takeDecodedValue` must surface `error.Malformed` here
+    // rather than fabricating a bogus `Value`.
+    try putLenPrefixed(w, &[_]u8{99});
+
+    try std.testing.expectError(error.Malformed, decodeAggGroupRows(allocator, buf.items));
+}
+
+test "table_explain args round trip a table and an expr" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableExplain(allocator, "users", "city eq s:warsaw");
+    defer allocator.free(payload);
+    const args = try decodeTableExplain(payload);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("city eq s:warsaw", args.exprText);
+}
+
+test "table_explain args round trip an empty expr" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableExplain(allocator, "users", "");
+    defer allocator.free(payload);
+    const args = try decodeTableExplain(payload);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("", args.exprText);
+}
+
+test "table_update args round trip a table, set fields, and an expr" {
+    const allocator = std.testing.allocator;
+    const sets = [_]rowmod.Field{
+        .{ .name = "active", .value = .{ .int = 1 } },
+        .{ .name = "city", .value = .{ .text = "krakow" } },
+    };
+    const payload = try encodeTableUpdate(allocator, "users", &sets, "city eq s:warsaw");
+    defer allocator.free(payload);
+    const args = try decodeTableUpdate(payload);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("city eq s:warsaw", args.exprText);
+
+    var decoded = try rowmod.Row.decode(allocator, args.setsBytes);
+    defer decoded.deinit();
+    try std.testing.expectEqual(rowmod.Value{ .int = 1 }, decoded.get("active").?);
+    try std.testing.expectEqualStrings("krakow", decoded.get("city").?.text);
+}
+
+test "table_update args round trip an empty expr, updating every row" {
+    const allocator = std.testing.allocator;
+    const sets = [_]rowmod.Field{.{ .name = "seen", .value = .{ .int = 1 } }};
+    const payload = try encodeTableUpdate(allocator, "users", &sets, "");
+    defer allocator.free(payload);
+    const args = try decodeTableUpdate(payload);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("", args.exprText);
+
+    var decoded = try rowmod.Row.decode(allocator, args.setsBytes);
+    defer decoded.deinit();
+    try std.testing.expectEqual(@as(usize, 1), decoded.count());
+}
+
+test "table_delete args round trip a table and an expr" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableDelete(allocator, "users", "city eq s:warsaw");
+    defer allocator.free(payload);
+    const args = try decodeTableDelete(payload);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("city eq s:warsaw", args.exprText);
+}
+
+test "table_delete args round trip an empty expr, deleting every row" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableDelete(allocator, "users", "");
+    defer allocator.free(payload);
+    const args = try decodeTableDelete(payload);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqualStrings("", args.exprText);
+}
+
+test "table_export args round trip a table and each format" {
+    const allocator = std.testing.allocator;
+
+    const csvPayload = try encodeTableExport(allocator, "users", .csv);
+    defer allocator.free(csvPayload);
+    const csvArgs = try decodeTableExport(csvPayload);
+    try std.testing.expectEqualStrings("users", csvArgs.table);
+    try std.testing.expectEqual(DumpFormat.csv, csvArgs.format);
+
+    const jsonPayload = try encodeTableExport(allocator, "users", .json);
+    defer allocator.free(jsonPayload);
+    const jsonArgs = try decodeTableExport(jsonPayload);
+    try std.testing.expectEqualStrings("users", jsonArgs.table);
+    try std.testing.expectEqual(DumpFormat.json, jsonArgs.format);
+}
+
+test "table_export rejects a format byte outside the DumpFormat enum" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, "users");
+    try w.byte(99);
+    try std.testing.expectError(error.Malformed, decodeTableExport(buf.items));
+}
+
+test "export result round trips a row count and content bytes" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeExportResult(allocator, 3, "__pk\ni:1\ni:2\ni:3\n");
+    defer allocator.free(payload);
+    const result = try decodeExportResult(payload);
+    try std.testing.expectEqual(@as(u64, 3), result.rowCount);
+    try std.testing.expectEqualStrings("__pk\ni:1\ni:2\ni:3\n", result.content);
+}
+
+test "export result round trips a zero row count with empty content" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeExportResult(allocator, 0, "");
+    defer allocator.free(payload);
+    const result = try decodeExportResult(payload);
+    try std.testing.expectEqual(@as(u64, 0), result.rowCount);
+    try std.testing.expectEqualStrings("", result.content);
+}
+
+test "table_import args round trip a table, format, and content" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTableImport(allocator, "users", .json, "[{\"__pk\": \"i:1\"}]");
+    defer allocator.free(payload);
+    const args = try decodeTableImport(payload);
+    try std.testing.expectEqualStrings("users", args.table);
+    try std.testing.expectEqual(DumpFormat.json, args.format);
+    try std.testing.expectEqualStrings("[{\"__pk\": \"i:1\"}]", args.content);
+}
+
+test "table_import rejects a format byte outside the DumpFormat enum" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, "users");
+    try w.byte(7);
+    try w.slice("ignored");
+    try std.testing.expectError(error.Malformed, decodeTableImport(buf.items));
+}
+
+test "Plan round trips full_scan with a null indexName" {
+    const allocator = std.testing.allocator;
+    const payload = try encodePlan(allocator, .{ .kind = .full_scan });
+    defer allocator.free(payload);
+    var decoded = try decodePlan(allocator, payload);
+    defer decoded.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.full_scan, decoded.kind);
+    try std.testing.expect(decoded.indexName == null);
+    try std.testing.expectEqual(@as(usize, 0), decoded.matchedFields);
+    try std.testing.expectEqual(@as(usize, 0), decoded.totalFields);
+}
+
+test "Plan round trips index_range with an indexName and field counts" {
+    const allocator = std.testing.allocator;
+    const payload = try encodePlan(allocator, .{ .kind = .index_range, .indexName = "score", .matchedFields = 1, .totalFields = 1 });
+    defer allocator.free(payload);
+    var decoded = try decodePlan(allocator, payload);
+    defer decoded.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.index_range, decoded.kind);
+    try std.testing.expectEqualStrings("score", decoded.indexName.?);
+    try std.testing.expectEqual(@as(usize, 1), decoded.matchedFields);
+    try std.testing.expectEqual(@as(usize, 1), decoded.totalFields);
+}
+
+test "Plan round trips composite_eq with a strict prefix match" {
+    const allocator = std.testing.allocator;
+    const payload = try encodePlan(allocator, .{ .kind = .composite_eq, .indexName = "city_age", .matchedFields = 1, .totalFields = 2 });
+    defer allocator.free(payload);
+    var decoded = try decodePlan(allocator, payload);
+    defer decoded.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.composite_eq, decoded.kind);
+    try std.testing.expectEqualStrings("city_age", decoded.indexName.?);
+    try std.testing.expectEqual(@as(usize, 1), decoded.matchedFields);
+    try std.testing.expectEqual(@as(usize, 2), decoded.totalFields);
+}
+
+test "decodePlan rejects an unknown PlanKind byte instead of corrupting a plan" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(200); // not a valid PlanKind tag
+    try putLenPrefixed(w, "");
+    try w.putU32(0);
+    try w.putU32(0);
+
+    try std.testing.expectError(error.Malformed, decodePlan(allocator, buf.items));
+}
+
+test "decodeRows rejects a corrupted row payload without leaking prior rows" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    var goodRow = rowmod.Row.init(allocator);
+    defer goodRow.deinit();
+    try goodRow.set("a", .{ .int = 1 });
+    const encoded = try goodRow.encode(allocator);
+    defer allocator.free(encoded);
+
+    try w.putU32(2);
+    try putLenPrefixed(w, encoded);
+    try putLenPrefixed(w, &.{ 9, 9, 9 });
+
+    try std.testing.expectError(error.Malformed, decodeRows(allocator, buf.items));
+}
+
+test "Cursor.takeLenPrefixed rejects a length that overruns the buffer" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(100);
+    try w.slice("short");
+    var c = Cursor{ .data = buf.items };
+    try std.testing.expectError(error.Malformed, c.takeLenPrefixed());
+}
+
+test "UserAdminAction.fromByte rejects an unknown action" {
+    try std.testing.expectError(error.Malformed, UserAdminAction.fromByte(200));
+    try std.testing.expectEqual(UserAdminAction.list, try UserAdminAction.fromByte(4));
+}
+
+test "user_admin create payload round trips role and rounds" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeUserAdmin(allocator, .create, "alice", "hunter2", .admin, 100_000);
+    defer allocator.free(payload);
+    const args = try decodeUserAdmin(payload);
+    try std.testing.expectEqual(UserAdminAction.create, args.action);
+    try std.testing.expectEqualStrings("alice", args.username);
+    try std.testing.expectEqualStrings("hunter2", args.password);
+    try std.testing.expectEqual(@intFromEnum(authmod.Role.admin), args.roleByte);
+    try std.testing.expectEqual(@as(u32, 100_000), args.rounds);
+}
+
+test "user_admin delete payload carries only the username" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeUserAdmin(allocator, .delete, "bob", "", .readonly, 0);
+    defer allocator.free(payload);
+    const args = try decodeUserAdmin(payload);
+    try std.testing.expectEqual(UserAdminAction.delete, args.action);
+    try std.testing.expectEqualStrings("bob", args.username);
+    try std.testing.expectEqualStrings("", args.password);
+}
+
+test "user_admin list payload round trips with an empty username" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeUserAdmin(allocator, .list, "", "", .readonly, 0);
+    defer allocator.free(payload);
+    const args = try decodeUserAdmin(payload);
+    try std.testing.expectEqual(UserAdminAction.list, args.action);
+    try std.testing.expectEqualStrings("", args.username);
+}
+
+test "user list round trips every username with its role" {
+    const allocator = std.testing.allocator;
+    const users = [_]authmod.UserInfo{
+        .{ .username = @constCast("alice"), .role = .readonly },
+        .{ .username = @constCast("root"), .role = .admin },
+    };
+    const payload = try encodeUserList(allocator, &users);
+    defer allocator.free(payload);
+
+    const decoded = try decodeUserList(allocator, payload);
+    defer authmod.freeUserList(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 2), decoded.len);
+    try std.testing.expectEqualStrings("alice", decoded[0].username);
+    try std.testing.expectEqual(authmod.Role.readonly, decoded[0].role);
+    try std.testing.expectEqualStrings("root", decoded[1].username);
+    try std.testing.expectEqual(authmod.Role.admin, decoded[1].role);
+}
+
+test "empty user list round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeUserList(allocator, &[_]authmod.UserInfo{});
+    defer allocator.free(payload);
+    const decoded = try decodeUserList(allocator, payload);
+    defer authmod.freeUserList(allocator, decoded);
+    try std.testing.expectEqual(@as(usize, 0), decoded.len);
+}
+
+test "decodeUserList rejects an unknown role byte" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(1);
+    try putLenPrefixed(w, "ghost");
+    try w.byte(200);
+    try std.testing.expectError(error.Malformed, decodeUserList(allocator, buf.items));
+}
+
+test "TtlAction.fromByte rejects an unknown action" {
+    try std.testing.expectError(error.Malformed, TtlAction.fromByte(200));
+    try std.testing.expectEqual(TtlAction.sweep, try TtlAction.fromByte(3));
+}
+
+test "ttl_op expire payload round trips key and seconds" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTtlOp(allocator, .expire, "session:1", 30);
+    defer allocator.free(payload);
+    const args = try decodeTtlOp(payload);
+    try std.testing.expectEqual(TtlAction.expire, args.action);
+    try std.testing.expectEqualStrings("session:1", args.key);
+    try std.testing.expectEqual(@as(u64, 30), args.seconds);
+}
+
+test "ttl_op sweep payload carries an empty key and zero seconds" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTtlOp(allocator, .sweep, "", 0);
+    defer allocator.free(payload);
+    const args = try decodeTtlOp(payload);
+    try std.testing.expectEqual(TtlAction.sweep, args.action);
+    try std.testing.expectEqualStrings("", args.key);
+    try std.testing.expectEqual(@as(u64, 0), args.seconds);
+}
+
+test "ttl result round trips noKey, noExpiry, and seconds" {
+    const allocator = std.testing.allocator;
+
+    const noKeyPayload = try encodeTtlResult(allocator, .noKey);
+    defer allocator.free(noKeyPayload);
+    try std.testing.expectEqual(ttlmod.TtlResult.noKey, try decodeTtlResult(noKeyPayload));
+
+    const noExpiryPayload = try encodeTtlResult(allocator, .noExpiry);
+    defer allocator.free(noExpiryPayload);
+    try std.testing.expectEqual(ttlmod.TtlResult.noExpiry, try decodeTtlResult(noExpiryPayload));
+
+    const secondsPayload = try encodeTtlResult(allocator, .{ .seconds = 42 });
+    defer allocator.free(secondsPayload);
+    const decoded = try decodeTtlResult(secondsPayload);
+    try std.testing.expectEqual(@as(u64, 42), decoded.seconds);
+}
+
+test "decodeTtlResult rejects an unknown kind byte" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(200);
+    try std.testing.expectError(error.Malformed, decodeTtlResult(buf.items));
+}
+
+test "ttl sweep count round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTtlSweepCount(allocator, 7);
+    defer allocator.free(payload);
+    try std.testing.expectEqual(@as(u64, 7), try decodeTtlSweepCount(payload));
+}
+
+test "coll_ttl_op expire payload round trips action, kind, name and seconds" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeCollTtlOp(allocator, .expire, .hash, "profile", 30);
+    defer allocator.free(payload);
+    const args = try decodeCollTtlOp(payload);
+    try std.testing.expectEqual(TtlAction.expire, args.action);
+    try std.testing.expectEqual(collmod.Kind.hash, args.kind);
+    try std.testing.expectEqualStrings("profile", args.name);
+    try std.testing.expectEqual(@as(u64, 30), args.seconds);
+}
+
+test "coll_ttl_op round trips every kind's tag byte" {
+    const allocator = std.testing.allocator;
+    const kinds = [_]collmod.Kind{ .counter, .hash, .set, .list, .zset };
+    for (kinds) |k| {
+        const payload = try encodeCollTtlOp(allocator, .query, k, "n", 0);
+        defer allocator.free(payload);
+        const args = try decodeCollTtlOp(payload);
+        try std.testing.expectEqual(k, args.kind);
+    }
+}
+
+test "coll_ttl_op sweep payload carries an empty name and zero seconds" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeCollTtlOp(allocator, .sweep, .counter, "", 0);
+    defer allocator.free(payload);
+    const args = try decodeCollTtlOp(payload);
+    try std.testing.expectEqual(TtlAction.sweep, args.action);
+    try std.testing.expectEqualStrings("", args.name);
+    try std.testing.expectEqual(@as(u64, 0), args.seconds);
+}
+
+test "decodeCollTtlOp rejects an unknown kind byte" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(@intFromEnum(TtlAction.query));
+    try w.byte('?');
+    try w.putU64(0);
+    try std.testing.expectError(error.Malformed, decodeCollTtlOp(buf.items));
+}
+
+test "decodeCollTtlOp rejects an unknown action byte before the kind byte is even read" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(200);
+    try w.byte('H');
+    try w.putU64(0);
+    try std.testing.expectError(error.Malformed, decodeCollTtlOp(buf.items));
+}
+
+test "CollAction.fromByte rejects an unknown action" {
+    try std.testing.expectError(error.Malformed, CollAction.fromByte(200));
+    try std.testing.expectEqual(CollAction.zset_rank, try CollAction.fromByte(29));
+}
+
+test "CollAction.kind groups every action under its collection kind" {
+    try std.testing.expectEqual(collmod.Kind.counter, CollAction.counter_incrby.kind());
+    try std.testing.expectEqual(collmod.Kind.hash, CollAction.hash_getall.kind());
+    try std.testing.expectEqual(collmod.Kind.set, CollAction.set_diff.kind());
+    try std.testing.expectEqual(collmod.Kind.list, CollAction.list_range.kind());
+    try std.testing.expectEqual(collmod.Kind.zset, CollAction.zset_rangebyscore.kind());
+}
+
+test "CollAction.isReadOnly separates reads from writes" {
+    try std.testing.expect(CollAction.counter_get.isReadOnly());
+    try std.testing.expect(!CollAction.counter_set.isReadOnly());
+    try std.testing.expect(CollAction.zset_rank.isReadOnly());
+    try std.testing.expect(!CollAction.zset_add.isReadOnly());
+    try std.testing.expect(CollAction.set_inter.isReadOnly());
+    try std.testing.expect(!CollAction.list_lpush.isReadOnly());
+}
+
+test "coll_op payload round trips action, name, and a variable arg list" {
+    const allocator = std.testing.allocator;
+    const args = [_][]const u8{ "alice", "10" };
+    const payload = try encodeCollOp(allocator, .zset_add, "leaderboard", &args);
+    defer allocator.free(payload);
+    const decoded = try decodeCollOp(allocator, payload);
+    defer allocator.free(decoded.args);
+    try std.testing.expectEqual(CollAction.zset_add, decoded.action);
+    try std.testing.expectEqualStrings("leaderboard", decoded.name);
+    try std.testing.expectEqual(@as(usize, 2), decoded.args.len);
+    try std.testing.expectEqualStrings("alice", decoded.args[0]);
+    try std.testing.expectEqualStrings("10", decoded.args[1]);
+}
+
+test "coll_op payload round trips a zero-arg action" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeCollOp(allocator, .hash_getall, "profile", &.{});
+    defer allocator.free(payload);
+    const decoded = try decodeCollOp(allocator, payload);
+    defer allocator.free(decoded.args);
+    try std.testing.expectEqual(CollAction.hash_getall, decoded.action);
+    try std.testing.expectEqualStrings("profile", decoded.name);
+    try std.testing.expectEqual(@as(usize, 0), decoded.args.len);
+}
+
+test "decodeCollOp rejects an unknown action byte" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(250);
+    try putLenPrefixed(w, "x");
+    try w.putU32(0);
+    try std.testing.expectError(error.Malformed, decodeCollOp(allocator, buf.items));
+}
+
+test "coll reply round trips nil and ok" {
+    const allocator = std.testing.allocator;
+
+    const nilPayload = try encodeCollReply(allocator, .nil);
+    defer allocator.free(nilPayload);
+    var nilReply = try decodeCollReply(allocator, nilPayload);
+    defer nilReply.deinit(allocator);
+    try std.testing.expect(nilReply == .nil);
+
+    const okPayload = try encodeCollReply(allocator, .ok);
+    defer allocator.free(okPayload);
+    var okReply = try decodeCollReply(allocator, okPayload);
+    defer okReply.deinit(allocator);
+    try std.testing.expect(okReply == .ok);
+}
+
+test "coll reply round trips int and real" {
+    const allocator = std.testing.allocator;
+
+    const intPayload = try encodeCollReply(allocator, .{ .int = -42 });
+    defer allocator.free(intPayload);
+    var intReply = try decodeCollReply(allocator, intPayload);
+    defer intReply.deinit(allocator);
+    try std.testing.expectEqual(@as(i64, -42), intReply.int);
+
+    const realPayload = try encodeCollReply(allocator, .{ .real = 3.5 });
+    defer allocator.free(realPayload);
+    var realReply = try decodeCollReply(allocator, realPayload);
+    defer realReply.deinit(allocator);
+    try std.testing.expectEqual(@as(f64, 3.5), realReply.real);
+}
+
+test "coll reply round trips raw bytes independently of the source payload" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeCollReply(allocator, .{ .bytes = "hello" });
+    defer allocator.free(payload);
+    var reply = try decodeCollReply(allocator, payload);
+    defer reply.deinit(allocator);
+    try std.testing.expectEqualStrings("hello", reply.bytes);
+}
+
+test "coll reply round trips a string list, including empty" {
+    const allocator = std.testing.allocator;
+    const items = [_][]const u8{ "a", "bb", "ccc" };
+    const payload = try encodeCollReply(allocator, .{ .stringList = &items });
+    defer allocator.free(payload);
+    var reply = try decodeCollReply(allocator, payload);
+    defer reply.deinit(allocator);
+    try std.testing.expectEqual(@as(usize, 3), reply.stringList.len);
+    try std.testing.expectEqualStrings("bb", reply.stringList[1]);
+
+    const emptyPayload = try encodeCollReply(allocator, .{ .stringList = &.{} });
+    defer allocator.free(emptyPayload);
+    var emptyReply = try decodeCollReply(allocator, emptyPayload);
+    defer emptyReply.deinit(allocator);
+    try std.testing.expectEqual(@as(usize, 0), emptyReply.stringList.len);
+}
+
+test "coll reply round trips a pair list (hash getall shape)" {
+    const allocator = std.testing.allocator;
+    const pairs = [_]CollPair{
+        .{ .field = "name", .value = "ada" },
+        .{ .field = "age", .value = "36" },
+    };
+    const payload = try encodeCollReply(allocator, .{ .pairList = &pairs });
+    defer allocator.free(payload);
+    var reply = try decodeCollReply(allocator, payload);
+    defer reply.deinit(allocator);
+    try std.testing.expectEqual(@as(usize, 2), reply.pairList.len);
+    try std.testing.expectEqualStrings("name", reply.pairList[0].field);
+    try std.testing.expectEqualStrings("ada", reply.pairList[0].value);
+    try std.testing.expectEqualStrings("age", reply.pairList[1].field);
+    try std.testing.expectEqualStrings("36", reply.pairList[1].value);
+}
+
+test "coll reply round trips a score pair list (zset range shape), including negative scores" {
+    const allocator = std.testing.allocator;
+    const pairs = [_]CollScorePair{
+        .{ .member = "bob", .score = -1.5 },
+        .{ .member = "ada", .score = 10.25 },
+    };
+    const payload = try encodeCollReply(allocator, .{ .scorePairList = &pairs });
+    defer allocator.free(payload);
+    var reply = try decodeCollReply(allocator, payload);
+    defer reply.deinit(allocator);
+    try std.testing.expectEqual(@as(usize, 2), reply.scorePairList.len);
+    try std.testing.expectEqualStrings("bob", reply.scorePairList[0].member);
+    try std.testing.expectEqual(@as(f64, -1.5), reply.scorePairList[0].score);
+    try std.testing.expectEqualStrings("ada", reply.scorePairList[1].member);
+    try std.testing.expectEqual(@as(f64, 10.25), reply.scorePairList[1].score);
+}
+
+test "decodeCollReply rejects an unknown tag byte" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.byte(250);
+    try std.testing.expectError(error.Malformed, decodeCollReply(allocator, buf.items));
+}
+
+test "txn_op entries round trip put and del across two tables" {
+    const allocator = std.testing.allocator;
+    const putFields = [_]rowmod.Field{
+        .{ .name = "balance", .value = .{ .int = 100 } },
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+    };
+    const entries = [_]TxnOpEntry{
+        .{ .verb = .put, .table = "accounts", .pk = .{ .int = 1 }, .fields = &putFields },
+        .{ .verb = .del, .table = "sessions", .pk = .{ .text = "abc" } },
+    };
+    const payload = try encodeTxnOp(allocator, &entries);
+    defer allocator.free(payload);
+
+    const decoded = try decodeTxnOp(allocator, payload);
+    defer allocator.free(decoded);
+    try std.testing.expectEqual(@as(usize, 2), decoded.len);
+
+    try std.testing.expectEqual(TxnVerb.put, decoded[0].verb);
+    try std.testing.expectEqualStrings("accounts", decoded[0].table);
+    const pk0 = try rowmod.decodeValue(allocator, decoded[0].pkBytes);
+    try std.testing.expectEqual(@as(i64, 1), pk0.int);
+    var fields0 = try rowmod.Row.decode(allocator, decoded[0].fieldsBytes);
+    defer fields0.deinit();
+    try std.testing.expectEqual(@as(i64, 100), fields0.get("balance").?.int);
+    try std.testing.expectEqualStrings("warsaw", fields0.get("city").?.text);
+
+    try std.testing.expectEqual(TxnVerb.del, decoded[1].verb);
+    try std.testing.expectEqualStrings("sessions", decoded[1].table);
+    var pk1 = try rowmod.decodeValue(allocator, decoded[1].pkBytes);
+    defer pk1.free(allocator);
+    try std.testing.expectEqualStrings("abc", pk1.text);
+    var fields1 = try rowmod.Row.decode(allocator, decoded[1].fieldsBytes);
+    defer fields1.deinit();
+    try std.testing.expectEqual(@as(usize, 0), fields1.count());
+}
+
+test "empty txn_op entry list round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTxnOp(allocator, &[_]TxnOpEntry{});
+    defer allocator.free(payload);
+    const decoded = try decodeTxnOp(allocator, payload);
+    defer allocator.free(decoded);
+    try std.testing.expectEqual(@as(usize, 0), decoded.len);
+}
+
+test "decodeTxnOp rejects an unknown verb byte" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(1);
+    try w.byte(9);
+    try std.testing.expectError(error.Malformed, decodeTxnOp(allocator, buf.items));
+}
+
+test "txn_op result round trips the applied count" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeTxnResult(allocator, 7);
+    defer allocator.free(payload);
+    try std.testing.expectEqual(@as(u32, 7), try decodeTxnResult(payload));
+}
+
+test "table_window args round trip a ranking spec with a partition, an order-by, and an expr" {
+    const allocator = std.testing.allocator;
+    const orderBy = [_]querymod.OrderBy{.{ .field = "day", .descending = false }};
+    const partitionBy = [_][]const u8{"city"};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .row_number }};
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &partitionBy, &orderBy, 0, 0, "total gt i:10", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqualStrings("orders", args.table);
+    try std.testing.expectEqual(@as(usize, 1), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.row_number, args.specs[0].kind);
+    try std.testing.expectEqualStrings("", args.specs[0].field);
+    try std.testing.expectEqual(@as(usize, 1), args.partitionBy.len);
+    try std.testing.expectEqualStrings("city", args.partitionBy[0]);
+    try std.testing.expectEqual(@as(usize, 1), args.orderBy.len);
+    try std.testing.expectEqualStrings("day", args.orderBy[0].field);
+    try std.testing.expect(!args.orderBy[0].descending);
+    try std.testing.expectEqualStrings("total gt i:10", args.exprText);
+}
+
+test "table_window args round trip a sum spec with no partition, no order-by, and an empty expr" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{.{ .field = "total", .kind = .sum }};
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 1), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.sum, args.specs[0].kind);
+    try std.testing.expectEqualStrings("total", args.specs[0].field);
+    try std.testing.expectEqual(@as(usize, 0), args.partitionBy.len);
+    try std.testing.expectEqual(@as(usize, 0), args.orderBy.len);
+    try std.testing.expectEqualStrings("", args.exprText);
+}
+
+test "table_window args round trip a count_distinct spec alongside sum, no extra wire bytes needed" {
+    const allocator = std.testing.allocator;
+    const orderBy = [_]querymod.OrderBy{.{ .field = "day" }};
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "tag", .kind = .count_distinct },
+        .{ .field = "amount", .kind = .sum },
+    };
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 2), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.count_distinct, args.specs[0].kind);
+    try std.testing.expectEqualStrings("tag", args.specs[0].field);
+    try std.testing.expectEqual(windowmod.WindowKind.sum, args.specs[1].kind);
+}
+
+test "table_window args round trip first_value/last_value specs alongside a partition/order/RANGE frame" {
+    const allocator = std.testing.allocator;
+    const orderBy = [_]querymod.OrderBy{.{ .field = "day" }};
+    const partitionBy = [_][]const u8{"city"};
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "amount", .kind = .first_value },
+        .{ .field = "amount", .kind = .last_value },
+    };
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &partitionBy, &orderBy, 0, 0, "", .range);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 2), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.first_value, args.specs[0].kind);
+    try std.testing.expectEqualStrings("amount", args.specs[0].field);
+    try std.testing.expectEqual(windowmod.WindowKind.last_value, args.specs[1].kind);
+    try std.testing.expectEqualStrings("amount", args.specs[1].field);
+    try std.testing.expectEqual(windowmod.FrameMode.range, args.frame);
+}
+
+test "table_window args round trip MULTIPLE specs sharing one partition/order/frame" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "total", .kind = .sum },
+        .{ .field = "total", .kind = .avg },
+        .{ .field = "", .kind = .rank },
+    };
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 3), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.sum, args.specs[0].kind);
+    try std.testing.expectEqualStrings("total", args.specs[0].field);
+    try std.testing.expectEqual(windowmod.WindowKind.avg, args.specs[1].kind);
+    try std.testing.expectEqualStrings("total", args.specs[1].field);
+    try std.testing.expectEqual(windowmod.WindowKind.rank, args.specs[2].kind);
+    try std.testing.expectEqualStrings("", args.specs[2].field);
+}
+
+test "table_window args round trip a nonzero offset and limit" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .rank }};
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &.{}, 2, 5, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(u32, 2), args.offset);
+    try std.testing.expectEqual(@as(u32, 5), args.limit);
+}
+
+test "table_window args round trip a RANGE frame, and default to ROWS when the byte is 0" {
+    const allocator = std.testing.allocator;
+    const order = [_]querymod.OrderBy{.{ .field = "day", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "amount", .kind = .sum }};
+
+    const rangePayload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &order, 0, 0, "", .range);
+    defer allocator.free(rangePayload);
+    const rangeArgs = try decodeTableWindow(allocator, rangePayload);
+    defer allocator.free(rangeArgs.specs);
+    defer allocator.free(rangeArgs.partitionBy);
+    defer allocator.free(rangeArgs.orderBy);
+    try std.testing.expectEqual(windowmod.FrameMode.range, rangeArgs.frame);
+
+    const rowsPayload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &order, 0, 0, "", .rows);
+    defer allocator.free(rowsPayload);
+    const rowsArgs = try decodeTableWindow(allocator, rowsPayload);
+    defer allocator.free(rowsArgs.specs);
+    defer allocator.free(rowsArgs.partitionBy);
+    defer allocator.free(rowsArgs.orderBy);
+    try std.testing.expectEqual(windowmod.FrameMode.rows, rowsArgs.frame);
+}
+
+test "decodeTableWindow rejects an unknown frame byte instead of silently defaulting to ROWS" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, "orders");
+    try w.byte(1); // specs count
+    try w.byte(@intFromEnum(windowmod.WindowKind.sum));
+    try putLenPrefixed(w, "total");
+    try w.byte(0); // partitionBy count
+    try w.byte(0); // orderBy count
+    try w.putU32(0);
+    try w.putU32(0);
+    try w.byte(200); // not a valid FrameMode tag
+
+    try std.testing.expectError(error.Malformed, decodeTableWindow(allocator, buf.items));
+}
+
+test "table_window args round trip a multi-column partition and multi-column descending order-by" {
+    const allocator = std.testing.allocator;
+    const partitionBy = [_][]const u8{ "city", "region" };
+    const orderBy = [_]querymod.OrderBy{
+        .{ .field = "day", .descending = true },
+        .{ .field = "amount", .descending = false },
+    };
+    const specs = [_]windowmod.WindowSpec{.{ .field = "amount", .kind = .max }};
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &partitionBy, &orderBy, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 2), args.partitionBy.len);
+    try std.testing.expectEqualStrings("city", args.partitionBy[0]);
+    try std.testing.expectEqualStrings("region", args.partitionBy[1]);
+    try std.testing.expectEqual(@as(usize, 2), args.orderBy.len);
+    try std.testing.expect(args.orderBy[0].descending);
+    try std.testing.expect(!args.orderBy[1].descending);
+}
+
+test "decodeTableWindow rejects an unknown window kind byte instead of corrupting a spec" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, "orders");
+    try w.byte(1); // specs count
+    try w.byte(200); // not a valid WindowKind tag
+    try putLenPrefixed(w, "total");
+    try w.byte(0); // partitionBy count
+    try w.byte(0); // orderBy count
+    try w.putU32(0);
+    try w.putU32(0);
+
+    try std.testing.expectError(error.Malformed, decodeTableWindow(allocator, buf.items));
+}
+
+test "window rows round trip through encode and decode" {
+    const allocator = std.testing.allocator;
+    var rows = [_]rowmod.Row{ rowmod.Row.init(allocator), rowmod.Row.init(allocator) };
+    defer for (&rows) |*r| r.deinit();
+    try rows[0].set("city", .{ .text = "warsaw" });
+    try rows[1].set("city", .{ .text = "krakow" });
+
+    var values0 = [_]rowmod.Value{.{ .int = 1 }};
+    var values1 = [_]rowmod.Value{.{ .int = 2 }};
+    const windowRows = [_]WindowRow{
+        .{ .row = rows[0], .values = &values0 },
+        .{ .row = rows[1], .values = &values1 },
+    };
+    const payload = try encodeWindowRows(allocator, &windowRows);
+    defer allocator.free(payload);
+
+    const decoded = try decodeWindowRows(allocator, payload);
+    defer freeWindowRows(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 2), decoded.len);
+    try std.testing.expectEqualStrings("warsaw", decoded[0].row.get("city").?.text);
+    try std.testing.expectEqual(@as(usize, 1), decoded[0].values.len);
+    try std.testing.expectEqual(@as(i64, 1), decoded[0].values[0].int);
+    try std.testing.expectEqualStrings("krakow", decoded[1].row.get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 2), decoded[1].values[0].int);
+}
+
+test "window rows round trip MULTIPLE values per row, same order as the request's specs" {
+    const allocator = std.testing.allocator;
+    var rows = [_]rowmod.Row{rowmod.Row.init(allocator)};
+    defer for (&rows) |*r| r.deinit();
+    try rows[0].set("city", .{ .text = "warsaw" });
+
+    var values0 = [_]rowmod.Value{ .{ .int = 30 }, .{ .float = 15.0 }, .{ .int = 1 } };
+    const windowRows = [_]WindowRow{.{ .row = rows[0], .values = &values0 }};
+    const payload = try encodeWindowRows(allocator, &windowRows);
+    defer allocator.free(payload);
+
+    const decoded = try decodeWindowRows(allocator, payload);
+    defer freeWindowRows(allocator, decoded);
+
+    try std.testing.expectEqual(@as(usize, 1), decoded.len);
+    try std.testing.expectEqual(@as(usize, 3), decoded[0].values.len);
+    try std.testing.expectEqual(@as(i64, 30), decoded[0].values[0].int);
+    try std.testing.expectEqual(@as(f64, 15.0), decoded[0].values[1].float);
+    try std.testing.expectEqual(@as(i64, 1), decoded[0].values[2].int);
+}
+
+test "empty window row list round trips" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeWindowRows(allocator, &[_]WindowRow{});
+    defer allocator.free(payload);
+    const decoded = try decodeWindowRows(allocator, payload);
+    defer freeWindowRows(allocator, decoded);
+    try std.testing.expectEqual(@as(usize, 0), decoded.len);
+}
+
+test "subscribe args round trip a multi-channel list" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeSubscribe(allocator, &.{ "orders", "alerts" });
+    defer allocator.free(payload);
+
+    const args = try decodeSubscribe(allocator, payload);
+    defer args.deinit(allocator);
+
+    try std.testing.expectEqual(@as(usize, 2), args.channels.len);
+    try std.testing.expectEqualStrings("orders", args.channels[0]);
+    try std.testing.expectEqualStrings("alerts", args.channels[1]);
+}
+
+test "subscribe args round trip an empty channel list" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeSubscribe(allocator, &.{});
+    defer allocator.free(payload);
+
+    const args = try decodeSubscribe(allocator, payload);
+    defer args.deinit(allocator);
+
+    try std.testing.expectEqual(@as(usize, 0), args.channels.len);
+}
+
+test "decodeSubscribe rejects a truncated channel count" {
+    const allocator = std.testing.allocator;
+    try std.testing.expectError(error.Malformed, decodeSubscribe(allocator, &.{ 0, 0 }));
+}
+
+test "decodeSubscribe rejects a channel count larger than the payload can hold" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU32(5);
+    try std.testing.expectError(error.Malformed, decodeSubscribe(allocator, buf.items));
+}
+
+test "subscribe ack round trips a subscriber id and channel count" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeSubscribeAck(allocator, 42, 3);
+    defer allocator.free(payload);
+    const ack = try decodeSubscribeAck(payload);
+    try std.testing.expectEqual(@as(u64, 42), ack.subscriberId);
+    try std.testing.expectEqual(@as(u32, 3), ack.channelCount);
+}
+
+test "unsubscribe args round trip a subscriber id and multi-channel list" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeUnsubscribe(allocator, 7, &.{ "orders", "alerts" });
+    defer allocator.free(payload);
+
+    const args = try decodeUnsubscribe(allocator, payload);
+    defer args.deinit(allocator);
+    try std.testing.expectEqual(@as(u64, 7), args.subscriberId);
+    try std.testing.expectEqual(@as(usize, 2), args.channels.len);
+    try std.testing.expectEqualStrings("orders", args.channels[0]);
+    try std.testing.expectEqualStrings("alerts", args.channels[1]);
+}
+
+test "unsubscribe args round trip an empty channel list" {
+    const allocator = std.testing.allocator;
+    const payload = try encodeUnsubscribe(allocator, 1, &.{});
+    defer allocator.free(payload);
+
+    const args = try decodeUnsubscribe(allocator, payload);
+    defer args.deinit(allocator);
+    try std.testing.expectEqual(@as(usize, 0), args.channels.len);
+}
+
+test "decodeUnsubscribe rejects a truncated channel count" {
+    const allocator = std.testing.allocator;
+    // 8 bytes of subscriber id, then only 2 of the 4 count bytes.
+    try std.testing.expectError(error.Malformed, decodeUnsubscribe(allocator, &.{ 0, 0, 0, 0, 0, 0, 0, 1, 0, 0 }));
+}
+
+test "decodeUnsubscribe rejects a channel count larger than the payload can hold" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try w.putU64(1);
+    try w.putU32(5);
+    try std.testing.expectError(error.Malformed, decodeUnsubscribe(allocator, buf.items));
+}
+
+test "unsubscribe result round trips a removed count, including zero" {
+    const allocator = std.testing.allocator;
+    const zero = try encodeUnsubscribeResult(allocator, 0);
+    defer allocator.free(zero);
+    try std.testing.expectEqual(@as(u32, 0), try decodeUnsubscribeResult(zero));
+
+    const some = try encodeUnsubscribeResult(allocator, 2);
+    defer allocator.free(some);
+    try std.testing.expectEqual(@as(u32, 2), try decodeUnsubscribeResult(some));
+}
+
+test "publish args round trip a channel and a binary-safe message" {
+    const allocator = std.testing.allocator;
+    const message = [_]u8{ 0, 1, 2, 0, 255 };
+    const payload = try encodePublish(allocator, "orders", &message);
+    defer allocator.free(payload);
+
+    const args = try decodePublish(payload);
+    try std.testing.expectEqualStrings("orders", args.channel);
+    try std.testing.expectEqualSlices(u8, &message, args.message);
+}
+
+test "publish result round trips a subscriber count, including zero" {
+    const allocator = std.testing.allocator;
+    const payload = try encodePublishResult(allocator, 0);
+    defer allocator.free(payload);
+    try std.testing.expectEqual(@as(u64, 0), try decodePublishResult(payload));
+
+    const payload2 = try encodePublishResult(allocator, 7);
+    defer allocator.free(payload2);
+    try std.testing.expectEqual(@as(u64, 7), try decodePublishResult(payload2));
+}
+
+test "pubsub message round trips channel and payload as independent owned copies" {
+    const allocator = std.testing.allocator;
+    const payload = try encodePubSubMessage(allocator, "alerts", "disk full");
+    defer allocator.free(payload);
+
+    const decoded = try decodePubSubMessage(allocator, payload);
+    defer decoded.deinit(allocator);
+
+    try std.testing.expectEqualStrings("alerts", decoded.channel);
+    try std.testing.expectEqualStrings("disk full", decoded.payload);
+}
+
+test "pubsub message round trips an empty payload" {
+    const allocator = std.testing.allocator;
+    const payload = try encodePubSubMessage(allocator, "ch", "");
+    defer allocator.free(payload);
+
+    const decoded = try decodePubSubMessage(allocator, payload);
+    defer decoded.deinit(allocator);
+
+    try std.testing.expectEqualStrings("ch", decoded.channel);
+    try std.testing.expectEqual(@as(usize, 0), decoded.payload.len);
+}
+
+test "table_window args round trip a lag spec with a nonzero offset and an int default" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{.{ .field = "amount", .kind = .lag, .offset = 3, .default = .{ .int = -1 } }};
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &order, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 1), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.lag, args.specs[0].kind);
+    try std.testing.expectEqualStrings("amount", args.specs[0].field);
+    try std.testing.expectEqual(@as(u64, 3), args.specs[0].offset);
+    try std.testing.expectEqual(@as(i64, -1), args.specs[0].default.int);
+}
+
+test "table_window args round trip a lead spec with its default text and default offset of 1" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{.{ .field = "status", .kind = .lead, .default = .{ .text = "none-yet" } }};
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(windowmod.WindowKind.lead, args.specs[0].kind);
+    try std.testing.expectEqual(@as(u64, 1), args.specs[0].offset);
+    try std.testing.expectEqualStrings("none-yet", args.specs[0].default.text);
+}
+
+test "table_window args round trip lag/lead alongside a plain sum spec in the same request" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "amount", .kind = .sum },
+        .{ .field = "amount", .kind = .lag, .offset = 2 },
+        .{ .field = "amount", .kind = .lead },
+    };
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 3), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.sum, args.specs[0].kind);
+    try std.testing.expectEqual(windowmod.WindowKind.lag, args.specs[1].kind);
+    try std.testing.expectEqual(@as(u64, 2), args.specs[1].offset);
+    try std.testing.expectEqual(windowmod.WindowKind.lead, args.specs[2].kind);
+    try std.testing.expectEqual(@as(u64, 1), args.specs[2].offset);
+}
+
+test "table_window args round trip an nth_value spec with its position and a custom default" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{.{ .field = "amount", .kind = .nth_value, .offset = 2, .default = .{ .int = -1 } }};
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &order, 0, 0, "", .range);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 1), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.nth_value, args.specs[0].kind);
+    try std.testing.expectEqualStrings("amount", args.specs[0].field);
+    try std.testing.expectEqual(@as(u64, 2), args.specs[0].offset);
+    try std.testing.expectEqual(@as(i64, -1), args.specs[0].default.int);
+}
+
+test "table_window args round trip nth_value alongside lag/lead/sum in the same request" {
+    const allocator = std.testing.allocator;
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "amount", .kind = .sum },
+        .{ .field = "amount", .kind = .nth_value, .offset = 3 },
+        .{ .field = "amount", .kind = .lag },
+    };
+    const payload = try encodeTableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "", .rows);
+    defer allocator.free(payload);
+    const args = try decodeTableWindow(allocator, payload);
+    defer allocator.free(args.specs);
+    defer allocator.free(args.partitionBy);
+    defer allocator.free(args.orderBy);
+
+    try std.testing.expectEqual(@as(usize, 3), args.specs.len);
+    try std.testing.expectEqual(windowmod.WindowKind.sum, args.specs[0].kind);
+    try std.testing.expectEqual(windowmod.WindowKind.nth_value, args.specs[1].kind);
+    try std.testing.expectEqual(@as(u64, 3), args.specs[1].offset);
+    try std.testing.expectEqual(windowmod.WindowKind.lag, args.specs[2].kind);
+}
+
+test "decodeTableWindow rejects a truncated nth_value default value instead of misreading trailing bytes" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, "orders");
+    try w.byte(1); // one spec
+    try w.byte(@intFromEnum(windowmod.WindowKind.nth_value));
+    try putLenPrefixed(w, "amount");
+    try w.putU64(2); // n
+    try w.byte(@intFromEnum(rowmod.ValueTag.int)); // default tag says int...
+    // ...but the 8-byte payload is missing entirely.
+
+    try std.testing.expectError(error.Malformed, decodeTableWindow(allocator, buf.items));
+}
+
+test "decodeTableWindow rejects a truncated lag/lead default value instead of misreading trailing bytes" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+    try putLenPrefixed(w, "orders");
+    try w.byte(1); // one spec
+    try w.byte(@intFromEnum(windowmod.WindowKind.lag));
+    try putLenPrefixed(w, "amount");
+    try w.putU64(1); // offset
+    try w.byte(@intFromEnum(rowmod.ValueTag.text)); // default tag says text...
+    // ...but the length-prefixed payload is missing entirely.
+
+    try std.testing.expectError(error.Malformed, decodeTableWindow(allocator, buf.items));
+}
diff --git a/src/pubsub.zig b/src/pubsub.zig
new file mode 100644
index 0000000..e6395f0
--- /dev/null
+++ b/src/pubsub.zig
@@ -0,0 +1,848 @@
+const std = @import("std");
+
+const Allocator = std.mem.Allocator;
+
+/// Default bound on how many undelivered messages a single subscriber's
+/// mailbox holds before the oldest is dropped to make room for the newest -
+/// see `Subscriber.push`'s doc comment for why drop-oldest (never blocking
+/// the publisher) is the chosen backpressure policy.
+pub const defaultCapacity: usize = 256;
+
+/// One delivered message: which channel it arrived on (a subscriber can
+/// listen to several, so the tag travels with the payload) and the payload
+/// bytes themselves, both independently owned copies - `publish` never
+/// hands the same buffer to two subscribers.
+pub const Message = struct {
+    channel: []u8,
+    payload: []u8,
+
+    pub fn deinit(self: Message, allocator: Allocator) void {
+        allocator.free(self.channel);
+        allocator.free(self.payload);
+    }
+};
+
+/// One subscriber's private mailbox: a bounded FIFO of `Message`s plus the
+/// synchronization a consumer thread needs to block until either a new
+/// message arrives or the subscription is closed. A `Subscriber` is always
+/// created by `Hub.subscribe` and must be retired through
+/// `Hub.closeSubscriber` then `Hub.destroySubscriber`, in that order (see
+/// their doc comments for why the two steps are separate).
+pub const Subscriber = struct {
+    allocator: Allocator,
+    mutex: std.Thread.Mutex = .{},
+    cond: std.Thread.Condition = .{},
+    queue: std.ArrayList(Message),
+    capacity: usize,
+    dropped: usize = 0,
+    closed: bool = false,
+    /// Assigned by `Hub.subscribe` (monotonically increasing per `Hub`
+    /// instance, never reused within its lifetime) so a control connection
+    /// that never saw this `Subscriber`'s pointer - a separate `unsubscribe`
+    /// request, possibly on a different TCP connection entirely - can still
+    /// name it. Only meaningful together with the `Hub` that assigned it;
+    /// not persisted, not unique across process restarts.
+    id: u64 = 0,
+    /// Channel names this subscriber is registered under in whichever `Hub`
+    /// created it - copied here (not just left as entries in
+    /// `Hub.channels`) so `Hub.closeSubscriber`/`Hub.unsubscribe` can find
+    /// every channel to unregister from without the caller having to
+    /// remember the original subscribe list.
+    channels: [][]u8,
+
+    fn init(allocator: Allocator, capacity: usize, channels: [][]u8) Subscriber {
+        return .{
+            .allocator = allocator,
+            .queue = std.ArrayList(Message).init(allocator),
+            .capacity = capacity,
+            .channels = channels,
+        };
+    }
+
+    /// Delivers one message, taking ownership of it. Never blocks: a
+    /// `capacity` of zero drops every message immediately (a legal, if
+    /// degenerate, "nobody's listening yet" mailbox); otherwise, once the
+    /// mailbox is at `capacity`, the oldest queued message is dropped (and
+    /// freed) to make room, `dropped` is incremented, and the new message
+    /// is appended - so `waitMessage` always eventually surfaces the most
+    /// RECENT messages a slow subscriber missed, never the oldest stale
+    /// ones. A message pushed after `close()` is silently freed and does
+    /// not count as delivered or dropped - a closed subscriber is never
+    /// coming back to read it, and `dropped` exists to describe backpressure
+    /// on a live subscriber, not the ordinary end of one.
+    fn push(self: *Subscriber, msg: Message) void {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        if (self.closed) {
+            msg.deinit(self.allocator);
+            return;
+        }
+        if (self.capacity == 0) {
+            msg.deinit(self.allocator);
+            self.dropped += 1;
+            return;
+        }
+        if (self.queue.items.len >= self.capacity) {
+            const old = self.queue.orderedRemove(0);
+            old.deinit(self.allocator);
+            self.dropped += 1;
+        }
+        self.queue.append(msg) catch {
+            msg.deinit(self.allocator);
+            self.dropped += 1;
+            return;
+        };
+        self.cond.signal();
+    }
+
+    /// Blocks until a message is available or the subscription is closed
+    /// with an empty mailbox, whichever happens first. A close with
+    /// messages still queued is drained first - `waitMessage` keeps
+    /// returning them in order before finally returning `null`, so a
+    /// consumer never loses a message that was successfully enqueued
+    /// before `close()` ran. Ownership of the returned `Message` passes to
+    /// the caller, who must `deinit` it.
+    pub fn waitMessage(self: *Subscriber) ?Message {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        while (self.queue.items.len == 0 and !self.closed) {
+            self.cond.wait(&self.mutex);
+        }
+        if (self.queue.items.len == 0) return null;
+        return self.queue.orderedRemove(0);
+    }
+
+    /// Idempotent: marks the mailbox closed and wakes every thread blocked
+    /// in `waitMessage`. Safe to call from any thread, any number of times
+    /// concurrently - a watcher thread noticing a client disconnect and a
+    /// publisher noticing a dead connection can both call it without
+    /// coordinating between themselves.
+    pub fn close(self: *Subscriber) void {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        if (self.closed) return;
+        self.closed = true;
+        self.cond.broadcast();
+    }
+
+    pub fn isClosed(self: *Subscriber) bool {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        return self.closed;
+    }
+
+    pub fn droppedCount(self: *Subscriber) usize {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        return self.dropped;
+    }
+
+    /// Frees the mailbox's own queued messages and the subscriber's
+    /// channel-name copies, then the caller frees the `Subscriber` struct
+    /// itself via `Hub.destroySubscriber`. Only the thread that owns this
+    /// subscriber past its last `waitMessage`/close call may reach this -
+    /// see `Hub.destroySubscriber`'s doc comment for the ownership handoff
+    /// it depends on.
+    fn deinitContents(self: *Subscriber) void {
+        for (self.queue.items) |m| m.deinit(self.allocator);
+        self.queue.deinit();
+        for (self.channels) |c| self.allocator.free(c);
+        self.allocator.free(self.channels);
+    }
+};
+
+/// The channel registry every `Subscriber` is filed under. Completely
+/// independent of `Db` - publish/subscribe never touches storage, so a
+/// `Hub`'s own mutex is never held anywhere near `Db`'s (see `server.zig`'s
+/// `dispatch`, which handles the `subscribe`/`publish` opcodes before it
+/// ever reaches for `Server.mutex`, so a slow or permanently-open
+/// subscriber connection can never stall a read or write against the
+/// store).
+pub const Hub = struct {
+    allocator: Allocator,
+    mutex: std.Thread.Mutex = .{},
+    channels: std.StringHashMap(std.ArrayList(*Subscriber)),
+    /// Every currently-live subscriber, keyed by the `id` `subscribe`
+    /// assigned it - lets `unsubscribe` (see its doc comment) look one up by
+    /// the bare number a client saw in its subscribe ack, without needing
+    /// the original `*Subscriber` pointer, which never crosses a second TCP
+    /// connection. Entries are removed exactly when `closeSubscriber` runs
+    /// (or `unsubscribe` empties a subscriber's channel set and closes it
+    /// itself), so a stale or already-closed id reliably misses here rather
+    /// than risking a dangling pointer.
+    byId: std.AutoHashMap(u64, *Subscriber),
+    nextId: u64 = 0,
+
+    pub fn init(allocator: Allocator) Hub {
+        return .{
+            .allocator = allocator,
+            .channels = std.StringHashMap(std.ArrayList(*Subscriber)).init(allocator),
+            .byId = std.AutoHashMap(u64, *Subscriber).init(allocator),
+        };
+    }
+
+    /// Frees every remaining channel's subscriber list and key copy, and the
+    /// id registry. Does NOT touch any `Subscriber` still registered -
+    /// callers must `closeSubscriber` (which also unregisters, so in an
+    /// orderly shutdown this map is already empty by the time `deinit` runs)
+    /// and `destroySubscriber` every subscriber they created first, the same
+    /// "caller drains, then frees the container" ordering `Db`/`Server`
+    /// already use elsewhere in this codebase.
+    pub fn deinit(self: *Hub) void {
+        var it = self.channels.iterator();
+        while (it.next()) |entry| {
+            entry.value_ptr.deinit();
+            self.allocator.free(entry.key_ptr.*);
+        }
+        self.channels.deinit();
+        self.byId.deinit();
+    }
+
+    /// Creates a new subscriber registered under every name in
+    /// `channelNames` (duplicate names collapse to one registration, so a
+    /// message published on a channel a caller listed twice is still only
+    /// ever delivered once). `capacity` bounds its mailbox (see
+    /// `Subscriber.push`). Returns a pointer the caller must eventually
+    /// pass to `closeSubscriber` then `destroySubscriber`, in that order.
+    pub fn subscribe(self: *Hub, channelNames: []const []const u8, capacity: usize) !*Subscriber {
+        var unique = std.ArrayList([]const u8).init(self.allocator);
+        defer unique.deinit();
+        for (channelNames) |name| {
+            var seen = false;
+            for (unique.items) |u| {
+                if (std.mem.eql(u8, u, name)) {
+                    seen = true;
+                    break;
+                }
+            }
+            if (!seen) try unique.append(name);
+        }
+
+        const owned = try self.allocator.alloc([]u8, unique.items.len);
+        var ownedCount: usize = 0;
+        errdefer {
+            for (owned[0..ownedCount]) |c| self.allocator.free(c);
+            self.allocator.free(owned);
+        }
+        for (unique.items, 0..) |name, i| {
+            owned[i] = try self.allocator.dupe(u8, name);
+            ownedCount += 1;
+        }
+
+        const sub = try self.allocator.create(Subscriber);
+        errdefer self.allocator.destroy(sub);
+        sub.* = Subscriber.init(self.allocator, capacity, owned);
+
+        self.mutex.lock();
+        defer self.mutex.unlock();
+
+        const id = self.nextId;
+        self.nextId += 1;
+        sub.id = id;
+        try self.byId.put(id, sub);
+        errdefer _ = self.byId.remove(id);
+
+        var registered: usize = 0;
+        errdefer {
+            for (owned[0..registered]) |name| {
+                if (self.channels.getPtr(name)) |list| {
+                    for (list.items, 0..) |s, idx| {
+                        if (s == sub) {
+                            _ = list.swapRemove(idx);
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        for (owned) |name| {
+            const gop = try self.channels.getOrPut(name);
+            if (!gop.found_existing) {
+                gop.key_ptr.* = self.allocator.dupe(u8, name) catch |err| {
+                    // The map entry was already inserted with `name`'s
+                    // pointer as a placeholder key by `getOrPut` itself;
+                    // remove it before propagating so `deinit`/`subscribe`
+                    // never iterate over a key pointing into memory this
+                    // function is about to free via `owned`'s errdefer.
+                    _ = self.channels.remove(name);
+                    return err;
+                };
+                gop.value_ptr.* = std.ArrayList(*Subscriber).init(self.allocator);
+            }
+            try gop.value_ptr.append(sub);
+            registered += 1;
+        }
+
+        return sub;
+    }
+
+    /// Stops delivering new messages to `sub` and unregisters it from every
+    /// channel it was subscribed to, wakes any thread blocked in its
+    /// `waitMessage`, and drops a channel's map entry entirely once its
+    /// subscriber list becomes empty (an unsubscribed-from channel is a
+    /// completely normal, permanent steady state, not a reason to keep an
+    /// empty list around forever). Safe to call more than once (from a
+    /// watcher thread and a failed publish both noticing the same dead
+    /// connection, say) - both `Subscriber.close` and the unregister loop
+    /// below are no-ops the second time. Does NOT free `sub` itself - see
+    /// `destroySubscriber`.
+    pub fn closeSubscriber(self: *Hub, sub: *Subscriber) void {
+        sub.close();
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        _ = self.byId.remove(sub.id);
+        for (sub.channels) |name| {
+            if (self.channels.getPtr(name)) |list| {
+                for (list.items, 0..) |s, idx| {
+                    if (s == sub) {
+                        _ = list.swapRemove(idx);
+                        break;
+                    }
+                }
+                if (list.items.len == 0) {
+                    if (self.channels.fetchRemove(name)) |kv| {
+                        kv.value.deinit();
+                        self.allocator.free(kv.key);
+                    }
+                }
+            }
+        }
+    }
+
+    /// Removes every name in `channelNames` from `id`'s subscription set
+    /// without disturbing any channel it stays registered on, so a client
+    /// that subscribed to several channels can drop a subset from a SEPARATE
+    /// connection - the control channel `handleSubscribe`'s doc comment
+    /// says a live subscribe connection can never multiplex further
+    /// requests onto itself. `channelNames` naming a channel `id` was never
+    /// on is harmless and simply does not count toward the returned total
+    /// (matching `publish`-to-an-empty-channel's "no-op, not an error"
+    /// posture). Returns `error.UnknownSubscriber` if `id` names no
+    /// currently-live subscriber - already closed (a normal disconnect
+    /// race, not a caller bug) or never issued (a caller typo) look
+    /// identical from here, both correctly rejected as "there is nothing
+    /// left to unsubscribe."
+    ///
+    /// If this empties `id`'s entire channel set, the subscriber is closed
+    /// outright (`sub.close()`, unregistered from `byId`) rather than left
+    /// alive with nothing left to ever receive - the same terminal state a
+    /// disconnect reaches through `closeSubscriber`, just reached from the
+    /// opposite direction. `handleSubscribe`'s push loop notices this
+    /// exactly like any other close: `sub.waitMessage()` returns `null`, the
+    /// loop ends, and the connection's own `closeSubscriber`/
+    /// `destroySubscriber` pair runs as usual - by then `sub.channels` is
+    /// already empty, so that second `closeSubscriber` call's unregister
+    /// loop simply does nothing (idempotent, like every other double-close
+    /// path in this file).
+    pub fn unsubscribe(self: *Hub, id: u64, channelNames: []const []const u8) !usize {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const sub = self.byId.get(id) orelse return error.UnknownSubscriber;
+
+        var kept = try std.ArrayList([]u8).initCapacity(self.allocator, sub.channels.len);
+        errdefer kept.deinit();
+        var removed: usize = 0;
+        for (sub.channels) |name| {
+            var matches = false;
+            for (channelNames) |target| {
+                if (std.mem.eql(u8, name, target)) {
+                    matches = true;
+                    break;
+                }
+            }
+            if (!matches) {
+                kept.appendAssumeCapacity(name);
+                continue;
+            }
+            removed += 1;
+            if (self.channels.getPtr(name)) |list| {
+                for (list.items, 0..) |s, idx| {
+                    if (s == sub) {
+                        _ = list.swapRemove(idx);
+                        break;
+                    }
+                }
+                if (list.items.len == 0) {
+                    if (self.channels.fetchRemove(name)) |kv| {
+                        kv.value.deinit();
+                        self.allocator.free(kv.key);
+                    }
+                }
+            }
+            self.allocator.free(name);
+        }
+        self.allocator.free(sub.channels);
+        sub.channels = try kept.toOwnedSlice();
+
+        if (sub.channels.len == 0) {
+            _ = self.byId.remove(id);
+            sub.close();
+        }
+        return removed;
+    }
+
+    /// Frees `sub`'s own memory (mailbox contents, channel-name copies, the
+    /// struct itself). Must only be called after `closeSubscriber(sub)` has
+    /// already run and every thread that might still call `sub.waitMessage`/
+    /// `sub.push` (directly or through `publish`) has stopped touching it -
+    /// `closeSubscriber` unregisters `sub` from `Hub.channels` precisely so
+    /// `publish` can never hand this function a dangling pointer to race
+    /// against.
+    pub fn destroySubscriber(self: *Hub, sub: *Subscriber) void {
+        sub.deinitContents();
+        self.allocator.destroy(sub);
+    }
+
+    /// Number of subscribers currently registered under `channel` (0 if it
+    /// has none, including a channel name nobody has ever used). Mainly for
+    /// tests and metrics - `publish` recomputes its own snapshot rather than
+    /// calling this, to avoid taking `self.mutex` twice per publish.
+    pub fn channelSubscriberCount(self: *Hub, channel: []const u8) usize {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        if (self.channels.get(channel)) |list| return list.items.len;
+        return 0;
+    }
+
+    /// Delivers an independent copy of `payload` to every subscriber
+    /// currently registered under `channel`, returning how many subscribers
+    /// it was handed to (0 if the channel currently has none - not an
+    /// error, matching real pub/sub semantics where publishing to an empty
+    /// channel is a routine no-op, not a failure). Never blocks on a slow
+    /// subscriber - see `Subscriber.push`. `allocator` is used only for the
+    /// short-lived snapshot of subscriber pointers, not the per-subscriber
+    /// message copies, which are always allocated from `self.allocator`
+    /// (each subscriber frees its own mailbox contents independently, so
+    /// they must not depend on a caller-supplied allocator outliving this
+    /// call).
+    pub fn publish(self: *Hub, allocator: Allocator, channel: []const u8, payload: []const u8) !usize {
+        self.mutex.lock();
+        errdefer self.mutex.unlock();
+        const subs = if (self.channels.get(channel)) |list| list.items else &[_]*Subscriber{};
+        // Snapshot the subscriber list under the lock, but do the actual
+        // per-subscriber copy+push OUTSIDE it: `Subscriber.push` takes its
+        // own independent mutex, never `self.mutex`, so holding this one
+        // across every subscriber's push would serialize every publish
+        // behind every subscriber's own lock contention for no reason.
+        const snapshot = try allocator.alloc(*Subscriber, subs.len);
+        defer allocator.free(snapshot);
+        @memcpy(snapshot, subs);
+        self.mutex.unlock();
+
+        for (snapshot) |sub| {
+            const channelCopy = self.allocator.dupe(u8, channel) catch continue;
+            const payloadCopy = self.allocator.dupe(u8, payload) catch {
+                self.allocator.free(channelCopy);
+                continue;
+            };
+            sub.push(.{ .channel = channelCopy, .payload = payloadCopy });
+        }
+        return snapshot.len;
+    }
+};
+
+fn destroy(hub: *Hub, sub: *Subscriber) void {
+    hub.closeSubscriber(sub);
+    hub.destroySubscriber(sub);
+}
+
+test "publish delivers a copy to a single subscriber on the channel it named" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"weather"}, defaultCapacity);
+    defer destroy(&hub, sub);
+
+    const delivered = try hub.publish(allocator, "weather", "sunny");
+    try std.testing.expectEqual(@as(usize, 1), delivered);
+
+    const msg = sub.waitMessage().?;
+    defer msg.deinit(allocator);
+    try std.testing.expectEqualStrings("weather", msg.channel);
+    try std.testing.expectEqualStrings("sunny", msg.payload);
+}
+
+test "publish to a channel with no subscribers returns 0 without crashing" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const delivered = try hub.publish(allocator, "nobody-home", "hello");
+    try std.testing.expectEqual(@as(usize, 0), delivered);
+}
+
+test "every subscriber on a channel gets its own independent copy" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const a = try hub.subscribe(&.{"orders"}, defaultCapacity);
+    defer destroy(&hub, a);
+    const b = try hub.subscribe(&.{"orders"}, defaultCapacity);
+    defer destroy(&hub, b);
+
+    const delivered = try hub.publish(allocator, "orders", "order-42");
+    try std.testing.expectEqual(@as(usize, 2), delivered);
+
+    const ma = a.waitMessage().?;
+    defer ma.deinit(allocator);
+    const mb = b.waitMessage().?;
+    defer mb.deinit(allocator);
+    try std.testing.expectEqualStrings("order-42", ma.payload);
+    try std.testing.expectEqualStrings("order-42", mb.payload);
+    // Independent allocations, not aliased - freeing one must not affect
+    // the other's still-valid pointer.
+    try std.testing.expect(ma.payload.ptr != mb.payload.ptr);
+}
+
+test "a subscriber on several channels gets messages tagged with the right channel" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{ "a", "b" }, defaultCapacity);
+    defer destroy(&hub, sub);
+
+    try std.testing.expectEqual(@as(usize, 1), try hub.publish(allocator, "b", "from-b"));
+    try std.testing.expectEqual(@as(usize, 1), try hub.publish(allocator, "a", "from-a"));
+
+    const first = sub.waitMessage().?;
+    defer first.deinit(allocator);
+    try std.testing.expectEqualStrings("b", first.channel);
+    try std.testing.expectEqualStrings("from-b", first.payload);
+
+    const second = sub.waitMessage().?;
+    defer second.deinit(allocator);
+    try std.testing.expectEqualStrings("a", second.channel);
+    try std.testing.expectEqualStrings("from-a", second.payload);
+}
+
+test "subscribing to the same channel name twice still delivers only once" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{ "dup", "dup" }, defaultCapacity);
+    defer destroy(&hub, sub);
+
+    try std.testing.expectEqual(@as(usize, 1), try hub.publish(allocator, "dup", "x"));
+    const msg = sub.waitMessage().?;
+    defer msg.deinit(allocator);
+    // Only one message was ever queued - a second `waitMessage` in a
+    // non-blocking check would hang, so instead assert there is exactly
+    // one by closing right after and expecting a drained-then-null result.
+    sub.close();
+    try std.testing.expect(sub.waitMessage() == null);
+}
+
+test "closing a subscriber unregisters it - a later publish no longer reaches it" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    hub.closeSubscriber(sub);
+
+    try std.testing.expectEqual(@as(usize, 0), try hub.publish(allocator, "ch", "too-late"));
+    try std.testing.expectEqual(@as(usize, 0), hub.channelSubscriberCount("ch"));
+
+    hub.destroySubscriber(sub);
+}
+
+test "waitMessage drains already-queued messages before returning null on close" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    defer hub.destroySubscriber(sub);
+
+    _ = try hub.publish(allocator, "ch", "one");
+    _ = try hub.publish(allocator, "ch", "two");
+    hub.closeSubscriber(sub);
+
+    const m1 = sub.waitMessage().?;
+    defer m1.deinit(allocator);
+    try std.testing.expectEqualStrings("one", m1.payload);
+    const m2 = sub.waitMessage().?;
+    defer m2.deinit(allocator);
+    try std.testing.expectEqualStrings("two", m2.payload);
+    try std.testing.expect(sub.waitMessage() == null);
+}
+
+test "a full mailbox drops the oldest message, not the newest" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, 2);
+    defer destroy(&hub, sub);
+
+    _ = try hub.publish(allocator, "ch", "1");
+    _ = try hub.publish(allocator, "ch", "2");
+    _ = try hub.publish(allocator, "ch", "3");
+    try std.testing.expectEqual(@as(usize, 1), sub.droppedCount());
+
+    const m1 = sub.waitMessage().?;
+    defer m1.deinit(allocator);
+    try std.testing.expectEqualStrings("2", m1.payload);
+    const m2 = sub.waitMessage().?;
+    defer m2.deinit(allocator);
+    try std.testing.expectEqualStrings("3", m2.payload);
+}
+
+test "capacity zero drops every message without ever panicking" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, 0);
+    defer destroy(&hub, sub);
+
+    _ = try hub.publish(allocator, "ch", "gone");
+    _ = try hub.publish(allocator, "ch", "also-gone");
+    try std.testing.expectEqual(@as(usize, 2), sub.droppedCount());
+    sub.close();
+    try std.testing.expect(sub.waitMessage() == null);
+}
+
+test "closing a subscriber wakes a thread already blocked in waitMessage" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    defer hub.destroySubscriber(sub);
+
+    const Waiter = struct {
+        fn run(s: *Subscriber, result: *?Message) void {
+            result.* = s.waitMessage();
+        }
+    };
+    var result: ?Message = undefined;
+    result = Message{ .channel = &.{}, .payload = &.{} };
+    const t = try std.Thread.spawn(.{}, Waiter.run, .{ sub, &result });
+    hub.closeSubscriber(sub);
+    t.join();
+    try std.testing.expect(result == null);
+}
+
+test "publishing after closeSubscriber but before destroySubscriber never touches freed memory" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    hub.closeSubscriber(sub);
+    // The channel entry is gone entirely now (empty list cleanup), so this
+    // publish must find zero subscribers rather than dereferencing `sub`.
+    try std.testing.expectEqual(@as(usize, 0), try hub.publish(allocator, "ch", "x"));
+    hub.destroySubscriber(sub);
+}
+
+test "concurrent publishers hammering one subscriber deliver every message intact" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const publisherCount = 4;
+    const perPublisher = 200;
+    const sub = try hub.subscribe(&.{"ch"}, publisherCount * perPublisher);
+    defer destroy(&hub, sub);
+
+    const Publisher = struct {
+        fn run(h: *Hub, alloc: Allocator, tag: usize) void {
+            var buf: [32]u8 = undefined;
+            var i: usize = 0;
+            while (i < perPublisher) : (i += 1) {
+                const text = std.fmt.bufPrint(&buf, "{d}:{d}", .{ tag, i }) catch unreachable;
+                _ = h.publish(alloc, "ch", text) catch unreachable;
+            }
+        }
+    };
+
+    var threads: [publisherCount]std.Thread = undefined;
+    for (0..publisherCount) |i| {
+        threads[i] = try std.Thread.spawn(.{}, Publisher.run, .{ &hub, allocator, i });
+    }
+    for (threads) |t| t.join();
+
+    try std.testing.expectEqual(@as(usize, 0), sub.droppedCount());
+
+    var seenPerTag = [_]usize{0} ** publisherCount;
+    var total: usize = 0;
+    while (sub.waitMessage()) |msg| {
+        defer msg.deinit(allocator);
+        total += 1;
+        var it = std.mem.splitScalar(u8, msg.payload, ':');
+        const tag = std.fmt.parseInt(usize, it.next().?, 10) catch unreachable;
+        seenPerTag[tag] += 1;
+        if (total == publisherCount * perPublisher) break;
+    }
+    try std.testing.expectEqual(@as(usize, publisherCount * perPublisher), total);
+    for (seenPerTag) |count| try std.testing.expectEqual(@as(usize, perPublisher), count);
+}
+
+test "subscribe leaves nothing registered when it fails partway through" {
+    var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 });
+    var hub = Hub.init(failing.allocator());
+    defer hub.deinit();
+
+    try std.testing.expectError(error.OutOfMemory, hub.subscribe(&.{ "a", "b", "c", "d" }, defaultCapacity));
+    // Nothing should be left registered anywhere after the unwind.
+    try std.testing.expectEqual(@as(usize, 0), hub.channelSubscriberCount("a"));
+    try std.testing.expectEqual(@as(usize, 0), hub.channelSubscriberCount("b"));
+}
+
+test "push under memory pressure drops the message and counts it instead of leaking" {
+    var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 });
+    const allocator = failing.allocator();
+    const channels = try std.testing.allocator.alloc([]u8, 0);
+    var sub = Subscriber.init(allocator, defaultCapacity, channels);
+    defer sub.deinitContents();
+
+    const channel = try std.testing.allocator.dupe(u8, "ch");
+    const payload = try std.testing.allocator.dupe(u8, "x");
+    sub.push(.{ .channel = channel, .payload = payload });
+
+    try std.testing.expectEqual(@as(usize, 1), sub.droppedCount());
+    try std.testing.expectEqual(@as(usize, 0), sub.queue.items.len);
+}
+
+test "publish tolerates an out-of-memory snapshot allocation without leaking" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    defer destroy(&hub, sub);
+
+    var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 });
+    try std.testing.expectError(error.OutOfMemory, hub.publish(failing.allocator(), "ch", "x"));
+}
+
+test "subscribe assigns each subscriber a distinct, increasing id" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const a = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    defer destroy(&hub, a);
+    const b = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    defer destroy(&hub, b);
+
+    try std.testing.expect(a.id != b.id);
+    try std.testing.expect(b.id > a.id);
+}
+
+test "unsubscribe from a subset of channels leaves the rest delivering" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{ "weather", "orders", "alerts" }, defaultCapacity);
+    defer destroy(&hub, sub);
+
+    const removed = try hub.unsubscribe(sub.id, &.{"orders"});
+    try std.testing.expectEqual(@as(usize, 1), removed);
+
+    try std.testing.expectEqual(@as(usize, 0), try hub.publish(allocator, "orders", "too-late"));
+    try std.testing.expectEqual(@as(usize, 1), try hub.publish(allocator, "weather", "sunny"));
+    try std.testing.expectEqual(@as(usize, 1), try hub.publish(allocator, "alerts", "fire"));
+
+    const m1 = sub.waitMessage().?;
+    defer m1.deinit(allocator);
+    try std.testing.expectEqualStrings("sunny", m1.payload);
+    const m2 = sub.waitMessage().?;
+    defer m2.deinit(allocator);
+    try std.testing.expectEqualStrings("fire", m2.payload);
+
+    // The channel-name registry itself must not have been disturbed, so a
+    // brand new subscriber can still register under the vacated channel.
+    try std.testing.expectEqual(@as(usize, 0), hub.channelSubscriberCount("orders"));
+    try std.testing.expectEqual(@as(usize, 1), hub.channelSubscriberCount("weather"));
+}
+
+test "unsubscribe naming a channel the subscriber was never on counts zero, no error" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"weather"}, defaultCapacity);
+    defer destroy(&hub, sub);
+
+    const removed = try hub.unsubscribe(sub.id, &.{"nonexistent"});
+    try std.testing.expectEqual(@as(usize, 0), removed);
+    try std.testing.expectEqual(@as(usize, 1), try hub.publish(allocator, "weather", "still-here"));
+    const msg = sub.waitMessage().?;
+    defer msg.deinit(allocator);
+}
+
+test "unsubscribe from every remaining channel closes the subscriber outright" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{ "a", "b" }, defaultCapacity);
+    defer hub.destroySubscriber(sub);
+
+    const removed = try hub.unsubscribe(sub.id, &.{ "a", "b" });
+    try std.testing.expectEqual(@as(usize, 2), removed);
+
+    try std.testing.expect(sub.isClosed());
+    try std.testing.expect(sub.waitMessage() == null);
+    try std.testing.expectEqual(@as(usize, 0), hub.channelSubscriberCount("a"));
+    try std.testing.expectEqual(@as(usize, 0), hub.channelSubscriberCount("b"));
+
+    // The id is gone too - a second unsubscribe by the same id must not
+    // find a dangling subscriber.
+    try std.testing.expectError(error.UnknownSubscriber, hub.unsubscribe(sub.id, &.{"a"}));
+
+    // Mirrors the normal disconnect path: `closeSubscriber` still runs
+    // afterward (e.g. from `handleSubscribe`'s push loop noticing the
+    // close) and must be a harmless no-op over an already-empty channel set.
+    hub.closeSubscriber(sub);
+}
+
+test "unsubscribe wakes a thread already blocked in waitMessage when it empties the set" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    defer hub.destroySubscriber(sub);
+
+    const Waiter = struct {
+        fn run(s: *Subscriber, result: *?Message) void {
+            result.* = s.waitMessage();
+        }
+    };
+    var result: ?Message = undefined;
+    result = Message{ .channel = &.{}, .payload = &.{} };
+    const t = try std.Thread.spawn(.{}, Waiter.run, .{ sub, &result });
+    _ = try hub.unsubscribe(sub.id, &.{"ch"});
+    t.join();
+    try std.testing.expect(result == null);
+}
+
+test "unsubscribe rejects an id nobody ever issued" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    try std.testing.expectError(error.UnknownSubscriber, hub.unsubscribe(999, &.{"ch"}));
+}
+
+test "closeSubscriber removes the id, so a later unsubscribe by that id is rejected" {
+    const allocator = std.testing.allocator;
+    var hub = Hub.init(allocator);
+    defer hub.deinit();
+
+    const sub = try hub.subscribe(&.{"ch"}, defaultCapacity);
+    const id = sub.id;
+    hub.closeSubscriber(sub);
+    defer hub.destroySubscriber(sub);
+
+    try std.testing.expectError(error.UnknownSubscriber, hub.unsubscribe(id, &.{"ch"}));
+}
diff --git a/src/query.zig b/src/query.zig
new file mode 100644
index 0000000..f91a6d4
--- /dev/null
+++ b/src/query.zig
@@ -0,0 +1,3868 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+const rowmod = @import("row.zig");
+const idx = @import("index.zig");
+const exprmod = @import("expr.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Value = rowmod.Value;
+const Row = rowmod.Row;
+const Field = rowmod.Field;
+const IndexSet = idx.IndexSet;
+const CompositeIndexSet = idx.CompositeIndexSet;
+const CompositeIndexSpec = idx.CompositeIndexSpec;
+const UniqueSet = idx.UniqueSet;
+const ForeignKeySet = idx.ForeignKeySet;
+const CheckConstraintSet = idx.CheckConstraintSet;
+const ReferencedBySet = idx.ReferencedBySet;
+
+/// Reserved field name a Table stores the primary key under, so a decoded
+/// Row is self-sufficient for callers that only have the Row (e.g. results
+/// of a full table scan) without needing to separately decode it from the
+/// row key's escaped ordered bytes.
+pub const pkField = "__pk";
+
+pub const Condition = struct {
+    field: []const u8,
+    value: Value,
+};
+
+/// Paging window for `Table.selectPage`: skip the first `offset` matches,
+/// return at most `limit` of them (0 = unlimited).
+pub const Page = struct {
+    offset: usize = 0,
+    limit: usize = 0,
+};
+
+/// One column of a `Table.selectPageOrdered` sort key: order matched rows
+/// by `field` (via `rowmod.compare`'s total order across value types). A
+/// row missing `field` entirely sorts as `Value.none`, which `compare`
+/// places before every other tag - so rows lacking the sort column
+/// consistently group at the front (ascending) or back (descending)
+/// instead of erroring. `selectPageOrdered` takes a `[]const OrderBy`
+/// (empty = unsorted): columns after the first only break ties left by
+/// the ones before them, the same lexicographic rule SQL's `ORDER BY a, b`
+/// follows - the sort is stable, so a `[]const OrderBy` with a single
+/// entry that leaves ties unresolved behaves exactly as before this type
+/// gained multi-column support (rows keep their relative scan order:
+/// ascending pk for a full scan, index order for an indexed lookup).
+pub const OrderBy = struct {
+    field: []const u8,
+    descending: bool = false,
+};
+
+/// Which access strategy `Table.selectPage` would take for a given
+/// predicate, as reported by `Table.explain`. Mirrors the three real
+/// branches of `selectPage`'s decision ladder: an unindexed full scan, a
+/// single-field index (`eq` narrows to one key, `lt`/`lte`/`gt`/`gte`
+/// narrow to a range), or a composite index matched on a leftmost prefix
+/// of its columns (`_eq` when the prefix is the whole match, `_range` when
+/// the column right after the prefix also had a range bound).
+pub const PlanKind = enum(u8) {
+    full_scan,
+    index_eq,
+    index_range,
+    composite_eq,
+    composite_range,
+};
+
+/// `indexName` is an owned copy the caller must free with `Plan.deinit` -
+/// null (and `matchedFields`/`totalFields` both 0) for `.full_scan`, which
+/// names no index. For `.index_eq`/`.index_range` it is the single indexed
+/// field name and `matchedFields == totalFields == 1`. For
+/// `.composite_eq`/`.composite_range` it is the composite index's name and
+/// `matchedFields` counts how many of the index's `totalFields` leading
+/// columns the query actually pinned down (a strict prefix match still
+/// narrows the scan, same leftmost-prefix rule a real multi-column B-tree
+/// index gives you).
+pub const Plan = struct {
+    kind: PlanKind,
+    indexName: ?[]const u8 = null,
+    matchedFields: usize = 0,
+    totalFields: usize = 0,
+
+    pub fn deinit(self: *Plan, allocator: Allocator) void {
+        if (self.indexName) |n| allocator.free(n);
+        self.* = undefined;
+    }
+};
+
+/// Predicate AST evaluated against a decoded Row. Leaves compare a named
+/// field to a literal Value; And/Or/Not compose leaves and other predicates.
+/// Predicate does not own the memory of any Value or field-name slice it
+/// references - callers must keep those alive for as long as the predicate
+/// tree is used.
+pub const Predicate = union(enum) {
+    eq: Condition,
+    ne: Condition,
+    lt: Condition,
+    lte: Condition,
+    gt: Condition,
+    gte: Condition,
+    like: Condition,
+    /// True when `field` is absent from the row entirely, or present but
+    /// holding an explicit `Value.none` - a sparse row's "never set" and a
+    /// row that set the field to none are indistinguishable to a caller
+    /// asking "does this row have a real value here", same as SQL NULL.
+    is_null: []const u8,
+    is_not_null: []const u8,
+    and_: []const Predicate,
+    or_: []const Predicate,
+    not_: *const Predicate,
+
+    fn isNullish(v: ?Value) bool {
+        const val = v orelse return true;
+        return val == .none;
+    }
+
+    pub fn evaluate(self: Predicate, row: *const Row) bool {
+        return switch (self) {
+            .eq => |c| if (row.get(c.field)) |v| rowmod.compare(v, c.value) == .eq else false,
+            .ne => |c| if (row.get(c.field)) |v| rowmod.compare(v, c.value) != .eq else true,
+            .lt => |c| if (row.get(c.field)) |v| rowmod.compare(v, c.value) == .lt else false,
+            .lte => |c| if (row.get(c.field)) |v| rowmod.compare(v, c.value) != .gt else false,
+            .gt => |c| if (row.get(c.field)) |v| rowmod.compare(v, c.value) == .gt else false,
+            .gte => |c| if (row.get(c.field)) |v| rowmod.compare(v, c.value) != .lt else false,
+            .like => |c| blk: {
+                const rowVal = row.get(c.field) orelse break :blk false;
+                if (rowVal != .text or c.value != .text) break :blk false;
+                break :blk matchLike(c.value.text, rowVal.text);
+            },
+            .is_null => |field| isNullish(row.get(field)),
+            .is_not_null => |field| !isNullish(row.get(field)),
+            .and_ => |preds| blk: {
+                for (preds) |p| {
+                    if (!p.evaluate(row)) break :blk false;
+                }
+                break :blk true;
+            },
+            .or_ => |preds| blk: {
+                for (preds) |p| {
+                    if (p.evaluate(row)) break :blk true;
+                }
+                break :blk false;
+            },
+            .not_ => |p| !p.evaluate(row),
+        };
+    }
+};
+
+/// SQL-style LIKE matching: `%` matches any run of characters (including
+/// none), `_` matches exactly one character, every other byte in `pattern`
+/// must match `text` literally. No escape character - a pattern that needs a
+/// literal `%`/`_` cannot express it, same simplification `expr.zig`'s other
+/// operators already make (no escaping in the predicate language at all).
+/// Iterative two-pointer wildcard matcher (not recursive backtracking) so a
+/// pattern like "a%a%a%a%a%a%b" against a long non-matching text stays
+/// linear-ish instead of exponential: on mismatch after a `%`, only the
+/// text pointer rewinds-and-retries, the pattern never re-walks from
+/// scratch.
+fn matchLike(pattern: []const u8, text: []const u8) bool {
+    var pIdx: usize = 0;
+    var tIdx: usize = 0;
+    var starIdx: ?usize = null;
+    var matchIdx: usize = 0;
+
+    while (tIdx < text.len) {
+        if (pIdx < pattern.len and (pattern[pIdx] == '_' or pattern[pIdx] == text[tIdx])) {
+            pIdx += 1;
+            tIdx += 1;
+        } else if (pIdx < pattern.len and pattern[pIdx] == '%') {
+            starIdx = pIdx;
+            matchIdx = tIdx;
+            pIdx += 1;
+        } else if (starIdx) |si| {
+            pIdx = si + 1;
+            matchIdx += 1;
+            tIdx = matchIdx;
+        } else {
+            return false;
+        }
+    }
+    while (pIdx < pattern.len and pattern[pIdx] == '%') : (pIdx += 1) {}
+    return pIdx == pattern.len;
+}
+
+test "matchLike handles literal, wildcard, and single-char patterns" {
+    try std.testing.expect(matchLike("warsaw", "warsaw"));
+    try std.testing.expect(!matchLike("warsaw", "krakow"));
+    try std.testing.expect(matchLike("", ""));
+    try std.testing.expect(!matchLike("a", ""));
+    try std.testing.expect(matchLike("%", "anything"));
+    try std.testing.expect(matchLike("%", ""));
+    try std.testing.expect(matchLike("A%", "Ada"));
+    try std.testing.expect(!matchLike("A%", "Boris"));
+    try std.testing.expect(matchLike("%son", "Johnson"));
+    try std.testing.expect(!matchLike("%son", "Sonata"));
+    try std.testing.expect(matchLike("%ada%", "the ada language"));
+    try std.testing.expect(matchLike("_da", "ada"));
+    try std.testing.expect(!matchLike("_da", "aada"));
+    try std.testing.expect(matchLike("a_a_a", "ababa"));
+    try std.testing.expect(matchLike("%a%b%c%", "xaxxbxxxcx"));
+    try std.testing.expect(!matchLike("%a%b%c%", "xxbxxxax"));
+    try std.testing.expect(matchLike("a%%a", "aXYZa"));
+}
+
+/// A table is a named partition of a single Db's keyspace (see index.zig for
+/// the exact key layout) plus a set of secondary indexes maintained on
+/// write. Rows are whole-row replace semantics: `put` fully overwrites
+/// whatever was stored at `pk`, syncing every registered index against the
+/// old and new field values in the same call.
+/// Composite indexes are capped at this many columns: generous for any
+/// realistic multi-column index while keeping the planner's per-spec match
+/// buffer (see `findCompositeMatch`) a fixed-size stack array.
+pub const maxCompositeFields = 8;
+
+pub const Table = struct {
+    db: *Db,
+    allocator: Allocator,
+    name: []u8,
+    indexes: IndexSet,
+    composite: CompositeIndexSet,
+    unique: UniqueSet,
+    foreignKeys: ForeignKeySet,
+    checks: CheckConstraintSet,
+
+    pub fn open(db: *Db, allocator: Allocator, name: []const u8) !Table {
+        if (!idx.validIdentifier(name)) return error.InvalidIdentifier;
+        return .{
+            .db = db,
+            .allocator = allocator,
+            .name = try allocator.dupe(u8, name),
+            .indexes = try IndexSet.load(allocator, db, name),
+            .composite = try CompositeIndexSet.load(allocator, db, name),
+            .unique = try UniqueSet.load(allocator, db, name),
+            .foreignKeys = try ForeignKeySet.load(allocator, db, name),
+            .checks = try CheckConstraintSet.load(allocator, db, name),
+        };
+    }
+
+    pub fn deinit(self: *Table) void {
+        self.allocator.free(self.name);
+        self.indexes.deinit();
+        self.composite.deinit();
+        self.unique.deinit();
+        self.foreignKeys.deinit();
+        self.checks.deinit();
+    }
+
+    pub fn createIndex(self: *Table, field: []const u8) !void {
+        if (!idx.validIdentifier(field)) return error.InvalidIdentifier;
+        if (self.indexes.has(field)) return;
+
+        // Backfill: every existing row's current value for `field` becomes
+        // an index entry before the index is advertised as usable.
+        const rows = try self.scanAll();
+        defer freeRows(self.allocator, rows);
+        for (rows) |*r| {
+            const pk = r.get(pkField) orelse continue;
+            const value = r.get(field) orelse continue;
+            try idx.addEntry(self.db, self.allocator, self.name, field, value, pk);
+        }
+
+        try self.indexes.add(field);
+        try self.indexes.save(self.db, self.name);
+    }
+
+    /// Dropping an index also drops any UNIQUE constraint riding on it -
+    /// `Table.put`'s constraint check relies on the field's index entries
+    /// existing (see `createUniqueIndex`), so a unique field with no
+    /// index left behind would silently stop being enforced instead of
+    /// erroring, which is worse than making the drop explicit here.
+    pub fn dropIndex(self: *Table, field: []const u8) !void {
+        if (!self.indexes.remove(field)) return;
+        try idx.dropAllEntries(self.db, self.allocator, self.name, field);
+        try self.indexes.save(self.db, self.name);
+        if (self.unique.remove(field)) try self.unique.save(self.db, self.name);
+    }
+
+    pub fn hasIndex(self: *const Table, field: []const u8) bool {
+        return self.indexes.has(field);
+    }
+
+    pub fn hasUniqueIndex(self: *const Table, field: []const u8) bool {
+        return self.unique.has(field);
+    }
+
+    /// Installs a UNIQUE constraint on `field` - SQL's `CREATE UNIQUE
+    /// INDEX`. Refuses outright if the table already holds two rows with
+    /// the same (non-null) value for `field`: existing data always wins
+    /// over a constraint that could never have held for it, exactly like
+    /// a real database refusing to add a unique index over dirty data.
+    /// Backfills the plain secondary index too when it is not already
+    /// present, since `put`'s duplicate check below is a `scanEq` against
+    /// those very index entries rather than a full table scan - a unique
+    /// field with no backing index would make every write pay for a full
+    /// scan just to enforce the constraint.
+    pub fn createUniqueIndex(self: *Table, field: []const u8) !void {
+        if (!idx.validIdentifier(field)) return error.InvalidIdentifier;
+        if (self.unique.has(field)) return;
+
+        const rows = try self.scanAll();
+        defer freeRows(self.allocator, rows);
+
+        {
+            var seen = std.StringHashMap(void).init(self.allocator);
+            defer {
+                var it = seen.keyIterator();
+                while (it.next()) |k| self.allocator.free(k.*);
+                seen.deinit();
+            }
+            for (rows) |*r| {
+                const value = r.get(field) orelse continue;
+                var encoded = std.ArrayList(u8).init(self.allocator);
+                defer encoded.deinit();
+                try rowmod.appendOrdered(&encoded, value);
+                if (seen.contains(encoded.items)) return error.UniqueViolation;
+                const owned = try self.allocator.dupe(u8, encoded.items);
+                errdefer self.allocator.free(owned);
+                try seen.put(owned, {});
+            }
+        }
+
+        if (!self.indexes.has(field)) {
+            for (rows) |*r| {
+                const pk = r.get(pkField) orelse continue;
+                const value = r.get(field) orelse continue;
+                try idx.addEntry(self.db, self.allocator, self.name, field, value, pk);
+            }
+            try self.indexes.add(field);
+            try self.indexes.save(self.db, self.name);
+        }
+
+        try self.unique.add(field);
+        try self.unique.save(self.db, self.name);
+    }
+
+    pub fn hasForeignKey(self: *const Table, field: []const u8) bool {
+        return self.foreignKeys.has(field);
+    }
+
+    /// Whether `value` names an existing row of `spec.refTable` under
+    /// `spec.refField` - `query.pkField` is checked via a plain `get`
+    /// (the primary key is inherently unique, no secondary index needed),
+    /// anything else via `idx.scanEq` against `spec.refTable`'s own index
+    /// entries (required to carry a UNIQUE constraint by
+    /// `Table.createForeignKey`, so at most one owner is expected here -
+    /// this only asks "does at least one exist", not "is it exactly one",
+    /// since a constraint installed correctly can only ever produce zero or
+    /// one).
+    fn foreignKeyTargetExists(self: *Table, refTableName: []const u8, refField: []const u8, value: Value) !bool {
+        if (std.mem.eql(u8, refField, pkField)) {
+            var refTable = try Table.open(self.db, self.allocator, refTableName);
+            defer refTable.deinit();
+            var found = try refTable.get(value) orelse return false;
+            found.deinit();
+            return true;
+        }
+        const owners = try idx.scanEq(self.db, self.allocator, refTableName, refField, value);
+        defer {
+            for (owners) |v| v.free(self.allocator);
+            self.allocator.free(owners);
+        }
+        return owners.len > 0;
+    }
+
+    /// Installs a FOREIGN KEY constraint: every row's (non-null) `field`
+    /// value must, from this point on, name a value that exists as
+    /// `refField` on `refTable` - SQL's `FOREIGN KEY (field) REFERENCES
+    /// refTable(refField)`. `refField` must be either `pkField` or a field
+    /// already carrying `refTable`'s own UNIQUE constraint (see
+    /// `foreignKeyTargetExists`'s doc comment for why); anything else is
+    /// refused with `error.ForeignKeyRequiresUniqueTarget` before touching
+    /// any row, the same "refuse before mutating" shape `createUniqueIndex`
+    /// uses for dirty data. Existing rows are checked against the target
+    /// before the constraint is recorded - a row whose current `field`
+    /// value has no matching parent aborts the whole install with
+    /// `error.ForeignKeyViolation`, leaving nothing installed.
+    ///
+    /// Registers the reverse relationship in `refTable`'s own
+    /// `ReferencedBySet` (see its doc comment) so `Table.delete` can later
+    /// enforce `onDelete` against it (SQL's `ON DELETE RESTRICT` or `ON
+    /// DELETE CASCADE`, see `idx.OnDelete`'s doc comment) - this used to be
+    /// a documented, unfixed gap ("no registry of dependent tables exists,
+    /// since tables are opened ad hoc by name and never catalogued
+    /// anywhere") before `ReferencedBySet` closed it.
+    ///
+    /// `onDelete` only governs `Table.delete`/`Table.deleteWhere`'s plain
+    /// (non-transactional) path - `txn_table.zig`'s `TableTxn.delete` reads
+    /// the same `ReferencedBySet` but does not look at this field at all,
+    /// so it continues to unconditionally restrict any delete that would
+    /// orphan a reference even for a `cascade` constraint. That is a
+    /// deliberately conservative gap, not an oversight: refusing is always
+    /// a safe fallback for a feature that has not been built yet, whereas
+    /// silently NOT cascading inside a transaction would leave a dangling
+    /// reference behind. Only `Table.put`'s `updateRestrictedByForeignKey`
+    /// check is unaffected by `onDelete` in EITHER path - there is no `ON
+    /// UPDATE CASCADE` here, so a value change under a live reference is
+    /// always restricted regardless of the FK's delete mode.
+    ///
+    /// Known gap that registry does NOT close, same documented-rather-
+    /// than-fixed shape as `TableTxn`'s missing composite/unique
+    /// enforcement: nothing here stops a later `refTable.dropIndex
+    /// (refField)` from removing the UNIQUE constraint this foreign key
+    /// depends on - doing so leaves the constraint silently checking
+    /// against an unconstrained (possibly duplicate-holding) column via
+    /// `scanEq`, which still answers "does at least one owner exist"
+    /// correctly but no longer guarantees at most one.
+    pub fn createForeignKey(self: *Table, field: []const u8, refTable: []const u8, refField: []const u8, onDelete: idx.OnDelete) !void {
+        if (!idx.validIdentifier(field)) return error.InvalidIdentifier;
+        if (!idx.validIdentifier(refTable)) return error.InvalidIdentifier;
+        if (!idx.validIdentifier(refField)) return error.InvalidIdentifier;
+        if (self.foreignKeys.has(field)) return;
+
+        if (!std.mem.eql(u8, refField, pkField)) {
+            var ref = try Table.open(self.db, self.allocator, refTable);
+            defer ref.deinit();
+            if (!ref.hasUniqueIndex(refField)) return error.ForeignKeyRequiresUniqueTarget;
+        }
+
+        const rows = try self.scanAll();
+        defer freeRows(self.allocator, rows);
+        for (rows) |*r| {
+            const value = r.get(field) orelse continue;
+            if (value == .none) continue;
+            if (!try self.foreignKeyTargetExists(refTable, refField, value)) return error.ForeignKeyViolation;
+        }
+
+        try self.foreignKeys.add(field, refTable, refField, onDelete);
+        try self.foreignKeys.save(self.db, self.name);
+
+        // Records the reverse relationship on `refTable` so a later delete
+        // against it (see `Table.delete`'s RESTRICT check) can discover
+        // this constraint without a global table catalog - see
+        // `ReferencedBySet`'s doc comment. Loaded, mutated, and saved
+        // transiently rather than cached on a `Table` field: unlike
+        // `foreignKeys`/`unique`/`checks` (always mutated through the same
+        // handle that holds them), `referencedBy` is mutated as a side
+        // effect of some OTHER table's `createForeignKey`/`dropForeignKey`
+        // call - a `refTable` handle the CALLER already has open (the
+        // ordinary "open customers, open orders, wire up the FK between
+        // them" shape) would otherwise go stale the moment this runs,
+        // silently under-enforcing every delete against it thereafter.
+        // Works unchanged for a self-referencing FK (`refTable ==
+        // self.name`) too, since it never touches `self`'s own cached
+        // sets at all - it only ever reads/writes `refTable`'s on-disk
+        // entry by name.
+        var revSet = try ReferencedBySet.load(self.allocator, self.db, refTable);
+        defer revSet.deinit();
+        try revSet.add(self.name, field, refField, onDelete);
+        try revSet.save(self.db, refTable);
+    }
+
+    /// Lifts a FOREIGN KEY and its reverse `ReferencedBySet` entry on
+    /// whichever table it pointed at, symmetric with `createForeignKey`
+    /// installing both. The target's name is copied out before
+    /// `self.foreignKeys.remove` frees the spec's own strings, since the
+    /// reverse cleanup below still needs it afterwards. See
+    /// `createForeignKey`'s doc comment on why the reverse entry is always
+    /// loaded/saved transiently rather than through a cached `Table` field.
+    pub fn dropForeignKey(self: *Table, field: []const u8) !void {
+        const existing = self.foreignKeys.find(field) orelse return;
+        const refTable = try self.allocator.dupe(u8, existing.refTable);
+        defer self.allocator.free(refTable);
+
+        _ = self.foreignKeys.remove(field);
+        try self.foreignKeys.save(self.db, self.name);
+
+        var revSet = try ReferencedBySet.load(self.allocator, self.db, refTable);
+        defer revSet.deinit();
+        _ = revSet.remove(self.name, field);
+        try revSet.save(self.db, refTable);
+    }
+
+    pub fn hasCheckConstraint(self: *const Table, name: []const u8) bool {
+        return self.checks.has(name);
+    }
+
+    /// Installs a named CHECK constraint - SQL's `CHECK (source)` - built on
+    /// the exact same predicate language `table select`/`table join` already
+    /// use (`expr.zig`'s recursive-descent parser over `Predicate`). `source`
+    /// is parsed once up front so a typo is rejected before anything is
+    /// persisted (`error.InvalidCheckExpression` wraps any `expr.ParseError`,
+    /// since a caller that only sees this constraint's name/source has no use
+    /// for which specific parse error fired), then evaluated against every
+    /// existing row - the same "refuse before mutating, existing data always
+    /// wins" shape `createUniqueIndex`/`createForeignKey` use, so installing
+    /// a CHECK that current data already violates fails outright rather than
+    /// silently starting to enforce only from the next write on.
+    pub fn createCheckConstraint(self: *Table, name: []const u8, source: []const u8) !void {
+        if (!idx.validIdentifier(name)) return error.InvalidIdentifier;
+        if (self.checks.has(name)) return;
+
+        var parsed = exprmod.parse(self.allocator, source) catch return error.InvalidCheckExpression;
+        defer parsed.deinit();
+
+        const rows = try self.scanAll();
+        defer freeRows(self.allocator, rows);
+        for (rows) |*r| {
+            if (!parsed.predicate.evaluate(r)) return error.CheckViolation;
+        }
+
+        try self.checks.add(name, source);
+        try self.checks.save(self.db, self.name);
+    }
+
+    pub fn dropCheckConstraint(self: *Table, name: []const u8) !void {
+        if (!self.checks.remove(name)) return;
+        try self.checks.save(self.db, self.name);
+    }
+
+    /// Creates a multi-column secondary index named `name` over `fields`, in
+    /// order - order matters, since only a leading ("leftmost") prefix of it
+    /// can be used to narrow a query (see `findCompositeMatch`). Rows
+    /// missing any of the fields are skipped entirely, both here and when
+    /// staying in sync on `put`/`delete`, since a composite entry with a
+    /// missing column would not be a well-formed tuple.
+    pub fn createCompositeIndex(self: *Table, name: []const u8, fields: []const []const u8) !void {
+        if (!idx.validIdentifier(name)) return error.InvalidIdentifier;
+        if (fields.len < 2 or fields.len > maxCompositeFields) return error.InvalidCompositeIndex;
+        for (fields) |f| if (!idx.validIdentifier(f)) return error.InvalidIdentifier;
+        if (self.composite.has(name)) return;
+
+        const rows = try self.scanAll();
+        defer freeRows(self.allocator, rows);
+        var values: [maxCompositeFields]Value = undefined;
+        for (rows) |*r| {
+            const pk = r.get(pkField) orelse continue;
+            var complete = true;
+            for (fields, 0..) |f, i| {
+                values[i] = r.get(f) orelse {
+                    complete = false;
+                    break;
+                };
+            }
+            if (!complete) continue;
+            try idx.addCompositeEntry(self.db, self.allocator, self.name, name, values[0..fields.len], pk);
+        }
+
+        try self.composite.add(name, fields);
+        try self.composite.save(self.db, self.name);
+    }
+
+    pub fn dropCompositeIndex(self: *Table, name: []const u8) !void {
+        if (!self.composite.remove(name)) return;
+        try idx.dropAllCompositeEntries(self.db, self.allocator, self.name, name);
+        try self.composite.save(self.db, self.name);
+    }
+
+    pub fn hasCompositeIndex(self: *const Table, name: []const u8) bool {
+        return self.composite.has(name);
+    }
+
+    /// Fully replaces the row stored at `pk` with `fields`, syncing every
+    /// registered secondary index against whatever the row held before.
+    pub fn put(self: *Table, pk: Value, fields: []const Field) !void {
+        var old = try self.get(pk);
+        defer if (old) |*o| o.deinit();
+
+        var newRow = Row.init(self.allocator);
+        defer newRow.deinit();
+        try newRow.set(pkField, pk);
+        for (fields) |f| try newRow.set(f.name, f.value);
+
+        const encoded = try newRow.encode(self.allocator);
+        defer self.allocator.free(encoded);
+        const key = try idx.rowKey(self.allocator, self.name, pk);
+        defer self.allocator.free(key);
+
+        // CHECK constraints run first, ahead of UNIQUE/FOREIGN KEY and any
+        // index or row mutation - a row that fails a CHECK never gets far
+        // enough to matter whether it would also have violated UNIQUE, same
+        // "cheapest, purely-local check first" ordering a real database
+        // uses. Re-parsed from source on every put (no cached Predicate is
+        // kept on Table), the same cost `table select`/`table join` already
+        // pay for their own expr text on every call.
+        for (self.checks.specs.items) |spec| {
+            var parsed = exprmod.parse(self.allocator, spec.source) catch return error.InvalidCheckExpression;
+            defer parsed.deinit();
+            if (!parsed.predicate.evaluate(&newRow)) return error.CheckViolation;
+        }
+
+        // UNIQUE constraint check runs before any index or row mutation
+        // below, so a violation leaves everything untouched - the same
+        // all-or-nothing shape callers already get from a plain `put`
+        // either succeeding outright or failing outright. A field that
+        // did not change value from the row's own previous value is
+        // exempt (it already legitimately owns that value), which is why
+        // updating unrelated fields on a row that already holds a unique
+        // value never spuriously conflicts with itself.
+        for (self.unique.fields.items) |field| {
+            const newValue = newRow.get(field) orelse continue;
+            const oldValue = if (old) |*o| o.get(field) else null;
+            if (oldValue != null and Value.eql(oldValue.?, newValue)) continue;
+            const owners = try idx.scanEq(self.db, self.allocator, self.name, field, newValue);
+            defer {
+                for (owners) |v| v.free(self.allocator);
+                self.allocator.free(owners);
+            }
+            for (owners) |ownerPk| {
+                if (!Value.eql(ownerPk, pk)) return error.UniqueViolation;
+            }
+        }
+
+        // FOREIGN KEY check, same "before any mutation" placement as UNIQUE
+        // above. Unlike UNIQUE, an unchanged value is NOT exempt: nothing in
+        // this codebase stops the referenced row from having been deleted
+        // out from under an already-valid reference since the last write
+        // (no catalog of dependent tables exists to block that delete - see
+        // `Table.createForeignKey`'s doc comment), so every put re-checks
+        // every constrained field's current target rather than trusting a
+        // value that merely did not change this time.
+        for (self.foreignKeys.specs.items) |spec| {
+            const newValue = newRow.get(spec.field) orelse continue;
+            if (newValue == .none) continue;
+            if (!try self.foreignKeyTargetExists(spec.refTable, spec.refField, newValue)) return error.ForeignKeyViolation;
+        }
+
+        // ON DELETE RESTRICT's update-side counterpart, see
+        // `updateRestrictedByForeignKey`'s doc comment - must run before any
+        // index or row mutation below, same all-or-nothing placement as
+        // every other constraint check in this function.
+        if (try self.updateRestrictedByForeignKey(pk, if (old) |*o| o else null, &newRow)) return error.ForeignKeyInUse;
+
+        for (self.indexes.fields.items) |indexedField| {
+            const newValue = newRow.get(indexedField);
+            const oldValue = if (old) |*o| o.get(indexedField) else null;
+            if (oldValue != null and (newValue == null or !Value.eql(oldValue.?, newValue.?))) {
+                try idx.removeEntry(self.db, self.allocator, self.name, indexedField, oldValue.?, pk);
+            }
+            if (newValue) |nv| {
+                if (oldValue == null or !Value.eql(oldValue.?, nv)) {
+                    try idx.addEntry(self.db, self.allocator, self.name, indexedField, nv, pk);
+                }
+            }
+        }
+
+        for (self.composite.specs.items) |spec| {
+            var oldValues: [maxCompositeFields]Value = undefined;
+            var oldComplete = old != null;
+            if (old) |*o| {
+                for (spec.fields, 0..) |f, i| {
+                    oldValues[i] = o.get(f) orelse {
+                        oldComplete = false;
+                        break;
+                    };
+                }
+            }
+            var newValues: [maxCompositeFields]Value = undefined;
+            var newComplete = true;
+            for (spec.fields, 0..) |f, i| {
+                newValues[i] = newRow.get(f) orelse {
+                    newComplete = false;
+                    break;
+                };
+            }
+            const unchanged = oldComplete and newComplete and valueTupleEql(oldValues[0..spec.fields.len], newValues[0..spec.fields.len]);
+            if (unchanged) continue;
+            if (oldComplete) try idx.removeCompositeEntry(self.db, self.allocator, self.name, spec.name, oldValues[0..spec.fields.len], pk);
+            if (newComplete) try idx.addCompositeEntry(self.db, self.allocator, self.name, spec.name, newValues[0..spec.fields.len], pk);
+        }
+
+        try self.db.put(key, encoded);
+    }
+
+    pub fn get(self: *Table, pk: Value) !?Row {
+        const key = try idx.rowKey(self.allocator, self.name, pk);
+        defer self.allocator.free(key);
+        const raw = try self.db.get(self.allocator, key) orelse return null;
+        defer self.allocator.free(raw);
+        return try Row.decode(self.allocator, raw);
+    }
+
+    /// One (table, pk) a cascading delete has decided to remove, in the
+    /// order `planCascade` discovered it - deepest dependents first, the
+    /// row that was actually asked for last. Owns copies of both fields
+    /// independently of whatever `Row`/`Table` produced them, since the
+    /// scan that found them is long gone (and possibly a different
+    /// `Table` handle entirely) by the time `delete` executes the plan.
+    const CascadeAction = struct {
+        table: []u8,
+        pk: Value,
+
+        fn deinit(self: *const CascadeAction, allocator: Allocator) void {
+            allocator.free(self.table);
+            self.pk.free(allocator);
+        }
+    };
+
+    /// Cycle guard for `planCascade`: every (table, pk) already visited
+    /// this call, so a cascade that loops back on itself (two tables
+    /// `ON DELETE CASCADE`-ing at each other, or a longer cycle through
+    /// three or more) terminates instead of recursing forever. Linear
+    /// scan is fine here - a cascading delete's fan-out is bounded by how
+    /// much data actually exists, and this runs once per row touched, not
+    /// once per row scanned.
+    const CascadeVisited = struct {
+        allocator: Allocator,
+        entries: std.ArrayList(CascadeAction),
+
+        fn init(allocator: Allocator) CascadeVisited {
+            return .{ .allocator = allocator, .entries = std.ArrayList(CascadeAction).init(allocator) };
+        }
+
+        fn contains(self: *const CascadeVisited, table: []const u8, pk: Value) bool {
+            for (self.entries.items) |e| {
+                if (std.mem.eql(u8, e.table, table) and Value.eql(e.pk, pk)) return true;
+            }
+            return false;
+        }
+
+        fn add(self: *CascadeVisited, table: []const u8, pk: Value) !void {
+            const tableCopy = try self.allocator.dupe(u8, table);
+            errdefer self.allocator.free(tableCopy);
+            const pkCopy = try pk.dupe(self.allocator);
+            try self.entries.append(.{ .table = tableCopy, .pk = pkCopy });
+        }
+
+        fn deinit(self: *CascadeVisited) void {
+            for (self.entries.items) |e| e.deinit(self.allocator);
+            self.entries.deinit();
+        }
+    };
+
+    /// Recursively works out everything a delete of `pk` must remove,
+    /// WITHOUT deleting anything yet, appending each decision to `plan` in
+    /// dependent-before-dependency order (see `CascadeAction`'s doc
+    /// comment) so `delete` can execute it leaves-first. This two-phase
+    /// plan/execute split is what keeps a cascading delete all-or-nothing:
+    /// a `restrict`-mode violation discovered three levels deep must abort
+    /// with NOTHING mutated, exactly like the single-table check this
+    /// replaced - if planning and deleting were interleaved, an earlier
+    /// sibling subtree could already be gone by the time a later one fails.
+    ///
+    /// For every `ReferencedBySet` entry naming a table with a live row
+    /// pointing at `old`'s value for the referenced field (see the
+    /// previous version of this function for why the child is opened and
+    /// scanned in full rather than through `idx.scanEq`, and why a
+    /// self-referencing FK excludes `pk` itself from matching): `restrict`
+    /// aborts the whole plan with `error.ForeignKeyInUse`; `cascade`
+    /// recurses into that child row first, so it lands in `plan` ahead of
+    /// `self` (a child must be gone before its parent is, or the delete
+    /// order would itself violate the very constraint being enforced).
+    ///
+    /// `visited` is checked (and updated) BEFORE any of that per-row work,
+    /// so a cycle (`planCascade(A)` reaching `planCascade(B)` reaching
+    /// `planCascade(A)` again) short-circuits the re-entrant call instead
+    /// of looping - the ORIGINAL call for that (table, pk) is still the one
+    /// that appends it to `plan`, once its own scan finishes, so nothing is
+    /// silently dropped from the plan by the cycle.
+    fn planCascade(self: *Table, pk: Value, visited: *CascadeVisited, plan: *std.ArrayList(CascadeAction)) !void {
+        if (visited.contains(self.name, pk)) return;
+        var old = try self.get(pk) orelse return;
+        defer old.deinit();
+        try visited.add(self.name, pk);
+
+        var referencedBy = try ReferencedBySet.load(self.allocator, self.db, self.name);
+        defer referencedBy.deinit();
+        for (referencedBy.specs.items) |spec| {
+            const value = old.get(spec.refField) orelse continue;
+            if (value == .none) continue;
+
+            var child = try Table.open(self.db, self.allocator, spec.childTable);
+            defer child.deinit();
+            const rows = try child.scanAll();
+            defer freeRows(self.allocator, rows);
+            const selfReferencing = std.mem.eql(u8, spec.childTable, self.name);
+            for (rows) |*r| {
+                if (selfReferencing) {
+                    if (r.get(pkField)) |rowPk| {
+                        if (Value.eql(rowPk, pk)) continue;
+                    }
+                }
+                const childValue = r.get(spec.childField) orelse continue;
+                if (childValue == .none) continue;
+                if (!Value.eql(childValue, value)) continue;
+
+                switch (spec.onDelete) {
+                    .restrict => return error.ForeignKeyInUse,
+                    .cascade => {
+                        const childPk = r.get(pkField) orelse continue;
+                        try child.planCascade(childPk, visited, plan);
+                    },
+                }
+            }
+        }
+
+        try plan.append(.{ .table = try self.allocator.dupe(u8, self.name), .pk = try pk.dupe(self.allocator) });
+    }
+
+    /// The actual row/index removal `delete` used to do inline before
+    /// cascading existed - no FOREIGN KEY check here at all, since by the
+    /// time this runs `planCascade` has already proven the entire plan is
+    /// safe to execute in order. Takes `pk` rather than a decoded row
+    /// because `CascadeAction` only carries the two, and re-fetching here
+    /// (rather than threading the `Row` `planCascade` already read) is
+    /// what lets `delete` stay tolerant of a row that no longer exists by
+    /// execution time - unreachable in practice (nothing between planning
+    /// and executing can delete a row out from under this single-threaded
+    /// call), but cheap to make robust to rather than to assume away.
+    fn executeDelete(self: *Table, pk: Value) !void {
+        var old = try self.get(pk) orelse return;
+        defer old.deinit();
+
+        for (self.indexes.fields.items) |indexedField| {
+            if (old.get(indexedField)) |v| {
+                try idx.removeEntry(self.db, self.allocator, self.name, indexedField, v, pk);
+            }
+        }
+
+        for (self.composite.specs.items) |spec| {
+            var values: [maxCompositeFields]Value = undefined;
+            var complete = true;
+            for (spec.fields, 0..) |f, i| {
+                values[i] = old.get(f) orelse {
+                    complete = false;
+                    break;
+                };
+            }
+            if (complete) try idx.removeCompositeEntry(self.db, self.allocator, self.name, spec.name, values[0..spec.fields.len], pk);
+        }
+
+        const key = try idx.rowKey(self.allocator, self.name, pk);
+        defer self.allocator.free(key);
+        try self.db.delete(key);
+    }
+
+    /// SQL's `ON DELETE RESTRICT`/`CASCADE` (see `planCascade` above) has an
+    /// easy-to-miss counterpart: this codebase never leaves a child dangling
+    /// when its parent ROW disappears, but until now nothing stopped a `put`
+    /// from changing the parent's *value* out from under a still-live child -
+    /// `refTable.dropIndex(refField)` and `updateWhere`/direct `put` changing
+    /// a `refField` are exactly the "carpet pulled from under the child"
+    /// cases `createForeignKey`'s own doc comment already named as open
+    /// gaps. Reuses the identical scan and self-reference exclusion as
+    /// `planCascade` (a value that stops existing under this pk is exactly
+    /// as dangerous to a live reference as a row that stops existing
+    /// entirely), but the trigger is "this pk's value for `refField` is
+    /// about to change", not "this pk is about to be deleted" - so `old` may
+    /// be null (a fresh insert has nothing to pull out from under anyone)
+    /// and a field whose new value equals its old value is exempt, the same
+    /// "unchanged is always safe" exemption `put`'s own UNIQUE check makes.
+    /// Unlike `planCascade`, this ALWAYS restricts regardless of the
+    /// constraint's `onDelete` mode - there is no `ON UPDATE CASCADE` here,
+    /// only `ON DELETE CASCADE`, so even a `cascade`-mode FK still blocks a
+    /// value change under a live reference.
+    fn updateRestrictedByForeignKey(self: *Table, pk: Value, old: ?*const Row, newRow: *const Row) !bool {
+        var referencedBy = try ReferencedBySet.load(self.allocator, self.db, self.name);
+        defer referencedBy.deinit();
+        for (referencedBy.specs.items) |spec| {
+            const oldValue = if (old) |o| o.get(spec.refField) else null;
+            if (oldValue == null or oldValue.? == .none) continue;
+            const newValue = newRow.get(spec.refField);
+            if (newValue != null and Value.eql(oldValue.?, newValue.?)) continue;
+
+            var child = try Table.open(self.db, self.allocator, spec.childTable);
+            defer child.deinit();
+            const rows = try child.scanAll();
+            defer freeRows(self.allocator, rows);
+            const selfReferencing = std.mem.eql(u8, spec.childTable, self.name);
+            for (rows) |*r| {
+                if (selfReferencing) {
+                    if (r.get(pkField)) |rowPk| {
+                        if (Value.eql(rowPk, pk)) continue;
+                    }
+                }
+                const childValue = r.get(spec.childField) orelse continue;
+                if (childValue == .none) continue;
+                if (Value.eql(childValue, oldValue.?)) return true;
+            }
+        }
+        return false;
+    }
+
+    /// Deletes `pk`, honoring every `ON DELETE` mode registered against
+    /// this table by some OTHER table's `createForeignKey` (see
+    /// `idx.OnDelete`'s doc comment): a `restrict`-mode reference still
+    /// pointing at this row aborts the whole call with
+    /// `error.ForeignKeyInUse` and nothing is mutated; a `cascade`-mode
+    /// one instead removes the referencing rows too, recursively, before
+    /// this row itself goes - see `planCascade`'s doc comment for why
+    /// that has to happen in two passes (plan every removal first, then
+    /// execute the plan) rather than deleting as it discovers each one.
+    /// A `pk` that does not exist is a silent no-op, same as before
+    /// cascading existed.
+    pub fn delete(self: *Table, pk: Value) !void {
+        var visited = CascadeVisited.init(self.allocator);
+        defer visited.deinit();
+        var plan = std.ArrayList(CascadeAction).init(self.allocator);
+        defer {
+            for (plan.items) |a| a.deinit(self.allocator);
+            plan.deinit();
+        }
+
+        try self.planCascade(pk, &visited, &plan);
+
+        for (plan.items) |action| {
+            var t = try Table.open(self.db, self.allocator, action.table);
+            defer t.deinit();
+            try t.executeDelete(action.pk);
+        }
+    }
+
+    /// Applies `sets` on top of every row matching `pred` (or every row, if
+    /// null) - SQL's `UPDATE <table> SET ... WHERE pred`. Deliberately not a
+    /// bespoke in-place mutation path: each match is merged with `sets`
+    /// (a `set` entry overrides a same-named existing field, or is appended
+    /// if the row does not have that field yet) and written back through
+    /// `put`, the exact same call an external caller doing `get` then `put`
+    /// by hand would make - so every secondary/composite index touched by a
+    /// changed field is maintained exactly like any other write, with zero
+    /// special-casing here. Uses `selectAllMatches` rather than `selectPage`
+    /// because every match must be visited regardless of any page window -
+    /// there is no `LIMIT` on an `UPDATE`. Returns the number of rows
+    /// updated.
+    pub fn updateWhere(self: *Table, pred: ?Predicate, sets: []const Field) !usize {
+        const matches = try self.selectAllMatches(pred);
+        defer freeRows(self.allocator, matches);
+
+        for (matches) |*row| {
+            const pk = row.get(pkField) orelse continue;
+
+            var merged = Row.init(self.allocator);
+            defer merged.deinit();
+            for (row.fields.items) |f| {
+                if (std.mem.eql(u8, f.name, pkField)) continue;
+                try merged.set(f.name, f.value);
+            }
+            for (sets) |f| try merged.set(f.name, f.value);
+
+            try self.put(pk, merged.fields.items);
+        }
+        return matches.len;
+    }
+
+    /// Deletes every row matching `pred` (or every row, if null) - SQL's
+    /// `DELETE FROM <table> WHERE pred`. Mirrors `updateWhere`: materializes
+    /// the full match set with `selectAllMatches` (a `DELETE` has no
+    /// `LIMIT` either, so partial-scan short-circuiting is wrong here same
+    /// as for update) then removes each match through the existing single-row
+    /// `delete`, so every secondary/composite index touched by the deleted
+    /// row is maintained exactly like a caller doing `get` then `delete` by
+    /// hand would - zero special-casing. Returns the number of rows deleted.
+    pub fn deleteWhere(self: *Table, pred: ?Predicate) !usize {
+        const matches = try self.selectAllMatches(pred);
+        defer freeRows(self.allocator, matches);
+
+        for (matches) |*row| {
+            const pk = row.get(pkField) orelse continue;
+            try self.delete(pk);
+        }
+        return matches.len;
+    }
+
+    /// Full table scan decoding every row, oldest key order. Callers own the
+    /// returned slice and each Row in it (see freeRows).
+    pub fn scanAll(self: *Table) ![]Row {
+        const prefix = try idx.rowPrefix(self.allocator, self.name);
+        defer self.allocator.free(prefix);
+
+        var results = std.ArrayList(Row).init(self.allocator);
+        errdefer {
+            for (results.items) |*r| r.deinit();
+            results.deinit();
+        }
+
+        var it = try self.db.scanPrefix(self.allocator, prefix);
+        defer it.deinit();
+        while (try it.next()) |entry| {
+            const decoded = try Row.decode(self.allocator, entry.value);
+            try results.append(decoded);
+        }
+        return results.toOwnedSlice();
+    }
+
+    /// Selects rows matching `pred` (or every row, if null). When `pred` is
+    /// a single indexed condition, or an And containing one, the matching
+    /// index is used to build a narrowed candidate set before the full
+    /// predicate is re-checked against each candidate row - so results are
+    /// always correct even though the optimization only ever inspects one
+    /// conjunct's index.
+    pub fn select(self: *Table, pred: ?Predicate) ![]Row {
+        return self.selectPage(pred, .{});
+    }
+
+    /// Same as `select`, but skips the first `page.offset` matches and stops
+    /// once `page.limit` matches have been collected (0 = unlimited, the
+    /// same convention `protocol.ScanArgs` uses). Both the full-scan and
+    /// index-narrowed paths stop iterating as soon as the limit is met
+    /// instead of materializing the whole match set first - a real
+    /// efficiency win for `LIMIT`-bounded queries against large tables, not
+    /// just a post-hoc slice of an already-full result.
+    pub fn selectPage(self: *Table, pred: ?Predicate, page: Page) ![]Row {
+        if (pred) |p| {
+            if (self.findCompositeMatch(p)) |match| {
+                const cursor = try self.compositeCursorForMatch(match);
+                return self.selectByIndexPage(p, cursor, page);
+            }
+            if (self.findIndexableLeaf(p)) |leaf| {
+                const cursor = try self.cursorForLeaf(leaf);
+                return self.selectByIndexPage(p, cursor, page);
+            }
+        }
+        return self.scanFilteredPage(pred, page);
+    }
+
+    /// Same as `selectPage`, but sorts the matches by `orderBy` (when
+    /// non-empty, one or more columns applied left to right - see
+    /// `OrderBy`'s doc comment) before applying `page`'s offset/limit
+    /// window. `selectPage`'s early-stop optimization (dropping a full scan
+    /// or index cursor the moment `page.limit` matches are collected) is
+    /// only correct when results come out in the strategy's natural order -
+    /// sorting requires the full match set first, so an `orderBy` request
+    /// materializes every match via `selectAllMatches` (still using
+    /// whichever index `explain` would report, just without the early
+    /// stop), sorts it, then slices the requested window with
+    /// `applyRowPage`. An empty `orderBy` falls straight through to
+    /// `selectPage`, keeping the early-stop behavior unchanged for the
+    /// common unordered case.
+    pub fn selectPageOrdered(self: *Table, pred: ?Predicate, page: Page, orderBy: []const OrderBy) ![]Row {
+        if (orderBy.len == 0) return self.selectPage(pred, page);
+        const all = try self.selectAllMatches(pred);
+        errdefer freeRows(self.allocator, all);
+        sortRowsBy(all, orderBy);
+        return applyRowPage(self.allocator, all, page);
+    }
+
+    /// Collects every row matching `pred`, unpaged - the same
+    /// index-vs-full-scan strategy choice `selectPage`/`explain` make,
+    /// just always run to completion instead of stopping at a page limit.
+    fn selectAllMatches(self: *Table, pred: ?Predicate) ![]Row {
+        if (pred) |p| {
+            if (self.findCompositeMatch(p)) |match| {
+                const cursor = try self.compositeCursorForMatch(match);
+                return self.selectByIndexPage(p, cursor, .{});
+            }
+            if (self.findIndexableLeaf(p)) |leaf| {
+                const cursor = try self.cursorForLeaf(leaf);
+                return self.selectByIndexPage(p, cursor, .{});
+            }
+        }
+        return self.scanFilteredPage(pred, .{});
+    }
+
+    /// Reports which strategy `selectPage` would pick for `pred` without
+    /// running it - the exact same decision ladder (composite match first,
+    /// then a single-field indexable leaf, then a full scan), just stopping
+    /// one step short of building a cursor. Exists so a caller (the CLI's
+    /// `table explain`, its network/repl mirrors) can answer "would this
+    /// query use an index" without materializing rows or mutating anything,
+    /// which is why this takes `*const Table` unlike `selectPage`.
+    pub fn explain(self: *const Table, allocator: Allocator, pred: ?Predicate) !Plan {
+        if (pred) |p| {
+            if (self.findCompositeMatch(p)) |match| {
+                const spec = self.composite.specs.items[match.specIdx];
+                const isRange = match.rangeLow != null or match.rangeHigh != null;
+                return .{
+                    .kind = if (isRange) .composite_range else .composite_eq,
+                    .indexName = try allocator.dupe(u8, spec.name),
+                    .matchedFields = match.matchedLen,
+                    .totalFields = spec.fields.len,
+                };
+            }
+            if (self.findIndexableLeaf(p)) |leaf| {
+                const field = switch (leaf) {
+                    .eq, .lt, .lte, .gt, .gte => |c| c.field,
+                    else => unreachable,
+                };
+                const isRange = switch (leaf) {
+                    .lt, .lte, .gt, .gte => true,
+                    else => false,
+                };
+                return .{
+                    .kind = if (isRange) .index_range else .index_eq,
+                    .indexName = try allocator.dupe(u8, field),
+                    .matchedFields = 1,
+                    .totalFields = 1,
+                };
+            }
+        }
+        return .{ .kind = .full_scan };
+    }
+
+    fn scanFilteredPage(self: *Table, pred: ?Predicate, page: Page) ![]Row {
+        const prefix = try idx.rowPrefix(self.allocator, self.name);
+        defer self.allocator.free(prefix);
+
+        var results = std.ArrayList(Row).init(self.allocator);
+        errdefer {
+            for (results.items) |*r| r.deinit();
+            results.deinit();
+        }
+
+        var skipped: usize = 0;
+        var it = try self.db.scanPrefix(self.allocator, prefix);
+        defer it.deinit();
+        while (try it.next()) |entry| {
+            var decoded = try Row.decode(self.allocator, entry.value);
+            const matches = if (pred) |p| p.evaluate(&decoded) else true;
+            if (!matches) {
+                decoded.deinit();
+                continue;
+            }
+            if (skipped < page.offset) {
+                skipped += 1;
+                decoded.deinit();
+                continue;
+            }
+            try results.append(decoded);
+            if (page.limit != 0 and results.items.len >= page.limit) break;
+        }
+        return results.toOwnedSlice();
+    }
+
+    /// Streams primary keys straight from the index cursor instead of first
+    /// materializing the whole candidate list (see `idx.EqCursor`/
+    /// `idx.RangeCursor`): once `page.limit` rows are collected the
+    /// underlying `Db` scan is simply dropped without decoding or even
+    /// reading whatever index entries would have come after it, which
+    /// matters when the indexed value has far more matches than the page
+    /// being asked for.
+    fn selectByIndexPage(self: *Table, p: Predicate, cursorIn: IndexCursor, page: Page) ![]Row {
+        var cursor = cursorIn;
+        defer cursor.deinit();
+
+        var results = std.ArrayList(Row).init(self.allocator);
+        errdefer {
+            for (results.items) |*r| r.deinit();
+            results.deinit();
+        }
+        var skipped: usize = 0;
+        while (try cursor.next(self.allocator)) |pk| {
+            defer pk.free(self.allocator);
+            var r = try self.get(pk) orelse continue;
+            if (!p.evaluate(&r)) {
+                r.deinit();
+                continue;
+            }
+            if (skipped < page.offset) {
+                skipped += 1;
+                r.deinit();
+                continue;
+            }
+            try results.append(r);
+            if (page.limit != 0 and results.items.len >= page.limit) break;
+        }
+        return results.toOwnedSlice();
+    }
+
+    fn findIndexableLeaf(self: *const Table, p: Predicate) ?Predicate {
+        switch (p) {
+            .eq, .lt, .lte, .gt, .gte => |c| {
+                if (self.indexes.has(c.field)) return p;
+                return null;
+            },
+            .and_ => |preds| {
+                for (preds) |sub| {
+                    if (self.findIndexableLeaf(sub)) |found| return found;
+                }
+                return null;
+            },
+            else => return null,
+        }
+    }
+
+    /// Streaming counterpart of the old `pksForLeaf` (which returned a fully
+    /// materialized `[]Value`): wraps whichever `idx` cursor constructor
+    /// matches the leaf's comparison so `selectByIndexPage` can decode and
+    /// discard candidates one at a time.
+    const IndexCursor = union(enum) {
+        eq: idx.EqCursor,
+        range: idx.RangeCursor,
+        compositeEq: idx.CompositeEqCursor,
+        compositeRange: idx.CompositeRangeCursor,
+
+        fn next(self: *IndexCursor, allocator: Allocator) !?Value {
+            return switch (self.*) {
+                .eq => |*c| c.next(allocator),
+                .range => |*c| c.next(allocator),
+                .compositeEq => |*c| c.next(allocator),
+                .compositeRange => |*c| c.next(allocator),
+            };
+        }
+
+        fn deinit(self: *IndexCursor) void {
+            switch (self.*) {
+                .eq => |*c| c.deinit(),
+                .range => |*c| c.deinit(),
+                .compositeEq => |*c| c.deinit(),
+                .compositeRange => |*c| c.deinit(),
+            }
+        }
+    };
+
+    fn cursorForLeaf(self: *Table, leaf: Predicate) !IndexCursor {
+        return switch (leaf) {
+            .eq => |c| .{ .eq = try idx.scanEqCursor(self.db, self.allocator, self.name, c.field, c.value) },
+            .lt => |c| .{ .range = try idx.scanRangeCursor(self.db, self.allocator, self.name, c.field, null, .{ .value = c.value, .inclusive = false }) },
+            .lte => |c| .{ .range = try idx.scanRangeCursor(self.db, self.allocator, self.name, c.field, null, .{ .value = c.value, .inclusive = true }) },
+            .gt => |c| .{ .range = try idx.scanRangeCursor(self.db, self.allocator, self.name, c.field, .{ .value = c.value, .inclusive = false }, null) },
+            .gte => |c| .{ .range = try idx.scanRangeCursor(self.db, self.allocator, self.name, c.field, .{ .value = c.value, .inclusive = true }, null) },
+            else => unreachable,
+        };
+    }
+
+    const CompositeMatch = struct {
+        specIdx: usize,
+        values: [maxCompositeFields]Value,
+        matchedLen: usize,
+        // A range condition on the column immediately after the matched
+        // eq prefix (spec.fields[matchedLen]), if the predicate has one -
+        // same leftmost-prefix rule a real multi-column B-tree range scan
+        // follows: only the column right after the pinned prefix can be
+        // range-bound by the index, anything further is unconstrained.
+        rangeLow: ?idx.Bound = null,
+        rangeHigh: ?idx.Bound = null,
+    };
+
+    /// Looks for a composite index whose leading ("leftmost") columns are
+    /// all pinned down by a top-level `eq` conjunct somewhere in `p` (an
+    /// `and_`, in any order - unlike a real SQL planner this does not
+    /// recurse into nested and_/or_, matching `findIndexableLeaf`'s scope).
+    /// The match may cover a strict prefix of the index's columns, not
+    /// necessarily all of them: a query naming only the first K of N
+    /// indexed fields still gets a narrowed lookup, same leftmost-prefix
+    /// rule a multi-column B-tree index gives you. When the column right
+    /// after the matched prefix also has a top-level lt/lte/gt/gte conjunct
+    /// on it, that becomes a range bound narrowing the scan further instead
+    /// of leaving it unconstrained. `selectByIndexPage` re-evaluates the
+    /// full predicate against every candidate row regardless, so an
+    /// unmatched suffix of columns (or any other conjunct entirely) never
+    /// affects correctness, only how much the index narrows the scan.
+    fn findCompositeMatch(self: *const Table, p: Predicate) ?CompositeMatch {
+        const preds = switch (p) {
+            .and_ => |ps| ps,
+            else => return null,
+        };
+        for (self.composite.specs.items, 0..) |spec, si| {
+            var values: [maxCompositeFields]Value = undefined;
+            var matched: usize = 0;
+            for (spec.fields) |f| {
+                const found = for (preds) |leaf| {
+                    if (leaf == .eq and std.mem.eql(u8, leaf.eq.field, f)) break leaf.eq.value;
+                } else null;
+                const v = found orelse break;
+                values[matched] = v;
+                matched += 1;
+            }
+            if (matched == 0) continue;
+
+            var rangeLow: ?idx.Bound = null;
+            var rangeHigh: ?idx.Bound = null;
+            if (matched < spec.fields.len) {
+                const nextField = spec.fields[matched];
+                for (preds) |leaf| {
+                    switch (leaf) {
+                        .gt => |c| if (std.mem.eql(u8, c.field, nextField)) {
+                            rangeLow = .{ .value = c.value, .inclusive = false };
+                        },
+                        .gte => |c| if (std.mem.eql(u8, c.field, nextField)) {
+                            rangeLow = .{ .value = c.value, .inclusive = true };
+                        },
+                        .lt => |c| if (std.mem.eql(u8, c.field, nextField)) {
+                            rangeHigh = .{ .value = c.value, .inclusive = false };
+                        },
+                        .lte => |c| if (std.mem.eql(u8, c.field, nextField)) {
+                            rangeHigh = .{ .value = c.value, .inclusive = true };
+                        },
+                        else => {},
+                    }
+                }
+            }
+            return .{ .specIdx = si, .values = values, .matchedLen = matched, .rangeLow = rangeLow, .rangeHigh = rangeHigh };
+        }
+        return null;
+    }
+
+    fn compositeCursorForMatch(self: *Table, match: CompositeMatch) !IndexCursor {
+        const spec = self.composite.specs.items[match.specIdx];
+        const eqValues = match.values[0..match.matchedLen];
+        if (match.rangeLow != null or match.rangeHigh != null) {
+            return .{ .compositeRange = try idx.scanCompositeRangeCursor(self.db, self.allocator, self.name, spec.name, eqValues, match.rangeLow, match.rangeHigh) };
+        }
+        return .{ .compositeEq = try idx.scanCompositeEqCursor(self.db, self.allocator, self.name, spec.name, eqValues) };
+    }
+};
+
+fn valueTupleEql(a: []const Value, b: []const Value) bool {
+    if (a.len != b.len) return false;
+    for (a, b) |av, bv| {
+        if (!Value.eql(av, bv)) return false;
+    }
+    return true;
+}
+
+pub fn freeRows(allocator: Allocator, rows: []Row) void {
+    for (rows) |*r| r.deinit();
+    allocator.free(rows);
+}
+
+/// Stable in-place sort of `rows` by `order`, using `rowmod.compare`'s
+/// total order across value types (see `OrderBy`'s doc comment for how a
+/// missing field sorts). Columns are compared left to right: the first
+/// entry decides unless it ties (`.eq`), in which case the next entry
+/// breaks the tie, and so on - a plain lexicographic comparator chain, the
+/// same rule SQL's `ORDER BY a, b, c` follows. `std.sort.block` rather than
+/// the faster unstable `std.sort.pdq` specifically so ties that survive
+/// every column preserve scan order, matching what `OrderBy`'s doc comment
+/// promises callers.
+fn sortRowsBy(rows: []Row, order: []const OrderBy) void {
+    const Ctx = struct {
+        order: []const OrderBy,
+
+        fn lessThan(ctx: @This(), a: Row, b: Row) bool {
+            for (ctx.order) |ob| {
+                const av = a.get(ob.field) orelse Value{ .none = {} };
+                const bv = b.get(ob.field) orelse Value{ .none = {} };
+                const cmp = rowmod.compare(av, bv);
+                if (cmp == .eq) continue;
+                return if (ob.descending) cmp == .gt else cmp == .lt;
+            }
+            return false;
+        }
+    };
+    std.sort.block(Row, rows, Ctx{ .order = order }, Ctx.lessThan);
+}
+
+/// Slices an already-materialized, unpaged match set (as `selectAllMatches`
+/// returns) down to `page`'s offset/limit window, freeing every row that
+/// falls outside it and the original backing allocation - the ordered
+/// counterpart of the early-stop windowing `selectByIndexPage`/
+/// `scanFilteredPage` do inline while scanning. `rows` must not be used
+/// after this call regardless of error (see `errdefer` at the call site).
+fn applyRowPage(allocator: Allocator, rows: []Row, page: Page) ![]Row {
+    const start = @min(page.offset, rows.len);
+    const end = if (page.limit == 0) rows.len else @min(rows.len, start + page.limit);
+    for (rows[0..start]) |*r| r.deinit();
+    for (rows[end..]) |*r| r.deinit();
+    const kept = rows[start..end];
+    const out = try allocator.alloc(Row, kept.len);
+    @memcpy(out, kept);
+    allocator.free(rows);
+    return out;
+}
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+    return Db.open(allocator, dbPath, .{});
+}
+
+test "table put get delete round trip" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "name", .value = .{ .text = "ada" } },
+        .{ .name = "age", .value = .{ .int = 36 } },
+    });
+
+    var got = (try table.get(.{ .int = 1 })).?;
+    defer got.deinit();
+    try std.testing.expectEqualStrings("ada", got.get("name").?.text);
+    try std.testing.expectEqual(@as(i64, 36), got.get("age").?.int);
+    try std.testing.expectEqual(@as(i64, 1), got.get(pkField).?.int);
+
+    try table.delete(.{ .int = 1 });
+    try std.testing.expect((try table.get(.{ .int = 1 })) == null);
+}
+
+test "table put replaces whole row" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "name", .value = .{ .text = "ada" } },
+        .{ .name = "age", .value = .{ .int = 36 } },
+    });
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "name", .value = .{ .text = "ada" } },
+    });
+
+    var got = (try table.get(.{ .int = 1 })).?;
+    defer got.deinit();
+    try std.testing.expect(got.get("age") == null);
+    try std.testing.expectEqualStrings("ada", got.get("name").?.text);
+}
+
+test "createIndex backfills then eq select uses index" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    try table.createIndex("city");
+    try std.testing.expect(table.hasIndex("city"));
+
+    const results = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 2), results.len);
+}
+
+test "like predicate filters by pattern and never uses an index on that field" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    // Index the very field the like-predicate targets: `like` must still
+    // fall back to a full scan (`Value.compare`-based index entries have no
+    // notion of substring matching), never mistake this for an eq lookup.
+    try table.createIndex("name");
+
+    try table.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada Lovelace" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "Alan Turing" } }});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "name", .value = .{ .text = "Grace Hopper" } }});
+
+    {
+        const results = try table.select(.{ .like = .{ .field = "name", .value = .{ .text = "A%" } } });
+        defer freeRows(allocator, results);
+        try std.testing.expectEqual(@as(usize, 2), results.len);
+    }
+    {
+        const results = try table.select(.{ .like = .{ .field = "name", .value = .{ .text = "%ing" } } });
+        defer freeRows(allocator, results);
+        try std.testing.expectEqual(@as(usize, 1), results.len);
+        try std.testing.expectEqualStrings("Alan Turing", results[0].get("name").?.text);
+    }
+    {
+        const results = try table.select(.{ .like = .{ .field = "name", .value = .{ .text = "%z%" } } });
+        defer freeRows(allocator, results);
+        try std.testing.expectEqual(@as(usize, 0), results.len);
+    }
+
+    var plan = try table.explain(allocator, .{ .like = .{ .field = "name", .value = .{ .text = "A%" } } });
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.full_scan, plan.kind);
+}
+
+test "like combines with an indexed eq leaf inside and_ without breaking the index plan" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+
+    try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "name", .value = .{ .text = "Ada" } } });
+    try table.put(.{ .int = 2 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "name", .value = .{ .text = "Boris" } } });
+    try table.put(.{ .int = 3 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "name", .value = .{ .text = "Ada" } } });
+
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .like = .{ .field = "name", .value = .{ .text = "A%" } } },
+    };
+    const pred = Predicate{ .and_ = &preds };
+
+    // findIndexableLeaf must still pick the `eq` leaf on `city` for the
+    // index scan even though `like` sits right next to it in the same and_;
+    // selectByIndexPage then re-evaluates the whole predicate (including
+    // `like`) against every index candidate.
+    var plan = try table.explain(allocator, pred);
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.index_eq, plan.kind);
+    try std.testing.expectEqualStrings("city", plan.indexName.?);
+
+    const results = try table.select(pred);
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 1), results.len);
+    try std.testing.expectEqual(@as(i64, 1), results[0].get(pkField).?.int);
+}
+
+test "index stays in sync across update and delete" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    {
+        const warsaw = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+        defer freeRows(allocator, warsaw);
+        try std.testing.expectEqual(@as(usize, 1), warsaw.len);
+    }
+
+    // Move the row to a different city: the old index entry must disappear.
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+    {
+        const warsaw = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+        defer freeRows(allocator, warsaw);
+        try std.testing.expectEqual(@as(usize, 0), warsaw.len);
+        const krakow = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "krakow" } } });
+        defer freeRows(allocator, krakow);
+        try std.testing.expectEqual(@as(usize, 1), krakow.len);
+    }
+
+    try table.delete(.{ .int = 1 });
+    {
+        const krakow = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "krakow" } } });
+        defer freeRows(allocator, krakow);
+        try std.testing.expectEqual(@as(usize, 0), krakow.len);
+    }
+}
+
+test "dropIndex removes entries and falls back to full scan" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    try table.dropIndex("city");
+    try std.testing.expect(!table.hasIndex("city"));
+
+    // Still correct without the index, just via full scan.
+    const results = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 1), results.len);
+}
+
+test "range predicate uses index and respects bounds" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "events");
+    defer table.deinit();
+    try table.createIndex("score");
+
+    var i: i64 = 0;
+    while (i < 10) : (i += 1) {
+        try table.put(.{ .int = i }, &.{.{ .name = "score", .value = .{ .int = i } }});
+    }
+
+    const results = try table.select(.{ .gte = .{ .field = "score", .value = .{ .int = 7 } } });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+}
+
+test "compound and predicate narrows via one indexed conjunct" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 20 } },
+    });
+    try table.put(.{ .int = 2 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 40 } },
+    });
+
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .gte = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    const results = try table.select(.{ .and_ = &preds });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 1), results.len);
+    try std.testing.expectEqual(@as(i64, 2), results[0].get(pkField).?.int);
+}
+
+test "not and or predicates evaluate via full scan" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+
+    try table.put(.{ .int = 1 }, &.{.{ .name = "age", .value = .{ .int = 10 } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "age", .value = .{ .int = 20 } }});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "age", .value = .{ .int = 30 } }});
+
+    const orPreds = [_]Predicate{
+        .{ .eq = .{ .field = "age", .value = .{ .int = 10 } } },
+        .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    const orResults = try table.select(.{ .or_ = &orPreds });
+    defer freeRows(allocator, orResults);
+    try std.testing.expectEqual(@as(usize, 2), orResults.len);
+
+    const inner = Predicate{ .eq = .{ .field = "age", .value = .{ .int = 20 } } };
+    const notResult = try table.select(.{ .not_ = &inner });
+    defer freeRows(allocator, notResult);
+    try std.testing.expectEqual(@as(usize, 2), notResult.len);
+}
+
+test "is_null/is_not_null evaluate against missing fields, explicit none, and present values" {
+    const allocator = std.testing.allocator;
+    var sparse = Row.init(allocator);
+    defer sparse.deinit();
+    try sparse.set("age", .{ .int = 10 });
+
+    var withNone = Row.init(allocator);
+    defer withNone.deinit();
+    try withNone.set("city", .{ .none = {} });
+
+    var withCity = Row.init(allocator);
+    defer withCity.deinit();
+    try withCity.set("city", .{ .text = "warsaw" });
+
+    const isNull = Predicate{ .is_null = "city" };
+    const isNotNull = Predicate{ .is_not_null = "city" };
+
+    try std.testing.expect(isNull.evaluate(&sparse));
+    try std.testing.expect(!isNotNull.evaluate(&sparse));
+    try std.testing.expect(isNull.evaluate(&withNone));
+    try std.testing.expect(!isNotNull.evaluate(&withNone));
+    try std.testing.expect(!isNull.evaluate(&withCity));
+    try std.testing.expect(isNotNull.evaluate(&withCity));
+}
+
+test "is_null selects only sparse rows missing the field, over a full scan" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "age", .value = .{ .int = 40 } }});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "age", .value = .{ .int = 50 } }});
+
+    var plan = try table.explain(allocator, .{ .is_null = "city" });
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.full_scan, plan.kind);
+
+    const missing = try table.select(.{ .is_null = "city" });
+    defer freeRows(allocator, missing);
+    try std.testing.expectEqual(@as(usize, 2), missing.len);
+
+    const present = try table.select(.{ .is_not_null = "city" });
+    defer freeRows(allocator, present);
+    try std.testing.expectEqual(@as(usize, 1), present.len);
+
+    // is_null on an indexed field still falls back to full_scan (not
+    // indexable), but the result is unaffected by the index's presence.
+    try table.createIndex("age");
+    const stillMissing = try table.select(.{ .is_null = "city" });
+    defer freeRows(allocator, stillMissing);
+    try std.testing.expectEqual(@as(usize, 2), stillMissing.len);
+}
+
+test "invalid identifiers are rejected" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try std.testing.expectError(error.InvalidIdentifier, Table.open(&db, allocator, ""));
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try std.testing.expectError(error.InvalidIdentifier, table.createIndex("bad\x00field"));
+}
+
+test "selectPage skips offset and stops at limit on a full scan" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+
+    // Row keys are the pk's order-preserving encoding, so full-scan order
+    // is ascending pk regardless of insertion order.
+    var pk: i64 = 10;
+    while (pk >= 1) : (pk -= 1) {
+        try table.put(.{ .int = pk }, &.{});
+    }
+
+    const page = try table.selectPage(null, .{ .offset = 3, .limit = 4 });
+    defer freeRows(allocator, page);
+    try std.testing.expectEqual(@as(usize, 4), page.len);
+    var expected: i64 = 4;
+    for (page) |r| {
+        try std.testing.expectEqual(expected, r.get(pkField).?.int);
+        expected += 1;
+    }
+}
+
+test "selectPage with limit 0 matches unlimited select" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    var pk: i64 = 1;
+    while (pk <= 5) : (pk += 1) try table.put(.{ .int = pk }, &.{});
+
+    const all = try table.select(null);
+    defer freeRows(allocator, all);
+    const page = try table.selectPage(null, .{});
+    defer freeRows(allocator, page);
+    try std.testing.expectEqual(all.len, page.len);
+}
+
+test "selectPage offset past the end returns nothing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{});
+    try table.put(.{ .int = 2 }, &.{});
+
+    const page = try table.selectPage(null, .{ .offset = 50 });
+    defer freeRows(allocator, page);
+    try std.testing.expectEqual(@as(usize, 0), page.len);
+}
+
+test "selectPage paginates through an index-narrowed predicate in pk order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+
+    var pk: i64 = 1;
+    while (pk <= 6) : (pk += 1) {
+        try table.put(.{ .int = pk }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    }
+    // Noise row indexed under a different value - must never leak into the
+    // paginated "warsaw" result regardless of offset/limit.
+    try table.put(.{ .int = 99 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+
+    const pred = Predicate{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } };
+
+    const first = try table.selectPage(pred, .{ .limit = 2 });
+    defer freeRows(allocator, first);
+    try std.testing.expectEqual(@as(usize, 2), first.len);
+    try std.testing.expectEqual(@as(i64, 1), first[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 2), first[1].get(pkField).?.int);
+
+    const second = try table.selectPage(pred, .{ .offset = 2, .limit = 2 });
+    defer freeRows(allocator, second);
+    try std.testing.expectEqual(@as(usize, 2), second.len);
+    try std.testing.expectEqual(@as(i64, 3), second[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 4), second[1].get(pkField).?.int);
+
+    const rest = try table.selectPage(pred, .{ .offset = 4 });
+    defer freeRows(allocator, rest);
+    try std.testing.expectEqual(@as(usize, 2), rest.len);
+    try std.testing.expectEqual(@as(i64, 5), rest[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 6), rest[1].get(pkField).?.int);
+}
+
+test "selectPage against a large indexed bucket stays correct with a small limit" {
+    // Exercises the streaming `cursorForLeaf` path (see index.zig's
+    // EqCursor) against a bucket far larger than the requested page: a
+    // regression that only materialized the first `limit` matches would
+    // silently pass this test too, but a regression that went back to
+    // materializing the whole 500-row match set first would still pass on
+    // correctness alone - the point of the streaming rewrite is that this
+    // scan touches roughly `offset + limit` index entries, not 500, which is
+    // asserted structurally in index.zig's cursor tests via early deinit.
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+
+    var pk: i64 = 0;
+    while (pk < 500) : (pk += 1) {
+        try table.put(.{ .int = pk }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    }
+
+    const pred = Predicate{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } };
+
+    const page = try table.selectPage(pred, .{ .offset = 497, .limit = 10 });
+    defer freeRows(allocator, page);
+    try std.testing.expectEqual(@as(usize, 3), page.len);
+    try std.testing.expectEqual(@as(i64, 497), page[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 498), page[1].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 499), page[2].get(pkField).?.int);
+}
+
+test "selectPageOrdered sorts a full scan ascending and descending by an int field" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    // Insert pks out of score order so ascending pk (the natural full-scan
+    // order) is NOT already sorted by `score` - a regression that forgot to
+    // sort and just returned scan order would fail both assertions below.
+    const scores = [_]i64{ 30, 10, 50, 20, 40 };
+    for (scores, 1..) |score, pk| {
+        try table.put(.{ .int = @intCast(pk) }, &.{.{ .name = "score", .value = .{ .int = score } }});
+    }
+
+    const asc = try table.selectPageOrdered(null, .{}, &.{.{ .field = "score" }});
+    defer freeRows(allocator, asc);
+    var expected = [_]i64{ 10, 20, 30, 40, 50 };
+    try std.testing.expectEqual(expected.len, asc.len);
+    for (asc, 0..) |r, i| try std.testing.expectEqual(expected[i], r.get("score").?.int);
+
+    const desc = try table.selectPageOrdered(null, .{}, &.{.{ .field = "score", .descending = true }});
+    defer freeRows(allocator, desc);
+    std.mem.reverse(i64, &expected);
+    for (desc, 0..) |r, i| try std.testing.expectEqual(expected[i], r.get("score").?.int);
+}
+
+test "selectPageOrdered applies offset/limit after sorting, not before" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    var pk: i64 = 1;
+    while (pk <= 10) : (pk += 1) {
+        // Descending score as pk increases, so "top 3 by score desc" is the
+        // FIRST 3 pks, not the last 3 - a page-then-sort bug (paging the
+        // natural scan order before sorting) would return the wrong rows.
+        try table.put(.{ .int = pk }, &.{.{ .name = "score", .value = .{ .int = 100 - pk } }});
+    }
+
+    const top3 = try table.selectPageOrdered(null, .{ .limit = 3 }, &.{.{ .field = "score", .descending = true }});
+    defer freeRows(allocator, top3);
+    try std.testing.expectEqual(@as(usize, 3), top3.len);
+    try std.testing.expectEqual(@as(i64, 1), top3[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 2), top3[1].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 3), top3[2].get(pkField).?.int);
+
+    const nextPage = try table.selectPageOrdered(null, .{ .offset = 3, .limit = 3 }, &.{.{ .field = "score", .descending = true }});
+    defer freeRows(allocator, nextPage);
+    try std.testing.expectEqual(@as(i64, 4), nextPage[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 6), nextPage[2].get(pkField).?.int);
+}
+
+test "selectPageOrdered sorts text fields lexically and is stable on ties" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    // Two "warsaw" rows (pk 1 and 3) tie on `city` - a stable sort must keep
+    // them in scan order (1 before 3) relative to each other even though
+    // "krakow" (pk 2) sorts between them lexically... except it doesn't,
+    // "krakow" < "warsaw", so both warsaw rows land after it, still in
+    // their original relative order (1 then 3).
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    const rows = try table.selectPageOrdered(null, .{}, &.{.{ .field = "city" }});
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 3), rows.len);
+    try std.testing.expectEqualStrings("krakow", rows[0].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 2), rows[0].get(pkField).?.int);
+    try std.testing.expectEqualStrings("warsaw", rows[1].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 1), rows[1].get(pkField).?.int);
+    try std.testing.expectEqualStrings("warsaw", rows[2].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 3), rows[2].get(pkField).?.int);
+}
+
+test "selectPageOrdered groups rows missing the sort field at the front" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "score", .value = .{ .int = 5 } }});
+    try table.put(.{ .int = 2 }, &.{});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "score", .value = .{ .int = 1 } }});
+
+    const rows = try table.selectPageOrdered(null, .{}, &.{.{ .field = "score" }});
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(i64, 2), rows[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 3), rows[1].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 1), rows[2].get(pkField).?.int);
+}
+
+test "selectPageOrdered on an indexed predicate still uses the index, not a full scan" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+    var pk: i64 = 1;
+    while (pk <= 20) : (pk += 1) {
+        const city: []const u8 = if (@mod(pk, 2) == 0) "warsaw" else "krakow";
+        try table.put(.{ .int = pk }, &.{
+            .{ .name = "city", .value = .{ .text = city } },
+            .{ .name = "score", .value = .{ .int = 100 - pk } },
+        });
+    }
+    const pred = Predicate{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } };
+
+    // Cross-check against `explain` (same predicate shape it already tests
+    // elsewhere): `selectAllMatches` must still pick the `city` index, only
+    // skipping the early-stop, not falling back to a full scan.
+    var plan = try table.explain(allocator, pred);
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.index_eq, plan.kind);
+
+    const rows = try table.selectPageOrdered(pred, .{}, &.{.{ .field = "score" }});
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 10), rows.len);
+    var lastScore: i64 = std.math.minInt(i64);
+    for (rows) |r| {
+        const s = r.get("score").?.int;
+        try std.testing.expect(s >= lastScore);
+        lastScore = s;
+        try std.testing.expectEqualStrings("warsaw", r.get("city").?.text);
+    }
+}
+
+test "selectPageOrdered with two columns sorts by the first, breaking ties with the second" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+    // Two cities, each with scores NOT already grouped or sorted by pk -
+    // a single-column sort on `city` alone would leave each city's rows in
+    // scan order (which happens to already be reverse-score here), so
+    // this only passes if `score` is truly applied as a tiebreaker.
+    try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "score", .value = .{ .int = 30 } } });
+    try table.put(.{ .int = 2 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "score", .value = .{ .int = 20 } } });
+    try table.put(.{ .int = 3 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "score", .value = .{ .int = 10 } } });
+    try table.put(.{ .int = 4 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "score", .value = .{ .int = 40 } } });
+
+    const rows = try table.selectPageOrdered(null, .{}, &.{ .{ .field = "city" }, .{ .field = "score" } });
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 4), rows.len);
+    // krakow (score 20, 40) before warsaw (score 10, 30), each group
+    // internally ascending by score regardless of pk/insertion order.
+    try std.testing.expectEqual(@as(i64, 2), rows[0].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 4), rows[1].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 3), rows[2].get(pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 1), rows[3].get(pkField).?.int);
+}
+
+test "selectPageOrdered with two columns honors independent directions per column" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "score", .value = .{ .int = 10 } } });
+    try table.put(.{ .int = 2 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "score", .value = .{ .int = 20 } } });
+    try table.put(.{ .int = 3 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "score", .value = .{ .int = 5 } } });
+
+    // city ascending, score DESCENDING - a comparator that only flips the
+    // whole tuple's sign (instead of applying `descending` per column)
+    // would get the city order right but the within-city score order
+    // backwards.
+    const rows = try table.selectPageOrdered(null, .{}, &.{ .{ .field = "city" }, .{ .field = "score", .descending = true } });
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(i64, 3), rows[0].get(pkField).?.int); // krakow
+    try std.testing.expectEqual(@as(i64, 2), rows[1].get(pkField).?.int); // warsaw score 20
+    try std.testing.expectEqual(@as(i64, 1), rows[2].get(pkField).?.int); // warsaw score 10
+}
+
+test "selectPageOrdered with an empty order-by falls through to selectPage's early-stop behavior" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "people");
+    defer table.deinit();
+    var pk: i64 = 1;
+    while (pk <= 5) : (pk += 1) {
+        try table.put(.{ .int = pk }, &.{});
+    }
+
+    const ordered = try table.selectPageOrdered(null, .{ .limit = 2 }, &.{});
+    defer freeRows(allocator, ordered);
+    const plain = try table.selectPage(null, .{ .limit = 2 });
+    defer freeRows(allocator, plain);
+    try std.testing.expectEqual(plain.len, ordered.len);
+    for (ordered, plain) |o, p| try std.testing.expectEqual(o.get(pkField).?.int, p.get(pkField).?.int);
+}
+
+test "createCompositeIndex backfills then full-tuple eq select uses it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+    try table.put(.{ .int = 2 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 40 } },
+    });
+    try table.put(.{ .int = 3 }, &.{
+        .{ .name = "city", .value = .{ .text = "krakow" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+    try std.testing.expect(table.hasCompositeIndex("city_age"));
+
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    const results = try table.select(.{ .and_ = &preds });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 1), results.len);
+    try std.testing.expectEqual(@as(i64, 1), results[0].get(pkField).?.int);
+}
+
+test "composite index leftmost prefix narrows without constraining every column" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+    try table.put(.{ .int = 2 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 40 } },
+    });
+    try table.put(.{ .int = 3 }, &.{
+        .{ .name = "city", .value = .{ .text = "krakow" } },
+        .{ .name = "age", .value = .{ .int = 50 } },
+    });
+
+    // Only the leading column is constrained - the composite index must
+    // still narrow the scan to the two warsaw rows via its leftmost prefix,
+    // and the (unindexed-alone) age column is unconstrained here.
+    const results = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 2), results.len);
+}
+
+test "composite index uses a range bound on the column after the matched prefix" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+
+    var age: i64 = 20;
+    while (age < 30) : (age += 1) {
+        try table.put(.{ .int = age }, &.{
+            .{ .name = "city", .value = .{ .text = "warsaw" } },
+            .{ .name = "age", .value = .{ .int = age } },
+        });
+        try table.put(.{ .int = age + 100 }, &.{
+            .{ .name = "city", .value = .{ .text = "krakow" } },
+            .{ .name = "age", .value = .{ .int = age } },
+        });
+    }
+
+    // city == "warsaw" and 23 <= age < 27: must stay inside the warsaw
+    // bucket of the composite index even though krakow rows overlap the
+    // same age range byte-for-byte.
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .gte = .{ .field = "age", .value = .{ .int = 23 } } },
+        .{ .lt = .{ .field = "age", .value = .{ .int = 27 } } },
+    };
+    const results = try table.select(.{ .and_ = &preds });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 4), results.len);
+    for (results) |r| {
+        try std.testing.expectEqualStrings("warsaw", r.get("city").?.text);
+        try std.testing.expect(r.get("age").?.int >= 23 and r.get("age").?.int < 27);
+    }
+
+    // A one-sided range (age > 27) narrows the same way.
+    const openPreds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .gt = .{ .field = "age", .value = .{ .int = 27 } } },
+    };
+    const openResults = try table.select(.{ .and_ = &openPreds });
+    defer freeRows(allocator, openResults);
+    try std.testing.expectEqual(@as(usize, 2), openResults.len);
+    for (openResults) |r| {
+        try std.testing.expectEqualStrings("warsaw", r.get("city").?.text);
+        try std.testing.expect(r.get("age").?.int > 27);
+    }
+}
+
+test "composite index stays in sync across update and delete" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    const pred = Predicate{ .and_ = &preds };
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+    {
+        const found = try table.select(pred);
+        defer freeRows(allocator, found);
+        try std.testing.expectEqual(@as(usize, 1), found.len);
+    }
+
+    // Moving age away from 30 must drop the old composite entry.
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 31 } },
+    });
+    {
+        const stale = try table.select(pred);
+        defer freeRows(allocator, stale);
+        try std.testing.expectEqual(@as(usize, 0), stale.len);
+    }
+
+    // A row missing one of the composite columns entirely must not produce
+    // a (partial, ill-formed) entry: the put must still succeed, and the
+    // row must never surface as a false match on any age value including
+    // its own current (missing) one.
+    try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    {
+        const wholeTable = try table.select(null);
+        defer freeRows(allocator, wholeTable);
+        try std.testing.expectEqual(@as(usize, 2), wholeTable.len);
+
+        const ageless = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = 31 } } },
+        };
+        const noMatch = try table.select(.{ .and_ = &ageless });
+        defer freeRows(allocator, noMatch);
+        try std.testing.expectEqual(@as(usize, 1), noMatch.len);
+        try std.testing.expectEqual(@as(i64, 1), noMatch[0].get(pkField).?.int);
+    }
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+    try table.delete(.{ .int = 1 });
+    {
+        const afterDelete = try table.select(pred);
+        defer freeRows(allocator, afterDelete);
+        try std.testing.expectEqual(@as(usize, 0), afterDelete.len);
+    }
+}
+
+test "dropCompositeIndex removes entries and falls back to full scan" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+
+    try table.dropCompositeIndex("city_age");
+    try std.testing.expect(!table.hasCompositeIndex("city_age"));
+
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    const results = try table.select(.{ .and_ = &preds });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 1), results.len);
+}
+
+test "createCompositeIndex rejects bad field counts and identifiers" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+
+    try std.testing.expectError(error.InvalidCompositeIndex, table.createCompositeIndex("solo", &.{"city"}));
+    try std.testing.expectError(error.InvalidIdentifier, table.createCompositeIndex("bad\x00name", &.{ "city", "age" }));
+    try std.testing.expectError(error.InvalidIdentifier, table.createCompositeIndex("ok", &.{ "city", "bad\x00field" }));
+}
+
+test "composite index survives a table reopen (persisted across process restart)" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var table = try Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createCompositeIndex("city_age", &.{ "city", "age" });
+        try table.put(.{ .int = 1 }, &.{
+            .{ .name = "city", .value = .{ .text = "warsaw" } },
+            .{ .name = "age", .value = .{ .int = 30 } },
+        });
+    }
+
+    var reopened = try Table.open(&db, allocator, "users");
+    defer reopened.deinit();
+    try std.testing.expect(reopened.hasCompositeIndex("city_age"));
+
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    const results = try reopened.select(.{ .and_ = &preds });
+    defer freeRows(allocator, results);
+    try std.testing.expectEqual(@as(usize, 1), results.len);
+}
+
+test "explain reports full_scan for a null predicate and an unindexed field" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    var noPred = try table.explain(allocator, null);
+    defer noPred.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.full_scan, noPred.kind);
+    try std.testing.expect(noPred.indexName == null);
+
+    var unindexed = try table.explain(allocator, .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer unindexed.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.full_scan, unindexed.kind);
+}
+
+test "explain reports index_eq and index_range for a single-field index" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "events");
+    defer table.deinit();
+    try table.createIndex("score");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "score", .value = .{ .int = 5 } }});
+
+    var eqPlan = try table.explain(allocator, .{ .eq = .{ .field = "score", .value = .{ .int = 5 } } });
+    defer eqPlan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.index_eq, eqPlan.kind);
+    try std.testing.expectEqualStrings("score", eqPlan.indexName.?);
+    try std.testing.expectEqual(@as(usize, 1), eqPlan.matchedFields);
+    try std.testing.expectEqual(@as(usize, 1), eqPlan.totalFields);
+
+    var rangePlan = try table.explain(allocator, .{ .gte = .{ .field = "score", .value = .{ .int = 5 } } });
+    defer rangePlan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.index_range, rangePlan.kind);
+    try std.testing.expectEqualStrings("score", rangePlan.indexName.?);
+}
+
+test "explain reports composite_eq and composite_range with matched/total field counts" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+
+    // Only the leading column pinned -> composite_eq over a strict prefix
+    // (matchedFields 1 of 2). `findCompositeMatch` only looks inside a
+    // top-level `and_` (see its doc comment), so a bare single `eq` outside
+    // one does not reach the composite index at all - wrapping in `and_`
+    // with itself as the sole conjunct is what actually exercises the
+    // leftmost-prefix match here.
+    const prefixPreds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+    };
+    var prefixOnly = try table.explain(allocator, .{ .and_ = &prefixPreds });
+    defer prefixOnly.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.composite_eq, prefixOnly.kind);
+    try std.testing.expectEqualStrings("city_age", prefixOnly.indexName.?);
+    try std.testing.expectEqual(@as(usize, 1), prefixOnly.matchedFields);
+    try std.testing.expectEqual(@as(usize, 2), prefixOnly.totalFields);
+
+    // Both columns pinned by equality -> composite_eq, fully matched.
+    const eqPreds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    var fullEq = try table.explain(allocator, .{ .and_ = &eqPreds });
+    defer fullEq.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.composite_eq, fullEq.kind);
+    try std.testing.expectEqual(@as(usize, 2), fullEq.matchedFields);
+
+    // Leading column pinned by equality, next column range-bound -> composite_range.
+    const rangePreds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .gte = .{ .field = "age", .value = .{ .int = 18 } } },
+    };
+    var rangeMatch = try table.explain(allocator, .{ .and_ = &rangePreds });
+    defer rangeMatch.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.composite_range, rangeMatch.kind);
+    try std.testing.expectEqualStrings("city_age", rangeMatch.indexName.?);
+    try std.testing.expectEqual(@as(usize, 1), rangeMatch.matchedFields);
+}
+
+test "explain never mutates the table (const receiver, no rows touched)" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    const pred = Predicate{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } };
+    const constTable: *const Table = &table;
+    var plan = try constTable.explain(allocator, pred);
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.index_eq, plan.kind);
+
+    // The row explain() was asked about is still there afterwards.
+    const rows = try table.select(pred);
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 1), rows.len);
+}
+
+test "updateWhere applies a set clause to every matching row and reports the count" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "active", .value = .{ .int = 0 } } });
+    try table.put(.{ .int = 2 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "active", .value = .{ .int = 0 } } });
+    try table.put(.{ .int = 3 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "active", .value = .{ .int = 0 } } });
+
+    const pred = Predicate{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } };
+    const updated = try table.updateWhere(pred, &.{.{ .name = "active", .value = .{ .int = 1 } }});
+    try std.testing.expectEqual(@as(usize, 2), updated);
+
+    var row1 = (try table.get(.{ .int = 1 })).?;
+    defer row1.deinit();
+    try std.testing.expectEqual(Value{ .int = 1 }, row1.get("active").?);
+    try std.testing.expectEqualStrings("warsaw", row1.get("city").?.text);
+
+    var row3 = (try table.get(.{ .int = 3 })).?;
+    defer row3.deinit();
+    try std.testing.expectEqual(Value{ .int = 0 }, row3.get("active").?);
+}
+
+test "updateWhere with a null predicate touches every row" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "counters");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "n", .value = .{ .int = 5 } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "n", .value = .{ .int = 7 } }});
+
+    const updated = try table.updateWhere(null, &.{.{ .name = "flag", .value = .{ .text = "seen" } }});
+    try std.testing.expectEqual(@as(usize, 2), updated);
+
+    var row1 = (try table.get(.{ .int = 1 })).?;
+    defer row1.deinit();
+    try std.testing.expectEqualStrings("seen", row1.get("flag").?.text);
+    // Untouched fields survive the merge.
+    try std.testing.expectEqual(Value{ .int = 5 }, row1.get("n").?);
+}
+
+test "updateWhere adds a brand new field a matched row never had" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    _ = try table.updateWhere(null, &.{.{ .name = "tier", .value = .{ .text = "gold" } }});
+
+    var row = (try table.get(.{ .int = 1 })).?;
+    defer row.deinit();
+    try std.testing.expectEqualStrings("gold", row.get("tier").?.text);
+    try std.testing.expectEqualStrings("warsaw", row.get("city").?.text);
+}
+
+test "updateWhere keeps a secondary index in sync when the indexed field changes" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    const updated = try table.updateWhere(
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        &.{.{ .name = "city", .value = .{ .text = "krakow" } }},
+    );
+    try std.testing.expectEqual(@as(usize, 1), updated);
+
+    // The stale index entry is gone, a fresh one under the new value works,
+    // and explain() confirms the index (not a full scan) still serves it.
+    const stale = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer freeRows(allocator, stale);
+    try std.testing.expectEqual(@as(usize, 0), stale.len);
+
+    const fresh = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "krakow" } } });
+    defer freeRows(allocator, fresh);
+    try std.testing.expectEqual(@as(usize, 1), fresh.len);
+
+    const constTable: *const Table = &table;
+    var plan = try constTable.explain(allocator, .{ .eq = .{ .field = "city", .value = .{ .text = "krakow" } } });
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.index_eq, plan.kind);
+}
+
+test "updateWhere keeps a composite index in sync across leading and trailing column moves" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+        .{ .name = "name", .value = .{ .text = "alice" } },
+    });
+    try table.put(.{ .int = 2 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 31 } },
+        .{ .name = "name", .value = .{ .text = "bob" } },
+    });
+    try table.put(.{ .int = 3 }, &.{
+        .{ .name = "city", .value = .{ .text = "krakow" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+        .{ .name = "name", .value = .{ .text = "carol" } },
+    });
+    try table.put(.{ .int = 4 }, &.{
+        .{ .name = "city", .value = .{ .text = "krakow" } },
+        .{ .name = "age", .value = .{ .int = 40 } },
+        .{ .name = "name", .value = .{ .text = "dave" } },
+    });
+
+    // updateWhere matched through the composite index (both columns pinned
+    // by equality) moves the TRAILING column (age). The old composite entry
+    // for row 1 must vanish and a fresh one under the new age must serve it.
+    {
+        const preds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+        };
+        const updated = try table.updateWhere(
+            .{ .and_ = &preds },
+            &.{.{ .name = "age", .value = .{ .int = 45 } }},
+        );
+        try std.testing.expectEqual(@as(usize, 1), updated);
+    }
+    {
+        const stalePreds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+        };
+        const stale = try table.select(.{ .and_ = &stalePreds });
+        defer freeRows(allocator, stale);
+        try std.testing.expectEqual(@as(usize, 0), stale.len);
+
+        const freshPreds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = 45 } } },
+        };
+        const fresh = try table.select(.{ .and_ = &freshPreds });
+        defer freeRows(allocator, fresh);
+        try std.testing.expectEqual(@as(usize, 1), fresh.len);
+        try std.testing.expectEqual(@as(i64, 1), fresh[0].get(pkField).?.int);
+
+        const constTable: *const Table = &table;
+        var plan = try constTable.explain(allocator, .{ .and_ = &freshPreds });
+        defer plan.deinit(allocator);
+        try std.testing.expectEqual(PlanKind.composite_eq, plan.kind);
+        try std.testing.expectEqualStrings("city_age", plan.indexName.?);
+        try std.testing.expectEqual(@as(usize, 2), plan.matchedFields);
+    }
+
+    // Same check but moving the LEADING column (city) instead of the
+    // trailing one - a different code path in the composite key encoding
+    // (the prefix itself shifts, not just the suffix).
+    {
+        const preds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = 31 } } },
+        };
+        const updated = try table.updateWhere(
+            .{ .and_ = &preds },
+            &.{.{ .name = "city", .value = .{ .text = "gdansk" } }},
+        );
+        try std.testing.expectEqual(@as(usize, 1), updated);
+    }
+    {
+        const stalePreds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = 31 } } },
+        };
+        const stale = try table.select(.{ .and_ = &stalePreds });
+        defer freeRows(allocator, stale);
+        try std.testing.expectEqual(@as(usize, 0), stale.len);
+
+        const freshPreds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "gdansk" } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = 31 } } },
+        };
+        const fresh = try table.select(.{ .and_ = &freshPreds });
+        defer freeRows(allocator, fresh);
+        try std.testing.expectEqual(@as(usize, 1), fresh.len);
+        try std.testing.expectEqual(@as(i64, 2), fresh[0].get(pkField).?.int);
+    }
+
+    // updateWhere reached through composite_range (leading column pinned by
+    // equality, trailing column range-bound) must update every row the
+    // range covers, and leave the composite index able to keep serving
+    // both afterwards even though only the unindexed "name" field changed.
+    {
+        const rangePreds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = "krakow" } } },
+            .{ .gte = .{ .field = "age", .value = .{ .int = 30 } } },
+        };
+        const constTable: *const Table = &table;
+        var rangePlan = try constTable.explain(allocator, .{ .and_ = &rangePreds });
+        defer rangePlan.deinit(allocator);
+        try std.testing.expectEqual(PlanKind.composite_range, rangePlan.kind);
+        try std.testing.expectEqualStrings("city_age", rangePlan.indexName.?);
+
+        const updated = try table.updateWhere(
+            .{ .and_ = &rangePreds },
+            &.{.{ .name = "name", .value = .{ .text = "updated" } }},
+        );
+        try std.testing.expectEqual(@as(usize, 2), updated);
+    }
+
+    // Final sanity sweep: every row is still reachable through the
+    // composite index under exactly its current (city, age), nothing was
+    // lost, duplicated, or left under a stale key.
+    const expectations = [_]struct { pk: i64, city: []const u8, age: i64, name: []const u8 }{
+        .{ .pk = 1, .city = "warsaw", .age = 45, .name = "alice" },
+        .{ .pk = 2, .city = "gdansk", .age = 31, .name = "bob" },
+        .{ .pk = 3, .city = "krakow", .age = 30, .name = "updated" },
+        .{ .pk = 4, .city = "krakow", .age = 40, .name = "updated" },
+    };
+    for (expectations) |exp| {
+        const preds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = exp.city } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = exp.age } } },
+        };
+        const rows = try table.select(.{ .and_ = &preds });
+        defer freeRows(allocator, rows);
+        try std.testing.expectEqual(@as(usize, 1), rows.len);
+        try std.testing.expectEqual(exp.pk, rows[0].get(pkField).?.int);
+        try std.testing.expectEqualStrings(exp.name, rows[0].get("name").?.text);
+    }
+
+    const everyone = try table.select(null);
+    defer freeRows(allocator, everyone);
+    try std.testing.expectEqual(@as(usize, 4), everyone.len);
+}
+
+test "deleteWhere removes every matching row and reports the count" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    try table.put(.{ .int = 3 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+
+    const pred = Predicate{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } };
+    const deleted = try table.deleteWhere(pred);
+    try std.testing.expectEqual(@as(usize, 2), deleted);
+
+    try std.testing.expectEqual(@as(?Row, null), try table.get(.{ .int = 1 }));
+    try std.testing.expectEqual(@as(?Row, null), try table.get(.{ .int = 2 }));
+
+    var row3 = (try table.get(.{ .int = 3 })).?;
+    defer row3.deinit();
+    try std.testing.expectEqualStrings("krakow", row3.get("city").?.text);
+}
+
+test "deleteWhere with a null predicate empties the table" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "counters");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "n", .value = .{ .int = 5 } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "n", .value = .{ .int = 7 } }});
+
+    const deleted = try table.deleteWhere(null);
+    try std.testing.expectEqual(@as(usize, 2), deleted);
+
+    const everyone = try table.select(null);
+    defer freeRows(allocator, everyone);
+    try std.testing.expectEqual(@as(usize, 0), everyone.len);
+}
+
+test "deleteWhere with no matches deletes nothing and leaves the table untouched" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    const deleted = try table.deleteWhere(.{ .eq = .{ .field = "city", .value = .{ .text = "gdansk" } } });
+    try std.testing.expectEqual(@as(usize, 0), deleted);
+
+    var row = (try table.get(.{ .int = 1 })).?;
+    defer row.deinit();
+    try std.testing.expectEqualStrings("warsaw", row.get("city").?.text);
+}
+
+test "deleteWhere removes stale secondary index entries so a fresh row can reuse the value" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("city");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+
+    const deleted = try table.deleteWhere(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    try std.testing.expectEqual(@as(usize, 1), deleted);
+
+    // The old index entry for pk 1 under "warsaw" must be gone, not just the
+    // row - otherwise a later put of a *different* pk under the same "warsaw"
+    // value would find a phantom sibling in the index.
+    const stale = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer freeRows(allocator, stale);
+    try std.testing.expectEqual(@as(usize, 0), stale.len);
+
+    try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    const fresh = try table.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer freeRows(allocator, fresh);
+    try std.testing.expectEqual(@as(usize, 1), fresh.len);
+    try std.testing.expectEqual(@as(i64, 2), fresh[0].get(pkField).?.int);
+
+    const constTable: *const Table = &table;
+    var plan = try constTable.explain(allocator, .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(PlanKind.index_eq, plan.kind);
+}
+
+test "deleteWhere removes stale composite index entries across matched equality prefix" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createCompositeIndex("city_age", &.{ "city", "age" });
+
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+    try table.put(.{ .int = 2 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "age", .value = .{ .int = 31 } },
+    });
+    try table.put(.{ .int = 3 }, &.{
+        .{ .name = "city", .value = .{ .text = "krakow" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+
+    const preds = [_]Predicate{
+        .{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } },
+        .{ .eq = .{ .field = "age", .value = .{ .int = 30 } } },
+    };
+    const deleted = try table.deleteWhere(.{ .and_ = &preds });
+    try std.testing.expectEqual(@as(usize, 1), deleted);
+
+    const gone = try table.select(.{ .and_ = &preds });
+    defer freeRows(allocator, gone);
+    try std.testing.expectEqual(@as(usize, 0), gone.len);
+
+    // The composite index must still correctly serve the two untouched rows,
+    // proving the deleted row's entry was surgically removed, not the whole
+    // (city="warsaw") or (age=30) bucket.
+    const survivors = [_]struct { pk: i64, city: []const u8, age: i64 }{
+        .{ .pk = 2, .city = "warsaw", .age = 31 },
+        .{ .pk = 3, .city = "krakow", .age = 30 },
+    };
+    for (survivors) |exp| {
+        const survivorPreds = [_]Predicate{
+            .{ .eq = .{ .field = "city", .value = .{ .text = exp.city } } },
+            .{ .eq = .{ .field = "age", .value = .{ .int = exp.age } } },
+        };
+        const rows = try table.select(.{ .and_ = &survivorPreds });
+        defer freeRows(allocator, rows);
+        try std.testing.expectEqual(@as(usize, 1), rows.len);
+        try std.testing.expectEqual(exp.pk, rows[0].get(pkField).?.int);
+
+        const constTable: *const Table = &table;
+        var plan = try constTable.explain(allocator, .{ .and_ = &survivorPreds });
+        defer plan.deinit(allocator);
+        try std.testing.expectEqual(PlanKind.composite_eq, plan.kind);
+    }
+}
+
+test "createUniqueIndex backfills the plain index and rejects a colliding insert" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@x.com" } }});
+
+    try table.createUniqueIndex("email");
+    try std.testing.expect(table.hasUniqueIndex("email"));
+    try std.testing.expect(table.hasIndex("email"));
+
+    try std.testing.expectError(error.UniqueViolation, table.put(.{ .int = 2 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@x.com" } },
+    }));
+
+    try table.put(.{ .int = 2 }, &.{.{ .name = "email", .value = .{ .text = "b@x.com" } }});
+    const rows = try table.scanAll();
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 2), rows.len);
+}
+
+test "createUniqueIndex refuses to install over data that already has a duplicate" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "dup@x.com" } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "email", .value = .{ .text = "dup@x.com" } }});
+
+    try std.testing.expectError(error.UniqueViolation, table.createUniqueIndex("email"));
+    try std.testing.expect(!table.hasUniqueIndex("email"));
+    // Refused install must not have left a half-installed plain index either.
+    try std.testing.expect(!table.hasIndex("email"));
+}
+
+test "createUniqueIndex over an already-indexed field reuses the index instead of duplicating entries" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createIndex("email");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@x.com" } }});
+
+    try table.createUniqueIndex("email");
+    try std.testing.expect(table.hasUniqueIndex("email"));
+
+    try std.testing.expectError(error.UniqueViolation, table.put(.{ .int = 2 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@x.com" } },
+    }));
+
+    const preds = Predicate{ .eq = .{ .field = "email", .value = .{ .text = "a@x.com" } } };
+    const rows = try table.select(preds);
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 1), rows.len);
+}
+
+test "unique constraint does not block updating a row's own value or an unrelated field" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@x.com" } },
+        .{ .name = "age", .value = .{ .int = 30 } },
+    });
+    try table.createUniqueIndex("email");
+
+    // Re-writing the same email on the same row must not conflict with itself.
+    try table.put(.{ .int = 1 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@x.com" } },
+        .{ .name = "age", .value = .{ .int = 31 } },
+    });
+
+    var row = (try table.get(.{ .int = 1 })).?;
+    defer row.deinit();
+    try std.testing.expectEqual(@as(i64, 31), row.get("age").?.int);
+}
+
+test "unique constraint frees a value for reuse once the owning row is deleted" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createUniqueIndex("email");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@x.com" } }});
+    try std.testing.expectError(error.UniqueViolation, table.put(.{ .int = 2 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@x.com" } },
+    }));
+
+    try table.delete(.{ .int = 1 });
+    try table.put(.{ .int = 2 }, &.{.{ .name = "email", .value = .{ .text = "a@x.com" } }});
+
+    var row = (try table.get(.{ .int = 2 })).?;
+    defer row.deinit();
+    try std.testing.expectEqualStrings("a@x.com", row.get("email").?.text);
+}
+
+test "dropIndex on a unique field also drops the unique constraint" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.createUniqueIndex("email");
+    try table.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@x.com" } }});
+
+    try table.dropIndex("email");
+    try std.testing.expect(!table.hasUniqueIndex("email"));
+    try std.testing.expect(!table.hasIndex("email"));
+
+    // With no constraint left, a colliding value must now be accepted.
+    try table.put(.{ .int = 2 }, &.{.{ .name = "email", .value = .{ .text = "a@x.com" } }});
+    const rows = try table.scanAll();
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 2), rows.len);
+}
+
+test "unique constraint survives a table reopen (persisted across process restart)" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var table = try Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createUniqueIndex("email");
+        try table.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@x.com" } }});
+    }
+
+    var reopened = try Table.open(&db, allocator, "users");
+    defer reopened.deinit();
+    try std.testing.expect(reopened.hasUniqueIndex("email"));
+    try std.testing.expectError(error.UniqueViolation, reopened.put(.{ .int = 2 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@x.com" } },
+    }));
+}
+
+test "createUniqueIndex rejects a bad field identifier" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try std.testing.expectError(error.InvalidIdentifier, table.createUniqueIndex("bad\x00field"));
+}
+
+test "rows missing the unique field entirely never collide with each other" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var table = try Table.open(&db, allocator, "users");
+    defer table.deinit();
+    try table.put(.{ .int = 1 }, &.{.{ .name = "age", .value = .{ .int = 20 } }});
+    try table.put(.{ .int = 2 }, &.{.{ .name = "age", .value = .{ .int = 21 } }});
+
+    try table.createUniqueIndex("email");
+    try table.put(.{ .int = 3 }, &.{.{ .name = "age", .value = .{ .int = 22 } }});
+    const rows = try table.scanAll();
+    defer freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 3), rows.len);
+}
+
+test "createForeignKey against the primary key rejects a dangling reference and accepts a real one" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    try std.testing.expect(orders.hasForeignKey("customer_id"));
+
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    try std.testing.expectError(error.ForeignKeyViolation, orders.put(.{ .int = 101 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 999 } },
+    }));
+}
+
+test "createForeignKey against a UNIQUE non-pk field works, and refuses a target with no unique backing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var products = try Table.open(&db, allocator, "products");
+    defer products.deinit();
+    try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "SKU-1" } }});
+
+    var lineItems = try Table.open(&db, allocator, "line_items");
+    defer lineItems.deinit();
+
+    // "sku" has no unique constraint on products yet.
+    try std.testing.expectError(error.ForeignKeyRequiresUniqueTarget, lineItems.createForeignKey("product_sku", "products", "sku", .restrict));
+
+    try products.createUniqueIndex("sku");
+    try lineItems.createForeignKey("product_sku", "products", "sku", .restrict);
+
+    try lineItems.put(.{ .int = 1 }, &.{.{ .name = "product_sku", .value = .{ .text = "SKU-1" } }});
+    try std.testing.expectError(error.ForeignKeyViolation, lineItems.put(.{ .int = 2 }, &.{
+        .{ .name = "product_sku", .value = .{ .text = "NOPE" } },
+    }));
+}
+
+test "createForeignKey refuses to install over a child row that already dangles" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 1 }, &.{.{ .name = "customer_id", .value = .{ .int = 42 } }});
+
+    try std.testing.expectError(error.ForeignKeyViolation, orders.createForeignKey("customer_id", "customers", pkField, .restrict));
+    try std.testing.expect(!orders.hasForeignKey("customer_id"));
+}
+
+test "a row with no value for the foreign key field is exempt from the constraint" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+
+    // No "customer_id" field at all - a nullable foreign key, not a violation.
+    try orders.put(.{ .int = 1 }, &.{.{ .name = "note", .value = .{ .text = "guest checkout" } }});
+    var row = (try orders.get(.{ .int = 1 })).?;
+    defer row.deinit();
+    try std.testing.expect(row.get("customer_id") == null);
+}
+
+test "dropForeignKey lifts the constraint" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+
+    try std.testing.expectError(error.ForeignKeyViolation, orders.put(.{ .int = 1 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 42 } },
+    }));
+
+    try orders.dropForeignKey("customer_id");
+    try std.testing.expect(!orders.hasForeignKey("customer_id"));
+    try orders.put(.{ .int = 1 }, &.{.{ .name = "customer_id", .value = .{ .int = 42 } }});
+}
+
+test "deleting a parent row is restricted while a child still references it via the primary key" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    try std.testing.expectError(error.ForeignKeyInUse, customers.delete(.{ .int = 1 }));
+    // Restricted, not silently ignored: the row is still there afterwards.
+    var stillThere = (try customers.get(.{ .int = 1 })).?;
+    stillThere.deinit();
+
+    // Once the referencing child row is gone, the parent can be deleted.
+    try orders.delete(.{ .int = 100 });
+    try customers.delete(.{ .int = 1 });
+    try std.testing.expect((try customers.get(.{ .int = 1 })) == null);
+}
+
+test "deleteWhere on a parent table stops at the first row a child still references" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "Boris" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 2 } }});
+
+    try std.testing.expectError(error.ForeignKeyInUse, customers.deleteWhere(null));
+    // customer 1 had no children and was already removed by the time
+    // deleteWhere hit customer 2's violation - deleteWhere has no
+    // per-batch atomicity (see its own doc comment), so a partial effect
+    // here is expected, not a bug this test is trying to hide.
+    try std.testing.expect((try customers.get(.{ .int = 1 })) == null);
+    var stillThere = (try customers.get(.{ .int = 2 })).?;
+    stillThere.deinit();
+}
+
+test "dropForeignKey lifts the delete restriction on the table it pointed at" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try std.testing.expectError(error.ForeignKeyInUse, customers.delete(.{ .int = 1 }));
+
+    try orders.dropForeignKey("customer_id");
+    try customers.delete(.{ .int = 1 });
+    try std.testing.expect((try customers.get(.{ .int = 1 })) == null);
+}
+
+test "delete restriction works through a UNIQUE non-pk foreign key target too" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var products = try Table.open(&db, allocator, "products");
+    defer products.deinit();
+    try products.createUniqueIndex("sku");
+    try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+
+    var lineItems = try Table.open(&db, allocator, "line_items");
+    defer lineItems.deinit();
+    try lineItems.createForeignKey("product_sku", "products", "sku", .restrict);
+    try lineItems.put(.{ .int = 1 }, &.{.{ .name = "product_sku", .value = .{ .text = "WIDGET-1" } }});
+
+    try std.testing.expectError(error.ForeignKeyInUse, products.delete(.{ .int = 1 }));
+
+    try lineItems.delete(.{ .int = 1 });
+    try products.delete(.{ .int = 1 });
+    try std.testing.expect((try products.get(.{ .int = 1 })) == null);
+}
+
+test "a self-referencing foreign key restricts deleting a manager with reports, but not a childless leaf" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var employees = try Table.open(&db, allocator, "employees");
+    defer employees.deinit();
+    try employees.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "CEO" } }});
+    try employees.createForeignKey("manager_id", "employees", pkField, .restrict);
+    try employees.put(.{ .int = 2 }, &.{
+        .{ .name = "name", .value = .{ .text = "VP" } },
+        .{ .name = "manager_id", .value = .{ .int = 1 } },
+    });
+
+    try std.testing.expectError(error.ForeignKeyInUse, employees.delete(.{ .int = 1 }));
+    // The leaf (no reports) deletes cleanly - and does not restrict its
+    // own deletion against itself despite scanning the same table.
+    try employees.delete(.{ .int = 2 });
+    try employees.delete(.{ .int = 1 });
+    try std.testing.expect((try employees.get(.{ .int = 1 })) == null);
+}
+
+test "foreign key constraint survives a table reopen" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var customers = try Table.open(&db, allocator, "customers");
+        defer customers.deinit();
+        var orders = try Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    }
+
+    var reopened = try Table.open(&db, allocator, "orders");
+    defer reopened.deinit();
+    try std.testing.expect(reopened.hasForeignKey("customer_id"));
+    try std.testing.expectError(error.ForeignKeyViolation, reopened.put(.{ .int = 1 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 7 } },
+    }));
+}
+
+test "createForeignKey rejects bad identifiers for field, refTable, and refField" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try std.testing.expectError(error.InvalidIdentifier, orders.createForeignKey("bad\x00field", "customers", pkField, .restrict));
+    try std.testing.expectError(error.InvalidIdentifier, orders.createForeignKey("customer_id", "bad\x00table", pkField, .restrict));
+    try std.testing.expectError(error.InvalidIdentifier, orders.createForeignKey("customer_id", "customers", "bad\x00field", .restrict));
+}
+
+test "a self-referencing foreign key enforces a tree structure against the table's own primary key" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var employees = try Table.open(&db, allocator, "employees");
+    defer employees.deinit();
+    try employees.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "CEO" } }});
+    try employees.createForeignKey("manager_id", "employees", pkField, .restrict);
+
+    // A row with no manager (the root of the tree) is exempt.
+    try employees.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "CEO" } }});
+    // A report naming an existing manager is fine.
+    try employees.put(.{ .int = 2 }, &.{
+        .{ .name = "name", .value = .{ .text = "VP" } },
+        .{ .name = "manager_id", .value = .{ .int = 1 } },
+    });
+    try std.testing.expectError(error.ForeignKeyViolation, employees.put(.{ .int = 3 }, &.{
+        .{ .name = "name", .value = .{ .text = "Ghost report" } },
+        .{ .name = "manager_id", .value = .{ .int = 999 } },
+    }));
+}
+
+test "deleting a referenced parent is blocked before it can leave a child's foreign key dangling" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    // This used to be the one gap `updateWhere`'s own per-row FK re-check
+    // existed to catch after the fact: a bare `customers.delete` leaving
+    // orders#100's reference dangling even though it was valid when first
+    // written (see createForeignKey's OLD doc comment). `Table.delete`'s
+    // ON DELETE RESTRICT check (backed by `ReferencedBySet`) now closes it
+    // at the source instead - the dangling state this test used to
+    // construct is no longer reachable through delete at all.
+    try std.testing.expectError(error.ForeignKeyInUse, customers.delete(.{ .int = 1 }));
+
+    // updateWhere re-writes the row through put with every field carried
+    // over unchanged, including "customer_id" - it has nothing to catch,
+    // because the reference was never allowed to go dangling in the first
+    // place.
+    try std.testing.expectEqual(@as(usize, 1), try orders.updateWhere(null, &.{
+        .{ .name = "note", .value = .{ .text = "touch" } },
+    }));
+}
+
+test "put is restricted from changing a UNIQUE foreign key target still referenced by a child" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var products = try Table.open(&db, allocator, "products");
+    defer products.deinit();
+    try products.createUniqueIndex("sku");
+    try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+
+    var lineItems = try Table.open(&db, allocator, "line_items");
+    defer lineItems.deinit();
+    try lineItems.createForeignKey("product_sku", "products", "sku", .restrict);
+    try lineItems.put(.{ .int = 1 }, &.{.{ .name = "product_sku", .value = .{ .text = "WIDGET-1" } }});
+
+    // Renaming the sku out from under the still-live line item must not
+    // silently strand it - the same RESTRICT a delete would get.
+    try std.testing.expectError(error.ForeignKeyInUse, products.put(.{ .int = 1 }, &.{
+        .{ .name = "sku", .value = .{ .text = "WIDGET-2" } },
+    }));
+    var stillThere = (try products.get(.{ .int = 1 })).?;
+    defer stillThere.deinit();
+    try std.testing.expectEqualStrings("WIDGET-1", stillThere.get("sku").?.text);
+
+    // Rewriting the same value back (or any other unrelated field) is not
+    // a change and is always exempt, mirroring the UNIQUE check's own
+    // "unchanged is safe" exemption.
+    try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+
+    // Once the reference is gone, the rename goes through.
+    try lineItems.delete(.{ .int = 1 });
+    try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-2" } }});
+    var renamed = (try products.get(.{ .int = 1 })).?;
+    defer renamed.deinit();
+    try std.testing.expectEqualStrings("WIDGET-2", renamed.get("sku").?.text);
+}
+
+test "updateWhere is restricted from pulling a UNIQUE foreign key target out from under a child" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var products = try Table.open(&db, allocator, "products");
+    defer products.deinit();
+    try products.createUniqueIndex("sku");
+    try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+
+    var lineItems = try Table.open(&db, allocator, "line_items");
+    defer lineItems.deinit();
+    try lineItems.createForeignKey("product_sku", "products", "sku", .restrict);
+    try lineItems.put(.{ .int = 1 }, &.{.{ .name = "product_sku", .value = .{ .text = "WIDGET-1" } }});
+
+    try std.testing.expectError(error.ForeignKeyInUse, products.updateWhere(null, &.{
+        .{ .name = "sku", .value = .{ .text = "WIDGET-2" } },
+    }));
+
+    // A bulk update that leaves the referenced field untouched has
+    // nothing to restrict.
+    try std.testing.expectEqual(@as(usize, 1), try products.updateWhere(null, &.{
+        .{ .name = "note", .value = .{ .text = "touch" } },
+    }));
+}
+
+test "a self-referencing foreign key restricts renaming a UNIQUE field still targeted by a report, but not by itself" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var employees = try Table.open(&db, allocator, "employees");
+    defer employees.deinit();
+    try employees.createUniqueIndex("badge");
+    try employees.createForeignKey("manager_badge", "employees", "badge", .restrict);
+    try employees.put(.{ .int = 1 }, &.{.{ .name = "badge", .value = .{ .text = "B1" } }});
+    try employees.put(.{ .int = 2 }, &.{
+        .{ .name = "badge", .value = .{ .text = "B2" } },
+        .{ .name = "manager_badge", .value = .{ .text = "B1" } },
+    });
+
+    // Employee 2 still points at "B1" - renaming employee 1's own badge
+    // must be restricted.
+    try std.testing.expectError(error.ForeignKeyInUse, employees.put(.{ .int = 1 }, &.{
+        .{ .name = "badge", .value = .{ .text = "B1-NEW" } },
+    }));
+
+    // Employee 2 renaming its OWN badge (not the field being referenced by
+    // anyone) is unaffected - and does not restrict against itself despite
+    // the scan covering the same table.
+    try employees.put(.{ .int = 2 }, &.{
+        .{ .name = "badge", .value = .{ .text = "B2-NEW" } },
+        .{ .name = "manager_badge", .value = .{ .text = "B1" } },
+    });
+
+    // Once the report's manager_badge field is dropped (a row with no
+    // value for the FK field is exempt from the constraint, so this is a
+    // valid way to stop referencing anything), the manager's badge can be
+    // renamed.
+    try employees.put(.{ .int = 2 }, &.{
+        .{ .name = "badge", .value = .{ .text = "B2-NEW" } },
+    });
+    try employees.put(.{ .int = 1 }, &.{.{ .name = "badge", .value = .{ .text = "B1-NEW" } }});
+    var renamed = (try employees.get(.{ .int = 1 })).?;
+    defer renamed.deinit();
+    try std.testing.expectEqualStrings("B1-NEW", renamed.get("badge").?.text);
+}
+
+test "createCheckConstraint rejects a row that violates it and accepts one that satisfies it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createCheckConstraint("qty_positive", "qty gt i:0");
+    try std.testing.expect(orders.hasCheckConstraint("qty_positive"));
+
+    try orders.put(.{ .int = 1 }, &.{.{ .name = "qty", .value = .{ .int = 5 } }});
+    try std.testing.expectError(error.CheckViolation, orders.put(.{ .int = 2 }, &.{
+        .{ .name = "qty", .value = .{ .int = 0 } },
+    }));
+    try std.testing.expectError(error.CheckViolation, orders.put(.{ .int = 3 }, &.{
+        .{ .name = "qty", .value = .{ .int = -1 } },
+    }));
+}
+
+test "createCheckConstraint refuses to install over existing rows that already fail it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 1 }, &.{.{ .name = "qty", .value = .{ .int = -5 } }});
+
+    try std.testing.expectError(error.CheckViolation, orders.createCheckConstraint("qty_positive", "qty gt i:0"));
+    try std.testing.expect(!orders.hasCheckConstraint("qty_positive"));
+}
+
+test "createCheckConstraint rejects a malformed expression before persisting anything" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try std.testing.expectError(error.InvalidCheckExpression, orders.createCheckConstraint("bad", "qty gt"));
+    try std.testing.expect(!orders.hasCheckConstraint("bad"));
+}
+
+test "dropCheckConstraint lifts the constraint, and a check constraint survives a table reopen" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var orders = try Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createCheckConstraint("qty_positive", "qty gt i:0");
+    }
+
+    var reopened = try Table.open(&db, allocator, "orders");
+    defer reopened.deinit();
+    try std.testing.expect(reopened.hasCheckConstraint("qty_positive"));
+    try std.testing.expectError(error.CheckViolation, reopened.put(.{ .int = 1 }, &.{
+        .{ .name = "qty", .value = .{ .int = 0 } },
+    }));
+
+    try reopened.dropCheckConstraint("qty_positive");
+    try std.testing.expect(!reopened.hasCheckConstraint("qty_positive"));
+    try reopened.put(.{ .int = 1 }, &.{.{ .name = "qty", .value = .{ .int = 0 } }});
+}
+
+test "a row missing the checked field entirely is exempt (like is_null), but present-and-none is still checked" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createCheckConstraint("qty_known", "qty is_not_null");
+
+    try std.testing.expectError(error.CheckViolation, orders.put(.{ .int = 1 }, &.{}));
+}
+
+test "multiple CHECK constraints on the same table all must pass" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createCheckConstraint("qty_positive", "qty gt i:0");
+    try orders.createCheckConstraint("qty_capped", "qty lt i:1000");
+
+    try orders.put(.{ .int = 1 }, &.{.{ .name = "qty", .value = .{ .int = 500 } }});
+    try std.testing.expectError(error.CheckViolation, orders.put(.{ .int = 2 }, &.{
+        .{ .name = "qty", .value = .{ .int = 1000 } },
+    }));
+}
+
+test "ON DELETE CASCADE removes referencing rows instead of restricting the parent delete" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "Boris" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .cascade);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 101 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 200 }, &.{.{ .name = "customer_id", .value = .{ .int = 2 } }});
+
+    try customers.delete(.{ .int = 1 });
+
+    try std.testing.expect((try customers.get(.{ .int = 1 })) == null);
+    try std.testing.expect((try orders.get(.{ .int = 100 })) == null);
+    try std.testing.expect((try orders.get(.{ .int = 101 })) == null);
+
+    // Untouched: customer 2 and its own order were never in the cascade's
+    // path.
+    var otherCustomer = (try customers.get(.{ .int = 2 })).?;
+    otherCustomer.deinit();
+    var otherOrder = (try orders.get(.{ .int = 200 })).?;
+    otherOrder.deinit();
+}
+
+test "ON DELETE CASCADE keeps secondary indexes on the cascaded rows in sync" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createIndex("status");
+    try orders.createForeignKey("customer_id", "customers", pkField, .cascade);
+    try orders.put(.{ .int = 100 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 1 } },
+        .{ .name = "status", .value = .{ .text = "open" } },
+    });
+
+    const before = try idx.scanEq(&db, allocator, "orders", "status", .{ .text = "open" });
+    defer allocator.free(before);
+    try std.testing.expectEqual(@as(usize, 1), before.len);
+
+    try customers.delete(.{ .int = 1 });
+
+    // The cascaded delete went through `executeDelete`, which maintains
+    // secondary indexes exactly like a direct `orders.delete` would - a
+    // stale index entry pointing at a now-gone row would otherwise poison
+    // every future `status = "open"` scan.
+    const after = try idx.scanEq(&db, allocator, "orders", "status", .{ .text = "open" });
+    defer allocator.free(after);
+    try std.testing.expectEqual(@as(usize, 0), after.len);
+}
+
+test "ON DELETE CASCADE recurses transitively across more than one hop" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .cascade);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    var lineItems = try Table.open(&db, allocator, "line_items");
+    defer lineItems.deinit();
+    try lineItems.createForeignKey("order_id", "orders", pkField, .cascade);
+    try lineItems.put(.{ .int = 1000 }, &.{.{ .name = "order_id", .value = .{ .int = 100 } }});
+    try lineItems.put(.{ .int = 1001 }, &.{.{ .name = "order_id", .value = .{ .int = 100 } }});
+
+    // Deleting the customer must cascade into orders, and from there into
+    // line_items - two hops, not just one.
+    try customers.delete(.{ .int = 1 });
+
+    try std.testing.expect((try customers.get(.{ .int = 1 })) == null);
+    try std.testing.expect((try orders.get(.{ .int = 100 })) == null);
+    try std.testing.expect((try lineItems.get(.{ .int = 1000 })) == null);
+    try std.testing.expect((try lineItems.get(.{ .int = 1001 })) == null);
+}
+
+test "ON DELETE CASCADE is all-or-nothing: a RESTRICT hit anywhere in the fan-out aborts with nothing deleted" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "Ada" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .cascade);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    // A shipment row RESTRICTs deleting the order it points at - deleting
+    // the customer would need to cascade into this order, but the order
+    // itself cannot legally go while its own restrict-mode reference is
+    // still live.
+    var shipments = try Table.open(&db, allocator, "shipments");
+    defer shipments.deinit();
+    try shipments.createForeignKey("order_id", "orders", pkField, .restrict);
+    try shipments.put(.{ .int = 9000 }, &.{.{ .name = "order_id", .value = .{ .int = 100 } }});
+
+    try std.testing.expectError(error.ForeignKeyInUse, customers.delete(.{ .int = 1 }));
+
+    // Two-phase plan-then-execute means the customer AND the order (which
+    // had already been planned for cascade removal before the restrict
+    // hit further down was discovered) are both still there - not just
+    // the customer.
+    var stillCustomer = (try customers.get(.{ .int = 1 })).?;
+    stillCustomer.deinit();
+    var stillOrder = (try orders.get(.{ .int = 100 })).?;
+    stillOrder.deinit();
+    var stillShipment = (try shipments.get(.{ .int = 9000 })).?;
+    stillShipment.deinit();
+}
+
+test "ON DELETE CASCADE terminates on a two-table delete cycle instead of recursing forever" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    // `a` and `b` each carry a nullable FK at the other, both ON DELETE
+    // CASCADE - a delete starting from either side must not infinite-loop
+    // bouncing back and forth between the two tables.
+    var a = try Table.open(&db, allocator, "a");
+    defer a.deinit();
+    var b = try Table.open(&db, allocator, "b");
+    defer b.deinit();
+
+    try a.put(.{ .int = 1 }, &.{});
+    try b.put(.{ .int = 1 }, &.{.{ .name = "a_id", .value = .{ .int = 1 } }});
+    try a.createForeignKey("b_id", "b", pkField, .cascade);
+    try a.put(.{ .int = 1 }, &.{.{ .name = "b_id", .value = .{ .int = 1 } }});
+    try b.createForeignKey("a_id", "a", pkField, .cascade);
+
+    try a.delete(.{ .int = 1 });
+
+    try std.testing.expect((try a.get(.{ .int = 1 })) == null);
+    try std.testing.expect((try b.get(.{ .int = 1 })) == null);
+}
+
+test "ON DELETE CASCADE on a self-referencing foreign key removes an entire subtree" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var employees = try Table.open(&db, allocator, "employees");
+    defer employees.deinit();
+    try employees.createForeignKey("manager_id", "employees", pkField, .cascade);
+
+    // 1 (CEO) -> 2 (VP) -> 3 and 4 (reports of the VP).
+    try employees.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "CEO" } }});
+    try employees.put(.{ .int = 2 }, &.{
+        .{ .name = "name", .value = .{ .text = "VP" } },
+        .{ .name = "manager_id", .value = .{ .int = 1 } },
+    });
+    try employees.put(.{ .int = 3 }, &.{
+        .{ .name = "name", .value = .{ .text = "IC-A" } },
+        .{ .name = "manager_id", .value = .{ .int = 2 } },
+    });
+    try employees.put(.{ .int = 4 }, &.{
+        .{ .name = "name", .value = .{ .text = "IC-B" } },
+        .{ .name = "manager_id", .value = .{ .int = 2 } },
+    });
+
+    // Deleting the VP must cascade to both reports, but must not touch the
+    // CEO (an ancestor, not a dependent).
+    try employees.delete(.{ .int = 2 });
+
+    var ceo = (try employees.get(.{ .int = 1 })).?;
+    ceo.deinit();
+    try std.testing.expect((try employees.get(.{ .int = 2 })) == null);
+    try std.testing.expect((try employees.get(.{ .int = 3 })) == null);
+    try std.testing.expect((try employees.get(.{ .int = 4 })) == null);
+}
+
+test "deleteWhere cascades every match, not just the first" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "region", .value = .{ .text = "eu" } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "region", .value = .{ .text = "eu" } }});
+    try customers.put(.{ .int = 3 }, &.{.{ .name = "region", .value = .{ .text = "us" } }});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .cascade);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    try orders.put(.{ .int = 200 }, &.{.{ .name = "customer_id", .value = .{ .int = 2 } }});
+    try orders.put(.{ .int = 300 }, &.{.{ .name = "customer_id", .value = .{ .int = 3 } }});
+
+    const deleted = try customers.deleteWhere(.{ .eq = .{ .field = "region", .value = .{ .text = "eu" } } });
+    try std.testing.expectEqual(@as(usize, 2), deleted);
+
+    try std.testing.expect((try customers.get(.{ .int = 1 })) == null);
+    try std.testing.expect((try customers.get(.{ .int = 2 })) == null);
+    try std.testing.expect((try orders.get(.{ .int = 100 })) == null);
+    try std.testing.expect((try orders.get(.{ .int = 200 })) == null);
+
+    var stillCustomer = (try customers.get(.{ .int = 3 })).?;
+    stillCustomer.deinit();
+    var stillOrder = (try orders.get(.{ .int = 300 })).?;
+    stillOrder.deinit();
+}
+
+test "dropForeignKey lifts a CASCADE constraint the same as a RESTRICT one" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var customers = try Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{});
+
+    var orders = try Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try orders.createForeignKey("customer_id", "customers", pkField, .cascade);
+    try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    try orders.dropForeignKey("customer_id");
+    try customers.delete(.{ .int = 1 });
+
+    try std.testing.expect((try customers.get(.{ .int = 1 })) == null);
+    // No FK left at all, so the order is untouched by the parent's delete -
+    // not restricted, not cascaded, simply irrelevant now.
+    var stillOrder = (try orders.get(.{ .int = 100 })).?;
+    stillOrder.deinit();
+}
diff --git a/src/repl.zig b/src/repl.zig
new file mode 100644
index 0000000..25dd975
--- /dev/null
+++ b/src/repl.zig
@@ -0,0 +1,2938 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+const txnmod = @import("txn.zig");
+const rowmod = @import("row.zig");
+const idx = @import("index.zig");
+const querymod = @import("query.zig");
+const txntablemod = @import("txn_table.zig");
+const collectionsmod = @import("collections.zig");
+const collttlmod = @import("collttl.zig");
+const ttlmod = @import("ttl.zig");
+const exprmod = @import("expr.zig");
+const joinmod = @import("join.zig");
+const aggregatemod = @import("aggregate.zig");
+const windowmod = @import("window.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+const Transaction = txnmod.Transaction;
+const Table = querymod.Table;
+const TableTxn = txntablemod.TableTxn;
+const Value = rowmod.Value;
+const Field = rowmod.Field;
+const Row = rowmod.Row;
+const CollKind = collectionsmod.Kind;
+
+/// Errors `Repl.dispatch` can raise on top of whatever the underlying `Db`/
+/// `Transaction`/`Table` call it wraps returns (those propagate as-is, e.g.
+/// `error.Conflict` from a failed commit).
+pub const ReplError = error{
+    UnknownCommand,
+    WrongArgCount,
+    NoActiveTransaction,
+    TransactionAlreadyActive,
+    InvalidField,
+    UnknownCollectionKind,
+    UnknownCollectionOp,
+    InvalidArgument,
+    NoSuchKey,
+};
+
+/// Interactive session bound to one already-open `*Db`. The one-shot CLI in
+/// main.zig opens a fresh `Db` per process per command, and its `txn
+/// <script-file>` command runs a whole transaction non-interactively from a
+/// static file. `Repl` instead keeps the store open across many commands and
+/// lets `begin`/`commit`/`rollback` bracket an interactive `Transaction`:
+/// a `get` between `begin` and `commit` can steer what the *next* `put`
+/// does (e.g. "read balance, then decide how much to add"), which a script
+/// file evaluated top to bottom cannot express.
+///
+/// `table put/get/del` follow the active transaction automatically: with no
+/// transaction open they go straight through `query.Table` (each call is
+/// independently durable the moment it returns, exactly like `table put` on
+/// the plain CLI); with a transaction open they route through a `TableTxn`
+/// bound to it instead, so multiple `table put` calls across multiple
+/// tables in the same `begin`/`commit` bracket commit atomically as one
+/// `WriteBatch`, or none of them do on `error.Conflict` - the interactive
+/// equivalent of `txn <script-file>`.
+///
+/// `scan` always reads the live, already-committed `Db` state regardless of
+/// any open transaction: `Transaction` has no scan/range primitive (only
+/// `get`, which resolves the transaction's own staged writes first), so a
+/// staged-but-uncommitted put is invisible to `scan` until `commit` lands it
+/// for real. This is a deliberate, documented limitation, not an oversight.
+/// `table select`/`table join` are the same story one level up: `TableTxn`
+/// only ever brackets single-row put/get/delete, so both always run against
+/// `query.Table.open(self.db, ...)` directly, never through the active
+/// transaction, exactly like `scan`.
+pub const Repl = struct {
+    db: *Db,
+    allocator: Allocator,
+    txn: ?Transaction = null,
+    tableTxns: std.StringHashMap(TableTxn),
+
+    pub fn init(allocator: Allocator, db: *Db) Repl {
+        return .{
+            .db = db,
+            .allocator = allocator,
+            .tableTxns = std.StringHashMap(TableTxn).init(allocator),
+        };
+    }
+
+    pub fn deinit(self: *Repl) void {
+        self.discardTxnState();
+        self.tableTxns.deinit();
+    }
+
+    pub fn inTransaction(self: *const Repl) bool {
+        return self.txn != null;
+    }
+
+    fn discardTxnState(self: *Repl) void {
+        var it = self.tableTxns.iterator();
+        while (it.next()) |entry| {
+            self.allocator.free(entry.key_ptr.*);
+            entry.value_ptr.deinit();
+        }
+        self.tableTxns.clearRetainingCapacity();
+        if (self.txn) |*t| {
+            t.deinit();
+            self.txn = null;
+        }
+    }
+
+    /// Runs one line of input, writing command output or `error: <name>` to
+    /// `writer`. Returns `false` on `exit`/`quit` (caller should stop
+    /// reading), `true` otherwise - including after a reported error, so one
+    /// bad line never kills the session.
+    pub fn runLine(self: *Repl, line: []const u8, writer: anytype) !bool {
+        const trimmed = std.mem.trim(u8, line, " \t\r\n");
+        if (trimmed.len == 0 or trimmed[0] == '#') return true;
+
+        var tokens = std.ArrayList([]const u8).init(self.allocator);
+        defer tokens.deinit();
+        var it = std.mem.tokenizeAny(u8, trimmed, " \t");
+        while (it.next()) |tok| try tokens.append(tok);
+        if (tokens.items.len == 0) return true;
+
+        const cmd = tokens.items[0];
+        if (std.mem.eql(u8, cmd, "exit") or std.mem.eql(u8, cmd, "quit")) return false;
+
+        self.dispatch(cmd, tokens.items[1..], writer) catch |err| {
+            try writer.print("error: {s}\n", .{@errorName(err)});
+        };
+        return true;
+    }
+
+    /// Reads lines from `reader` until EOF, running each through `runLine`.
+    /// Writes a `cobalt>`/`cobalt(txn)>` prompt before each read when
+    /// `prompt` is set (interactive stdin use); script files pass `false`.
+    pub fn runFromReader(self: *Repl, reader: anytype, writer: anytype, prompt: bool) !void {
+        var buf: [8192]u8 = undefined;
+        while (true) {
+            if (prompt) {
+                try writer.writeAll(if (self.inTransaction()) "cobalt(txn)> " else "cobalt> ");
+            }
+            const line = (try reader.readUntilDelimiterOrEof(&buf, '\n')) orelse break;
+            if (!try self.runLine(line, writer)) break;
+        }
+    }
+
+    fn dispatch(self: *Repl, cmd: []const u8, args: []const []const u8, writer: anytype) !void {
+        if (std.mem.eql(u8, cmd, "begin")) return self.cmdBegin(args, writer);
+        if (std.mem.eql(u8, cmd, "commit")) return self.cmdCommit(args, writer);
+        if (std.mem.eql(u8, cmd, "rollback")) return self.cmdRollback(args, writer);
+        if (std.mem.eql(u8, cmd, "put")) return self.cmdPut(args, writer);
+        if (std.mem.eql(u8, cmd, "get")) return self.cmdGet(args, writer);
+        if (std.mem.eql(u8, cmd, "del")) return self.cmdDel(args, writer);
+        if (std.mem.eql(u8, cmd, "scan")) return self.cmdScan(args, writer);
+        if (std.mem.eql(u8, cmd, "stats")) return self.cmdStats(args, writer);
+        if (std.mem.eql(u8, cmd, "flush")) return self.cmdFlush(args, writer);
+        if (std.mem.eql(u8, cmd, "compact")) return self.cmdCompact(args, writer);
+        if (std.mem.eql(u8, cmd, "table")) return self.cmdTable(args, writer);
+        if (std.mem.eql(u8, cmd, "coll")) return self.cmdColl(args, writer);
+        if (std.mem.eql(u8, cmd, "expire")) return self.cmdExpire(args, writer);
+        if (std.mem.eql(u8, cmd, "persist")) return self.cmdPersist(args, writer);
+        if (std.mem.eql(u8, cmd, "ttl")) return self.cmdTtl(args, writer);
+        if (std.mem.eql(u8, cmd, "expire-sweep")) return self.cmdExpireSweep(args, writer);
+        if (std.mem.eql(u8, cmd, "help")) return self.cmdHelp(writer);
+        return ReplError.UnknownCommand;
+    }
+
+    fn cmdBegin(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 0) return ReplError.WrongArgCount;
+        if (self.txn != null) return ReplError.TransactionAlreadyActive;
+        self.txn = Transaction.begin(self.db);
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdCommit(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 0) return ReplError.WrongArgCount;
+        if (self.txn == null) return ReplError.NoActiveTransaction;
+        try self.txn.?.commit();
+        self.discardTxnState();
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdRollback(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 0) return ReplError.WrongArgCount;
+        if (self.txn == null) return ReplError.NoActiveTransaction;
+        self.discardTxnState();
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdPut(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 2) return ReplError.WrongArgCount;
+        if (self.txn) |*t| {
+            try t.put(args[0], args[1]);
+        } else {
+            try self.db.put(args[0], args[1]);
+        }
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdGet(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 1) return ReplError.WrongArgCount;
+        const value = if (self.txn) |*t|
+            try t.get(self.allocator, args[0])
+        else
+            try self.db.get(self.allocator, args[0]);
+        defer if (value) |v| self.allocator.free(v);
+        if (value) |v| {
+            try writer.print("{s}\n", .{v});
+        } else {
+            try writer.writeAll("(nil)\n");
+        }
+    }
+
+    fn cmdDel(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 1) return ReplError.WrongArgCount;
+        if (self.txn) |*t| {
+            try t.delete(args[0]);
+        } else {
+            try self.db.delete(args[0]);
+        }
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdScan(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len > 1) return ReplError.WrongArgCount;
+        const prefix = if (args.len == 1) args[0] else "";
+        var iter = try self.db.scanPrefix(self.allocator, prefix);
+        defer iter.deinit();
+        while (try iter.next()) |entry| {
+            try writer.print("{s}\t{s}\n", .{ entry.key, entry.value });
+        }
+    }
+
+    /// `expire`/`persist`/`ttl`/`expire-sweep` mirror the one-shot CLI's
+    /// same-named commands (main.zig) over `ttl.zig`'s flat-key TTL layer.
+    /// Like `scan` above, these always act on the live, already-committed
+    /// `Db` regardless of any open transaction: a TTL marker lives under its
+    /// own keyspace tag, set/cleared directly against `self.db`, never
+    /// staged through `Transaction` - there is no OCC-safe way to make
+    /// "expire this key in N seconds" conditional on a commit that hasn't
+    /// happened yet, so (deliberately, like `coll`'s ops) this bypasses the
+    /// active transaction entirely rather than pretending to participate in
+    /// it.
+    fn cmdExpire(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 2) return ReplError.WrongArgCount;
+        const seconds = std.fmt.parseInt(u64, args[1], 10) catch return ReplError.InvalidArgument;
+        const existing = try self.db.get(self.allocator, args[0]) orelse return ReplError.NoSuchKey;
+        self.allocator.free(existing);
+        try ttlmod.setExpireSeconds(self.db, self.allocator, args[0], std.time.nanoTimestamp(), seconds);
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdPersist(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 1) return ReplError.WrongArgCount;
+        try ttlmod.clearExpire(self.db, self.allocator, args[0]);
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdTtl(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 1) return ReplError.WrongArgCount;
+        switch (try ttlmod.remaining(self.db, self.allocator, args[0], std.time.nanoTimestamp())) {
+            .noKey => try writer.writeAll("-2\n"),
+            .noExpiry => try writer.writeAll("-1\n"),
+            .seconds => |s| try writer.print("{d}\n", .{s}),
+        }
+    }
+
+    fn cmdExpireSweep(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 0) return ReplError.WrongArgCount;
+        const reaped = try ttlmod.sweepExpired(self.db, self.allocator, std.time.nanoTimestamp());
+        try writer.print("reaped: {d}\n", .{reaped});
+    }
+
+    fn cmdStats(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 0) return ReplError.WrongArgCount;
+        try self.db.stats().print(writer);
+    }
+
+    fn cmdFlush(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 0) return ReplError.WrongArgCount;
+        try self.db.flush();
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdCompact(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len != 0) return ReplError.WrongArgCount;
+        try self.db.compact();
+        try writer.writeAll("OK\n");
+    }
+
+    fn cmdTable(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len < 1) return ReplError.WrongArgCount;
+        const op = args[0];
+        const rest = args[1..];
+
+        if (std.mem.eql(u8, op, "select")) return self.cmdTableSelect(rest, writer);
+        if (std.mem.eql(u8, op, "explain")) return self.cmdTableExplain(rest, writer);
+        if (std.mem.eql(u8, op, "update")) return self.cmdTableUpdate(rest, writer);
+        if (std.mem.eql(u8, op, "delete")) return self.cmdTableDelete(rest, writer);
+        if (std.mem.eql(u8, op, "join")) return self.cmdTableJoin(rest, writer);
+        if (std.mem.eql(u8, op, "aggregate")) return self.cmdTableAggregate(rest, writer);
+        if (std.mem.eql(u8, op, "window")) return self.cmdTableWindow(rest, writer);
+
+        if (rest.len < 2) return ReplError.WrongArgCount;
+        const tableName = rest[0];
+        const pk = try Value.parseCli(rest[1]);
+
+        if (std.mem.eql(u8, op, "put")) {
+            var fields = std.ArrayList(Field).init(self.allocator);
+            defer fields.deinit();
+            for (rest[2..]) |raw| try fields.append(try parseField(raw));
+            try self.tablePut(tableName, pk, fields.items);
+            try writer.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "get")) {
+            if (rest.len != 2) return ReplError.WrongArgCount;
+            var row = try self.tableGet(tableName, pk) orelse {
+                try writer.writeAll("(nil)\n");
+                return;
+            };
+            defer row.deinit();
+            try printRow(writer, row);
+        } else if (std.mem.eql(u8, op, "del")) {
+            if (rest.len != 2) return ReplError.WrongArgCount;
+            try self.tableDel(tableName, pk);
+            try writer.writeAll("OK\n");
+        } else {
+            return ReplError.UnknownCommand;
+        }
+    }
+
+    /// `table select <table> [expr...] [--limit N] [--offset N] [--order-by
+    /// field[:desc][,field[:desc]...]]`: interactive counterpart of the
+    /// one-shot CLI's `table select` (main.zig's `runTable`) over
+    /// query.zig's `Table.selectPageOrdered`, same expr grammar (expr.zig)
+    /// and `--limit`/`--offset`/`--order-by` conventions.
+    fn cmdTableSelect(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len < 1) return ReplError.WrongArgCount;
+        var table = try Table.open(self.db, self.allocator, args[0]);
+        defer table.deinit();
+
+        const sel = try extractSelectFlags(self.allocator, args[1..]);
+        defer self.allocator.free(sel.rest);
+        defer self.allocator.free(sel.flags.orderBy);
+
+        const exprText = try std.mem.join(self.allocator, " ", sel.rest);
+        defer self.allocator.free(exprText);
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = try exprmod.parse(self.allocator, exprText);
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const rows = try table.selectPageOrdered(pred, .{ .offset = sel.flags.page.offset, .limit = sel.flags.page.limit }, sel.flags.orderBy);
+        defer querymod.freeRows(self.allocator, rows);
+        for (rows) |r| try printRow(writer, r);
+    }
+
+    /// `table explain <table> [expr...]`: interactive counterpart of the
+    /// one-shot CLI's `table explain` (main.zig's `runTable`), reporting
+    /// which strategy `table select` would use for the same predicate
+    /// without running it - `query.Table.explain` over the same expr
+    /// grammar `cmdTableSelect` already uses.
+    fn cmdTableExplain(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len < 1) return ReplError.WrongArgCount;
+        var table = try Table.open(self.db, self.allocator, args[0]);
+        defer table.deinit();
+
+        const exprText = try std.mem.join(self.allocator, " ", args[1..]);
+        defer self.allocator.free(exprText);
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = try exprmod.parse(self.allocator, exprText);
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        var plan = try table.explain(self.allocator, pred);
+        defer plan.deinit(self.allocator);
+        try printPlan(writer, plan);
+    }
+
+    /// `table update <table> --set field=value[,field=value...] [expr...]`:
+    /// interactive counterpart of the one-shot CLI's `table update`
+    /// (main.zig's `runTable`) over `query.Table.updateWhere`, same
+    /// `--set`/expr grammar. Prints the number of rows updated.
+    fn cmdTableUpdate(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len < 1) return ReplError.WrongArgCount;
+        var table = try Table.open(self.db, self.allocator, args[0]);
+        defer table.deinit();
+
+        const setf = try extractSetFlag(self.allocator, args[1..]);
+        defer self.allocator.free(setf.sets);
+        defer self.allocator.free(setf.rest);
+
+        const exprText = try std.mem.join(self.allocator, " ", setf.rest);
+        defer self.allocator.free(exprText);
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = try exprmod.parse(self.allocator, exprText);
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const updated = try table.updateWhere(pred, setf.sets);
+        try writer.print("{d}\n", .{updated});
+    }
+
+    /// `table delete <table> [expr...]`: interactive counterpart of the
+    /// one-shot CLI's `table delete` (main.zig's `runTable`) over
+    /// `query.Table.deleteWhere`, same expr grammar as `cmdTableSelect`/
+    /// `cmdTableExplain` (empty expr deletes every row). Prints the number
+    /// of rows deleted.
+    fn cmdTableDelete(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len < 1) return ReplError.WrongArgCount;
+        var table = try Table.open(self.db, self.allocator, args[0]);
+        defer table.deinit();
+
+        const exprText = try std.mem.join(self.allocator, " ", args[1..]);
+        defer self.allocator.free(exprText);
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) {
+            parsed = try exprmod.parse(self.allocator, exprText);
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const deleted = try table.deleteWhere(pred);
+        try writer.print("{d}\n", .{deleted});
+    }
+
+    /// `table join [--left|--right|--full] <leftTable> <leftField>
+    /// <rightTable> <rightField> [--limit N] [--offset N]`: interactive
+    /// counterpart of the one-shot CLI's `table join` over join.zig's four
+    /// join functions. With no flag, prints inner-join pairs (`L <row>`
+    /// then `R <row>`); `--left`/`--right`/`--full` print `L (nil)`/
+    /// `R (nil)` for the unmatched side exactly like the CLI.
+    /// `--limit`/`--offset` window the already-joined result through
+    /// `join.applyPage`, same convention as `table select`'s paging (0 or
+    /// omitted = unlimited). Predicates on either side are not exposed here
+    /// (same deliberately minimal CLI surface as `table join` itself - the
+    /// richer path is the `join.zig` library API, as its own tests cover).
+    fn cmdTableJoin(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        const JoinMode = enum { inner, left, right, full };
+        var mode: JoinMode = .inner;
+        var positional = std.ArrayList([]const u8).init(self.allocator);
+        defer positional.deinit();
+        for (args) |a| {
+            if (std.mem.eql(u8, a, "--left")) {
+                mode = .left;
+            } else if (std.mem.eql(u8, a, "--right")) {
+                mode = .right;
+            } else if (std.mem.eql(u8, a, "--full")) {
+                mode = .full;
+            } else {
+                try positional.append(a);
+            }
+        }
+        const pf = try extractPageFlags(self.allocator, positional.items);
+        defer self.allocator.free(pf.rest);
+        if (pf.rest.len != 4) return ReplError.WrongArgCount;
+        const jargs = pf.rest;
+        const page = querymod.Page{ .offset = pf.page.offset, .limit = pf.page.limit };
+
+        var left = try Table.open(self.db, self.allocator, jargs[0]);
+        defer left.deinit();
+        var right = try Table.open(self.db, self.allocator, jargs[2]);
+        defer right.deinit();
+
+        switch (mode) {
+            .inner => {
+                const joined = try joinmod.innerJoin(self.allocator, &left, jargs[1], null, &right, jargs[3], null);
+                const paged = try joinmod.applyPage(joinmod.JoinedRow, self.allocator, joined, page);
+                defer joinmod.freeJoined(self.allocator, paged);
+                for (paged) |pair| {
+                    try writer.writeAll("L ");
+                    try printRow(writer, pair.left);
+                    try writer.writeAll("R ");
+                    try printRow(writer, pair.right);
+                }
+            },
+            .left => {
+                const joined = try joinmod.leftOuterJoin(self.allocator, &left, jargs[1], null, &right, jargs[3], null);
+                const paged = try joinmod.applyPage(joinmod.OuterJoinedRow, self.allocator, joined, page);
+                defer joinmod.freeOuterJoined(self.allocator, paged);
+                for (paged) |pair| {
+                    try writer.writeAll("L ");
+                    try printRow(writer, pair.left);
+                    if (pair.right) |r| {
+                        try writer.writeAll("R ");
+                        try printRow(writer, r);
+                    } else {
+                        try writer.writeAll("R (nil)\n");
+                    }
+                }
+            },
+            .right => {
+                const joined = try joinmod.rightOuterJoin(self.allocator, &left, jargs[1], null, &right, jargs[3], null);
+                const paged = try joinmod.applyPage(joinmod.RightOuterJoinedRow, self.allocator, joined, page);
+                defer joinmod.freeRightOuterJoined(self.allocator, paged);
+                for (paged) |pair| {
+                    if (pair.left) |l| {
+                        try writer.writeAll("L ");
+                        try printRow(writer, l);
+                    } else {
+                        try writer.writeAll("L (nil)\n");
+                    }
+                    try writer.writeAll("R ");
+                    try printRow(writer, pair.right);
+                }
+            },
+            .full => {
+                const joined = try joinmod.fullOuterJoin(self.allocator, &left, jargs[1], null, &right, jargs[3], null);
+                const paged = try joinmod.applyPage(joinmod.FullOuterJoinedRow, self.allocator, joined, page);
+                defer joinmod.freeFullOuterJoined(self.allocator, paged);
+                for (paged) |pair| {
+                    if (pair.left) |l| {
+                        try writer.writeAll("L ");
+                        try printRow(writer, l);
+                    } else {
+                        try writer.writeAll("L (nil)\n");
+                    }
+                    if (pair.right) |r| {
+                        try writer.writeAll("R ");
+                        try printRow(writer, r);
+                    } else {
+                        try writer.writeAll("R (nil)\n");
+                    }
+                }
+            },
+        }
+    }
+
+    /// `table aggregate <table> <groupField|*> <spec>[,<spec>...] [expr...]
+    /// [--limit N] [--offset N]`: interactive counterpart of the one-shot
+    /// CLI's `table aggregate` (main.zig's `runTable`) over `aggregate.zig`'s
+    /// `GroupBy`/`runGlobal`. `*` as the group field means no grouping
+    /// (`runGlobal`, always exactly one output line, `--limit`/`--offset`
+    /// ignored - nothing to page over a single row), same sentinel the CLI
+    /// uses; anything else groups by that field (`run`, one line per
+    /// distinct group value, first-seen order), windowed by
+    /// `aggregate.applyPageGroups` same as local `table aggregate`.
+    fn cmdTableAggregate(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len < 2) return ReplError.WrongArgCount;
+        var table = try Table.open(self.db, self.allocator, args[0]);
+        defer table.deinit();
+        const groupField = args[1];
+
+        const specs = parseAggSpecs(self.allocator, args[2]) catch return ReplError.InvalidArgument;
+        defer self.allocator.free(specs);
+
+        const flags = try extractPageFlags(self.allocator, args[3..]);
+        defer self.allocator.free(flags.rest);
+
+        const exprText = try std.mem.join(self.allocator, " ", flags.rest);
+        defer self.allocator.free(exprText);
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) parsed = try exprmod.parse(self.allocator, exprText);
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const rows = try table.select(pred);
+        defer querymod.freeRows(self.allocator, rows);
+
+        if (std.mem.eql(u8, groupField, "*")) {
+            const values = try aggregatemod.runGlobal(self.allocator, rows, specs);
+            defer aggregatemod.freeGlobalResult(self.allocator, values);
+            for (specs, values, 0..) |spec, v, i| {
+                if (i > 0) try writer.writeAll("\t");
+                try printAggLabel(writer, spec);
+                try writer.writeAll("=");
+                try printValue(writer, v);
+            }
+            try writer.writeAll("\n");
+        } else {
+            const unpaged = try aggregatemod.run(self.allocator, rows, groupField, specs);
+            const groups = try aggregatemod.applyPageGroups(self.allocator, unpaged, .{ .offset = flags.page.offset, .limit = flags.page.limit });
+            defer {
+                for (groups) |*g| g.deinit(self.allocator);
+                self.allocator.free(groups);
+            }
+            for (groups) |g| {
+                try writer.writeAll("group=");
+                try printValue(writer, g.group);
+                for (specs, g.values) |spec, v| {
+                    try writer.writeAll("\t");
+                    try printAggLabel(writer, spec);
+                    try writer.writeAll("=");
+                    try printValue(writer, v);
+                }
+                try writer.writeAll("\n");
+            }
+        }
+    }
+
+    /// `table window <table> <kind[:field]>[,<kind[:field]>...] [expr...]
+    /// [partition <field>[,field...]] [order <field[:desc]>[,field...]]
+    /// [--limit N] [--offset N] [--range]`: interactive counterpart of the
+    /// one-shot CLI's `table window` (main.zig's `runTable`) over
+    /// `window.zig`'s `computeMany` - a comma-separated spec list computes
+    /// multiple annotation columns sharing one partition/order/frame,
+    /// mirroring `table aggregate`'s multi-spec list. Unlike
+    /// `cmdTableAggregate`, a window annotation never collapses rows - every
+    /// matching row is printed, annotated with the computed value(s) - so
+    /// `--limit`/`--offset` window WHICH rows get
+    /// printed, walked in `window.orderedIndices`' partition-then-order
+    /// display sequence (matching local `table window`'s fix for the same
+    /// raw-scan-order paging bug, not raw scan order). `--range` switches
+    /// sum/avg/count/min/max from the default ROWS running frame to SQL's
+    /// actual RANGE default (rows tied on `order` share the tie group's
+    /// combined value), same as local `table window`/`remote-window`;
+    /// rejected together with row_number/rank/dense_rank.
+    fn cmdTableWindow(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len < 2) return ReplError.WrongArgCount;
+        var table = try Table.open(self.db, self.allocator, args[0]);
+        defer table.deinit();
+
+        const specs = parseWindowSpecs(self.allocator, args[1]) catch return ReplError.InvalidArgument;
+        defer self.allocator.free(specs);
+
+        const flags = try extractPageFlags(self.allocator, args[2..]);
+        defer self.allocator.free(flags.rest);
+
+        const rangeFlag = try extractRangeFlag(self.allocator, flags.rest);
+        defer self.allocator.free(rangeFlag.rest);
+        const frame: windowmod.FrameMode = if (rangeFlag.range) .range else .rows;
+
+        const split = splitWindowArgs(rangeFlag.rest);
+
+        const exprText = try std.mem.join(self.allocator, " ", split.whereArgs);
+        defer self.allocator.free(exprText);
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (exprText.len > 0) parsed = try exprmod.parse(self.allocator, exprText);
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        var partitionBy: [][]const u8 = &.{};
+        defer self.allocator.free(partitionBy);
+        if (split.partitionArgs) |partitionArgs| {
+            if (partitionArgs.len != 1) return ReplError.InvalidArgument;
+            partitionBy = parsePartitionList(self.allocator, partitionArgs[0]) catch return ReplError.InvalidArgument;
+        }
+
+        var orderBy: []querymod.OrderBy = &.{};
+        defer self.allocator.free(orderBy);
+        if (split.orderArgs) |orderArgs| {
+            if (orderArgs.len != 1) return ReplError.InvalidArgument;
+            orderBy = parseOrderByList(self.allocator, orderArgs[0]) catch return ReplError.InvalidArgument;
+        }
+
+        const rows = try table.select(pred);
+        defer querymod.freeRows(self.allocator, rows);
+
+        const results = try windowmod.computeMany(self.allocator, rows, partitionBy, orderBy, specs, frame);
+        defer windowmod.freeManyResults(self.allocator, results);
+
+        const displayOrder = try windowmod.orderedIndices(self.allocator, rows, partitionBy, orderBy);
+        defer self.allocator.free(displayOrder);
+
+        const total = displayOrder.len;
+        const start = @min(flags.page.offset, total);
+        const end = if (flags.page.limit == 0) total else @min(start + flags.page.limit, total);
+        var i: usize = start;
+        while (i < end) : (i += 1) {
+            const rowIdx = displayOrder[i];
+            for (rows[rowIdx].fields.items, 0..) |f, j| {
+                if (j > 0) try writer.writeAll("\t");
+                try writer.print("{s}=", .{f.name});
+                try printValue(writer, f.value);
+            }
+            if (rows[rowIdx].fields.items.len > 0) try writer.writeAll("\t");
+            for (specs, 0..) |spec, specIdx| {
+                if (specIdx > 0) try writer.writeAll("\t");
+                try printWindowLabel(writer, spec);
+                try writer.writeAll("=");
+                try printValue(writer, results[rowIdx][specIdx]);
+            }
+            try writer.writeAll("\n");
+        }
+    }
+
+    fn getOrOpenTableTxn(self: *Repl, name: []const u8) !*TableTxn {
+        if (self.tableTxns.getPtr(name)) |existing| return existing;
+        var opened = try TableTxn.open(&self.txn.?, self.allocator, name);
+        errdefer opened.deinit();
+        const nameCopy = try self.allocator.dupe(u8, name);
+        errdefer self.allocator.free(nameCopy);
+        try self.tableTxns.put(nameCopy, opened);
+        return self.tableTxns.getPtr(name).?;
+    }
+
+    fn tablePut(self: *Repl, name: []const u8, pk: Value, fields: []const Field) !void {
+        if (self.txn != null) {
+            const tt = try self.getOrOpenTableTxn(name);
+            return tt.put(pk, fields);
+        }
+        var table = try Table.open(self.db, self.allocator, name);
+        defer table.deinit();
+        try table.put(pk, fields);
+    }
+
+    fn tableGet(self: *Repl, name: []const u8, pk: Value) !?Row {
+        if (self.txn != null) {
+            const tt = try self.getOrOpenTableTxn(name);
+            return tt.get(pk);
+        }
+        var table = try Table.open(self.db, self.allocator, name);
+        defer table.deinit();
+        return table.get(pk);
+    }
+
+    fn tableDel(self: *Repl, name: []const u8, pk: Value) !void {
+        if (self.txn != null) {
+            const tt = try self.getOrOpenTableTxn(name);
+            return tt.delete(pk);
+        }
+        var table = try Table.open(self.db, self.allocator, name);
+        defer table.deinit();
+        try table.delete(pk);
+    }
+
+    /// Runs `coll <kind> <op> [args...]` against the live `Db` - the
+    /// interactive counterpart of the one-shot CLI's `coll` command
+    /// (main.zig's `runColl`), same dispatch shape and lazy-expiry-on-
+    /// access behavior (every op below reads/writes a named collection as
+    /// `rest[0]`, so a collection whose TTL already elapsed is expired
+    /// before the op sees it, matching the CLI). Deliberately NOT routed
+    /// through the REPL's active `Transaction` the way `table`/plain
+    /// `put`/`get`/`del` are: `Counter.incrBy`/`List.pushLeft`/`ZSet.add`/
+    /// etc. already open and commit their OWN internal `Transaction` with
+    /// OCC retry per call (see collections.zig), so there is no staged,
+    /// uncommitted state here for `begin`/`commit` to bracket the way
+    /// `TableTxn` brackets table writes - every `coll` op is independently
+    /// durable the instant it returns, with or without an open REPL
+    /// transaction, exactly like `scan` above always sees committed state
+    /// only regardless of any in-flight transaction.
+    fn cmdColl(self: *Repl, args: []const []const u8, writer: anytype) !void {
+        if (args.len >= 1 and std.mem.eql(u8, args[0], "expire-sweep")) {
+            if (args.len != 1) return ReplError.WrongArgCount;
+            const reaped = try collttlmod.sweepExpired(self.db, self.allocator, std.time.nanoTimestamp());
+            try writer.print("reaped: {d}\n", .{reaped});
+            return;
+        }
+        if (args.len < 2) return ReplError.WrongArgCount;
+        const kind = CollKind.parse(args[0]) orelse return ReplError.UnknownCollectionKind;
+        const op = args[1];
+        const rest = args[2..];
+
+        if (std.mem.eql(u8, op, "expire") or std.mem.eql(u8, op, "ttl") or std.mem.eql(u8, op, "persist")) {
+            return self.cmdCollTtl(kind, op, rest, writer);
+        }
+
+        if (rest.len >= 1) {
+            _ = try collttlmod.expireIfDue(self.db, self.allocator, kind, rest[0], std.time.nanoTimestamp());
+        }
+
+        switch (kind) {
+            .counter => try self.cmdCollCounter(op, rest, writer),
+            .hash => try self.cmdCollHash(op, rest, writer),
+            .set => try self.cmdCollSet(op, rest, writer),
+            .list => try self.cmdCollList(op, rest, writer),
+            .zset => try self.cmdCollZSet(op, rest, writer),
+        }
+    }
+
+    /// `coll <kind> expire|ttl|persist <name>` and `coll expire-sweep`
+    /// mirror the CLI's `runCollTtl`/top-of-`runColl` special case over
+    /// collttl.zig - the collection-namespace counterpart of `cmdExpire`/
+    /// `cmdPersist`/`cmdTtl`/`cmdExpireSweep` above, same reasoning for
+    /// bypassing the active transaction (a whole collection's expiry is not
+    /// staged through `Transaction` either).
+    fn cmdCollTtl(self: *Repl, kind: CollKind, op: []const u8, args: []const []const u8, writer: anytype) !void {
+        if (std.mem.eql(u8, op, "expire")) {
+            if (args.len != 2) return ReplError.WrongArgCount;
+            const seconds = std.fmt.parseInt(u64, args[1], 10) catch return ReplError.InvalidArgument;
+            if (!try collectionsmod.collectionExists(self.db, self.allocator, kind, args[0])) return ReplError.NoSuchKey;
+            try collttlmod.setExpireSeconds(self.db, self.allocator, kind, args[0], std.time.nanoTimestamp(), seconds);
+            try writer.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "persist")) {
+            if (args.len != 1) return ReplError.WrongArgCount;
+            try collttlmod.clearExpire(self.db, self.allocator, kind, args[0]);
+            try writer.writeAll("OK\n");
+        } else {
+            if (args.len != 1) return ReplError.WrongArgCount;
+            switch (try collttlmod.remaining(self.db, self.allocator, kind, args[0], std.time.nanoTimestamp())) {
+                .noKey => try writer.writeAll("-2\n"),
+                .noExpiry => try writer.writeAll("-1\n"),
+                .seconds => |s| try writer.print("{d}\n", .{s}),
+            }
+        }
+    }
+
+    fn cmdCollCounter(self: *Repl, op: []const u8, args: []const []const u8, writer: anytype) !void {
+        const Counter = collectionsmod.Counter;
+        if (std.mem.eql(u8, op, "get")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const v = try Counter.get(self.db, self.allocator, args[0]);
+            try writer.print("{d}\n", .{v});
+        } else if (std.mem.eql(u8, op, "set")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            const v = std.fmt.parseInt(i64, args[1], 10) catch return ReplError.InvalidArgument;
+            try Counter.set(self.db, self.allocator, args[0], v);
+            try writer.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "incrby")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            const delta = std.fmt.parseInt(i64, args[1], 10) catch return ReplError.InvalidArgument;
+            const v = try Counter.incrBy(self.db, self.allocator, args[0], delta);
+            try writer.print("{d}\n", .{v});
+        } else {
+            return ReplError.UnknownCollectionOp;
+        }
+    }
+
+    fn cmdCollHash(self: *Repl, op: []const u8, args: []const []const u8, writer: anytype) !void {
+        const Hash = collectionsmod.Hash;
+        if (std.mem.eql(u8, op, "set")) {
+            if (args.len < 3) return ReplError.WrongArgCount;
+            const created = try Hash.set(self.db, self.allocator, args[0], args[1], args[2]);
+            try writer.print("{s}\n", .{if (created) "created" else "updated"});
+        } else if (std.mem.eql(u8, op, "get")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            if (try Hash.get(self.db, self.allocator, args[0], args[1])) |v| {
+                defer self.allocator.free(v);
+                try writer.print("{s}\n", .{v});
+            } else {
+                try writer.writeAll("(nil)\n");
+            }
+        } else if (std.mem.eql(u8, op, "del")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            const existed = try Hash.del(self.db, self.allocator, args[0], args[1]);
+            try writer.print("{d}\n", .{@intFromBool(existed)});
+        } else if (std.mem.eql(u8, op, "len")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const n = try Hash.len(self.db, self.allocator, args[0]);
+            try writer.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "getall")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const fields = try Hash.getAll(self.db, self.allocator, args[0]);
+            defer {
+                for (fields) |f| f.free(self.allocator);
+                self.allocator.free(fields);
+            }
+            for (fields) |f| try writer.print("{s}\t{s}\n", .{ f.field, f.value });
+        } else {
+            return ReplError.UnknownCollectionOp;
+        }
+    }
+
+    fn cmdCollSet(self: *Repl, op: []const u8, args: []const []const u8, writer: anytype) !void {
+        const Set = collectionsmod.Set;
+        if (std.mem.eql(u8, op, "add")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            const added = try Set.add(self.db, self.allocator, args[0], args[1]);
+            try writer.print("{d}\n", .{@intFromBool(added)});
+        } else if (std.mem.eql(u8, op, "rem")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            const removed = try Set.remove(self.db, self.allocator, args[0], args[1]);
+            try writer.print("{d}\n", .{@intFromBool(removed)});
+        } else if (std.mem.eql(u8, op, "ismember")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            const is = try Set.isMember(self.db, self.allocator, args[0], args[1]);
+            try writer.print("{d}\n", .{@intFromBool(is)});
+        } else if (std.mem.eql(u8, op, "card")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const n = try Set.card(self.db, self.allocator, args[0]);
+            try writer.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "members")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const ms = try Set.members(self.db, self.allocator, args[0]);
+            defer {
+                for (ms) |m| self.allocator.free(m);
+                self.allocator.free(ms);
+            }
+            for (ms) |m| try writer.print("{s}\n", .{m});
+        } else if (std.mem.eql(u8, op, "inter") or std.mem.eql(u8, op, "union")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            _ = try collttlmod.expireIfDueMany(self.db, self.allocator, .set, args[1..], std.time.nanoTimestamp());
+            const ms = if (std.mem.eql(u8, op, "inter"))
+                try Set.intersect(self.db, self.allocator, args)
+            else
+                try Set.unionOf(self.db, self.allocator, args);
+            defer {
+                for (ms) |m| self.allocator.free(m);
+                self.allocator.free(ms);
+            }
+            for (ms) |m| try writer.print("{s}\n", .{m});
+        } else if (std.mem.eql(u8, op, "diff")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            _ = try collttlmod.expireIfDueMany(self.db, self.allocator, .set, args[1..], std.time.nanoTimestamp());
+            const ms = try Set.difference(self.db, self.allocator, args[0], args[1..]);
+            defer {
+                for (ms) |m| self.allocator.free(m);
+                self.allocator.free(ms);
+            }
+            for (ms) |m| try writer.print("{s}\n", .{m});
+        } else {
+            return ReplError.UnknownCollectionOp;
+        }
+    }
+
+    fn cmdCollList(self: *Repl, op: []const u8, args: []const []const u8, writer: anytype) !void {
+        const List = collectionsmod.List;
+        if (std.mem.eql(u8, op, "lpush")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            try List.pushLeft(self.db, self.allocator, args[0], args[1]);
+            try writer.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "rpush")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            try List.pushRight(self.db, self.allocator, args[0], args[1]);
+            try writer.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "lpop") or std.mem.eql(u8, op, "rpop")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const popped = if (std.mem.eql(u8, op, "lpop"))
+                try List.popLeft(self.db, self.allocator, args[0])
+            else
+                try List.popRight(self.db, self.allocator, args[0]);
+            if (popped) |v| {
+                defer self.allocator.free(v);
+                try writer.print("{s}\n", .{v});
+            } else {
+                try writer.writeAll("(nil)\n");
+            }
+        } else if (std.mem.eql(u8, op, "len")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const n = try List.len(self.db, self.allocator, args[0]);
+            try writer.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "range")) {
+            if (args.len < 3) return ReplError.WrongArgCount;
+            const start = std.fmt.parseInt(i64, args[1], 10) catch return ReplError.InvalidArgument;
+            const stop = std.fmt.parseInt(i64, args[2], 10) catch return ReplError.InvalidArgument;
+            const vals = try List.range(self.db, self.allocator, args[0], start, stop);
+            defer {
+                for (vals) |v| self.allocator.free(v);
+                self.allocator.free(vals);
+            }
+            for (vals) |v| try writer.print("{s}\n", .{v});
+        } else {
+            return ReplError.UnknownCollectionOp;
+        }
+    }
+
+    fn cmdCollZSet(self: *Repl, op: []const u8, args: []const []const u8, writer: anytype) !void {
+        const ZSet = collectionsmod.ZSet;
+        if (std.mem.eql(u8, op, "add")) {
+            if (args.len < 3) return ReplError.WrongArgCount;
+            const scoreVal = std.fmt.parseFloat(f64, args[2]) catch return ReplError.InvalidArgument;
+            try ZSet.add(self.db, self.allocator, args[0], args[1], scoreVal);
+            try writer.writeAll("OK\n");
+        } else if (std.mem.eql(u8, op, "score")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            if (try ZSet.score(self.db, self.allocator, args[0], args[1])) |s| {
+                try writer.print("{d}\n", .{s});
+            } else {
+                try writer.writeAll("(nil)\n");
+            }
+        } else if (std.mem.eql(u8, op, "incrby")) {
+            if (args.len < 3) return ReplError.WrongArgCount;
+            const delta = std.fmt.parseFloat(f64, args[2]) catch return ReplError.InvalidArgument;
+            const s = try ZSet.incrBy(self.db, self.allocator, args[0], args[1], delta);
+            try writer.print("{d}\n", .{s});
+        } else if (std.mem.eql(u8, op, "rem")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            const removed = try ZSet.remove(self.db, self.allocator, args[0], args[1]);
+            try writer.print("{d}\n", .{@intFromBool(removed)});
+        } else if (std.mem.eql(u8, op, "card")) {
+            if (args.len < 1) return ReplError.WrongArgCount;
+            const n = try ZSet.card(self.db, self.allocator, args[0]);
+            try writer.print("{d}\n", .{n});
+        } else if (std.mem.eql(u8, op, "rangebyrank") or std.mem.eql(u8, op, "rangebyscore")) {
+            if (args.len < 3) return ReplError.WrongArgCount;
+            const zms = if (std.mem.eql(u8, op, "rangebyrank")) blk: {
+                const start = std.fmt.parseInt(i64, args[1], 10) catch return ReplError.InvalidArgument;
+                const stop = std.fmt.parseInt(i64, args[2], 10) catch return ReplError.InvalidArgument;
+                break :blk try ZSet.rangeByRank(self.db, self.allocator, args[0], start, stop);
+            } else blk: {
+                const min = std.fmt.parseFloat(f64, args[1]) catch return ReplError.InvalidArgument;
+                const max = std.fmt.parseFloat(f64, args[2]) catch return ReplError.InvalidArgument;
+                break :blk try ZSet.rangeByScore(self.db, self.allocator, args[0], min, max);
+            };
+            defer {
+                for (zms) |zm| zm.free(self.allocator);
+                self.allocator.free(zms);
+            }
+            for (zms) |zm| try writer.print("{s}\t{d}\n", .{ zm.member, zm.score });
+        } else if (std.mem.eql(u8, op, "rank")) {
+            if (args.len < 2) return ReplError.WrongArgCount;
+            if (try ZSet.rank(self.db, self.allocator, args[0], args[1])) |r| {
+                try writer.print("{d}\n", .{r});
+            } else {
+                try writer.writeAll("(nil)\n");
+            }
+        } else {
+            return ReplError.UnknownCollectionOp;
+        }
+    }
+
+    fn cmdHelp(self: *Repl, writer: anytype) !void {
+        _ = self;
+        try writer.writeAll(
+            \\commands:
+            \\  put <key> <value>            table put <table> <pk> [field=value ...]
+            \\  get <key>                    table get <table> <pk>
+            \\  del <key>                    table del <table> <pk>
+            \\  scan [prefix]                begin / commit / rollback
+            \\  stats / flush / compact      exit / quit
+            \\  table select <table> [expr...] [--limit N] [--offset N]
+            \\                        [--order-by f[:desc][,f[:desc]...]]
+            \\  table join [--left|--right|--full] <lt> <lf> <rt> <rf> [--limit N] [--offset N]
+            \\  table aggregate <table> <groupField|*> <spec>[,<spec>...] [expr...] [--limit N] [--offset N]
+            \\  table window <table> <kind[:field]>[,<kind[:field]>...] [expr...] [partition f[,f...]]
+            \\                        [order f[:desc][,f...]] [--limit N] [--offset N] [--range]
+            \\  coll <kind> <op> [args...]   kind: counter/hash/set/list/zset
+            \\  expire/persist/ttl <key>     coll <kind> expire/persist/ttl <name>
+            \\  expire-sweep                 coll expire-sweep
+            \\
+        );
+    }
+};
+
+const PageFlags = struct { limit: u32 = 0, offset: u32 = 0 };
+
+/// Pulls `--limit N` / `--offset N` out of a `table select` argument list
+/// wherever they appear, returning the remaining tokens (destined to be
+/// joined into the expr text) alongside the parsed page window. Same shape
+/// as main.zig's identically-named helper for `table select`/`remote-select`
+/// on the one-shot CLI - kept as its own small copy here rather than shared,
+/// since main.zig is the binary entry point and not a module repl.zig can
+/// import. Caller owns and frees `rest`.
+fn extractPageFlags(allocator: Allocator, args: []const []const u8) !struct { page: PageFlags, rest: [][]const u8 } {
+    var page = PageFlags{};
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        const isLimit = std.mem.eql(u8, args[i], "--limit");
+        const isOffset = std.mem.eql(u8, args[i], "--offset");
+        if (isLimit or isOffset) {
+            i += 1;
+            if (i >= args.len) return error.InvalidPageFlag;
+            const n = std.fmt.parseInt(u32, args[i], 10) catch return error.InvalidPageFlag;
+            if (isLimit) page.limit = n else page.offset = n;
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    return .{ .page = page, .rest = try rest.toOwnedSlice() };
+}
+
+/// Pulls a lone `--range` flag (no value) out of `table window`'s trailing
+/// args, requesting `window.FrameMode.range` instead of the default
+/// `.rows` running frame - see `window.zig`'s `compute` doc comment. Same
+/// shape as main.zig's identically-named helper, kept as its own small copy
+/// here for the same reason `extractPageFlags` above is. Caller owns and
+/// frees `rest`.
+fn extractRangeFlag(allocator: Allocator, args: []const []const u8) !struct { range: bool, rest: [][]const u8 } {
+    var range = false;
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+    for (args) |a| {
+        if (std.mem.eql(u8, a, "--range")) {
+            range = true;
+        } else {
+            try rest.append(a);
+        }
+    }
+    return .{ .range = range, .rest = try rest.toOwnedSlice() };
+}
+
+const SelectFlags = struct { page: PageFlags = .{}, orderBy: []const querymod.OrderBy = &.{} };
+
+/// `table select`-only counterpart of `extractPageFlags` above, mirroring
+/// main.zig's identically-shaped `extractSelectFlags`/`SelectFlags`: same
+/// `--limit`/`--offset` handling plus `--order-by
+/// field[:desc][,field[:desc]...]` (comma-separated, applied left to
+/// right), kept SEPARATE from `extractPageFlags` rather than folded into
+/// it because `extractPageFlags` is also used by `table join`/`table
+/// aggregate` here, neither of which sorts its result - recognizing
+/// `--order-by` there too would silently consume the flag without
+/// honoring it. Caller owns and frees `rest` AND `flags.orderBy`.
+fn extractSelectFlags(allocator: Allocator, args: []const []const u8) !struct { flags: SelectFlags, rest: [][]const u8 } {
+    var flags = SelectFlags{};
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        const isLimit = std.mem.eql(u8, args[i], "--limit");
+        const isOffset = std.mem.eql(u8, args[i], "--offset");
+        const isOrderBy = std.mem.eql(u8, args[i], "--order-by");
+        if (isLimit or isOffset) {
+            i += 1;
+            if (i >= args.len) return error.InvalidPageFlag;
+            const n = std.fmt.parseInt(u32, args[i], 10) catch return error.InvalidPageFlag;
+            if (isLimit) flags.page.limit = n else flags.page.offset = n;
+        } else if (isOrderBy) {
+            i += 1;
+            if (i >= args.len) return error.InvalidPageFlag;
+            allocator.free(flags.orderBy);
+            flags.orderBy = try parseOrderByList(allocator, args[i]);
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    return .{ .flags = flags, .rest = try rest.toOwnedSlice() };
+}
+
+/// Parses `--order-by`'s `field[:desc]` value - mirrors main.zig's
+/// identically-shaped `parseOrderByFlag` (kept as its own copy for the same
+/// reason `extractPageFlags`'s doc comment gives: repl.zig cannot import
+/// main.zig, the binary entry point). `:desc`/`:asc` are the only accepted
+/// suffixes; anything else is a malformed flag, not a silent default.
+fn parseOrderByFlag(text: []const u8) !querymod.OrderBy {
+    if (std.mem.indexOfScalar(u8, text, ':')) |colon| {
+        const field = text[0..colon];
+        const dir = text[colon + 1 ..];
+        if (field.len == 0) return error.InvalidPageFlag;
+        if (std.mem.eql(u8, dir, "desc")) return .{ .field = field, .descending = true };
+        if (std.mem.eql(u8, dir, "asc")) return .{ .field = field, .descending = false };
+        return error.InvalidPageFlag;
+    }
+    if (text.len == 0) return error.InvalidPageFlag;
+    return .{ .field = text };
+}
+
+/// Splits `--order-by`'s comma-separated value into one or more columns -
+/// mirrors main.zig's identically-shaped `parseOrderByList` (kept as its
+/// own copy for the same reason `parseOrderByFlag` above is). Caller owns
+/// and frees the returned slice.
+fn parseOrderByList(allocator: Allocator, text: []const u8) ![]querymod.OrderBy {
+    var list = std.ArrayList(querymod.OrderBy).init(allocator);
+    errdefer list.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |segment| {
+        try list.append(try parseOrderByFlag(segment));
+    }
+    return list.toOwnedSlice();
+}
+
+/// Splits `name=value` into a Field, validating the name the same way
+/// index/table identifiers already are. Values follow the CLI's `i:`/`f:`/
+/// `b:`/`s:` typed-literal convention via `Value.parseCli`.
+fn parseField(text: []const u8) !Field {
+    const eq = std.mem.indexOfScalar(u8, text, '=') orelse return ReplError.InvalidField;
+    const name = text[0..eq];
+    if (!idx.validIdentifier(name)) return ReplError.InvalidField;
+    const value = try Value.parseCli(text[eq + 1 ..]);
+    return .{ .name = name, .value = value };
+}
+
+/// Splits `--set`'s comma-separated `name=value[,name=value...]` value into
+/// a list of Fields, each parsed by `parseField` - mirrors main.zig's
+/// identically-shaped `parseSetList` (kept as its own copy for the same
+/// reason `parseOrderByList` above is).  Caller owns and frees the returned
+/// slice.
+fn parseSetList(allocator: Allocator, text: []const u8) ![]Field {
+    var list = std.ArrayList(Field).init(allocator);
+    errdefer list.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |segment| {
+        try list.append(try parseField(segment));
+    }
+    return list.toOwnedSlice();
+}
+
+/// Pulls a single required `--set name=value[,name=value...]` flag out of a
+/// `table update` argument list - mirrors main.zig's identically-shaped
+/// `extractSetFlag`. Missing `--set` is `error.MissingSetFlag`: a `SET`-less
+/// `UPDATE` names nothing to change. Caller owns and frees `rest` and the
+/// returned `sets` slice.
+fn extractSetFlag(allocator: Allocator, args: []const []const u8) !struct { sets: []Field, rest: [][]const u8 } {
+    var sets: []Field = &.{};
+    errdefer allocator.free(sets);
+    var rest = std.ArrayList([]const u8).init(allocator);
+    errdefer rest.deinit();
+
+    var i: usize = 0;
+    while (i < args.len) : (i += 1) {
+        if (std.mem.eql(u8, args[i], "--set")) {
+            i += 1;
+            if (i >= args.len) return error.InvalidSetFlag;
+            allocator.free(sets);
+            sets = parseSetList(allocator, args[i]) catch return error.InvalidSetFlag;
+        } else {
+            try rest.append(args[i]);
+        }
+    }
+    if (sets.len == 0) return error.MissingSetFlag;
+    return .{ .sets = sets, .rest = try rest.toOwnedSlice() };
+}
+
+fn parseAggKind(name: []const u8) ?aggregatemod.AggKind {
+    if (std.mem.eql(u8, name, "count")) return .count;
+    if (std.mem.eql(u8, name, "sum")) return .sum;
+    if (std.mem.eql(u8, name, "avg")) return .avg;
+    if (std.mem.eql(u8, name, "min")) return .min;
+    if (std.mem.eql(u8, name, "max")) return .max;
+    if (std.mem.eql(u8, name, "distinct")) return .count_distinct;
+    return null;
+}
+
+/// Parses a comma-separated `table aggregate` spec list, same grammar and
+/// same small standalone copy as main.zig's identically-named helper (see
+/// `extractPageFlags` above for why this is not shared - main.zig is the
+/// binary entry point, not a module repl.zig can import).
+fn parseAggSpecs(allocator: Allocator, text: []const u8) ![]aggregatemod.AggSpec {
+    var specs = std.ArrayList(aggregatemod.AggSpec).init(allocator);
+    errdefer specs.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |part| {
+        if (part.len == 0) return error.InvalidAggSpec;
+        if (std.mem.indexOfScalar(u8, part, ':')) |colon| {
+            const kind = parseAggKind(part[0..colon]) orelse return error.InvalidAggSpec;
+            const field = part[colon + 1 ..];
+            if (!idx.validIdentifier(field)) return error.InvalidAggSpec;
+            try specs.append(.{ .field = field, .kind = kind });
+        } else {
+            const kind = parseAggKind(part) orelse return error.InvalidAggSpec;
+            if (kind != .count) return error.InvalidAggSpec;
+            try specs.append(.{ .field = "", .kind = kind });
+        }
+    }
+    if (specs.items.len == 0) return error.InvalidAggSpec;
+    return specs.toOwnedSlice();
+}
+
+fn printAggLabel(writer: anytype, spec: aggregatemod.AggSpec) !void {
+    if (spec.field.len == 0) {
+        try writer.writeAll(@tagName(spec.kind));
+    } else {
+        try writer.print("{s}_{s}", .{ @tagName(spec.kind), spec.field });
+    }
+}
+
+fn parseWindowKind(name: []const u8) ?windowmod.WindowKind {
+    if (std.mem.eql(u8, name, "row_number")) return .row_number;
+    if (std.mem.eql(u8, name, "rank")) return .rank;
+    if (std.mem.eql(u8, name, "dense_rank")) return .dense_rank;
+    if (std.mem.eql(u8, name, "sum")) return .sum;
+    if (std.mem.eql(u8, name, "avg")) return .avg;
+    if (std.mem.eql(u8, name, "count")) return .count;
+    if (std.mem.eql(u8, name, "count_distinct")) return .count_distinct;
+    if (std.mem.eql(u8, name, "min")) return .min;
+    if (std.mem.eql(u8, name, "max")) return .max;
+    if (std.mem.eql(u8, name, "lag")) return .lag;
+    if (std.mem.eql(u8, name, "lead")) return .lead;
+    if (std.mem.eql(u8, name, "first_value")) return .first_value;
+    if (std.mem.eql(u8, name, "last_value")) return .last_value;
+    if (std.mem.eql(u8, name, "nth_value")) return .nth_value;
+    return null;
+}
+
+/// Parses a single `table window` spec token, same grammar (including
+/// lag/lead's optional `:offset[:default]` suffix and nth_value's required
+/// `:n[:default]` suffix) and same small standalone copy as main.zig's
+/// identically-named helper (see `parseAggSpecs` above for why this is not
+/// shared).
+fn parseWindowSpec(text: []const u8) !windowmod.WindowSpec {
+    var it = std.mem.splitScalar(u8, text, ':');
+    const kind = parseWindowKind(it.next().?) orelse return error.InvalidWindowSpec;
+
+    if (kind == .row_number or kind == .rank or kind == .dense_rank) {
+        if (it.next() != null) return error.InvalidWindowSpec;
+        return .{ .field = "", .kind = kind };
+    }
+    if (kind == .lag or kind == .lead) {
+        const field = it.next() orelse return error.InvalidWindowSpec;
+        if (!idx.validIdentifier(field)) return error.InvalidWindowSpec;
+        var spec = windowmod.WindowSpec{ .field = field, .kind = kind };
+        if (it.next()) |offsetText| {
+            spec.offset = std.fmt.parseInt(u64, offsetText, 10) catch return error.InvalidWindowSpec;
+            // `it.rest()`, NOT another `it.next()`: a typed default literal
+            // (`i:-1`, `s:foo:bar`) can itself contain colons, which would
+            // get wrongly re-split by a further `splitScalar` step.
+            const rest = it.rest();
+            if (rest.len > 0) spec.default = Value.parseCli(rest) catch return error.InvalidWindowSpec;
+        }
+        return spec;
+    }
+    if (kind == .nth_value) {
+        const field = it.next() orelse return error.InvalidWindowSpec;
+        if (!idx.validIdentifier(field)) return error.InvalidWindowSpec;
+        const nText = it.next() orelse return error.InvalidWindowSpec;
+        const n = std.fmt.parseInt(u64, nText, 10) catch return error.InvalidWindowSpec;
+        if (n == 0) return error.InvalidWindowSpec;
+        var spec = windowmod.WindowSpec{ .field = field, .kind = kind, .offset = n };
+        const rest = it.rest();
+        if (rest.len > 0) spec.default = Value.parseCli(rest) catch return error.InvalidWindowSpec;
+        return spec;
+    }
+
+    const field = it.next() orelse {
+        if (kind == .count) return .{ .field = "", .kind = kind };
+        return error.InvalidWindowSpec;
+    };
+    if (it.next() != null) return error.InvalidWindowSpec;
+    if (!idx.validIdentifier(field)) return error.InvalidWindowSpec;
+    return .{ .field = field, .kind = kind };
+}
+
+/// Parses `table window`'s comma-separated spec list, same grammar and same
+/// small standalone copy as main.zig's identically-named helper (see
+/// `parseAggSpecs` above for why this is not shared) - lets one interactive
+/// `table window` call annotate rows with multiple columns sharing one
+/// `PARTITION BY`/`ORDER BY`/frame (`window.computeMany`).
+fn parseWindowSpecs(allocator: Allocator, text: []const u8) ![]windowmod.WindowSpec {
+    var specs = std.ArrayList(windowmod.WindowSpec).init(allocator);
+    errdefer specs.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |part| {
+        if (part.len == 0) return error.InvalidWindowSpec;
+        try specs.append(try parseWindowSpec(part));
+    }
+    if (specs.items.len == 0) return error.InvalidWindowSpec;
+    return specs.toOwnedSlice();
+}
+
+fn printWindowLabel(writer: anytype, spec: windowmod.WindowSpec) !void {
+    if (spec.field.len == 0) {
+        try writer.writeAll(@tagName(spec.kind));
+    } else {
+        try writer.print("{s}_{s}", .{ @tagName(spec.kind), spec.field });
+    }
+}
+
+fn findLiteralToken(args: []const []const u8, token: []const u8) ?usize {
+    for (args, 0..) |a, i| {
+        if (std.mem.eql(u8, a, token)) return i;
+    }
+    return null;
+}
+
+/// Splits the trailing free-text args of `table window` on literal
+/// `partition` and `order` tokens, same grammar and same small standalone
+/// copy as main.zig's identically-named helper (see `parseAggSpecs` above
+/// for why this is not shared).
+fn splitWindowArgs(args: []const []const u8) struct { whereArgs: []const []const u8, partitionArgs: ?[]const []const u8, orderArgs: ?[]const []const u8 } {
+    if (findLiteralToken(args, "partition")) |pi| {
+        const whereArgs = args[0..pi];
+        const afterPartition = args[pi + 1 ..];
+        if (findLiteralToken(afterPartition, "order")) |oi| {
+            return .{ .whereArgs = whereArgs, .partitionArgs = afterPartition[0..oi], .orderArgs = afterPartition[oi + 1 ..] };
+        }
+        return .{ .whereArgs = whereArgs, .partitionArgs = afterPartition, .orderArgs = null };
+    }
+    if (findLiteralToken(args, "order")) |oi| {
+        return .{ .whereArgs = args[0..oi], .partitionArgs = null, .orderArgs = args[oi + 1 ..] };
+    }
+    return .{ .whereArgs = args, .partitionArgs = null, .orderArgs = null };
+}
+
+/// Parses `table window`'s `partition <field>[,field...]` value, same
+/// grammar and same small standalone copy as main.zig's identically-named
+/// helper. Caller owns and frees the returned slice (not each field - they
+/// borrow from `text`).
+fn parsePartitionList(allocator: Allocator, text: []const u8) ![][]const u8 {
+    var list = std.ArrayList([]const u8).init(allocator);
+    errdefer list.deinit();
+    var it = std.mem.splitScalar(u8, text, ',');
+    while (it.next()) |field| {
+        if (!idx.validIdentifier(field)) return error.InvalidPartitionField;
+        try list.append(field);
+    }
+    return list.toOwnedSlice();
+}
+
+fn printValue(writer: anytype, value: Value) !void {
+    switch (value) {
+        .none => try writer.writeAll("(none)"),
+        .boolean => |b| try writer.print("{}", .{b}),
+        .int => |i| try writer.print("{d}", .{i}),
+        .float => |f| try writer.print("{d}", .{f}),
+        .text => |s| try writer.writeAll(s),
+        .bytes => |b| for (b) |byte| try writer.print("{x:0>2}", .{byte}),
+    }
+}
+
+fn printRow(writer: anytype, row: Row) !void {
+    for (row.fields.items, 0..) |f, i| {
+        if (i > 0) try writer.writeAll("\t");
+        try writer.print("{s}=", .{f.name});
+        try printValue(writer, f.value);
+    }
+    try writer.writeAll("\n");
+}
+
+/// Same wording as main.zig's own `printPlan` (the two binaries do not
+/// share this helper - main.zig has no repl.zig dependency and vice versa).
+fn printPlan(writer: anytype, plan: querymod.Plan) !void {
+    switch (plan.kind) {
+        .full_scan => try writer.writeAll("full scan (no usable index)\n"),
+        .index_eq => try writer.print("index '{s}' (equality)\n", .{plan.indexName.?}),
+        .index_range => try writer.print("index '{s}' (range)\n", .{plan.indexName.?}),
+        .composite_eq => try writer.print("composite index '{s}' (equality, {d}/{d} columns matched)\n", .{ plan.indexName.?, plan.matchedFields, plan.totalFields }),
+        .composite_range => try writer.print("composite index '{s}' (range, {d}/{d} columns matched)\n", .{ plan.indexName.?, plan.matchedFields, plan.totalFields }),
+    }
+}
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    var pathBuf: [std.fs.max_path_bytes]u8 = undefined;
+    const base = try tmp.dir.realpath(".", &pathBuf);
+    var dbPathBuf: [std.fs.max_path_bytes]u8 = undefined;
+    const dbPath = try std.fmt.bufPrint(&dbPathBuf, "{s}/store", .{base});
+    return Db.open(allocator, dbPath, .{});
+}
+
+fn runScript(allocator: Allocator, repl: *Repl, script: []const u8) ![]u8 {
+    var stream = std.io.fixedBufferStream(script);
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try repl.runFromReader(stream.reader(), out.writer(), false);
+    return out.toOwnedSlice();
+}
+
+test "plain put/get/del run immediately without a transaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "put a 1\nget a\ndel a\nget a\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\n1\nOK\n(nil)\n", out);
+}
+
+test "comments and blank lines are ignored, exit stops the loop early" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\# a comment
+        \\
+        \\put a 1
+        \\exit
+        \\get a
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\n", out);
+}
+
+test "table select filters by expr and honors --limit/--offset" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put items i:1 name=a price=i:10
+        \\table put items i:2 name=b price=i:20
+        \\table put items i:3 name=c price=i:30
+        \\table select items price gt i:10
+        \\table select items price gt i:10 --limit 1
+        \\table select items price gt i:10 --offset 1
+        \\table select items
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=2\tname=b\tprice=20\n" ++
+            "__pk=3\tname=c\tprice=30\n" ++
+            "__pk=2\tname=b\tprice=20\n" ++
+            "__pk=3\tname=c\tprice=30\n" ++
+            "__pk=1\tname=a\tprice=10\n" ++
+            "__pk=2\tname=b\tprice=20\n" ++
+            "__pk=3\tname=c\tprice=30\n",
+        out,
+    );
+}
+
+test "table select --order-by sorts by field, honoring :desc and combining with --limit/--offset" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    // Insert with pk NOT in price order, so a bug that sorted only within
+    // the natural pk scan order (or ignored --order-by entirely) would
+    // produce a visibly different sequence than asserted below.
+    const out = try runScript(allocator, &repl,
+        \\table put items i:1 name=b price=i:20
+        \\table put items i:2 name=a price=i:30
+        \\table put items i:3 name=c price=i:10
+        \\table select items --order-by price
+        \\table select items --order-by price:desc
+        \\table select items --order-by price:desc --limit 1 --offset 1
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=3\tname=c\tprice=10\n" ++
+            "__pk=1\tname=b\tprice=20\n" ++
+            "__pk=2\tname=a\tprice=30\n" ++
+            "__pk=2\tname=a\tprice=30\n" ++
+            "__pk=1\tname=b\tprice=20\n" ++
+            "__pk=3\tname=c\tprice=10\n" ++
+            "__pk=1\tname=b\tprice=20\n",
+        out,
+    );
+}
+
+test "table select --order-by rejects a malformed direction suffix instead of defaulting to ascending" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "table put items i:1 price=i:5\ntable select items --order-by price:dsc\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nerror: InvalidPageFlag\n", out);
+}
+
+test "table select --order-by with two comma-separated columns sorts by the first, breaking ties with the second" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    // Two rows share city "warsaw" with prices NOT in insertion order, so
+    // a single-column city sort alone would leave them in whatever order
+    // they were inserted - only a real `price` tiebreak fixes that.
+    const out = try runScript(allocator, &repl,
+        \\table put items i:1 city=warsaw price=i:30
+        \\table put items i:2 city=krakow price=i:5
+        \\table put items i:3 city=warsaw price=i:10
+        \\table select items --order-by city,price
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=2\tcity=krakow\tprice=5\n" ++
+            "__pk=3\tcity=warsaw\tprice=10\n" ++
+            "__pk=1\tcity=warsaw\tprice=30\n",
+        out,
+    );
+}
+
+test "table select --order-by rejects an empty segment from a doubled comma instead of silently collapsing it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "table put items i:1 price=i:5\ntable select items --order-by city,,price\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nerror: InvalidPageFlag\n", out);
+}
+
+test "table select reports a parse error on malformed expr without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "table select items price bogus i:1\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("error: UnknownOperator\n", out);
+}
+
+test "table explain reports full_scan, an index, and a composite index, matching what table select would actually use" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var table = try Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createIndex("age");
+        try table.createCompositeIndex("city_age", &.{ "city", "age" });
+    }
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put users i:1 city=s:warsaw age=i:30
+        \\table explain users
+        \\table explain users city eq s:warsaw
+        \\table explain users age eq i:30
+        \\table explain users city eq s:warsaw and age eq i:30
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\n" ++
+            "full scan (no usable index)\n" ++
+            "full scan (no usable index)\n" ++
+            "index 'age' (equality)\n" ++
+            "composite index 'city_age' (equality, 2/2 columns matched)\n",
+        out,
+    );
+}
+
+test "table update applies --set to matching rows, prints the count, and leaves other rows untouched" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put users i:1 city=s:warsaw active=i:0
+        \\table put users i:2 city=s:warsaw active=i:0
+        \\table put users i:3 city=s:krakow active=i:0
+        \\table update users --set active=i:1 city eq s:warsaw
+        \\table select users --order-by __pk
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "2\n" ++
+            "__pk=1\tcity=warsaw\tactive=1\n" ++
+            "__pk=2\tcity=warsaw\tactive=1\n" ++
+            "__pk=3\tcity=krakow\tactive=0\n",
+        out,
+    );
+}
+
+test "table update without --set is rejected as MissingSetFlag instead of silently updating nothing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "table put users i:1 city=s:warsaw\ntable update users city eq s:warsaw\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nerror: MissingSetFlag\n", out);
+}
+
+test "table join inner/left/right/full match main.zig's L/R printing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put customers i:1 name=alice
+        \\table put customers i:2 name=bob
+        \\table put orders i:100 customer_id=i:1 total=i:50
+        \\table put orders i:101 customer_id=i:999 total=i:5
+        \\table join customers __pk orders customer_id
+        \\table join --left customers __pk orders customer_id
+        \\table join --right customers __pk orders customer_id
+        \\table join --full customers __pk orders customer_id
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        // plain inner join: only alice/order100 matches, bob and the orphan
+        // order are absent.
+        "OK\nOK\nOK\nOK\n" ++
+            "L __pk=1\tname=alice\n" ++
+            "R __pk=100\tcustomer_id=1\ttotal=50\n" ++
+            // --left: bob survives with R (nil), the orphan order is still absent.
+            "L __pk=1\tname=alice\n" ++
+            "R __pk=100\tcustomer_id=1\ttotal=50\n" ++
+            "L __pk=2\tname=bob\n" ++
+            "R (nil)\n" ++
+            // --right: the orphan order survives with L (nil), bob is absent.
+            "L __pk=1\tname=alice\n" ++
+            "R __pk=100\tcustomer_id=1\ttotal=50\n" ++
+            "L (nil)\n" ++
+            "R __pk=101\tcustomer_id=999\ttotal=5\n" ++
+            // --full: both bob and the orphan order survive.
+            "L __pk=1\tname=alice\n" ++
+            "R __pk=100\tcustomer_id=1\ttotal=50\n" ++
+            "L __pk=2\tname=bob\n" ++
+            "R (nil)\n" ++
+            "L (nil)\n" ++
+            "R __pk=101\tcustomer_id=999\ttotal=5\n",
+        out,
+    );
+}
+
+test "table join respects --limit and --offset like table select does" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put customers i:1 name=alice
+        \\table put customers i:2 name=bob
+        \\table put customers i:3 name=carol
+        \\table join --left customers __pk orders customer_id --offset 1 --limit 1
+        \\table join --left customers __pk orders customer_id --offset 50
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            // --offset 1 --limit 1: skip alice, keep exactly bob.
+            "L __pk=2\tname=bob\n" ++
+            "R (nil)\n" ++
+            // --offset 50 is past the end of a 3-row left outer join: nothing.
+            "",
+        out,
+    );
+}
+
+test "table join needs exactly four positional args after mode flags" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "table join --left customers __pk orders\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("error: WrongArgCount\n", out);
+}
+
+test "table aggregate groups by field with count/sum/avg/min/max, matching main.zig's CLI output" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw total=i:100
+        \\table put orders i:2 city=warsaw total=i:250
+        \\table put orders i:3 city=krakow total=i:40
+        \\table aggregate orders city count,sum:total,avg:total,min:total,max:total
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "group=warsaw\tcount=2\tsum_total=350\tavg_total=175\tmin_total=100\tmax_total=250\n" ++
+            "group=krakow\tcount=1\tsum_total=40\tavg_total=40\tmin_total=40\tmax_total=40\n",
+        out,
+    );
+}
+
+test "table aggregate distinct:field counts unique values, collapsing repeats within a group" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw region=mazovia
+        \\table put orders i:2 city=warsaw region=mazovia
+        \\table put orders i:3 city=warsaw region=innerwarsaw
+        \\table put orders i:4 city=krakow region=malopolska
+        \\table aggregate orders city count,distinct:region
+        \\table aggregate orders * distinct:region
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\nOK\n" ++
+            "group=warsaw\tcount=3\tcount_distinct_region=2\n" ++
+            "group=krakow\tcount=1\tcount_distinct_region=1\n" ++
+            "count_distinct_region=3\n",
+        out,
+    );
+}
+
+test "table aggregate with * groups nothing and honors an expr filter before aggregating" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw total=i:100
+        \\table put orders i:2 city=warsaw total=i:250
+        \\table put orders i:3 city=krakow total=i:40
+        \\table aggregate orders * count,sum:total
+        \\table aggregate orders * count,sum:total total gt i:50
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "count=3\tsum_total=390\n" ++
+            "count=2\tsum_total=350\n",
+        out,
+    );
+}
+
+test "table aggregate rejects an invalid spec without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "table aggregate orders city bogus:total\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("error: InvalidArgument\n", out);
+}
+
+test "table window row_number annotates every row without collapsing, restarting per partition in order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw total=i:100
+        \\table put orders i:2 city=warsaw total=i:250
+        \\table put orders i:3 city=krakow total=i:40
+        \\table window orders row_number partition city order total
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tcity=warsaw\ttotal=100\trow_number=1\n" ++
+            "__pk=2\tcity=warsaw\ttotal=250\trow_number=2\n" ++
+            "__pk=3\tcity=krakow\ttotal=40\trow_number=1\n",
+        out,
+    );
+}
+
+test "table window with a comma-separated spec list annotates every row with all columns, sharing one partition/order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw total=i:100
+        \\table put orders i:2 city=warsaw total=i:250
+        \\table put orders i:3 city=krakow total=i:40
+        \\table window orders row_number,sum:total partition city order total
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tcity=warsaw\ttotal=100\trow_number=1\tsum_total=100\n" ++
+            "__pk=2\tcity=warsaw\ttotal=250\trow_number=2\tsum_total=350\n" ++
+            "__pk=3\tcity=krakow\ttotal=40\trow_number=1\tsum_total=40\n",
+        out,
+    );
+}
+
+test "table window sum:field with order runs a running total along the sorted sequence" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw total=i:100
+        \\table put orders i:2 city=warsaw total=i:250
+        \\table put orders i:3 city=krakow total=i:40
+        \\table window orders sum:total order total
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=3\tcity=krakow\ttotal=40\tsum_total=40\n" ++
+            "__pk=1\tcity=warsaw\ttotal=100\tsum_total=140\n" ++
+            "__pk=2\tcity=warsaw\ttotal=250\tsum_total=390\n",
+        out,
+    );
+}
+
+test "table window --range shares a tied group's combined total, without it each tied row gets its own running total" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    // Two rows tied at day=1 (10, 20), then one row at day=2 (5).
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table put orders i:2 day=i:1 amount=i:20
+        \\table put orders i:3 day=i:2 amount=i:5
+        \\table window orders sum:amount order day --range
+        \\table window orders sum:amount order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            // --range: both day=1 rows share the tie group's combined total.
+            "__pk=1\tday=1\tamount=10\tsum_amount=30\n" ++
+            "__pk=2\tday=1\tamount=20\tsum_amount=30\n" ++
+            "__pk=3\tday=2\tamount=5\tsum_amount=35\n" ++
+            // default (ROWS): each physical row keeps its own running total.
+            "__pk=1\tday=1\tamount=10\tsum_amount=10\n" ++
+            "__pk=2\tday=1\tamount=20\tsum_amount=30\n" ++
+            "__pk=3\tday=2\tamount=5\tsum_amount=35\n",
+        out,
+    );
+}
+
+test "table window --range is rejected together with a ranking kind, not silently ignored" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 total=i:100
+        \\table window orders row_number order total --range
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nerror: RangeNotApplicable\n", out);
+}
+
+test "table window sum:field with a partition but no order stamps the same whole-partition total on every row" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw total=i:100
+        \\table put orders i:2 city=warsaw total=i:250
+        \\table put orders i:3 city=krakow total=i:40
+        \\table window orders sum:total partition city
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tcity=warsaw\ttotal=100\tsum_total=350\n" ++
+            "__pk=2\tcity=warsaw\ttotal=250\tsum_total=350\n" ++
+            "__pk=3\tcity=krakow\ttotal=40\tsum_total=40\n",
+        out,
+    );
+}
+
+test "table window honors --limit/--offset in partition-then-order display order, not raw scan order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 city=warsaw total=i:100
+        \\table put orders i:2 city=warsaw total=i:250
+        \\table put orders i:3 city=krakow total=i:40
+        \\table window orders row_number order total --offset 1 --limit 1
+        \\
+    );
+    defer allocator.free(out);
+    // Sorted by total ascending: krakow/40 (rownum 1), warsaw/100 (rownum
+    // 2), warsaw/250 (rownum 3) - offset 1 limit 1 must land on the SECOND
+    // entry of that sorted walk, not the second row `table put` inserted.
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tcity=warsaw\ttotal=100\trow_number=2\n",
+        out,
+    );
+}
+
+test "table window rejects an invalid spec without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "table window orders bogus\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("error: InvalidArgument\n", out);
+}
+
+test "table window lag/lead read the adjacent row's value within order, NULL at the partition edge" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table put orders i:2 day=i:2 amount=i:20
+        \\table put orders i:3 day=i:3 amount=i:30
+        \\table window orders lag:amount,lead:amount order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tday=1\tamount=10\tlag_amount=(none)\tlead_amount=20\n" ++
+            "__pk=2\tday=2\tamount=20\tlag_amount=10\tlead_amount=30\n" ++
+            "__pk=3\tday=3\tamount=30\tlag_amount=20\tlead_amount=(none)\n",
+        out,
+    );
+}
+
+test "table window lag with an explicit offset and a caller-supplied default instead of NULL" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table put orders i:2 day=i:2 amount=i:20
+        \\table window orders lag:amount:1:i:-1 order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\n" ++
+            "__pk=1\tday=1\tamount=10\tlag_amount=-1\n" ++
+            "__pk=2\tday=2\tamount=20\tlag_amount=10\n",
+        out,
+    );
+}
+
+test "table window lag/lead --range is rejected outright, like row_number" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 amount=i:10
+        \\table window orders lag:amount order amount --range
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nerror: RangeNotApplicable\n", out);
+}
+
+test "table window first_value/last_value --range: last_value shares the current tie group's last member" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table put orders i:2 day=i:1 amount=i:20
+        \\table put orders i:3 day=i:2 amount=i:5
+        \\table window orders first_value:amount,last_value:amount order day --range
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tday=1\tamount=10\tfirst_value_amount=10\tlast_value_amount=20\n" ++
+            "__pk=2\tday=1\tamount=20\tfirst_value_amount=10\tlast_value_amount=20\n" ++
+            "__pk=3\tday=2\tamount=5\tfirst_value_amount=10\tlast_value_amount=5\n",
+        out,
+    );
+}
+
+test "table window last_value without --range degenerates to the row's own field (ROWS default)" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table put orders i:2 day=i:2 amount=i:20
+        \\table window orders last_value:amount order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\n" ++
+            "__pk=1\tday=1\tamount=10\tlast_value_amount=10\n" ++
+            "__pk=2\tday=2\tamount=20\tlast_value_amount=20\n",
+        out,
+    );
+}
+
+test "table window nth_value --range: position resolved against the CUMULATIVE frame, not just the current tie group" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table put orders i:2 day=i:1 amount=i:20
+        \\table put orders i:3 day=i:2 amount=i:5
+        \\table window orders nth_value:amount:2 order day --range
+        \\
+    );
+    defer allocator.free(out);
+    // day=1's tie group has 2 members - position 2 is its second member (20).
+    // day=2's frame is UNBOUNDED PRECEDING through its own tie group, so it
+    // already includes day=1's rows too - position 2 was already resolved
+    // to 20 there and stays 20, even though day=2's OWN group has just 1 row.
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tday=1\tamount=10\tnth_value_amount=20\n" ++
+            "__pk=2\tday=1\tamount=20\tnth_value_amount=20\n" ++
+            "__pk=3\tday=2\tamount=5\tnth_value_amount=20\n",
+        out,
+    );
+}
+
+test "table window nth_value ROWS default: NULL until the frame grows to reach the requested position" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table put orders i:2 day=i:2 amount=i:20
+        \\table window orders nth_value:amount:2 order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\n" ++
+            "__pk=1\tday=1\tamount=10\tnth_value_amount=(none)\n" ++
+            "__pk=2\tday=2\tamount=20\tnth_value_amount=20\n",
+        out,
+    );
+}
+
+test "table window nth_value with a caller-supplied default instead of NULL" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table window orders nth_value:amount:5:i:-1 order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\n__pk=1\tday=1\tamount=10\tnth_value_amount=-1\n",
+        out,
+    );
+}
+
+test "table window nth_value with no field or no position reports InvalidArgument" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 amount=i:10
+        \\table window orders nth_value order day
+        \\table window orders nth_value:amount order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nerror: InvalidArgument\nerror: InvalidArgument\n",
+        out,
+    );
+}
+
+test "table window count_distinct runs a per-row distinct total, repeats do not grow it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 day=i:1 tag=s:a
+        \\table put orders i:2 day=i:2 tag=s:b
+        \\table put orders i:3 day=i:3 tag=s:a
+        \\table window orders count_distinct:tag order day
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n" ++
+            "__pk=1\tday=1\ttag=a\tcount_distinct_tag=1\n" ++
+            "__pk=2\tday=2\ttag=b\tcount_distinct_tag=2\n" ++
+            "__pk=3\tday=3\ttag=a\tcount_distinct_tag=2\n",
+        out,
+    );
+}
+
+test "table window count_distinct with no field reports InvalidArgument, unlike bare count" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl,
+        \\table put orders i:1 tag=s:a
+        \\table window orders count_distinct
+        \\
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nerror: InvalidArgument\n", out);
+}
+
+test "unknown command and wrong arg counts report errors without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "bogus\nput onlyone\nget\nput a 1\nget a\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "error: UnknownCommand\nerror: WrongArgCount\nerror: WrongArgCount\nOK\n1\n",
+        out,
+    );
+}
+
+test "staged writes inside a transaction are invisible until commit, then durable" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "begin\nput bal 100\nget bal\ncommit\nget bal\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nOK\n100\nOK\n100\n", out);
+}
+
+test "get mid-transaction steers the next put, applied atomically on commit" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    try db.put("bal", "100");
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "begin\nget bal\nput bal 150\ncommit\nget bal\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\n100\nOK\nOK\n150\n", out);
+
+    const stored = (try db.get(allocator, "bal")).?;
+    defer allocator.free(stored);
+    try std.testing.expectEqualStrings("150", stored);
+}
+
+test "rollback discards staged writes entirely" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "begin\nput x 1\nrollback\nget x\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nOK\nOK\n(nil)\n", out);
+    try std.testing.expectEqual(@as(?[]u8, null), try db.get(allocator, "x"));
+}
+
+test "commit/rollback without an active transaction report NoActiveTransaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "commit\nrollback\nput a 1\nget a\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "error: NoActiveTransaction\nerror: NoActiveTransaction\nOK\n1\n",
+        out,
+    );
+}
+
+test "double begin is rejected and leaves the first transaction usable" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "begin\nput a 1\nbegin\ncommit\nget a\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nOK\nerror: TransactionAlreadyActive\nOK\n1\n", out);
+}
+
+test "table put/get/del inside a transaction stage through TableTxn atomically across two tables" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "begin\n" ++
+            "table put accounts 1 name=alice balance=i:100\n" ++
+            "table put ledger 1 note=opening\n" ++
+            "table get accounts 1\n" ++
+            "commit\n" ++
+            "table get accounts 1\n" ++
+            "table get ledger 1\n",
+    );
+    defer allocator.free(out);
+
+    var lines = std.mem.splitScalar(u8, std.mem.trimRight(u8, out, "\n"), '\n');
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    const preCommitGet = lines.next().?;
+    try std.testing.expect(std.mem.indexOf(u8, preCommitGet, "name=alice") != null);
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    const postAccounts = lines.next().?;
+    try std.testing.expect(std.mem.indexOf(u8, postAccounts, "balance=100") != null);
+    const postLedger = lines.next().?;
+    try std.testing.expect(std.mem.indexOf(u8, postLedger, "note=opening") != null);
+    try std.testing.expectEqual(@as(?[]const u8, null), lines.next());
+
+    var directTable = try Table.open(&db, allocator, "accounts");
+    defer directTable.deinit();
+    var row = (try directTable.get(.{ .text = "1" })).?;
+    defer row.deinit();
+    try std.testing.expectEqual(@as(i64, 100), row.get("balance").?.int);
+}
+
+test "table writes made before commit are not visible to an independent Table handle" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    var stream = std.io.fixedBufferStream("begin\ntable put accounts 1 name=alice\n");
+    var out = std.ArrayList(u8).init(allocator);
+    defer out.deinit();
+    try repl.runFromReader(stream.reader(), out.writer(), false);
+    try std.testing.expectEqualStrings("OK\nOK\n", out.items);
+
+    var outsider = try Table.open(&db, allocator, "accounts");
+    defer outsider.deinit();
+    try std.testing.expectEqual(@as(?Row, null), try outsider.get(.{ .text = "1" }));
+
+    try repl.txn.?.commit();
+    repl.discardTxnState();
+
+    var again = try Table.open(&db, allocator, "accounts");
+    defer again.deinit();
+    var row = (try again.get(.{ .text = "1" })).?;
+    defer row.deinit();
+    try std.testing.expectEqualStrings("alice", row.get("name").?.text);
+}
+
+test "table put/get/del outside a transaction autocommit immediately like plain Table" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "table put widgets 7 sku=s:ABC qty=i:3\ntable get widgets 7\ntable del widgets 7\ntable get widgets 7\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expect(std.mem.startsWith(u8, out, "OK\n"));
+    try std.testing.expect(std.mem.indexOf(u8, out, "sku=ABC") != null);
+    try std.testing.expect(std.mem.indexOf(u8, out, "qty=3") != null);
+    try std.testing.expect(std.mem.endsWith(u8, out, "(nil)\n"));
+}
+
+test "malformed field is rejected before staging, transaction stays usable" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "begin\ntable put accounts 1 badfieldnoequals\ntable put accounts 1 name=bob\ncommit\ntable get accounts 1\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expect(std.mem.startsWith(u8, out, "OK\nerror: InvalidField\nOK\nOK\n"));
+    try std.testing.expect(std.mem.indexOf(u8, out, "name=bob") != null);
+}
+
+test "a real external conflict surfaces error.Conflict on commit and applies nothing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    try db.put("balance", "100");
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    var stream = std.io.fixedBufferStream("begin\nget balance\n");
+    var out = std.ArrayList(u8).init(allocator);
+    defer out.deinit();
+    try repl.runFromReader(stream.reader(), out.writer(), false);
+
+    try db.put("balance", "external");
+
+    var stream2 = std.io.fixedBufferStream("put balance 150\ncommit\n");
+    try repl.runFromReader(stream2.reader(), out.writer(), false);
+    try std.testing.expect(std.mem.endsWith(u8, out.items, "OK\nerror: Conflict\n"));
+
+    const current = (try db.get(allocator, "balance")).?;
+    defer allocator.free(current);
+    try std.testing.expectEqualStrings("external", current);
+    try std.testing.expect(repl.inTransaction());
+
+    var stream3 = std.io.fixedBufferStream("rollback\n");
+    try repl.runFromReader(stream3.reader(), out.writer(), false);
+    try std.testing.expect(!repl.inTransaction());
+}
+
+test "scan always reflects committed Db state, not an in-flight transaction's staged writes" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "put k1 v1\nbegin\nput k2 v2\nscan k\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nOK\nOK\nk1\tv1\n", out);
+}
+
+test "abandoning an open transaction on deinit frees staged writes and pending TableTxn state" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    const out = try runScript(allocator, &repl, "begin\nput a 1\ntable put accounts 1 name=alice\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("OK\nOK\nOK\n", out);
+    repl.deinit();
+
+    try std.testing.expectEqual(@as(?[]u8, null), try db.get(allocator, "a"));
+    var table = try Table.open(&db, allocator, "accounts");
+    defer table.deinit();
+    try std.testing.expectEqual(@as(?Row, null), try table.get(.{ .text = "1" }));
+}
+
+test "flush and compact run against the live Db and stats reflects it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "put a 1\nflush\ncompact\nstats\n");
+    defer allocator.free(out);
+    try std.testing.expect(std.mem.startsWith(u8, out, "OK\nOK\nOK\n"));
+    try std.testing.expect(out.len > "OK\nOK\nOK\n".len);
+}
+
+test "help lists commands without touching db state" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "help\n");
+    defer allocator.free(out);
+    try std.testing.expect(std.mem.indexOf(u8, out, "begin / commit / rollback") != null);
+}
+
+test "prompt is written before each read only when requested" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    var stream = std.io.fixedBufferStream("begin\nput a 1\n");
+    var out = std.ArrayList(u8).init(allocator);
+    defer out.deinit();
+    try repl.runFromReader(stream.reader(), out.writer(), true);
+    try std.testing.expectEqualStrings("cobalt> OK\ncobalt(txn)> OK\ncobalt(txn)> ", out.items);
+}
+
+test "coll counter get/set/incrby work interactively like the CLI's coll command" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "coll counter get hits\ncoll counter set hits 10\ncoll counter incrby hits 5\ncoll counter get hits\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("0\nOK\n15\n15\n", out);
+}
+
+test "coll hash set/get/del/len/getall round-trip a field" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "coll hash set user name alice\ncoll hash get user name\ncoll hash len user\n" ++
+            "coll hash getall user\ncoll hash del user name\ncoll hash get user name\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "created\nalice\n1\nname\talice\n1\n(nil)\n",
+        out,
+    );
+}
+
+test "coll set add/ismember/card/members/inter/union/diff cover real set operations" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "coll set add a x\ncoll set add a y\ncoll set add b y\n" ++
+            "coll set ismember a x\ncoll set card a\n" ++
+            "coll set inter a b\ncoll set diff a b\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "1\n1\n1\n1\n2\ny\nx\n",
+        out,
+    );
+}
+
+test "coll list lpush/rpush/lpop/rpop/len/range behave like a deque" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "coll list rpush q one\ncoll list rpush q two\ncoll list lpush q zero\n" ++
+            "coll list len q\ncoll list range q 0 -1\ncoll list lpop q\ncoll list rpop q\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\nOK\n3\nzero\none\ntwo\nzero\ntwo\n",
+        out,
+    );
+}
+
+test "coll zset add/score/incrby/rangebyscore/rank track member order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "coll zset add ranks alice 10\ncoll zset add ranks bob 20\n" ++
+            "coll zset incrby ranks alice 15\ncoll zset score ranks alice\n" ++
+            "coll zset rank ranks alice\ncoll zset rangebyscore ranks 0 100\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "OK\nOK\n25\n25\n1\nbob\t20\nalice\t25\n",
+        out,
+    );
+}
+
+test "coll reports UnknownCollectionKind/UnknownCollectionOp/InvalidArgument without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "coll bogus get x\ncoll counter frobnicate x\ncoll counter set x notanumber\ncoll counter get x\n",
+    );
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings(
+        "error: UnknownCollectionKind\nerror: UnknownCollectionOp\nerror: InvalidArgument\n0\n",
+        out,
+    );
+}
+
+test "expire/ttl/persist manage a plain key's TTL like the CLI's same-named commands" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "put a 1\nttl a\nexpire a 100\nttl a\npersist a\nttl a\nttl missing\n",
+    );
+    defer allocator.free(out);
+
+    var lines = std.mem.splitScalar(u8, std.mem.trimRight(u8, out, "\n"), '\n');
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    try std.testing.expectEqualStrings("-1", lines.next().?);
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    const withTtl = std.fmt.parseInt(i64, lines.next().?, 10) catch unreachable;
+    try std.testing.expect(withTtl > 0 and withTtl <= 100);
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    try std.testing.expectEqualStrings("-1", lines.next().?);
+    try std.testing.expectEqualStrings("-2", lines.next().?);
+    try std.testing.expectEqual(@as(?[]const u8, null), lines.next());
+}
+
+test "expire on a missing key reports NoSuchKey without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "expire ghost 10\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("error: NoSuchKey\n", out);
+}
+
+test "expire-sweep reaps an already-elapsed plain-key TTL" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    try db.put("a", "1");
+    try ttlmod.setExpireSeconds(&db, allocator, "a", std.time.nanoTimestamp() - 10 * std.time.ns_per_s, 1);
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "expire-sweep\nget a\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("reaped: 1\n(nil)\n", out);
+}
+
+test "coll expire/ttl/persist manage a whole collection's TTL, and coll expire-sweep reaps it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(
+        allocator,
+        &repl,
+        "coll counter set hits 1\ncoll counter ttl hits\ncoll counter expire hits 100\n" ++
+            "coll counter ttl hits\ncoll counter persist hits\ncoll counter ttl hits\n",
+    );
+    defer allocator.free(out);
+
+    var lines = std.mem.splitScalar(u8, std.mem.trimRight(u8, out, "\n"), '\n');
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    try std.testing.expectEqualStrings("-1", lines.next().?);
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    const withTtl = std.fmt.parseInt(i64, lines.next().?, 10) catch unreachable;
+    try std.testing.expect(withTtl > 0 and withTtl <= 100);
+    try std.testing.expectEqualStrings("OK", lines.next().?);
+    try std.testing.expectEqualStrings("-1", lines.next().?);
+    try std.testing.expectEqual(@as(?[]const u8, null), lines.next());
+
+    try collttlmod.setExpireSeconds(&db, allocator, .counter, "hits", std.time.nanoTimestamp() - 10 * std.time.ns_per_s, 1);
+    const swept = try runScript(allocator, &repl, "coll expire-sweep\n");
+    defer allocator.free(swept);
+    try std.testing.expectEqualStrings("reaped: 1\n", swept);
+    try std.testing.expect(!try collectionsmod.collectionExists(&db, allocator, .counter, "hits"));
+}
+
+test "coll expire on a nonexistent collection reports NoSuchKey" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    const out = try runScript(allocator, &repl, "coll counter expire ghost 10\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("error: NoSuchKey\n", out);
+}
+
+test "coll expires a collection lazily via collttl before the next op sees it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try collectionsmod.Counter.set(&db, allocator, "session", 42);
+    try collttlmod.setExpireSeconds(&db, allocator, .counter, "session", std.time.nanoTimestamp() - 10 * std.time.ns_per_s, 1);
+    try std.testing.expect(try collectionsmod.collectionExists(&db, allocator, .counter, "session"));
+
+    var repl = Repl.init(allocator, &db);
+    defer repl.deinit();
+
+    // Reading it through the REPL must trigger the same lazy-expiry check
+    // the CLI's `runColl` performs before every op, so an already-elapsed
+    // TTL is honored immediately instead of only on the next sweep.
+    const out = try runScript(allocator, &repl, "coll counter get session\n");
+    defer allocator.free(out);
+    try std.testing.expectEqualStrings("0\n", out);
+    try std.testing.expect(!try collectionsmod.collectionExists(&db, allocator, .counter, "session"));
+}
diff --git a/src/replicate.zig b/src/replicate.zig
new file mode 100644
index 0000000..4221db5
--- /dev/null
+++ b/src/replicate.zig
@@ -0,0 +1,808 @@
+const std = @import("std");
+const encode = @import("encode.zig");
+const dbmod = @import("db.zig");
+const walmod = @import("wal.zig");
+
+const Allocator = std.mem.Allocator;
+const Kind = encode.Kind;
+const Db = dbmod.Db;
+const WriteBatch = dbmod.WriteBatch;
+
+// Physical WAL-tailing replication: reads the primary's on-disk wal.log file
+// directly (same binary frame format as wal.zig: [crc32 u32][seq u64][kind u8]
+// [keyLen u32][valLen u32][key][value], or a batch frame marked by kind byte
+// 0xB0 holding a count then per-op [kind][seq][keyLen][valLen][key][value]),
+// independently of wal.zig's private replay-into-memtable path, and applies
+// newly appended, crc-verified, complete frames onto a separate replica Db.
+//
+// This mirrors real physical log shipping (e.g. Postgres WAL streaming): it
+// only sees what is still in the WAL file. Db.flush() truncates the primary's
+// wal.log to empty once its memtable is durable in an SSTable (see db.zig
+// flush()), so a tailer that has fallen behind a flush can no longer recover
+// the truncated records from the WAL alone - poll() detects that condition
+// (current file size smaller than the tailer's already-consumed offset) and
+// fails loudly with error.WalTruncatedAheadOfTailer instead of silently
+// resuming from zero and dropping data. The caller is expected to recover via
+// fullResync(), which re-bases the replica from a live Snapshot (paying the
+// same "logical snapshot, not a physical replica of on-disk levels/history"
+// cost already documented for backup.zig) and restarts tailing from the
+// (now known-empty) WAL, exactly mirroring a real base-backup-plus-streaming
+// recovery: bulk-copy current state, then resume incremental log shipping
+// from the offset the bulk copy was taken at.
+
+const headerLen = 8 + 1 + 4 + 4;
+const batchMarker: u8 = 0xB0;
+const batchHeader = 8 + 1 + 4;
+const opHeader = 1 + 8 + 4 + 4;
+const walName = "wal.log";
+const maxTailRead: usize = 256 * 1024 * 1024;
+
+pub const ReplicateError = error{ WalTruncatedAheadOfTailer, WalGenerationChanged };
+
+/// Reads the WAL generation stamp (see wal.zig's currentGeneration) for a
+/// primary directory given only its path, for callers (WalTailer.poll,
+/// Replicator construction from a persisted offset) that do not hold a live
+/// *Db handle to the primary and so cannot reuse its already-open Dir.
+fn readGenerationByPath(primaryDirPath: []const u8) !u64 {
+    var dir = try std.fs.cwd().openDir(primaryDirPath, .{});
+    defer dir.close();
+    return walmod.currentGeneration(dir);
+}
+
+pub const OwnedRecord = struct {
+    kind: Kind,
+    seq: u64,
+    key: []u8,
+    value: []u8,
+
+    pub fn deinit(self: OwnedRecord, allocator: Allocator) void {
+        allocator.free(self.key);
+        allocator.free(self.value);
+    }
+};
+
+fn freeAll(allocator: Allocator, records: []OwnedRecord) void {
+    for (records) |record| record.deinit(allocator);
+    allocator.free(records);
+}
+
+/// Tails a single WAL file from a byte offset, decoding whole, crc-verified
+/// frames appended since the last poll. Never advances past an incomplete or
+/// corrupt tail frame (mirrors wal.zig's own torn-write tolerance), so a
+/// concurrent writer mid-append is simply not observed until its frame is
+/// fully flushed and synced.
+pub const WalTailer = struct {
+    allocator: Allocator,
+    file: std.fs.File,
+    offset: u64,
+    primaryDir: []u8,
+    generation: u64,
+
+    pub fn open(allocator: Allocator, primaryDirPath: []const u8, startOffset: u64, startGeneration: u64) !WalTailer {
+        const path = try std.fs.path.join(allocator, &.{ primaryDirPath, walName });
+        defer allocator.free(path);
+        const file = try std.fs.cwd().openFile(path, .{});
+        errdefer file.close();
+        const dirCopy = try allocator.dupe(u8, primaryDirPath);
+        return .{ .allocator = allocator, .file = file, .offset = startOffset, .primaryDir = dirCopy, .generation = startGeneration };
+    }
+
+    pub fn deinit(self: *WalTailer) void {
+        self.file.close();
+        self.allocator.free(self.primaryDir);
+    }
+
+    /// Returns newly observed records in append order. Caller owns the
+    /// returned slice and each record's key/value (free via freeAll or by
+    /// calling deinit() on each record then freeing the slice). Checks the
+    /// primary's WAL generation stamp before anything else: a changed
+    /// generation means the primary truncated (flushed) since the last poll,
+    /// which the caller must recover from via fullResync() regardless of how
+    /// the raw byte offsets happen to compare (see wal.zig's bumpGeneration
+    /// doc comment for why the byte-size comparison alone is not enough).
+    pub fn poll(self: *WalTailer) ![]OwnedRecord {
+        const nowGeneration = try readGenerationByPath(self.primaryDir);
+        if (nowGeneration != self.generation) return ReplicateError.WalGenerationChanged;
+
+        const endPos = try self.file.getEndPos();
+        if (endPos < self.offset) return ReplicateError.WalTruncatedAheadOfTailer;
+        if (endPos == self.offset) return &.{};
+
+        try self.file.seekTo(self.offset);
+        const data = try self.file.readToEndAlloc(self.allocator, maxTailRead);
+        defer self.allocator.free(data);
+
+        var out = std.ArrayList(OwnedRecord).init(self.allocator);
+        errdefer {
+            for (out.items) |record| record.deinit(self.allocator);
+            out.deinit();
+        }
+
+        var pos: usize = 0;
+        while (pos + 4 + batchHeader <= data.len) {
+            const storedCrc = encode.readU32(data, pos);
+            const bodyStart = pos + 4;
+            const bodyLen = frameBodyLen(data, bodyStart) orelse break;
+            if (bodyStart + bodyLen > data.len) break;
+            const body = data[bodyStart .. bodyStart + bodyLen];
+            if (encode.crc(body) != storedCrc) break;
+
+            try decodeFrame(self.allocator, body, &out);
+
+            pos = bodyStart + bodyLen;
+        }
+
+        self.offset += pos;
+        return try out.toOwnedSlice();
+    }
+};
+
+fn frameBodyLen(data: []const u8, bodyStart: usize) ?usize {
+    const marker = data[bodyStart + 8];
+    if (marker == batchMarker) {
+        if (bodyStart + batchHeader > data.len) return null;
+        const opCount = encode.readU32(data, bodyStart + 9);
+        var p = bodyStart + batchHeader;
+        var n: u32 = 0;
+        while (n < opCount) : (n += 1) {
+            if (p + opHeader > data.len) return null;
+            const keyLen = encode.readU32(data, p + 9);
+            const valLen = encode.readU32(data, p + 13);
+            const end = p + opHeader + keyLen + valLen;
+            if (end > data.len) return null;
+            p = end;
+        }
+        return p - bodyStart;
+    }
+    if (bodyStart + headerLen > data.len) return null;
+    const keyLen = encode.readU32(data, bodyStart + 9);
+    const valLen = encode.readU32(data, bodyStart + 13);
+    return headerLen + keyLen + valLen;
+}
+
+fn decodeFrame(allocator: Allocator, body: []const u8, out: *std.ArrayList(OwnedRecord)) !void {
+    if (body[8] == batchMarker) {
+        const opCount = encode.readU32(body, 9);
+        var p: usize = batchHeader;
+        var n: u32 = 0;
+        while (n < opCount) : (n += 1) {
+            const kind: Kind = @enumFromInt(body[p]);
+            const seq = encode.readU64(body, p + 1);
+            const keyLen = encode.readU32(body, p + 9);
+            const valLen = encode.readU32(body, p + 13);
+            const keyStart = p + opHeader;
+            const key = try allocator.dupe(u8, body[keyStart .. keyStart + keyLen]);
+            errdefer allocator.free(key);
+            const value = try allocator.dupe(u8, body[keyStart + keyLen .. keyStart + keyLen + valLen]);
+            try out.append(.{ .kind = kind, .seq = seq, .key = key, .value = value });
+            p = keyStart + keyLen + valLen;
+        }
+        return;
+    }
+    const seq = encode.readU64(body, 0);
+    const kind: Kind = @enumFromInt(body[8]);
+    const keyLen = encode.readU32(body, 9);
+    const valLen = encode.readU32(body, 13);
+    const key = try allocator.dupe(u8, body[headerLen .. headerLen + keyLen]);
+    errdefer allocator.free(key);
+    const value = try allocator.dupe(u8, body[headerLen + keyLen .. headerLen + keyLen + valLen]);
+    try out.append(.{ .kind = kind, .seq = seq, .key = key, .value = value });
+}
+
+/// Ties a WalTailer to a target Db, applying newly tailed records as a single
+/// WriteBatch per syncOnce(). Replicated writes get FRESH sequence numbers on
+/// the target (Db.apply always assigns from its own nextSeq), so the replica
+/// mirrors primary key/value state but not primary's original seq history -
+/// same documented tradeoff as backup.zig's restore.
+pub const Replicator = struct {
+    allocator: Allocator,
+    tailer: WalTailer,
+    target: *Db,
+
+    pub fn init(allocator: Allocator, primaryDirPath: []const u8, target: *Db) !Replicator {
+        const gen = try readGenerationByPath(primaryDirPath);
+        return initFromOffset(allocator, primaryDirPath, target, 0, gen);
+    }
+
+    pub fn initFromOffset(allocator: Allocator, primaryDirPath: []const u8, target: *Db, startOffset: u64, startGeneration: u64) !Replicator {
+        const tailer = try WalTailer.open(allocator, primaryDirPath, startOffset, startGeneration);
+        return .{ .allocator = allocator, .tailer = tailer, .target = target };
+    }
+
+    pub fn deinit(self: *Replicator) void {
+        self.tailer.deinit();
+    }
+
+    pub fn offset(self: *const Replicator) u64 {
+        return self.tailer.offset;
+    }
+
+    pub fn generation(self: *const Replicator) u64 {
+        return self.tailer.generation;
+    }
+
+    /// Applies every record newly visible in the primary's WAL since the last
+    /// call. Returns the number of records applied (0 if nothing new).
+    /// Propagates error.WalTruncatedAheadOfTailer if the primary flushed
+    /// (truncating its WAL) before this replicator consumed everything - the
+    /// caller must recover via fullResync().
+    pub fn syncOnce(self: *Replicator) !usize {
+        const records = try self.tailer.poll();
+        defer freeAll(self.allocator, records);
+        if (records.len == 0) return 0;
+
+        var batch = WriteBatch.init(self.allocator);
+        defer batch.deinit();
+        for (records) |record| {
+            switch (record.kind) {
+                .value => try batch.put(record.key, record.value),
+                .tombstone => try batch.delete(record.key),
+            }
+        }
+        try self.target.apply(&batch);
+        return records.len;
+    }
+
+    /// Recovers from a fallen-behind tailer (or bootstraps a brand new
+    /// replica) by copying every live key/value from a fresh primary
+    /// Snapshot into the target in chunks, then re-bases the tailer at the
+    /// primary's current WAL offset. Snapshot() flushes the primary first
+    /// (see db.zig), so immediately after this call the primary's wal.log is
+    /// known to be empty - offset 0 is therefore always the correct restart
+    /// point. Requires no concurrent writer on the primary during the call
+    /// (same single-writer assumption as the rest of this project - Db has
+    /// no internal cross-thread synchronization).
+    pub fn fullResync(self: *Replicator, primary: *Db, chunkSize: usize) !usize {
+        const snap = try primary.snapshot();
+        var iter = try snap.scan(self.allocator, null, null);
+        defer iter.deinit();
+
+        var batch = WriteBatch.init(self.allocator);
+        defer batch.deinit();
+        var applied: usize = 0;
+        var staged: usize = 0;
+        while (try iter.next()) |entry| {
+            try batch.put(entry.key, entry.value);
+            staged += 1;
+            applied += 1;
+            if (staged >= chunkSize) {
+                try self.target.apply(&batch);
+                batch.deinit();
+                batch = WriteBatch.init(self.allocator);
+                staged = 0;
+            }
+        }
+        if (staged > 0) try self.target.apply(&batch);
+
+        self.tailer.offset = 0;
+        // snapshot() above flushes the primary if it had unflushed writes,
+        // which bumps its WAL generation (see wal.zig) - re-baseline here so
+        // the very next poll() does not immediately see a "changed"
+        // generation caused by this resync itself.
+        self.tailer.generation = try walmod.currentGeneration(primary.dir);
+        return applied;
+    }
+};
+
+const stateMagic = "CRPS";
+const stateFormatVersion: u32 = 2;
+
+/// A tail offset paired with the WAL generation it was captured against.
+/// Persisting both (not just the offset) is what lets a brand-new process -
+/// which never saw the in-memory generation check in WalTailer.poll() - tell
+/// whether the primary truncated its WAL while this process was not running
+/// at all, the same blind spot the in-memory check closes for a live one.
+pub const PersistedState = struct {
+    offset: u64,
+    generation: u64,
+};
+const stateFileName = "replicate.state";
+const stateTmpName = "replicate.state.tmp";
+const maxStateRead: usize = 64 * 1024;
+
+pub const StateError = error{
+    BadMagic,
+    UnsupportedVersion,
+    Truncated,
+    Corrupt,
+    PrimaryMismatch,
+};
+
+/// Atomically persists a replicator's tail offset next to the replica's own
+/// data (in replicaDirPath), so a later, brand-new `cobalt replicate --once`
+/// process - which has no in-memory Replicator to resume from - can pick up
+/// tailing exactly where the previous invocation left off instead of paying
+/// for a full snapshot fullResync() every single time it starts. Also stores
+/// primaryDirPath so a mismatched later call (pointed at a different primary
+/// by mistake) is caught by loadOffset() rather than silently tailing the
+/// wrong WAL from a stale offset. Written via tmp-file + rename (same pattern
+/// as version.zig's writeCurrent), so a crash mid-write can never leave a
+/// half-written state file where a good one used to be.
+pub fn saveState(allocator: Allocator, replicaDirPath: []const u8, primaryDirPath: []const u8, offsetValue: u64, generationValue: u64) !void {
+    var dir = try std.fs.cwd().openDir(replicaDirPath, .{});
+    defer dir.close();
+
+    var body = std.ArrayList(u8).init(allocator);
+    defer body.deinit();
+    const writer = encode.ByteWriter.init(&body);
+    try writer.slice(stateMagic);
+    try writer.putU32(stateFormatVersion);
+    try writer.putU64(offsetValue);
+    try writer.putU64(generationValue);
+    try writer.putU32(@intCast(primaryDirPath.len));
+    try writer.slice(primaryDirPath);
+    try writer.putU32(encode.crc(body.items));
+
+    {
+        const file = try dir.createFile(stateTmpName, .{ .truncate = true });
+        defer file.close();
+        try file.writeAll(body.items);
+        try file.sync();
+    }
+    try dir.rename(stateTmpName, stateFileName);
+}
+
+/// Loads a previously persisted tail offset for a replica directory. Returns
+/// null (not an error) when no state file has ever been written there yet -
+/// callers treat that as "fresh replica, bootstrap via fullResync()" exactly
+/// like before this existed. Returns StateError.PrimaryMismatch if the file
+/// was written while tailing a different primary directory, so a replica
+/// can never silently resume against the wrong primary from a stale offset.
+pub fn loadOffset(allocator: Allocator, replicaDirPath: []const u8, primaryDirPath: []const u8) !?PersistedState {
+    var dir = try std.fs.cwd().openDir(replicaDirPath, .{});
+    defer dir.close();
+
+    const data = dir.readFileAlloc(allocator, stateFileName, maxStateRead) catch |err| switch (err) {
+        error.FileNotFound => return null,
+        else => return err,
+    };
+    defer allocator.free(data);
+
+    const fixedLen = 4 + 4 + 8 + 8 + 4;
+    if (data.len < fixedLen + 4) return StateError.Truncated;
+    if (!std.mem.eql(u8, data[0..4], stateMagic)) return StateError.BadMagic;
+    const version = encode.readU32(data, 4);
+    if (version != stateFormatVersion) return StateError.UnsupportedVersion;
+    const offsetValue = encode.readU64(data, 8);
+    const generationValue = encode.readU64(data, 16);
+    const pathLen = encode.readU32(data, 24);
+    const pathStart = fixedLen;
+    if (data.len != pathStart + pathLen + 4) return StateError.Truncated;
+    const storedPath = data[pathStart .. pathStart + pathLen];
+    const storedCrc = encode.readU32(data, pathStart + pathLen);
+    if (encode.crc(data[0 .. pathStart + pathLen]) != storedCrc) return StateError.Corrupt;
+    if (!std.mem.eql(u8, storedPath, primaryDirPath)) return StateError.PrimaryMismatch;
+
+    return .{ .offset = offsetValue, .generation = generationValue };
+}
+
+test "replicator mirrors puts and deletes from a live primary" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+    const primaryDir = try std.fs.path.join(allocator, &.{ base, "primary" });
+    defer allocator.free(primaryDir);
+    const replicaDir = try std.fs.path.join(allocator, &.{ base, "replica" });
+    defer allocator.free(replicaDir);
+
+    var primary = try Db.open(allocator, primaryDir, .{});
+    defer primary.close();
+    var replica = try Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    try primary.put("alpha", "one");
+    try primary.put("bravo", "two");
+
+    var rep = try Replicator.init(allocator, primaryDir, &replica);
+    defer rep.deinit();
+
+    const applied = try rep.syncOnce();
+    try std.testing.expectEqual(@as(usize, 2), applied);
+
+    const a = try replica.get(allocator, "alpha");
+    defer if (a) |v| allocator.free(v);
+    try std.testing.expectEqualStrings("one", a.?);
+    const b = try replica.get(allocator, "bravo");
+    defer if (b) |v| allocator.free(v);
+    try std.testing.expectEqualStrings("two", b.?);
+
+    try primary.delete("alpha");
+    const applied2 = try rep.syncOnce();
+    try std.testing.expectEqual(@as(usize, 1), applied2);
+
+    const a2 = try replica.get(allocator, "alpha");
+    try std.testing.expectEqual(@as(?[]u8, null), a2);
+}
+
+test "replicator syncOnce is idempotent between polls" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+    const primaryDir = try std.fs.path.join(allocator, &.{ base, "primary" });
+    defer allocator.free(primaryDir);
+    const replicaDir = try std.fs.path.join(allocator, &.{ base, "replica" });
+    defer allocator.free(replicaDir);
+
+    var primary = try Db.open(allocator, primaryDir, .{});
+    defer primary.close();
+    var replica = try Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    var rep = try Replicator.init(allocator, primaryDir, &replica);
+    defer rep.deinit();
+
+    try primary.put("k1", "v1");
+    try std.testing.expectEqual(@as(usize, 1), try rep.syncOnce());
+    try std.testing.expectEqual(@as(usize, 0), try rep.syncOnce());
+
+    try primary.put("k2", "v2");
+    try std.testing.expectEqual(@as(usize, 1), try rep.syncOnce());
+    try std.testing.expectEqual(@as(usize, 0), try rep.syncOnce());
+
+    var count: usize = 0;
+    var iter = try replica.scan(allocator, null, null);
+    defer iter.deinit();
+    while (try iter.next()) |_| count += 1;
+    try std.testing.expectEqual(@as(usize, 2), count);
+}
+
+test "replicator applies batched writes from Db.apply as one poll" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+    const primaryDir = try std.fs.path.join(allocator, &.{ base, "primary" });
+    defer allocator.free(primaryDir);
+    const replicaDir = try std.fs.path.join(allocator, &.{ base, "replica" });
+    defer allocator.free(replicaDir);
+
+    var primary = try Db.open(allocator, primaryDir, .{});
+    defer primary.close();
+    var replica = try Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    var writeBatch = WriteBatch.init(allocator);
+    defer writeBatch.deinit();
+    try writeBatch.put("x", "1");
+    try writeBatch.put("y", "2");
+    try writeBatch.delete("z");
+    try primary.apply(&writeBatch);
+
+    var rep = try Replicator.init(allocator, primaryDir, &replica);
+    defer rep.deinit();
+    const applied = try rep.syncOnce();
+    try std.testing.expectEqual(@as(usize, 3), applied);
+
+    const x = try replica.get(allocator, "x");
+    defer if (x) |v| allocator.free(v);
+    try std.testing.expectEqualStrings("1", x.?);
+    const z = try replica.get(allocator, "z");
+    try std.testing.expectEqual(@as(?[]u8, null), z);
+}
+
+test "replicator poll does not consume a torn tail frame" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+    const primaryDir = try std.fs.path.join(allocator, &.{ base, "primary" });
+    defer allocator.free(primaryDir);
+    const replicaDir = try std.fs.path.join(allocator, &.{ base, "replica" });
+    defer allocator.free(replicaDir);
+
+    var primary = try Db.open(allocator, primaryDir, .{});
+    defer primary.close();
+    var replica = try Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    var rep = try Replicator.init(allocator, primaryDir, &replica);
+    defer rep.deinit();
+
+    try primary.put("good", "data");
+    try std.testing.expectEqual(@as(usize, 1), try rep.syncOnce());
+
+    // Simulate a writer mid-append: raw bytes appended after the good frame
+    // that never form a complete, crc-verified frame.
+    try primary.wal.file.seekFromEnd(0);
+    try primary.wal.file.writeAll(&[_]u8{ 0xAA, 0xBB, 0xCC });
+    try primary.wal.sync();
+
+    try std.testing.expectEqual(@as(usize, 0), try rep.syncOnce());
+
+    // The writer "finishes": a real, complete frame lands after the torn
+    // bytes are naturally never completed (matches wal.zig's own tolerance -
+    // torn tail bytes are simply never a valid prefix of a later frame, so
+    // this models a stalled partial write, not a resumed one).
+    var count: usize = 0;
+    var iter = try replica.scan(allocator, null, null);
+    defer iter.deinit();
+    while (try iter.next()) |_| count += 1;
+    try std.testing.expectEqual(@as(usize, 1), count);
+}
+
+test "replicator surfaces truncation when it falls behind a primary flush" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+    const primaryDir = try std.fs.path.join(allocator, &.{ base, "primary" });
+    defer allocator.free(primaryDir);
+    const replicaDir = try std.fs.path.join(allocator, &.{ base, "replica" });
+    defer allocator.free(replicaDir);
+
+    var primary = try Db.open(allocator, primaryDir, .{});
+    defer primary.close();
+    var replica = try Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    try primary.put("k", "v");
+
+    var rep = try Replicator.init(allocator, primaryDir, &replica);
+    defer rep.deinit();
+    // Advance the tailer's offset without applying, then flush the primary
+    // (truncates wal.log to 0) so the tailer's remembered offset now points
+    // past the end of the (now-empty) file.
+    const staleRecords = try rep.tailer.poll();
+    freeAll(allocator, staleRecords);
+    try primary.flush();
+
+    // The primary's flush() bumped its WAL generation, so the generation
+    // check in poll() fires before the (now also true, but weaker) raw
+    // byte-offset comparison would have.
+    try std.testing.expectError(ReplicateError.WalGenerationChanged, rep.syncOnce());
+
+    const recovered = try rep.fullResync(&primary, 500);
+    try std.testing.expectEqual(@as(usize, 1), recovered);
+    try std.testing.expectEqual(@as(u64, 0), rep.offset());
+
+    const v = try replica.get(allocator, "k");
+    defer if (v) |val| allocator.free(val);
+    try std.testing.expectEqualStrings("v", v.?);
+
+    // New writes after the resync are picked up normally through the
+    // freshly-restarted tail at offset 0.
+    try primary.put("k2", "v2");
+    try std.testing.expectEqual(@as(usize, 1), try rep.syncOnce());
+    const v2 = try replica.get(allocator, "k2");
+    defer if (v2) |val| allocator.free(val);
+    try std.testing.expectEqualStrings("v2", v2.?);
+}
+
+test "replicator fullResync bootstraps a brand new replica" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+    const primaryDir = try std.fs.path.join(allocator, &.{ base, "primary" });
+    defer allocator.free(primaryDir);
+    const replicaDir = try std.fs.path.join(allocator, &.{ base, "replica" });
+    defer allocator.free(replicaDir);
+
+    var primary = try Db.open(allocator, primaryDir, .{});
+    defer primary.close();
+    var replica = try Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    var i: usize = 0;
+    while (i < 50) : (i += 1) {
+        var keyBuf: [16]u8 = undefined;
+        var valBuf: [16]u8 = undefined;
+        const key = try std.fmt.bufPrint(&keyBuf, "key{d}", .{i});
+        const val = try std.fmt.bufPrint(&valBuf, "val{d}", .{i});
+        try primary.put(key, val);
+    }
+
+    var rep = try Replicator.init(allocator, primaryDir, &replica);
+    defer rep.deinit();
+    const applied = try rep.fullResync(&primary, 7);
+    try std.testing.expectEqual(@as(usize, 50), applied);
+
+    var count: usize = 0;
+    var iter = try replica.scan(allocator, null, null);
+    defer iter.deinit();
+    while (try iter.next()) |_| count += 1;
+    try std.testing.expectEqual(@as(usize, 50), count);
+
+    // Fresh writes after the bootstrap keep tailing correctly from offset 0.
+    try primary.put("late", "arrival");
+    try std.testing.expectEqual(@as(usize, 1), try rep.syncOnce());
+    const v = try replica.get(allocator, "late");
+    defer if (v) |val| allocator.free(val);
+    try std.testing.expectEqualStrings("arrival", v.?);
+}
+
+test "walTailer rejects a nonexistent primary directory" {
+    const allocator = std.testing.allocator;
+    try std.testing.expectError(error.FileNotFound, WalTailer.open(allocator, "/nonexistent", 0, 0));
+}
+
+test "loadOffset returns null for a replica directory that never saved state" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    const loaded = try loadOffset(allocator, base, "/some/primary");
+    try std.testing.expectEqual(@as(?PersistedState, null), loaded);
+}
+
+test "saveState then loadOffset round-trips the offset, generation, and primary path" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    try saveState(allocator, base, "/data/primary", 4096, 7);
+    const loaded = try loadOffset(allocator, base, "/data/primary");
+    try std.testing.expectEqual(@as(u64, 4096), loaded.?.offset);
+    try std.testing.expectEqual(@as(u64, 7), loaded.?.generation);
+}
+
+test "saveState overwrites a prior state file with the newest offset and generation" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    try saveState(allocator, base, "/data/primary", 10, 0);
+    try saveState(allocator, base, "/data/primary", 20, 1);
+    try saveState(allocator, base, "/data/primary", 30, 2);
+    const loaded = try loadOffset(allocator, base, "/data/primary");
+    try std.testing.expectEqual(@as(u64, 30), loaded.?.offset);
+    try std.testing.expectEqual(@as(u64, 2), loaded.?.generation);
+}
+
+test "loadOffset rejects a state file saved for a different primary" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    try saveState(allocator, base, "/data/primary-a", 123, 0);
+    try std.testing.expectError(StateError.PrimaryMismatch, loadOffset(allocator, base, "/data/primary-b"));
+}
+
+test "loadOffset rejects a corrupted state file without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    try saveState(allocator, base, "/data/primary", 55, 3);
+
+    {
+        const file = try tmp.dir.openFile(stateFileName, .{ .mode = .read_write });
+        defer file.close();
+        try file.seekTo(9);
+        try file.writeAll(&[_]u8{0xFF});
+    }
+
+    try std.testing.expectError(StateError.Corrupt, loadOffset(allocator, base, "/data/primary"));
+}
+
+test "loadOffset rejects a truncated state file" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    try saveState(allocator, base, "/data/primary", 55, 3);
+
+    {
+        const file = try tmp.dir.openFile(stateFileName, .{ .mode = .read_write });
+        defer file.close();
+        try file.setEndPos(6);
+    }
+
+    try std.testing.expectError(StateError.Truncated, loadOffset(allocator, base, "/data/primary"));
+}
+
+test "loadOffset rejects a bad magic header" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    try saveState(allocator, base, "/data/primary", 55, 3);
+
+    {
+        const file = try tmp.dir.openFile(stateFileName, .{ .mode = .read_write });
+        defer file.close();
+        try file.seekTo(0);
+        try file.writeAll("XXXX");
+    }
+
+    try std.testing.expectError(StateError.BadMagic, loadOffset(allocator, base, "/data/primary"));
+}
+
+test "loadOffset rejects a state file written in the pre-generation v1 format" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+
+    var body = std.ArrayList(u8).init(allocator);
+    defer body.deinit();
+    const writer = encode.ByteWriter.init(&body);
+    try writer.slice("CRPS");
+    try writer.putU32(1);
+    try writer.putU64(999);
+    const primaryPath = "/data/primary";
+    try writer.putU32(@intCast(primaryPath.len));
+    try writer.slice(primaryPath);
+    try writer.putU32(encode.crc(body.items));
+
+    const file = try tmp.dir.createFile(stateFileName, .{ .truncate = true });
+    defer file.close();
+    try file.writeAll(body.items);
+
+    try std.testing.expectError(StateError.UnsupportedVersion, loadOffset(allocator, base, "/data/primary"));
+}
+
+test "saveState and loadOffset round-trip through a real replicate directory end to end" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const base = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(base);
+    const primaryDir = try std.fs.path.join(allocator, &.{ base, "primary" });
+    defer allocator.free(primaryDir);
+    const replicaDir = try std.fs.path.join(allocator, &.{ base, "replica" });
+    defer allocator.free(replicaDir);
+
+    var primary = try Db.open(allocator, primaryDir, .{});
+    defer primary.close();
+    var replica = try Db.open(allocator, replicaDir, .{});
+    defer replica.close();
+
+    try primary.put("a", "1");
+    try primary.put("b", "2");
+
+    var rep = try Replicator.init(allocator, primaryDir, &replica);
+    defer rep.deinit();
+    _ = try rep.syncOnce();
+    try saveState(allocator, replicaDir, primaryDir, rep.offset(), rep.generation());
+    const savedOffset = rep.offset();
+    try std.testing.expect(savedOffset > 0);
+
+    // A brand new process would reopen the replica Db and reconstruct a
+    // Replicator from the persisted offset instead of offset 0.
+    var replica2 = try Db.open(allocator, replicaDir, .{});
+    defer replica2.close();
+    const resumed = (try loadOffset(allocator, replicaDir, primaryDir)).?;
+    try std.testing.expectEqual(savedOffset, resumed.offset);
+    try std.testing.expectEqual(rep.generation(), resumed.generation);
+
+    var rep2 = try Replicator.initFromOffset(allocator, primaryDir, &replica2, resumed.offset, resumed.generation);
+    defer rep2.deinit();
+    try primary.put("c", "3");
+    const applied = try rep2.syncOnce();
+    try std.testing.expectEqual(@as(usize, 1), applied);
+
+    const c = try replica2.get(allocator, "c");
+    defer if (c) |v| allocator.free(v);
+    try std.testing.expectEqualStrings("3", c.?);
+    // The earlier keys were never re-applied through rep2 (it resumed past
+    // them), yet they are still visible because replica2 is the same
+    // on-disk replica Db that rep already wrote them into.
+    const a = try replica2.get(allocator, "a");
+    defer if (a) |v| allocator.free(v);
+    try std.testing.expectEqualStrings("1", a.?);
+}
diff --git a/src/root.zig b/src/root.zig
index 8c0ad79..56849ca 100644
--- a/src/root.zig
+++ b/src/root.zig
@@ -17,6 +17,80 @@ pub const BlockCache = @import("cache.zig").BlockCache;
 pub const compress = @import("compress.zig");
 pub const Transaction = @import("txn.zig").Transaction;
 pub const Stats = @import("stats.zig").Stats;
+pub const protocol = @import("protocol.zig");
+pub const Server = @import("server.zig").Server;
+pub const Client = @import("client.zig").Client;
+pub const row = @import("row.zig");
+pub const index = @import("index.zig");
+pub const query = @import("query.zig");
+pub const Table = query.Table;
+pub const Predicate = query.Predicate;
+pub const Page = query.Page;
+pub const expr = @import("expr.zig");
+pub const join = @import("join.zig");
+pub const JoinedRow = join.JoinedRow;
+pub const OuterJoinedRow = join.OuterJoinedRow;
+pub const RightOuterJoinedRow = join.RightOuterJoinedRow;
+pub const FullOuterJoinedRow = join.FullOuterJoinedRow;
+pub const txnTable = @import("txn_table.zig");
+pub const TableTxn = txnTable.TableTxn;
+pub const collections = @import("collections.zig");
+pub const Counter = collections.Counter;
+pub const Hash = collections.Hash;
+pub const Set = collections.Set;
+pub const List = collections.List;
+pub const ZSet = collections.ZSet;
+pub const backup = @import("backup.zig");
+pub const BackupError = backup.BackupError;
+pub const BackupInfo = backup.BackupInfo;
+pub const metrics = @import("metrics.zig");
+pub const MetricCounter = metrics.MetricCounter;
+pub const Gauge = metrics.Gauge;
+pub const Histogram = metrics.Histogram;
+pub const TokenBucket = metrics.TokenBucket;
+pub const SlidingWindowLimiter = metrics.SlidingWindowLimiter;
+pub const MetricsRegistry = metrics.Registry;
+pub const replicate = @import("replicate.zig");
+pub const Replicator = replicate.Replicator;
+pub const WalTailer = replicate.WalTailer;
+pub const ReplicateError = replicate.ReplicateError;
+pub const heap = @import("heap.zig");
+pub const MinHeap = heap.MinHeap;
+pub const version = @import("version.zig");
+pub const VersionSet = version.VersionSet;
+pub const VersionEdit = version.VersionEdit;
+pub const auth = @import("auth.zig");
+pub const AuthStore = auth.Store;
+pub const AuthRole = auth.Role;
+pub const AuthError = auth.AuthError;
+pub const session = @import("session.zig");
+pub const SessionStore = session.SessionStore;
+pub const ttl = @import("ttl.zig");
+pub const TtlResult = ttl.TtlResult;
+pub const collttl = @import("collttl.zig");
+pub const CollectionKind = collections.Kind;
+pub const concurrent = @import("concurrent.zig");
+pub const GuardedDb = concurrent.GuardedDb;
+pub const keyspace = @import("keyspace.zig");
+pub const repl = @import("repl.zig");
+pub const Repl = repl.Repl;
+pub const ReplError = repl.ReplError;
+pub const dump = @import("dump.zig");
+pub const aggregate = @import("aggregate.zig");
+pub const AggKind = aggregate.AggKind;
+pub const AggSpec = aggregate.AggSpec;
+pub const GroupBy = aggregate.GroupBy;
+pub const GroupRow = aggregate.GroupRow;
+pub const AggregateError = aggregate.AggregateError;
+pub const window = @import("window.zig");
+pub const WindowKind = window.WindowKind;
+pub const WindowSpec = window.WindowSpec;
+pub const WindowError = window.WindowError;
+pub const WindowFrameMode = window.FrameMode;
+pub const pubsub = @import("pubsub.zig");
+pub const PubSubHub = pubsub.Hub;
+pub const PubSubSubscriber = pubsub.Subscriber;
+pub const PubSubMessage = pubsub.Message;
 
 test {
     _ = @import("encode.zig");
@@ -30,4 +104,30 @@ test {
     _ = @import("txn.zig");
     _ = @import("stats.zig");
     _ = @import("db.zig");
+    _ = @import("protocol.zig");
+    _ = @import("server.zig");
+    _ = @import("client.zig");
+    _ = @import("row.zig");
+    _ = @import("index.zig");
+    _ = @import("query.zig");
+    _ = @import("expr.zig");
+    _ = @import("join.zig");
+    _ = @import("txn_table.zig");
+    _ = @import("collections.zig");
+    _ = @import("backup.zig");
+    _ = @import("metrics.zig");
+    _ = @import("replicate.zig");
+    _ = @import("heap.zig");
+    _ = @import("version.zig");
+    _ = @import("auth.zig");
+    _ = @import("session.zig");
+    _ = @import("ttl.zig");
+    _ = @import("collttl.zig");
+    _ = @import("concurrent.zig");
+    _ = @import("keyspace.zig");
+    _ = @import("repl.zig");
+    _ = @import("aggregate.zig");
+    _ = @import("dump.zig");
+    _ = @import("window.zig");
+    _ = @import("pubsub.zig");
 }
diff --git a/src/row.zig b/src/row.zig
new file mode 100644
index 0000000..eb4b449
--- /dev/null
+++ b/src/row.zig
@@ -0,0 +1,487 @@
+const std = @import("std");
+
+const Allocator = std.mem.Allocator;
+
+/// Dynamically typed value stored inside a row field, an index key, or a
+/// primary key. Kept small and copyable by tag; owned byte payloads (text,
+/// bytes) are heap-allocated and must be freed by whoever owns the Row/Value.
+pub const ValueTag = enum(u8) {
+    none = 0,
+    boolean = 1,
+    int = 2,
+    float = 3,
+    text = 4,
+    bytes = 5,
+};
+
+pub const Value = union(ValueTag) {
+    none: void,
+    boolean: bool,
+    int: i64,
+    float: f64,
+    text: []const u8,
+    bytes: []const u8,
+
+    pub fn dupe(self: Value, allocator: Allocator) !Value {
+        return switch (self) {
+            .text => |s| .{ .text = try allocator.dupe(u8, s) },
+            .bytes => |s| .{ .bytes = try allocator.dupe(u8, s) },
+            else => self,
+        };
+    }
+
+    pub fn free(self: Value, allocator: Allocator) void {
+        switch (self) {
+            .text => |s| allocator.free(s),
+            .bytes => |s| allocator.free(s),
+            else => {},
+        }
+    }
+
+    pub fn eql(a: Value, b: Value) bool {
+        return compare(a, b) == .eq;
+    }
+
+    /// Parses a single CLI/query-language token into a typed Value, using the
+    /// same `i:`/`f:`/`b:`/`s:` type-prefix convention throughout the CLI
+    /// (unprefixed tokens default to text). The returned `.text`/`.bytes`
+    /// payload (when present) is a slice into `text` - callers that need it
+    /// to outlive `text` must `dupe` the result.
+    pub fn parseCli(text: []const u8) error{InvalidValue}!Value {
+        if (std.mem.startsWith(u8, text, "i:")) {
+            const n = std.fmt.parseInt(i64, text[2..], 10) catch return error.InvalidValue;
+            return .{ .int = n };
+        } else if (std.mem.startsWith(u8, text, "f:")) {
+            const f = std.fmt.parseFloat(f64, text[2..]) catch return error.InvalidValue;
+            return .{ .float = f };
+        } else if (std.mem.startsWith(u8, text, "b:")) {
+            if (std.mem.eql(u8, text[2..], "true")) return .{ .boolean = true };
+            if (std.mem.eql(u8, text[2..], "false")) return .{ .boolean = false };
+            return error.InvalidValue;
+        } else if (std.mem.startsWith(u8, text, "s:")) {
+            return .{ .text = text[2..] };
+        } else {
+            return .{ .text = text };
+        }
+    }
+};
+
+/// Total order across all values: first by type tag, then by payload. This
+/// keeps a well-defined ordering even when a field holds mixed types across
+/// rows, which the ordered byte encoding below must mirror exactly.
+pub fn compare(a: Value, b: Value) std.math.Order {
+    const ta = @intFromEnum(@as(ValueTag, a));
+    const tb = @intFromEnum(@as(ValueTag, b));
+    if (ta != tb) return std.math.order(ta, tb);
+    return switch (a) {
+        .none => .eq,
+        .boolean => |av| std.math.order(@intFromBool(av), @intFromBool(b.boolean)),
+        .int => |av| std.math.order(av, b.int),
+        .float => |av| std.math.order(av, b.float),
+        .text => |av| std.mem.order(u8, av, b.text),
+        .bytes => |av| std.mem.order(u8, av, b.bytes),
+    };
+}
+
+pub const Field = struct {
+    name: []const u8,
+    value: Value,
+};
+
+/// Self-describing, schema-less row: an ordered list of named fields. Rows
+/// are the unit stored under a table's primary-key row keys and are what
+/// query.zig hands back from scans and index lookups.
+pub const Row = struct {
+    allocator: Allocator,
+    fields: std.ArrayList(Field),
+
+    pub fn init(allocator: Allocator) Row {
+        return .{ .allocator = allocator, .fields = std.ArrayList(Field).init(allocator) };
+    }
+
+    pub fn deinit(self: *Row) void {
+        for (self.fields.items) |f| {
+            self.allocator.free(f.name);
+            f.value.free(self.allocator);
+        }
+        self.fields.deinit();
+    }
+
+    /// Sets a field, replacing any existing field with the same name. Copies
+    /// both the name and any owned payload of `value` into the row.
+    pub fn set(self: *Row, name: []const u8, value: Value) !void {
+        const owned = try value.dupe(self.allocator);
+        errdefer owned.free(self.allocator);
+        for (self.fields.items) |*f| {
+            if (std.mem.eql(u8, f.name, name)) {
+                f.value.free(self.allocator);
+                f.value = owned;
+                return;
+            }
+        }
+        const nameCopy = try self.allocator.dupe(u8, name);
+        try self.fields.append(.{ .name = nameCopy, .value = owned });
+    }
+
+    pub fn get(self: *const Row, name: []const u8) ?Value {
+        for (self.fields.items) |f| {
+            if (std.mem.eql(u8, f.name, name)) return f.value;
+        }
+        return null;
+    }
+
+    pub fn count(self: *const Row) usize {
+        return self.fields.items.len;
+    }
+
+    /// Serializes the row to a self-contained byte blob suitable as a Db
+    /// value: [u32 fieldCount] { [u16 nameLen][name][u8 tag][payload] }*.
+    pub fn encode(self: *const Row, allocator: Allocator) ![]u8 {
+        var out = std.ArrayList(u8).init(allocator);
+        errdefer out.deinit();
+        try putU32(&out, @intCast(self.fields.items.len));
+        for (self.fields.items) |f| {
+            try putU16(&out, @intCast(f.name.len));
+            try out.appendSlice(f.name);
+            try out.append(@intFromEnum(@as(ValueTag, f.value)));
+            switch (f.value) {
+                .none => {},
+                .boolean => |v| try out.append(if (v) 1 else 0),
+                .int => |v| try putU64(&out, @bitCast(v)),
+                .float => |v| try putU64(&out, @bitCast(v)),
+                .text, .bytes => |s| {
+                    try putU32(&out, @intCast(s.len));
+                    try out.appendSlice(s);
+                },
+            }
+        }
+        return out.toOwnedSlice();
+    }
+
+    pub fn decode(allocator: Allocator, data: []const u8) !Row {
+        var row = Row.init(allocator);
+        errdefer row.deinit();
+        var pos: usize = 0;
+        const fieldCount = try readU32(data, &pos);
+        var i: u32 = 0;
+        while (i < fieldCount) : (i += 1) {
+            const nameLen = try readU16(data, &pos);
+            if (pos + nameLen > data.len) return error.Malformed;
+            const name = data[pos .. pos + nameLen];
+            pos += nameLen;
+            if (pos >= data.len) return error.Malformed;
+            const tag: ValueTag = std.meta.intToEnum(ValueTag, data[pos]) catch return error.Malformed;
+            pos += 1;
+            const value: Value = switch (tag) {
+                .none => .{ .none = {} },
+                .boolean => blk: {
+                    if (pos >= data.len) return error.Malformed;
+                    const b = data[pos];
+                    pos += 1;
+                    break :blk .{ .boolean = b != 0 };
+                },
+                .int => .{ .int = @bitCast(try readU64(data, &pos)) },
+                .float => .{ .float = @bitCast(try readU64(data, &pos)) },
+                .text => blk: {
+                    const len = try readU32(data, &pos);
+                    if (pos + len > data.len) return error.Malformed;
+                    const s = data[pos .. pos + len];
+                    pos += len;
+                    break :blk .{ .text = s };
+                },
+                .bytes => blk: {
+                    const len = try readU32(data, &pos);
+                    if (pos + len > data.len) return error.Malformed;
+                    const s = data[pos .. pos + len];
+                    pos += len;
+                    break :blk .{ .bytes = s };
+                },
+            };
+            try row.set(name, value);
+        }
+        if (pos != data.len) return error.Malformed;
+        return row;
+    }
+};
+
+fn putU16(out: *std.ArrayList(u8), v: u16) !void {
+    var b: [2]u8 = undefined;
+    std.mem.writeInt(u16, &b, v, .little);
+    try out.appendSlice(&b);
+}
+
+fn putU32(out: *std.ArrayList(u8), v: u32) !void {
+    var b: [4]u8 = undefined;
+    std.mem.writeInt(u32, &b, v, .little);
+    try out.appendSlice(&b);
+}
+
+fn putU64(out: *std.ArrayList(u8), v: u64) !void {
+    var b: [8]u8 = undefined;
+    std.mem.writeInt(u64, &b, v, .little);
+    try out.appendSlice(&b);
+}
+
+fn readU16(data: []const u8, pos: *usize) !u16 {
+    if (pos.* + 2 > data.len) return error.Malformed;
+    const v = std.mem.readInt(u16, data[pos.*..][0..2], .little);
+    pos.* += 2;
+    return v;
+}
+
+fn readU32(data: []const u8, pos: *usize) !u32 {
+    if (pos.* + 4 > data.len) return error.Malformed;
+    const v = std.mem.readInt(u32, data[pos.*..][0..4], .little);
+    pos.* += 4;
+    return v;
+}
+
+fn readU64(data: []const u8, pos: *usize) !u64 {
+    if (pos.* + 8 > data.len) return error.Malformed;
+    const v = std.mem.readInt(u64, data[pos.*..][0..8], .little);
+    pos.* += 8;
+    return v;
+}
+
+/// Appends an order-preserving byte encoding of `value` to `out`, such that
+/// lexicographic byte comparison of two encodings matches `compare()` of the
+/// original values. Used to build index keys and primary-key suffixes that
+/// must sort correctly inside the LSM tree's byte-ordered keyspace.
+///
+/// Text/bytes payloads are escaped (0x00 -> 0x00 0xFF) and terminated with
+/// 0x00 0x00 so that concatenating several encoded values back to back stays
+/// unambiguous and order-preserving (no payload can be a byte-for-byte prefix
+/// of another once escaped and terminated).
+pub fn appendOrdered(out: *std.ArrayList(u8), value: Value) !void {
+    try out.append(@intFromEnum(@as(ValueTag, value)));
+    switch (value) {
+        .none => {},
+        .boolean => |v| try out.append(if (v) 1 else 0),
+        .int => |v| {
+            const flipped: u64 = @as(u64, @bitCast(v)) ^ 0x8000000000000000;
+            var b: [8]u8 = undefined;
+            std.mem.writeInt(u64, &b, flipped, .big);
+            try out.appendSlice(&b);
+        },
+        .float => |v| {
+            var bits: u64 = @bitCast(v);
+            if (bits & 0x8000000000000000 != 0) {
+                bits = ~bits;
+            } else {
+                bits |= 0x8000000000000000;
+            }
+            var b: [8]u8 = undefined;
+            std.mem.writeInt(u64, &b, bits, .big);
+            try out.appendSlice(&b);
+        },
+        .text, .bytes => |s| {
+            for (s) |byte| {
+                if (byte == 0x00) {
+                    try out.appendSlice(&.{ 0x00, 0xFF });
+                } else {
+                    try out.append(byte);
+                }
+            }
+            try out.appendSlice(&.{ 0x00, 0x00 });
+        },
+    }
+}
+
+pub fn encodeOrdered(allocator: Allocator, value: Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try appendOrdered(&out, value);
+    return out.toOwnedSlice();
+}
+
+/// Encodes a single standalone Value using the same (non order-preserving)
+/// tag+payload format as a Row field, minus the field name. Used to store
+/// primary keys as index-entry values, where later exact reconstruction
+/// matters more than byte ordering.
+pub fn encodeValue(allocator: Allocator, value: Value) ![]u8 {
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+    try out.append(@intFromEnum(@as(ValueTag, value)));
+    switch (value) {
+        .none => {},
+        .boolean => |v| try out.append(if (v) 1 else 0),
+        .int => |v| try putU64(&out, @bitCast(v)),
+        .float => |v| try putU64(&out, @bitCast(v)),
+        .text, .bytes => |s| {
+            try putU32(&out, @intCast(s.len));
+            try out.appendSlice(s);
+        },
+    }
+    return out.toOwnedSlice();
+}
+
+pub fn decodeValue(allocator: Allocator, data: []const u8) !Value {
+    var pos: usize = 0;
+    if (pos >= data.len) return error.Malformed;
+    const tag: ValueTag = std.meta.intToEnum(ValueTag, data[pos]) catch return error.Malformed;
+    pos += 1;
+    return switch (tag) {
+        .none => .{ .none = {} },
+        .boolean => blk: {
+            if (pos >= data.len) return error.Malformed;
+            break :blk .{ .boolean = data[pos] != 0 };
+        },
+        .int => .{ .int = @bitCast(try readU64(data, &pos)) },
+        .float => .{ .float = @bitCast(try readU64(data, &pos)) },
+        .text => blk: {
+            const len = try readU32(data, &pos);
+            if (pos + len > data.len) return error.Malformed;
+            break :blk .{ .text = try allocator.dupe(u8, data[pos .. pos + len]) };
+        },
+        .bytes => blk: {
+            const len = try readU32(data, &pos);
+            if (pos + len > data.len) return error.Malformed;
+            break :blk .{ .bytes = try allocator.dupe(u8, data[pos .. pos + len]) };
+        },
+    };
+}
+
+test "row set get overwrite and free" {
+    const allocator = std.testing.allocator;
+    var row = Row.init(allocator);
+    defer row.deinit();
+
+    try row.set("name", .{ .text = "ada" });
+    try row.set("age", .{ .int = 30 });
+    try row.set("name", .{ .text = "ada lovelace" });
+
+    try std.testing.expectEqual(@as(usize, 2), row.count());
+    try std.testing.expectEqualStrings("ada lovelace", row.get("name").?.text);
+    try std.testing.expectEqual(@as(i64, 30), row.get("age").?.int);
+    try std.testing.expect(row.get("missing") == null);
+}
+
+test "row encode decode round trip all types" {
+    const allocator = std.testing.allocator;
+    var row = Row.init(allocator);
+    defer row.deinit();
+
+    try row.set("id", .{ .int = -42 });
+    try row.set("score", .{ .float = 3.5 });
+    try row.set("active", .{ .boolean = true });
+    try row.set("bio", .{ .text = "hello world" });
+    try row.set("blob", .{ .bytes = &.{ 0, 1, 2, 255 } });
+    try row.set("nothing", .{ .none = {} });
+
+    const encoded = try row.encode(allocator);
+    defer allocator.free(encoded);
+
+    var decoded = try Row.decode(allocator, encoded);
+    defer decoded.deinit();
+
+    try std.testing.expectEqual(@as(i64, -42), decoded.get("id").?.int);
+    try std.testing.expectEqual(@as(f64, 3.5), decoded.get("score").?.float);
+    try std.testing.expectEqual(true, decoded.get("active").?.boolean);
+    try std.testing.expectEqualStrings("hello world", decoded.get("bio").?.text);
+    try std.testing.expectEqualSlices(u8, &.{ 0, 1, 2, 255 }, decoded.get("blob").?.bytes);
+    try std.testing.expectEqual(ValueTag.none, @as(ValueTag, decoded.get("nothing").?));
+}
+
+test "row decode rejects malformed data" {
+    const allocator = std.testing.allocator;
+    try std.testing.expectError(error.Malformed, Row.decode(allocator, &.{ 1, 0, 0, 0 }));
+    try std.testing.expectError(error.Malformed, Row.decode(allocator, &.{ 1, 0, 0, 0, 5, 0, 'a' }));
+}
+
+test "compare orders by type tag then payload" {
+    try std.testing.expectEqual(std.math.Order.lt, compare(.{ .none = {} }, .{ .boolean = false }));
+    try std.testing.expectEqual(std.math.Order.lt, compare(.{ .int = 5 }, .{ .float = 0.0 }));
+    try std.testing.expectEqual(std.math.Order.lt, compare(.{ .int = -5 }, .{ .int = 3 }));
+    try std.testing.expectEqual(std.math.Order.gt, compare(.{ .text = "b" }, .{ .text = "a" }));
+    try std.testing.expect(Value.eql(.{ .text = "x" }, .{ .text = "x" }));
+}
+
+test "appendOrdered preserves int order across sign boundary" {
+    const allocator = std.testing.allocator;
+    const values = [_]i64{ std.math.minInt(i64), -1000, -1, 0, 1, 1000, std.math.maxInt(i64) };
+    var prev: ?[]u8 = null;
+    defer if (prev) |p| allocator.free(p);
+    for (values) |v| {
+        const encoded = try encodeOrdered(allocator, .{ .int = v });
+        if (prev) |p| {
+            try std.testing.expect(std.mem.order(u8, p, encoded) == .lt);
+            allocator.free(p);
+        }
+        prev = encoded;
+    }
+}
+
+test "appendOrdered preserves float order across sign and magnitude" {
+    const allocator = std.testing.allocator;
+    const values = [_]f64{ -100.0, -1.5, -0.001, 0.0, 0.001, 1.5, 100.0 };
+    var prev: ?[]u8 = null;
+    defer if (prev) |p| allocator.free(p);
+    for (values) |v| {
+        const encoded = try encodeOrdered(allocator, .{ .float = v });
+        if (prev) |p| {
+            try std.testing.expect(std.mem.order(u8, p, encoded) == .lt);
+            allocator.free(p);
+        }
+        prev = encoded;
+    }
+}
+
+test "appendOrdered escapes embedded zero bytes unambiguously" {
+    const allocator = std.testing.allocator;
+    const a = try encodeOrdered(allocator, .{ .text = "ab" });
+    defer allocator.free(a);
+    const b = try encodeOrdered(allocator, .{ .text = "ab\x00c" });
+    defer allocator.free(b);
+    const c = try encodeOrdered(allocator, .{ .text = "ab" ++ "c"[0..0] });
+    defer allocator.free(c);
+    // "ab" must sort before "ab\x00c" (shorter, unescaped terminator wins),
+    // and the escaped embedded zero must not corrupt ordering.
+    try std.testing.expect(std.mem.order(u8, a, b) == .lt);
+    try std.testing.expect(std.mem.eql(u8, a, c));
+}
+
+test "encodeValue decodeValue round trip" {
+    const allocator = std.testing.allocator;
+    const original = Value{ .text = "primary-key-42" };
+    const encoded = try encodeValue(allocator, original);
+    defer allocator.free(encoded);
+    const decoded = try decodeValue(allocator, encoded);
+    defer decoded.free(allocator);
+    try std.testing.expectEqualStrings("primary-key-42", decoded.text);
+
+    const intEncoded = try encodeValue(allocator, .{ .int = -7 });
+    defer allocator.free(intEncoded);
+    const intDecoded = try decodeValue(allocator, intEncoded);
+    try std.testing.expectEqual(@as(i64, -7), intDecoded.int);
+}
+
+test "appendOrdered text ordering matches string ordering" {
+    const allocator = std.testing.allocator;
+    const words = [_][]const u8{ "apple", "banana", "banjo", "zebra" };
+    var prev: ?[]u8 = null;
+    defer if (prev) |p| allocator.free(p);
+    for (words) |w| {
+        const encoded = try encodeOrdered(allocator, .{ .text = w });
+        if (prev) |p| {
+            try std.testing.expect(std.mem.order(u8, p, encoded) == .lt);
+            allocator.free(p);
+        }
+        prev = encoded;
+    }
+}
+
+test "parseCli honors type prefixes and defaults to text" {
+    try std.testing.expectEqual(@as(i64, 42), (try Value.parseCli("i:42")).int);
+    try std.testing.expectEqual(@as(i64, -3), (try Value.parseCli("i:-3")).int);
+    try std.testing.expectEqual(@as(f64, 1.5), (try Value.parseCli("f:1.5")).float);
+    try std.testing.expectEqual(true, (try Value.parseCli("b:true")).boolean);
+    try std.testing.expectEqual(false, (try Value.parseCli("b:false")).boolean);
+    try std.testing.expectEqualStrings("hi", (try Value.parseCli("s:hi")).text);
+    try std.testing.expectEqualStrings("plain", (try Value.parseCli("plain")).text);
+}
+
+test "parseCli rejects malformed prefixed values" {
+    try std.testing.expectError(error.InvalidValue, Value.parseCli("i:notanumber"));
+    try std.testing.expectError(error.InvalidValue, Value.parseCli("f:notafloat"));
+    try std.testing.expectError(error.InvalidValue, Value.parseCli("b:maybe"));
+}
diff --git a/src/server.zig b/src/server.zig
new file mode 100644
index 0000000..5440b3e
--- /dev/null
+++ b/src/server.zig
@@ -0,0 +1,8145 @@
+const std = @import("std");
+const protocol = @import("protocol.zig");
+const dbmod = @import("db.zig");
+const metrics = @import("metrics.zig");
+const querymod = @import("query.zig");
+const exprmod = @import("expr.zig");
+const authmod = @import("auth.zig");
+const sessionmod = @import("session.zig");
+const ttlmod = @import("ttl.zig");
+const collmod = @import("collections.zig");
+const collttlmod = @import("collttl.zig");
+const rowmod = @import("row.zig");
+const txnmod = @import("txn.zig");
+const txntablemod = @import("txn_table.zig");
+const joinmod = @import("join.zig");
+const aggregatemod = @import("aggregate.zig");
+const windowmod = @import("window.zig");
+const dumpmod = @import("dump.zig");
+const pubsubmod = @import("pubsub.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+
+/// Which role a given opcode needs at minimum when auth is enabled. `ping`
+/// and `auth` itself are handled before this is ever consulted (see
+/// `dispatch`) - every other read op needs `readonly`, every mutation
+/// needs `readwrite`, and `user_admin` (remote user management: create,
+/// change password, change role, delete, list) needs `admin` - the one
+/// opcode reserved for administrative server operations. Bootstrapping the
+/// very first admin account still has to happen CLI-only over a local Db
+/// handle (see `main.zig`'s `user add` and `serve --auth`'s refusal to
+/// start without one), since a fresh server has no admin to authenticate
+/// this opcode with in the first place.
+///
+/// `ttl_op` bundles four actions (see `protocol.TtlAction`) behind one
+/// opcode, unlike every other entry here which is a single action - so it
+/// is the one case that needs to peek at the payload's first byte (the
+/// action tag) rather than deciding purely from `op`. `query` is read-only;
+/// `expire`/`persist`/`sweep` all mutate the store and need `readwrite`. A
+/// payload too short to carry an action byte falls back to `readwrite` (the
+/// stricter requirement) - the actual decode in `handleTtlOp` will reject it
+/// as malformed either way, so this only affects which error status a
+/// bad frame gets before it is ever decoded.
+fn requiredRole(op: protocol.Op, payload: []const u8) authmod.Role {
+    return switch (op) {
+        .ping, .auth, .auth_token => .readonly,
+        .get, .scan, .prefix, .stats, .table_select, .table_join, .table_aggregate, .table_window, .table_explain, .table_export, .metrics => .readonly,
+        .set, .del, .batch, .flush, .compact, .table_update, .table_delete, .table_import => .readwrite,
+        .user_admin => .admin,
+        .ttl_op => if (payload.len > 0 and payload[0] == @intFromEnum(protocol.TtlAction.query))
+            .readonly
+        else
+            .readwrite,
+        // Same action-byte peek as `.ttl_op` above, and for the same
+        // reason: `coll_ttl_op` bundles the same four actions, just
+        // against a whole collection instead of one flat key.
+        .coll_ttl_op => if (payload.len > 0 and payload[0] == @intFromEnum(protocol.TtlAction.query))
+            .readonly
+        else
+            .readwrite,
+        // `coll_op` bundles thirty collection actions behind one opcode
+        // (see `protocol.CollAction`) - same action-byte peek as `ttl_op`/
+        // `coll_ttl_op`, but the read/write split is looked up from
+        // `CollAction.isReadOnly` instead of a single fixed action value,
+        // since unlike the four TTL actions this opcode's actions are not
+        // all one enum-comparison away from each other.
+        .coll_op => if (payload.len > 0)
+            (if ((protocol.CollAction.fromByte(payload[0]) catch null)) |a|
+                (if (a.isReadOnly()) authmod.Role.readonly else .readwrite)
+            else
+                .readwrite)
+        else
+            .readwrite,
+        // `txn_op` is always a write (every entry is a put or a delete),
+        // unlike `ttl_op`/`coll_ttl_op`/`coll_op` above it has no read-only
+        // action to peek for, so it needs no payload inspection at all.
+        .txn_op => .readwrite,
+        // Pub/sub never touches `Db` at all (see `pubsub.zig`'s `Hub` doc
+        // comment) - all three are gated `readonly` purely so a server with
+        // auth enabled still requires SOME authenticated connection before
+        // any of them works, matching every other opcode's default
+        // posture, rather than because any of them reads storage.
+        // `unsubscribe` in particular is always sent from a DIFFERENT
+        // connection than the one that subscribed (see
+        // `protocol.encodeUnsubscribe`'s doc comment) - it needs no
+        // stronger role than `subscribe`/`publish` just because it arrives
+        // over its own connection.
+        .subscribe, .publish, .unsubscribe => .readonly,
+    };
+}
+
+const PerConnLimitConfig = struct {
+    capacity: f64,
+    refillPerSecond: f64,
+};
+
+/// A TCP server that exposes a single `Db` over the binary protocol in
+/// `protocol.zig`. One accept loop thread hands each connection off to
+/// its own detached worker thread; every worker serialises its access to
+/// `db` through `mutex` since `Db` itself keeps no internal locking.
+pub const Server = struct {
+    allocator: Allocator,
+    db: *Db,
+    mutex: std.Thread.Mutex = .{},
+    net: std.net.Server,
+    acceptThread: ?std.Thread = null,
+    active: std.atomic.Value(usize) = std.atomic.Value(usize).init(0),
+    stopping: std.atomic.Value(bool) = std.atomic.Value(bool).init(false),
+    limiter: ?metrics.TokenBucket = null,
+    perConnLimit: ?PerConnLimitConfig = null,
+    requestsTotal: metrics.MetricCounter = .{},
+    rateLimitedTotal: metrics.MetricCounter = .{},
+    connRateLimitedTotal: metrics.MetricCounter = .{},
+    authStore: ?authmod.Store = null,
+    unauthorizedTotal: metrics.MetricCounter = .{},
+    forbiddenTotal: metrics.MetricCounter = .{},
+    sessions: ?*sessionmod.SessionStore = null,
+    sessionTtlNanos: i128 = 0,
+    sessionExpiredTotal: metrics.MetricCounter = .{},
+    sweepIntervalNanos: u64 = 0,
+    sweeperThread: ?std.Thread = null,
+    sessionsSweptTotal: metrics.MetricCounter = .{},
+    ttlSweepIntervalNanos: u64 = 0,
+    ttlSweeperThread: ?std.Thread = null,
+    ttlSweptTotal: metrics.MetricCounter = .{},
+    collTtlSweepIntervalNanos: u64 = 0,
+    collTtlSweeperThread: ?std.Thread = null,
+    collTtlSweptTotal: metrics.MetricCounter = .{},
+    /// Channel registry for `subscribe`/`publish` - see `pubsub.zig`'s doc
+    /// comment on `Hub` for why this is entirely separate from `mutex`/`db`
+    /// above (a live subscriber must never be able to block a store read or
+    /// write, or vice versa).
+    pubsub: pubsubmod.Hub = undefined,
+    messagesPublishedTotal: metrics.MetricCounter = .{},
+
+    pub fn init(allocator: Allocator, db: *Db, address: std.net.Address) !Server {
+        const net = try address.listen(.{ .reuse_address = true });
+        return .{ .allocator = allocator, .db = db, .net = net, .pubsub = pubsubmod.Hub.init(allocator) };
+    }
+
+    pub fn boundAddress(self: *Server) std.net.Address {
+        return self.net.listen_address;
+    }
+
+    /// Number of connections currently being served. Exposed for tests
+    /// that need to wait for a handler to finish without racing on
+    /// thread teardown.
+    pub fn activeConnections(self: *Server) usize {
+        return self.active.load(.acquire);
+    }
+
+    /// Turns on a token-bucket rate limit shared across every connection:
+    /// each dispatched request consumes one token before it is allowed to
+    /// touch `db.mutex` at all, so an overload is rejected cheaply instead
+    /// of queuing behind real storage work. Disabled (unlimited) by
+    /// default; call once before `start()`.
+    pub fn enableRateLimit(self: *Server, capacity: f64, refillPerSecond: f64) void {
+        self.limiter = metrics.TokenBucket.init(capacity, refillPerSecond, @intCast(std.time.nanoTimestamp()));
+    }
+
+    /// Gives every accepted connection its own private token bucket,
+    /// independent of every other connection's budget and of the shared
+    /// `limiter` above. A fresh bucket is created per connection in
+    /// `handleConnection` (not shared state, so no locking is needed beyond
+    /// what TokenBucket already does internally) - one noisy client cannot
+    /// starve another client's share of the server, which a single global
+    /// bucket cannot express. Both limits can be enabled together: a
+    /// request must clear the per-connection budget before it is even
+    /// checked against the global one. Disabled by default; call once
+    /// before `start()`.
+    pub fn enablePerConnectionRateLimit(self: *Server, capacity: f64, refillPerSecond: f64) void {
+        self.perConnLimit = .{ .capacity = capacity, .refillPerSecond = refillPerSecond };
+    }
+
+    /// Turns on username/password authentication and role enforcement for
+    /// every connection: after this call, every opcode except `ping` and
+    /// `auth` itself requires a prior successful `auth` on that connection
+    /// (`unauthorized` otherwise), and the authenticated role must meet
+    /// `requiredRole(op)` (`forbidden` otherwise). `store` is not owned by
+    /// the server - the caller keeps managing the underlying `Db` user
+    /// records (creating the first admin, etc.) through `store` directly.
+    /// Disabled (no auth required, matching every prior version of this
+    /// server) by default; call once before `start()`.
+    pub fn enableAuth(self: *Server, store: authmod.Store) void {
+        self.authStore = store;
+    }
+
+    /// Layers expiring session tokens on top of password auth (requires
+    /// `enableAuth` to also be called - sessions are only ever minted from
+    /// a successful password check, never a substitute for one). Once
+    /// enabled: a successful `auth` response carries a fresh token in its
+    /// payload (empty payload otherwise, unchanged from before this
+    /// existed) valid for `ttlNanos`; a NEW connection can skip the
+    /// password entirely by sending that token as `auth_token` instead;
+    /// and - the actual behavior change from plain password auth - a
+    /// connection's authenticated role stops being honored the moment its
+    /// session's expiry passes, even if the TCP connection itself has
+    /// stayed open the whole time (`dispatch` re-checks the wall clock on
+    /// every request, not just at `auth` time). `store` is not owned by
+    /// the server, exactly like `enableAuth`'s `authmod.Store` - the
+    /// caller keeps it alive and can inspect/revoke sessions directly.
+    pub fn enableSessions(self: *Server, store: *sessionmod.SessionStore, ttlNanos: i128) void {
+        self.sessions = store;
+        self.sessionTtlNanos = ttlNanos;
+    }
+
+    /// Runs `SessionStore.sweepExpired` on a background thread every
+    /// `intervalNanos`, starting once `start()` is called. Without this, a
+    /// session nobody ever presents again (the client that held it simply
+    /// vanished) sits in `sessions` forever - `validate()` only ever cleans
+    /// up a token someone actually tries to use. Requires `enableSessions`
+    /// to have been called first (checked in `start()`, not here, since
+    /// callers are free to call these two in either order before `start`).
+    pub fn enableSessionSweep(self: *Server, intervalNanos: u64) void {
+        self.sweepIntervalNanos = intervalNanos;
+    }
+
+    /// Runs `ttl.sweepExpired` on a background thread every `intervalNanos`,
+    /// starting once `start()` is called - independent of `enableAuth`/
+    /// `enableSessions`/`enableSessionSweep` above, since key TTLs (set via
+    /// the `ttl_op` opcode or the CLI's local `put --ttl`/`expire`) are a
+    /// property of the `Db` itself, not of authentication. Without this, a
+    /// key whose TTL elapsed but that nobody ever reads again (so
+    /// `ttl.getLive`'s lazy expiry never fires) sits in the store forever -
+    /// exactly the same gap `enableSessionSweep` closes for session tokens.
+    /// Call once before `start()`.
+    pub fn enableTtlSweep(self: *Server, intervalNanos: u64) void {
+        self.ttlSweepIntervalNanos = intervalNanos;
+    }
+
+    /// Runs `collttl.sweepExpired` on a background thread every
+    /// `intervalNanos`, starting once `start()` is called - the whole-
+    /// collection counterpart of `enableTtlSweep` above, independent of it
+    /// (a server can enable one, both, or neither). Without this, a
+    /// collection whose TTL elapsed but that nobody ever touches again (so
+    /// `coll_ttl_op`'s lazy `expireIfDue` never fires, matching the CLI's
+    /// local `coll` dispatcher) sits in the store forever. Call once before
+    /// `start()`.
+    pub fn enableCollTtlSweep(self: *Server, intervalNanos: u64) void {
+        self.collTtlSweepIntervalNanos = intervalNanos;
+    }
+
+    /// Registers this server's request counters into `reg` under fixed
+    /// names, so they show up alongside any other Prometheus metrics an
+    /// embedding application already exports.
+    pub fn registerMetrics(self: *Server, reg: *metrics.Registry) !void {
+        try reg.registerCounter("cobalt_server_requests_total", &self.requestsTotal);
+        try reg.registerCounter("cobalt_server_rate_limited_total", &self.rateLimitedTotal);
+        try reg.registerCounter("cobalt_server_conn_rate_limited_total", &self.connRateLimitedTotal);
+        try reg.registerCounter("cobalt_server_unauthorized_total", &self.unauthorizedTotal);
+        try reg.registerCounter("cobalt_server_forbidden_total", &self.forbiddenTotal);
+        try reg.registerCounter("cobalt_server_session_expired_total", &self.sessionExpiredTotal);
+        try reg.registerCounter("cobalt_server_sessions_swept_total", &self.sessionsSweptTotal);
+        try reg.registerCounter("cobalt_server_ttl_swept_total", &self.ttlSweptTotal);
+        try reg.registerCounter("cobalt_server_coll_ttl_swept_total", &self.collTtlSweptTotal);
+        try reg.registerCounter("cobalt_server_messages_published_total", &self.messagesPublishedTotal);
+    }
+
+    pub fn start(self: *Server) !void {
+        self.acceptThread = try std.Thread.spawn(.{}, acceptLoop, .{self});
+        if (self.sessions != null and self.sweepIntervalNanos > 0) {
+            self.sweeperThread = try std.Thread.spawn(.{}, sweepLoop, .{self});
+        }
+        if (self.ttlSweepIntervalNanos > 0) {
+            self.ttlSweeperThread = try std.Thread.spawn(.{}, ttlSweepLoop, .{self});
+        }
+        if (self.collTtlSweepIntervalNanos > 0) {
+            self.collTtlSweeperThread = try std.Thread.spawn(.{}, collTtlSweepLoop, .{self});
+        }
+    }
+
+    /// Blocks until the accept loop exits (only happens via `stop()` or
+    /// an unrecoverable accept error). Used by long-running foreground
+    /// servers such as the CLI's `serve` command.
+    pub fn wait(self: *Server) void {
+        if (self.acceptThread) |t| t.join();
+    }
+
+    /// Background loop started by `start()` when `enableSessionSweep` set a
+    /// nonzero interval and sessions are enabled. Sleeps the full interval
+    /// between sweeps (a sweep is pure housekeeping, never load-bearing for
+    /// correctness - `validate()` already refuses an expired token on its
+    /// own), and checks `stopping` both before and after each sleep so
+    /// `stop()` never has to wait more than one interval to join it.
+    fn sweepLoop(self: *Server) void {
+        const store = self.sessions orelse return;
+        while (!self.stopping.load(.acquire)) {
+            std.time.sleep(self.sweepIntervalNanos);
+            if (self.stopping.load(.acquire)) return;
+            const dropped = store.sweepExpired(std.time.nanoTimestamp());
+            if (dropped > 0) self.sessionsSweptTotal.incrBy(@intCast(dropped));
+        }
+    }
+
+    /// Background loop started by `start()` when `enableTtlSweep` set a
+    /// nonzero interval. Unlike `sweepLoop` above, `ttl.sweepExpired` reads
+    /// and mutates the same `Db` every request handler touches, so this
+    /// loop must take `self.mutex` around the call exactly like `dispatch`
+    /// does for every opcode - `Db` itself keeps no internal locking (see
+    /// the doc comment on `Server`). A failed sweep (e.g. a transient I/O
+    /// error) is skipped rather than crashing the server; the next tick
+    /// tries again.
+    fn ttlSweepLoop(self: *Server) void {
+        while (!self.stopping.load(.acquire)) {
+            std.time.sleep(self.ttlSweepIntervalNanos);
+            if (self.stopping.load(.acquire)) return;
+            self.mutex.lock();
+            const reaped = ttlmod.sweepExpired(self.db, self.allocator, std.time.nanoTimestamp()) catch {
+                self.mutex.unlock();
+                continue;
+            };
+            self.mutex.unlock();
+            if (reaped > 0) self.ttlSweptTotal.incrBy(@intCast(reaped));
+        }
+    }
+
+    /// Background loop started by `start()` when `enableCollTtlSweep` set a
+    /// nonzero interval - the whole-collection counterpart of `ttlSweepLoop`
+    /// above, same shape (own thread, takes `self.mutex` around the actual
+    /// `Db` access, skips a failed sweep rather than crashing).
+    /// `collttl.sweepExpired` walks every kind's marker namespace in one
+    /// prefix scan, so one thread covers Counter/Hash/Set/List/ZSet at once
+    /// rather than needing one sweeper per kind.
+    fn collTtlSweepLoop(self: *Server) void {
+        while (!self.stopping.load(.acquire)) {
+            std.time.sleep(self.collTtlSweepIntervalNanos);
+            if (self.stopping.load(.acquire)) return;
+            self.mutex.lock();
+            const reaped = collttlmod.sweepExpired(self.db, self.allocator, std.time.nanoTimestamp()) catch {
+                self.mutex.unlock();
+                continue;
+            };
+            self.mutex.unlock();
+            if (reaped > 0) self.collTtlSweptTotal.incrBy(@intCast(reaped));
+        }
+    }
+
+    fn acceptLoop(self: *Server) void {
+        while (true) {
+            const conn = self.net.accept() catch return;
+            if (self.stopping.load(.acquire)) {
+                conn.stream.close();
+                return;
+            }
+            _ = self.active.fetchAdd(1, .acq_rel);
+            const t = std.Thread.spawn(.{}, handleConnection, .{ self, conn }) catch {
+                _ = self.active.fetchSub(1, .acq_rel);
+                conn.stream.close();
+                continue;
+            };
+            t.detach();
+        }
+    }
+
+    fn handleConnection(self: *Server, conn: std.net.Server.Connection) void {
+        defer conn.stream.close();
+        defer _ = self.active.fetchSub(1, .acq_rel);
+        var stream = conn.stream;
+
+        // A private bucket for this one connection, if enabled. It lives on
+        // this worker's own stack and is only ever touched by this thread,
+        // so unlike `self.limiter` it needs no cross-thread synchronization
+        // even though TokenBucket carries its own mutex regardless.
+        var connLimiter: ?metrics.TokenBucket = if (self.perConnLimit) |cfg|
+            metrics.TokenBucket.init(cfg.capacity, cfg.refillPerSecond, @intCast(std.time.nanoTimestamp()))
+        else
+            null;
+
+        // Which role (if any) this one connection has authenticated as.
+        // Lives on this worker's stack, exactly like `connLimiter` above -
+        // a fresh, private slot per connection, never shared.
+        var connRole: ?authmod.Role = null;
+
+        // When sessions are enabled (see `enableSessions`), the nanosecond
+        // timestamp at which `connRole` above stops being honored - set
+        // whenever `auth`/`auth_token` succeeds, re-checked on every
+        // request in `dispatch`. Stays null (never expires on its own) for
+        // a server with auth but no session store, matching the original
+        // "authenticated for as long as the connection is open" behavior.
+        var connExpiresAtNanos: ?i128 = null;
+
+        while (true) {
+            var frame = protocol.readFrame(self.allocator, stream.reader()) catch return;
+            defer frame.deinit();
+            const limPtr: ?*metrics.TokenBucket = if (connLimiter) |*cl| cl else null;
+            self.dispatch(&frame, stream, stream.writer(), limPtr, &connRole, &connExpiresAtNanos) catch return;
+        }
+    }
+
+    fn writeErr(writer: anytype, status: protocol.Status, message: []const u8) !void {
+        try protocol.writeFrame(writer, @intFromEnum(status), message);
+    }
+
+    fn dispatch(self: *Server, frame: *protocol.Frame, stream: std.net.Stream, writer: anytype, connLimiter: ?*metrics.TokenBucket, connRole: *?authmod.Role, connExpiresAtNanos: *?i128) !void {
+        self.requestsTotal.incr();
+        if (connLimiter) |cl| {
+            if (!cl.tryAcquireNow(1)) {
+                self.connRateLimitedTotal.incr();
+                return writeErr(writer, .rate_limited, "per-connection rate limit exceeded");
+            }
+        }
+        if (self.limiter) |*lim| {
+            if (!lim.tryAcquireNow(1)) {
+                self.rateLimitedTotal.incr();
+                return writeErr(writer, .rate_limited, "rate limit exceeded");
+            }
+        }
+
+        const op = protocol.Op.fromByte(frame.tag) catch {
+            return writeErr(writer, .bad_request, "unknown opcode");
+        };
+
+        if (self.authStore) |store| {
+            if (op == .auth) return self.handleAuth(store, frame.payload, writer, connRole, connExpiresAtNanos);
+            if (op == .auth_token) return self.handleAuthToken(frame.payload, writer, connRole, connExpiresAtNanos);
+            if (op != .ping) {
+                const role = connRole.* orelse {
+                    self.unauthorizedTotal.incr();
+                    return writeErr(writer, .unauthorized, "authentication required");
+                };
+                // A role survives only as long as its session does, when
+                // sessions are enabled: a session that expired since the
+                // last request on this same connection is treated exactly
+                // like never having authenticated at all, forcing a fresh
+                // `auth`/`auth_token` before anything else proceeds.
+                if (connExpiresAtNanos.*) |expiresAt| {
+                    if (std.time.nanoTimestamp() >= expiresAt) {
+                        connRole.* = null;
+                        connExpiresAtNanos.* = null;
+                        self.sessionExpiredTotal.incr();
+                        self.unauthorizedTotal.incr();
+                        return writeErr(writer, .unauthorized, "session expired");
+                    }
+                }
+                if (!role.atLeast(requiredRole(op, frame.payload))) {
+                    self.forbiddenTotal.incr();
+                    return writeErr(writer, .forbidden, "insufficient role for this operation");
+                }
+            }
+        }
+
+        // `subscribe`/`publish` never touch `db` - handled here, before
+        // `self.mutex` is ever taken, so neither one can be blocked behind
+        // (or block) a store read/write. `subscribe` in particular can hold
+        // this stack frame open for the entire remaining lifetime of the
+        // connection (see `handleSubscribe`'s doc comment), which would
+        // starve every other connection forever if it happened under
+        // `self.mutex`.
+        if (op == .subscribe) return self.handleSubscribe(frame.payload, stream);
+        if (op == .publish) return self.handlePublish(frame.payload, writer);
+        if (op == .unsubscribe) return self.handleUnsubscribe(frame.payload, writer);
+
+        self.mutex.lock();
+        defer self.mutex.unlock();
+
+        switch (op) {
+            .ping => try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "PONG"),
+
+            // Only reachable when `self.authStore == null` - a server with
+            // auth enabled answers `auth` requests in `handleAuth` above,
+            // before this switch is ever entered. A server with auth
+            // disabled has nothing to check credentials against, so it
+            // always accepts, matching every other opcode's "auth is
+            // simply not enforced" behavior on this server.
+            .auth => try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), ""),
+
+            // Only reachable when `self.authStore == null`, for the exact
+            // same reason as `.auth` above: a server without auth enabled
+            // has no notion of a session either, so it accepts any token
+            // unconditionally rather than ever consulting a session store.
+            .auth_token => try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), ""),
+
+            .get => {
+                const value = self.db.get(self.allocator, frame.payload) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                if (value) |v| {
+                    defer self.allocator.free(v);
+                    try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), v);
+                } else {
+                    try protocol.writeFrame(writer, @intFromEnum(protocol.Status.not_found), "");
+                }
+            },
+
+            .set => {
+                const args = protocol.decodeSet(frame.payload) catch {
+                    return writeErr(writer, .bad_request, "malformed set payload");
+                };
+                self.db.put(args.key, args.value) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .del => {
+                self.db.delete(frame.payload) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .scan => try self.handleScan(frame.payload, writer),
+            .prefix => try self.handlePrefix(frame.payload, writer),
+
+            .stats => {
+                const s = self.db.stats();
+                const payload = protocol.encodeStats(self.allocator, s) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(payload);
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), payload);
+            },
+
+            .flush => {
+                self.db.flush() catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .compact => {
+                self.db.compact() catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .batch => try self.handleBatch(frame.payload, writer),
+
+            .table_select => try self.handleTableSelect(frame.payload, writer),
+
+            .table_join => try self.handleTableJoin(frame.payload, writer),
+
+            .table_aggregate => try self.handleTableAggregate(frame.payload, writer),
+            .table_window => try self.handleTableWindow(frame.payload, writer),
+
+            // All three already handled and returned from above, before
+            // `self.mutex` was ever taken - never reached here.
+            .subscribe, .publish, .unsubscribe => unreachable,
+
+            .table_explain => try self.handleTableExplain(frame.payload, writer),
+
+            .table_update => try self.handleTableUpdate(frame.payload, writer),
+
+            .table_delete => try self.handleTableDelete(frame.payload, writer),
+
+            .table_export => try self.handleTableExport(frame.payload, writer),
+
+            .table_import => try self.handleTableImport(frame.payload, writer),
+
+            .user_admin => try self.handleUserAdmin(frame.payload, writer),
+
+            .metrics => try self.handleMetrics(writer),
+
+            .ttl_op => try self.handleTtlOp(frame.payload, writer),
+
+            .coll_ttl_op => try self.handleCollTtlOp(frame.payload, writer),
+
+            .coll_op => try self.handleCollOp(frame.payload, writer),
+
+            .txn_op => try self.handleTxnOp(frame.payload, writer),
+        }
+    }
+
+    /// Answers the `ttl_op` opcode: the network counterpart of the CLI's
+    /// local `expire`/`persist`/`ttl`/`expire-sweep` (main.zig), all backed
+    /// by the same `ttl.zig` functions the local commands call directly -
+    /// `query`/`sweep` were previously reachable only from a process that
+    /// had the `Db` open itself. `expire` mirrors the CLI's Redis-EXPIRE-
+    /// strict existence check (main.zig checks `db.get` before calling
+    /// `ttl.setExpireSeconds`; here the same check happens before the same
+    /// call) and answers `not_found` rather than `ok` when the key does not
+    /// currently exist, instead of the looser PEXPIREAT-like
+    /// `ttl.setExpireAt` that would silently accept it.
+    fn handleTtlOp(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTtlOp(payload) catch {
+            return writeErr(writer, .bad_request, "malformed ttl payload");
+        };
+        const now = std.time.nanoTimestamp();
+        switch (args.action) {
+            .expire => {
+                const existing = self.db.get(self.allocator, args.key) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                if (existing == null) return writeErr(writer, .not_found, "no such key");
+                self.allocator.free(existing.?);
+                ttlmod.setExpireSeconds(self.db, self.allocator, args.key, now, args.seconds) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+            .persist => {
+                ttlmod.clearExpire(self.db, self.allocator, args.key) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+            .query => {
+                const result = ttlmod.remaining(self.db, self.allocator, args.key, now) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                const respPayload = protocol.encodeTtlResult(self.allocator, result) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(respPayload);
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), respPayload);
+            },
+            .sweep => {
+                const reaped = ttlmod.sweepExpired(self.db, self.allocator, now) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                if (reaped > 0) self.ttlSweptTotal.incrBy(@intCast(reaped));
+                const respPayload = protocol.encodeTtlSweepCount(self.allocator, @intCast(reaped)) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(respPayload);
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), respPayload);
+            },
+        }
+    }
+
+    /// Answers the `coll_ttl_op` opcode: the network counterpart of the
+    /// CLI's local `coll <kind> expire|ttl|persist <name>`/`coll
+    /// expire-sweep` (main.zig), all backed by the same `collttl.zig`
+    /// functions the local commands call directly - same shape as
+    /// `handleTtlOp` above, but `expire`'s existence check is
+    /// `collections.collectionExists` (a whole namespace) instead of
+    /// `db.get` (one key), matching the CLI's own `coll <kind> expire`
+    /// check.
+    fn handleCollTtlOp(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeCollTtlOp(payload) catch {
+            return writeErr(writer, .bad_request, "malformed coll ttl payload");
+        };
+        const now = std.time.nanoTimestamp();
+        switch (args.action) {
+            .expire => {
+                const exists = collmod.collectionExists(self.db, self.allocator, args.kind, args.name) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                if (!exists) return writeErr(writer, .not_found, "no such collection");
+                collttlmod.setExpireSeconds(self.db, self.allocator, args.kind, args.name, now, args.seconds) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+            .persist => {
+                collttlmod.clearExpire(self.db, self.allocator, args.kind, args.name) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+            .query => {
+                const result = collttlmod.remaining(self.db, self.allocator, args.kind, args.name, now) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                const respPayload = protocol.encodeTtlResult(self.allocator, result) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(respPayload);
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), respPayload);
+            },
+            .sweep => {
+                const reaped = collttlmod.sweepExpired(self.db, self.allocator, now) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                if (reaped > 0) self.collTtlSweptTotal.incrBy(@intCast(reaped));
+                const respPayload = protocol.encodeTtlSweepCount(self.allocator, @intCast(reaped)) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(respPayload);
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), respPayload);
+            },
+        }
+    }
+
+    /// Answers the `coll_op` opcode: the network counterpart of the CLI's
+    /// local `coll <kind> <op> ...` (main.zig's `runColl`, backed by
+    /// `collections.zig`) - collections were previously reachable only from
+    /// a process holding the `Db` directly, the same gap `ttl_op`/
+    /// `coll_ttl_op` already closed for TTL management. Applies the same
+    /// lazy-expiry check `runColl` performs locally before every dispatch
+    /// (`collttl.expireIfDue` on the target name, plus `expireIfDueMany` on
+    /// the extra names of the three multi-set actions) so a collection
+    /// whose TTL is already due never appears alive over the wire either.
+    /// The actual per-action work lives in `dispatchCollOp` below; this
+    /// function only handles decode and the shared expiry check.
+    fn handleCollOp(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeCollOp(self.allocator, payload) catch {
+            return writeErr(writer, .bad_request, "malformed coll payload");
+        };
+        defer self.allocator.free(args.args);
+        const now = std.time.nanoTimestamp();
+        _ = collttlmod.expireIfDue(self.db, self.allocator, args.action.kind(), args.name, now) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        switch (args.action) {
+            .set_inter, .set_union, .set_diff => _ = collttlmod.expireIfDueMany(self.db, self.allocator, .set, args.args, now) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            },
+            else => {},
+        }
+        // Thirty actions each wrapping their own `db` call in a `catch |err|
+        // return writeErr(...)` (the pattern every other handler in this
+        // file uses) would triple the size of this function for no benefit
+        // over one shared boundary: `dispatchCollOp` uses plain `try` and
+        // two sentinel errors for malformed arguments, and this one catch
+        // maps both cases to the right status - the same information either
+        // way, just not repeated thirty times.
+        self.dispatchCollOp(args, writer) catch |err| return switch (err) {
+            error.InvalidArgCount, error.InvalidNumber => writeErr(writer, .bad_request, @errorName(err)),
+            else => writeErr(writer, .internal, @errorName(err)),
+        };
+    }
+
+    fn writeCollReply(self: *Server, writer: anytype, reply: protocol.CollReply) !void {
+        const respPayload = protocol.encodeCollReply(self.allocator, reply) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(respPayload);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), respPayload);
+    }
+
+    /// One arm per `protocol.CollAction`, each translating straight from
+    /// `args.args` (the CLI-text-form string arguments) into the matching
+    /// `collections.zig` call and back into a `protocol.CollReply` - the
+    /// exact same translation `main.zig`'s `runColl` already does for the
+    /// local CLI, just producing a wire reply instead of a printed line.
+    fn dispatchCollOp(self: *Server, args: protocol.CollOpArgs, writer: anytype) !void {
+        const a = args.args;
+        switch (args.action) {
+            .counter_get => {
+                const v = try collmod.Counter.get(self.db, self.allocator, args.name);
+                try self.writeCollReply(writer, .{ .int = v });
+            },
+            .counter_set => {
+                if (a.len < 1) return error.InvalidArgCount;
+                const v = std.fmt.parseInt(i64, a[0], 10) catch return error.InvalidNumber;
+                try collmod.Counter.set(self.db, self.allocator, args.name, v);
+                try self.writeCollReply(writer, .ok);
+            },
+            .counter_incrby => {
+                if (a.len < 1) return error.InvalidArgCount;
+                const delta = std.fmt.parseInt(i64, a[0], 10) catch return error.InvalidNumber;
+                const v = try collmod.Counter.incrBy(self.db, self.allocator, args.name, delta);
+                try self.writeCollReply(writer, .{ .int = v });
+            },
+            .hash_set => {
+                if (a.len < 2) return error.InvalidArgCount;
+                const created = try collmod.Hash.set(self.db, self.allocator, args.name, a[0], a[1]);
+                try self.writeCollReply(writer, .{ .int = if (created) 1 else 0 });
+            },
+            .hash_get => {
+                if (a.len < 1) return error.InvalidArgCount;
+                if (try collmod.Hash.get(self.db, self.allocator, args.name, a[0])) |v| {
+                    defer self.allocator.free(v);
+                    try self.writeCollReply(writer, .{ .bytes = v });
+                } else {
+                    try self.writeCollReply(writer, .nil);
+                }
+            },
+            .hash_del => {
+                if (a.len < 1) return error.InvalidArgCount;
+                const existed = try collmod.Hash.del(self.db, self.allocator, args.name, a[0]);
+                try self.writeCollReply(writer, .{ .int = if (existed) 1 else 0 });
+            },
+            .hash_len => {
+                const n = try collmod.Hash.len(self.db, self.allocator, args.name);
+                try self.writeCollReply(writer, .{ .int = @intCast(n) });
+            },
+            .hash_getall => {
+                const fields = try collmod.Hash.getAll(self.db, self.allocator, args.name);
+                defer {
+                    for (fields) |f| f.free(self.allocator);
+                    self.allocator.free(fields);
+                }
+                const pairs = try self.allocator.alloc(protocol.CollPair, fields.len);
+                defer self.allocator.free(pairs);
+                for (fields, 0..) |f, i| pairs[i] = .{ .field = f.field, .value = f.value };
+                try self.writeCollReply(writer, .{ .pairList = pairs });
+            },
+            .set_add => {
+                if (a.len < 1) return error.InvalidArgCount;
+                const added = try collmod.Set.add(self.db, self.allocator, args.name, a[0]);
+                try self.writeCollReply(writer, .{ .int = if (added) 1 else 0 });
+            },
+            .set_rem => {
+                if (a.len < 1) return error.InvalidArgCount;
+                const removed = try collmod.Set.remove(self.db, self.allocator, args.name, a[0]);
+                try self.writeCollReply(writer, .{ .int = if (removed) 1 else 0 });
+            },
+            .set_ismember => {
+                if (a.len < 1) return error.InvalidArgCount;
+                const is = try collmod.Set.isMember(self.db, self.allocator, args.name, a[0]);
+                try self.writeCollReply(writer, .{ .int = if (is) 1 else 0 });
+            },
+            .set_card => {
+                const n = try collmod.Set.card(self.db, self.allocator, args.name);
+                try self.writeCollReply(writer, .{ .int = @intCast(n) });
+            },
+            .set_members => {
+                const ms = try collmod.Set.members(self.db, self.allocator, args.name);
+                defer {
+                    for (ms) |m| self.allocator.free(m);
+                    self.allocator.free(ms);
+                }
+                try self.writeCollReply(writer, .{ .stringList = ms });
+            },
+            .set_inter, .set_union => |action| {
+                const names = try self.allocator.alloc([]const u8, a.len + 1);
+                defer self.allocator.free(names);
+                names[0] = args.name;
+                @memcpy(names[1..], a);
+                const ms = if (action == .set_inter)
+                    try collmod.Set.intersect(self.db, self.allocator, names)
+                else
+                    try collmod.Set.unionOf(self.db, self.allocator, names);
+                defer {
+                    for (ms) |m| self.allocator.free(m);
+                    self.allocator.free(ms);
+                }
+                try self.writeCollReply(writer, .{ .stringList = ms });
+            },
+            .set_diff => {
+                const ms = try collmod.Set.difference(self.db, self.allocator, args.name, a);
+                defer {
+                    for (ms) |m| self.allocator.free(m);
+                    self.allocator.free(ms);
+                }
+                try self.writeCollReply(writer, .{ .stringList = ms });
+            },
+            .list_lpush => {
+                if (a.len < 1) return error.InvalidArgCount;
+                try collmod.List.pushLeft(self.db, self.allocator, args.name, a[0]);
+                try self.writeCollReply(writer, .ok);
+            },
+            .list_rpush => {
+                if (a.len < 1) return error.InvalidArgCount;
+                try collmod.List.pushRight(self.db, self.allocator, args.name, a[0]);
+                try self.writeCollReply(writer, .ok);
+            },
+            .list_lpop => {
+                if (try collmod.List.popLeft(self.db, self.allocator, args.name)) |v| {
+                    defer self.allocator.free(v);
+                    try self.writeCollReply(writer, .{ .bytes = v });
+                } else {
+                    try self.writeCollReply(writer, .nil);
+                }
+            },
+            .list_rpop => {
+                if (try collmod.List.popRight(self.db, self.allocator, args.name)) |v| {
+                    defer self.allocator.free(v);
+                    try self.writeCollReply(writer, .{ .bytes = v });
+                } else {
+                    try self.writeCollReply(writer, .nil);
+                }
+            },
+            .list_len => {
+                const n = try collmod.List.len(self.db, self.allocator, args.name);
+                try self.writeCollReply(writer, .{ .int = @intCast(n) });
+            },
+            .list_range => {
+                if (a.len < 2) return error.InvalidArgCount;
+                const rangeStart = std.fmt.parseInt(i64, a[0], 10) catch return error.InvalidNumber;
+                const rangeStop = std.fmt.parseInt(i64, a[1], 10) catch return error.InvalidNumber;
+                const vals = try collmod.List.range(self.db, self.allocator, args.name, rangeStart, rangeStop);
+                defer {
+                    for (vals) |v| self.allocator.free(v);
+                    self.allocator.free(vals);
+                }
+                try self.writeCollReply(writer, .{ .stringList = vals });
+            },
+            .zset_add => {
+                if (a.len < 2) return error.InvalidArgCount;
+                const score = std.fmt.parseFloat(f64, a[1]) catch return error.InvalidNumber;
+                try collmod.ZSet.add(self.db, self.allocator, args.name, a[0], score);
+                try self.writeCollReply(writer, .ok);
+            },
+            .zset_score => {
+                if (a.len < 1) return error.InvalidArgCount;
+                if (try collmod.ZSet.score(self.db, self.allocator, args.name, a[0])) |s| {
+                    try self.writeCollReply(writer, .{ .real = s });
+                } else {
+                    try self.writeCollReply(writer, .nil);
+                }
+            },
+            .zset_incrby => {
+                if (a.len < 2) return error.InvalidArgCount;
+                const delta = std.fmt.parseFloat(f64, a[1]) catch return error.InvalidNumber;
+                const s = try collmod.ZSet.incrBy(self.db, self.allocator, args.name, a[0], delta);
+                try self.writeCollReply(writer, .{ .real = s });
+            },
+            .zset_rem => {
+                if (a.len < 1) return error.InvalidArgCount;
+                const removed = try collmod.ZSet.remove(self.db, self.allocator, args.name, a[0]);
+                try self.writeCollReply(writer, .{ .int = if (removed) 1 else 0 });
+            },
+            .zset_card => {
+                const n = try collmod.ZSet.card(self.db, self.allocator, args.name);
+                try self.writeCollReply(writer, .{ .int = @intCast(n) });
+            },
+            .zset_rangebyrank, .zset_rangebyscore => |action| {
+                if (a.len < 2) return error.InvalidArgCount;
+                const zms = if (action == .zset_rangebyrank) blk: {
+                    const rangeStart = std.fmt.parseInt(i64, a[0], 10) catch return error.InvalidNumber;
+                    const rangeStop = std.fmt.parseInt(i64, a[1], 10) catch return error.InvalidNumber;
+                    break :blk try collmod.ZSet.rangeByRank(self.db, self.allocator, args.name, rangeStart, rangeStop);
+                } else blk: {
+                    const min = std.fmt.parseFloat(f64, a[0]) catch return error.InvalidNumber;
+                    const max = std.fmt.parseFloat(f64, a[1]) catch return error.InvalidNumber;
+                    break :blk try collmod.ZSet.rangeByScore(self.db, self.allocator, args.name, min, max);
+                };
+                defer {
+                    for (zms) |zm| zm.free(self.allocator);
+                    self.allocator.free(zms);
+                }
+                const pairs = try self.allocator.alloc(protocol.CollScorePair, zms.len);
+                defer self.allocator.free(pairs);
+                for (zms, 0..) |zm, i| pairs[i] = .{ .member = zm.member, .score = zm.score };
+                try self.writeCollReply(writer, .{ .scorePairList = pairs });
+            },
+            .zset_rank => {
+                if (a.len < 1) return error.InvalidArgCount;
+                if (try collmod.ZSet.rank(self.db, self.allocator, args.name, a[0])) |r| {
+                    try self.writeCollReply(writer, .{ .int = @intCast(r) });
+                } else {
+                    try self.writeCollReply(writer, .nil);
+                }
+            },
+        }
+    }
+
+    /// Answers the `metrics` opcode: the network counterpart of the CLI's
+    /// `stats --prom` (which only ever renders `Db.stats()` locally) plus
+    /// this server's own request/rate-limit/auth/session counters from
+    /// `registerMetrics` - until now those counters were only ever
+    /// observable in-process, by a test holding a direct `*Server`
+    /// pointer. The registry is built fresh per request and thrown away
+    /// immediately after rendering: there is nothing to keep alive between
+    /// calls, since every counter it reads lives on `self` regardless.
+    fn handleMetrics(self: *Server, writer: anytype) !void {
+        var reg = metrics.Registry.init(self.allocator);
+        defer reg.deinit();
+        self.registerMetrics(&reg) catch |err| return writeErr(writer, .internal, @errorName(err));
+
+        var buf = std.ArrayList(u8).init(self.allocator);
+        defer buf.deinit();
+        reg.exportText(self.allocator, buf.writer()) catch |err| return writeErr(writer, .internal, @errorName(err));
+        metrics.formatDbStats(buf.writer(), "cobalt", self.db.stats()) catch |err| return writeErr(writer, .internal, @errorName(err));
+
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), buf.items);
+    }
+
+    /// Verifies credentials against `store` and, on success, stamps the
+    /// resulting role into this connection's `connRole` slot so every
+    /// subsequent request on the same connection is dispatched under it.
+    /// Locks `self.mutex` only around the actual `Db` read `verify`
+    /// performs, same as every other handler here.
+    fn handleAuth(self: *Server, store: authmod.Store, payload: []const u8, writer: anytype, connRole: *?authmod.Role, connExpiresAtNanos: *?i128) !void {
+        const args = protocol.decodeAuth(payload) catch {
+            return writeErr(writer, .bad_request, "malformed auth payload");
+        };
+
+        self.mutex.lock();
+        const result = store.verify(self.allocator, args.username, args.password);
+        self.mutex.unlock();
+
+        const role = result catch |err| {
+            self.unauthorizedTotal.incr();
+            return switch (err) {
+                error.InvalidCredentials, error.Malformed => writeErr(writer, .unauthorized, "invalid credentials"),
+                else => writeErr(writer, .internal, @errorName(err)),
+            };
+        };
+        connRole.* = role;
+        connExpiresAtNanos.* = null;
+
+        if (self.sessions) |store_| {
+            const now = std.time.nanoTimestamp();
+            const token = store_.issue(role, self.sessionTtlNanos, now) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            defer self.allocator.free(token);
+            connExpiresAtNanos.* = now + self.sessionTtlNanos;
+            const responsePayload = protocol.encodeAuthOk(self.allocator, token) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            defer self.allocator.free(responsePayload);
+            return protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), responsePayload);
+        }
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+    }
+
+    /// Authenticates a connection from a previously issued session token
+    /// instead of a username/password pair (see `enableSessions`). Only
+    /// reachable when `self.sessions` is set, since `dispatch` only routes
+    /// `auth_token` here while `self.authStore` is also set.
+    fn handleAuthToken(self: *Server, payload: []const u8, writer: anytype, connRole: *?authmod.Role, connExpiresAtNanos: *?i128) !void {
+        const store = self.sessions orelse {
+            self.unauthorizedTotal.incr();
+            return writeErr(writer, .unauthorized, "session tokens are not enabled on this server");
+        };
+        const token = protocol.decodeAuthToken(payload);
+        const session = store.validate(token, std.time.nanoTimestamp()) orelse {
+            self.unauthorizedTotal.incr();
+            return writeErr(writer, .unauthorized, "invalid or expired session token");
+        };
+        connRole.* = session.role;
+        connExpiresAtNanos.* = session.expiresAtNanos;
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+    }
+
+    fn handleScan(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeScan(payload) catch {
+            return writeErr(writer, .bad_request, "malformed scan payload");
+        };
+        var entries = std.ArrayList(dbmod.Entry).init(self.allocator);
+        defer entries.deinit();
+
+        if (args.reverse) {
+            var it = self.db.scanReverse(self.allocator, .{ .start = args.start, .end = args.end }) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            defer it.deinit();
+            while (try it.next()) |e| {
+                try entries.append(e);
+                if (args.limit != 0 and entries.items.len >= args.limit) break;
+            }
+        } else {
+            var it = self.db.scanRange(self.allocator, .{ .start = args.start, .end = args.end }) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            defer it.deinit();
+            while (try it.next()) |e| {
+                try entries.append(e);
+                if (args.limit != 0 and entries.items.len >= args.limit) break;
+            }
+        }
+
+        const out = protocol.encodeEntries(self.allocator, entries.items) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    fn handlePrefix(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodePrefix(payload) catch {
+            return writeErr(writer, .bad_request, "malformed prefix payload");
+        };
+        var it = self.db.scanPrefix(self.allocator, args.prefix) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer it.deinit();
+
+        var entries = std.ArrayList(dbmod.Entry).init(self.allocator);
+        defer entries.deinit();
+        while (try it.next()) |e| {
+            try entries.append(e);
+            if (args.limit != 0 and entries.items.len >= args.limit) break;
+        }
+
+        const out = protocol.encodeEntries(self.allocator, entries.items) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    fn handleBatch(self: *Server, payload: []const u8, writer: anytype) !void {
+        const ops = protocol.decodeBatch(self.allocator, payload) catch {
+            return writeErr(writer, .bad_request, "malformed batch payload");
+        };
+        defer self.allocator.free(ops);
+
+        var wb = dbmod.WriteBatch.init(self.allocator);
+        defer wb.deinit();
+        for (ops) |op| {
+            switch (op) {
+                .put => |kv| try wb.put(kv.key, kv.value),
+                .del => |key| try wb.delete(key),
+            }
+        }
+        self.db.apply(&wb) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+    }
+
+    /// Executes a `txn_op` request: the network counterpart of the CLI's
+    /// local `txn <script-file>` (main.zig's `runTxn`), applying every
+    /// put/delete in `entries` as one atomic `Transaction` commit across
+    /// however many tables they touch. Runs entirely inside `dispatch`'s
+    /// single `self.mutex` acquisition, like every other opcode - which
+    /// means, unlike a raw multi-thread `Transaction` against an unguarded
+    /// `*Db` (see `concurrent.zig`'s `GuardedDb` doc comment), no other
+    /// connection's request can ever interleave between this transaction's
+    /// begin and its commit. `txn.commit()`'s OCC conflict check stays in
+    /// place and still maps to `Status.conflict` below, but under this
+    /// server's locking discipline nothing can actually trigger it for a
+    /// request that arrives, stages, and commits within one dispatch call -
+    /// the same reason `concurrent.zig`'s `TableTransferWorker` test treats
+    /// a real `error.Conflict` under `GuardedDb.acquire()` as a bug, not an
+    /// expected outcome.
+    fn handleTxnOp(self: *Server, payload: []const u8, writer: anytype) !void {
+        const entries = protocol.decodeTxnOp(self.allocator, payload) catch {
+            return writeErr(writer, .bad_request, "malformed txn_op payload");
+        };
+        defer self.allocator.free(entries);
+        if (entries.len == 0) return writeErr(writer, .bad_request, "txn_op requires at least one operation");
+
+        var txn = txnmod.Transaction.begin(self.db);
+        defer txn.deinit();
+
+        var tables = std.StringHashMap(txntablemod.TableTxn).init(self.allocator);
+        defer {
+            var it = tables.valueIterator();
+            while (it.next()) |t| t.deinit();
+            tables.deinit();
+        }
+
+        for (entries) |e| {
+            const gop = tables.getOrPut(e.table) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            if (!gop.found_existing) {
+                gop.value_ptr.* = txntablemod.TableTxn.open(&txn, self.allocator, e.table) catch |err| {
+                    return writeErr(writer, .bad_request, @errorName(err));
+                };
+                gop.key_ptr.* = e.table;
+            }
+            const table = gop.value_ptr;
+
+            const pk = rowmod.decodeValue(self.allocator, e.pkBytes) catch {
+                return writeErr(writer, .bad_request, "malformed primary key");
+            };
+            defer pk.free(self.allocator);
+
+            switch (e.verb) {
+                .put => {
+                    var fieldsRow = rowmod.Row.decode(self.allocator, e.fieldsBytes) catch {
+                        return writeErr(writer, .bad_request, "malformed fields");
+                    };
+                    defer fieldsRow.deinit();
+                    table.put(pk, fieldsRow.fields.items) catch |err| {
+                        return writeErr(writer, .internal, @errorName(err));
+                    };
+                },
+                .del => {
+                    table.delete(pk) catch |err| {
+                        return writeErr(writer, .internal, @errorName(err));
+                    };
+                },
+            }
+        }
+
+        txn.commit() catch |err| {
+            return switch (err) {
+                error.Conflict => writeErr(writer, .conflict, "transaction conflict"),
+                else => writeErr(writer, .internal, @errorName(err)),
+            };
+        };
+
+        const out = protocol.encodeTxnResult(self.allocator, @intCast(entries.len)) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `table select <table> [expr]` remotely: opens the named
+    /// table over the same `*Db` the rest of the server serves (so it sees
+    /// exactly the indexes/rows a local CLI `table` command would), parses
+    /// the expression text with the same `expr.zig` grammar the CLI uses
+    /// (empty text means "every row", matching `Table.select(null)`), and
+    /// wire-encodes the resulting rows. `args.orderBy`, when present, is
+    /// forwarded to `Table.selectPageOrdered` so the offset/limit window
+    /// applies AFTER sorting, exactly like the local `table select
+    /// --order-by` CLI path - `null` falls through to the plain
+    /// `selectPage` early-stop behavior instead. A bad table name or
+    /// malformed expression is a client mistake (`bad_request`), not a
+    /// server fault.
+    fn handleTableSelect(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableSelect(self.allocator, payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_select payload");
+        };
+        defer self.allocator.free(args.orderBy);
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (args.exprText.len > 0) {
+            parsed = exprmod.parse(self.allocator, args.exprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const rows = table.selectPageOrdered(pred, .{ .offset = args.offset, .limit = args.limit }, args.orderBy) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer querymod.freeRows(self.allocator, rows);
+
+        const out = protocol.encodeRows(self.allocator, rows) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `table_join` request against `join.zig`'s four equi-join
+    /// variants, chosen by `args.mode` - the network counterpart of the
+    /// CLI's local `table join [--left|--right|--full]`. Each variant
+    /// produces its own result type (`JoinedRow`/`OuterJoinedRow`/
+    /// `RightOuterJoinedRow`/`FullOuterJoinedRow`), but every one of them is
+    /// just two optional `Row`s under the hood, so this flattens whichever
+    /// one came back into `protocol.JoinPair` before encoding - one wire
+    /// format for all four modes, exactly like `coll_op` bundles thirty
+    /// collection actions behind one opcode instead of thirty. Ownership of
+    /// each row is moved (by value) from the mode-specific slice into
+    /// `pairs`, then that mode-specific slice is freed as a raw allocation
+    /// (not through `join.freeJoined`/`freeOuterJoined`/etc, which would
+    /// double-deinit rows already moved into `pairs`) - `pairs`'s own defer
+    /// is what actually frees the row contents, once encoding is done.
+    /// `args.offset`/`args.limit` window the mode-specific slice through
+    /// `join.applyPage` right after it comes back, before the flatten -
+    /// `applyPage` already frees the pre-page slice and hands back a fresh
+    /// one, so the pattern below frees `paged`, never `joined` directly.
+    fn handleTableJoin(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableJoin(payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_join payload");
+        };
+
+        var left = querymod.Table.open(self.db, self.allocator, args.leftTable) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer left.deinit();
+        var right = querymod.Table.open(self.db, self.allocator, args.rightTable) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer right.deinit();
+
+        var leftParsed: ?exprmod.Parsed = null;
+        defer if (leftParsed) |*p| p.deinit();
+        if (args.leftExprText.len > 0) {
+            leftParsed = exprmod.parse(self.allocator, args.leftExprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const leftPred: ?querymod.Predicate = if (leftParsed) |p| p.predicate else null;
+
+        var rightParsed: ?exprmod.Parsed = null;
+        defer if (rightParsed) |*p| p.deinit();
+        if (args.rightExprText.len > 0) {
+            rightParsed = exprmod.parse(self.allocator, args.rightExprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const rightPred: ?querymod.Predicate = if (rightParsed) |p| p.predicate else null;
+
+        var pairs = std.ArrayList(protocol.JoinPair).init(self.allocator);
+        defer {
+            for (pairs.items) |*p| {
+                if (p.left) |*l| l.deinit();
+                if (p.right) |*r| r.deinit();
+            }
+            pairs.deinit();
+        }
+
+        const page = querymod.Page{ .offset = args.offset, .limit = args.limit };
+
+        switch (args.mode) {
+            .inner => {
+                const joined = joinmod.innerJoin(self.allocator, &left, args.leftField, leftPred, &right, args.rightField, rightPred) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                const paged = joinmod.applyPage(joinmod.JoinedRow, self.allocator, joined, page) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(paged);
+                for (paged) |p| try pairs.append(.{ .left = p.left, .right = p.right });
+            },
+            .left => {
+                const joined = joinmod.leftOuterJoin(self.allocator, &left, args.leftField, leftPred, &right, args.rightField, rightPred) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                const paged = joinmod.applyPage(joinmod.OuterJoinedRow, self.allocator, joined, page) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(paged);
+                for (paged) |p| try pairs.append(.{ .left = p.left, .right = p.right });
+            },
+            .right => {
+                const joined = joinmod.rightOuterJoin(self.allocator, &left, args.leftField, leftPred, &right, args.rightField, rightPred) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                const paged = joinmod.applyPage(joinmod.RightOuterJoinedRow, self.allocator, joined, page) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(paged);
+                for (paged) |p| try pairs.append(.{ .left = p.left, .right = p.right });
+            },
+            .full => {
+                const joined = joinmod.fullOuterJoin(self.allocator, &left, args.leftField, leftPred, &right, args.rightField, rightPred) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                const paged = joinmod.applyPage(joinmod.FullOuterJoinedRow, self.allocator, joined, page) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(paged);
+                for (paged) |p| try pairs.append(.{ .left = p.left, .right = p.right });
+            },
+        }
+
+        const out = protocol.encodeJoinedRows(self.allocator, pairs.items) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `table_aggregate` request: opens the named table over the
+    /// same `*Db` the rest of the server serves, filters rows with the same
+    /// `expr.zig` grammar `table_select`/`table_join` already use (empty
+    /// text selects every row), then hands the filtered rows to
+    /// `aggregate.zig` - `runGlobal` when `args.groupField` is empty (the
+    /// network counterpart of the CLI's `*` sentinel for "no GROUP BY"),
+    /// `run` otherwise. When `args.havingText` is non-empty, it is parsed
+    /// with the same `expr.zig` grammar and applied AFTER aggregation but
+    /// BEFORE paging - `globalMatchesHaving` on the `runGlobal` path (an
+    /// excluded single result comes back as zero values, not an error) or
+    /// `filterHaving` on the grouped path - then, on the grouped path only,
+    /// a non-empty `args.orderBy` sorts the HAVING-narrowed groups via
+    /// `aggregate.sortGroupsBy` (an unknown order field is `bad_request`,
+    /// same treatment as a malformed HAVING expr) - then windowed by
+    /// `args.offset`/`args.limit` through `aggregate.applyPageGroups` (0/0 =
+    /// unlimited, ignored for the `runGlobal` path since that always
+    /// produces at most one result row, same as `args.orderBy`). Two distinct wire shapes come back
+    /// (`encodeAggGlobalResult` vs `encodeAggGroupRows`) because the client
+    /// already knows which one it asked for (it is the one that chose
+    /// `groupField`), so no extra discriminator byte is needed on the wire -
+    /// the client just decodes with whichever matches its own request, the
+    /// same reasoning `Client.tableAggregateGlobal`/`tableAggregateGroups`
+    /// document. A bad table name, malformed expr, or a spec referencing a
+    /// non-numeric field (`error.NonNumericField`/`error.Overflow` from
+    /// `aggregate.zig`) is a client mistake (`bad_request`), not a server
+    /// fault.
+    fn handleTableAggregate(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableAggregate(self.allocator, payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_aggregate payload");
+        };
+        defer self.allocator.free(args.specs);
+        defer self.allocator.free(args.orderBy);
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (args.exprText.len > 0) {
+            parsed = exprmod.parse(self.allocator, args.exprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        var havingParsed: ?exprmod.Parsed = null;
+        defer if (havingParsed) |*p| p.deinit();
+        if (args.havingText.len > 0) {
+            havingParsed = exprmod.parse(self.allocator, args.havingText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const havingPred: ?querymod.Predicate = if (havingParsed) |p| p.predicate else null;
+
+        const rows = table.select(pred) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer querymod.freeRows(self.allocator, rows);
+
+        if (args.groupField.len == 0) {
+            const values = aggregatemod.runGlobal(self.allocator, rows, args.specs) catch |err| {
+                return switch (err) {
+                    error.NonNumericField, error.Overflow => writeErr(writer, .bad_request, @errorName(err)),
+                    else => writeErr(writer, .internal, @errorName(err)),
+                };
+            };
+            defer aggregatemod.freeGlobalResult(self.allocator, values);
+            const matches = if (havingPred) |hp|
+                aggregatemod.globalMatchesHaving(self.allocator, args.specs, values, hp) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                }
+            else
+                true;
+            const out = protocol.encodeAggGlobalResult(self.allocator, if (matches) values else &.{}) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            defer self.allocator.free(out);
+            try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+        } else {
+            const unpaged = aggregatemod.run(self.allocator, rows, args.groupField, args.specs) catch |err| {
+                return switch (err) {
+                    error.NonNumericField, error.Overflow => writeErr(writer, .bad_request, @errorName(err)),
+                    else => writeErr(writer, .internal, @errorName(err)),
+                };
+            };
+            const filtered = if (havingPred) |hp|
+                aggregatemod.filterHaving(self.allocator, unpaged, args.groupField, args.specs, hp) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                }
+            else
+                unpaged;
+            if (args.orderBy.len > 0) {
+                aggregatemod.sortGroupsBy(self.allocator, filtered, args.groupField, args.specs, args.orderBy) catch |err| {
+                    protocol.freeAggGroupRows(self.allocator, filtered);
+                    return switch (err) {
+                        error.UnknownOrderField => writeErr(writer, .bad_request, @errorName(err)),
+                        else => writeErr(writer, .internal, @errorName(err)),
+                    };
+                };
+            }
+            const page = querymod.Page{ .offset = args.offset, .limit = args.limit };
+            const groups = aggregatemod.applyPageGroups(self.allocator, filtered, page) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            defer protocol.freeAggGroupRows(self.allocator, groups);
+            const out = protocol.encodeAggGroupRows(self.allocator, groups) catch |err| {
+                return writeErr(writer, .internal, @errorName(err));
+            };
+            defer self.allocator.free(out);
+            try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+        }
+    }
+
+    /// Executes a `table_window` request: opens the named table, filters
+    /// rows with the same `expr.zig` grammar every other `table_*` opcode
+    /// uses (empty text selects every row), then hands the filtered rows to
+    /// `window.compute` for the single `args.spec` annotation, along with
+    /// `args.frame` (ROWS or RANGE - see `window.zig`'s `FrameMode` doc
+    /// comment) - unlike `table_aggregate`, this NEVER collapses rows, so
+    /// `results[i]` stays aligned 1:1 with `rows[i]` regardless of paging (a
+    /// `NonNumericField`/`Overflow`/`MissingField`/`RangeNotApplicable` from
+    /// `window.zig` is a client mistake, `bad_request`, same treatment as
+    /// `table_aggregate`).
+    /// `args.offset`/`args.limit` then window which rows get PRINTED, walked
+    /// in `window.orderedIndices`' partition-then-order sequence (the same
+    /// display order local `table window` uses, not raw scan order) rather
+    /// than slicing `rows`/`results` directly - the exact bug local `table
+    /// window` hit and fixed (see `window.zig`'s `orderedIndices` doc
+    /// comment) before this network path existed, so it is built paginated
+    /// the correct way from the start instead of repeating that mistake.
+    /// Each surviving row is paired with its already-computed value into a
+    /// `protocol.WindowRow` and sent back via `encodeWindowRows` - the
+    /// client prints them in the order received, no further sorting needed.
+    /// A `subscribe` request never returns in the normal sense: once the
+    /// connection is registered in `self.pubsub`, this function owns the
+    /// rest of the connection's lifetime (both directions of the socket)
+    /// until the client disconnects, then propagates `error.SubscriptionEnded`
+    /// so `handleConnection`'s `catch return` unwinds cleanly - the same
+    /// "any error just ends the connection" contract every other opcode
+    /// already relies on for a plain disconnect mid-frame.
+    ///
+    /// Design: a `subscribe` connection becomes receive-only after the ack.
+    /// A dedicated watcher thread does exactly one blocking read attempt on
+    /// `stream` - whatever it gets back (a byte the client sent, or an
+    /// error/EOF from a disconnect) closes the subscription, since there is
+    /// no way to both keep reading further commands AND push messages on
+    /// one TCP connection without either a second concurrent writer (a
+    /// write race against the push loop below) or re-entering this same
+    /// read/dispatch loop (a read race against the watcher). Unlike a
+    /// protocol like Redis's, which multiplexes further commands
+    /// (UNSUBSCRIBE, PING) onto the same subscribed connection, this
+    /// connection itself never reads another request - but `unsubscribe`
+    /// (see `handleUnsubscribe`) reaches the SAME `sub` from a completely
+    /// different connection, keyed by the id this function's ack carries
+    /// (`sub.id`), so dropping a subset of channels still does not require
+    /// closing the connection outright; only dropping every remaining
+    /// channel does (`pubsub.Hub.unsubscribe`'s doc comment). Once the push loop ends (for any reason - the
+    /// watcher closed `sub`, or a write here failed because the peer is
+    /// gone), `std.posix.shutdown` unblocks the watcher's still-pending read
+    /// (rather than relying on `conn.stream.close()` racing a live read on
+    /// the same fd from another thread, which is a well-known way to
+    /// recycle a file descriptor into an unrelated, concurrently-accepted
+    /// connection) before joining it - so by the time this returns, no
+    /// other thread still touches `stream` or `sub`.
+    fn handleSubscribe(self: *Server, payload: []const u8, stream: std.net.Stream) !void {
+        const args = protocol.decodeSubscribe(self.allocator, payload) catch {
+            return writeErr(stream.writer(), .bad_request, "malformed subscribe payload");
+        };
+        defer args.deinit(self.allocator);
+        if (args.channels.len == 0) {
+            return writeErr(stream.writer(), .bad_request, "subscribe needs at least one channel");
+        }
+
+        const channelNames = try self.allocator.alloc([]const u8, args.channels.len);
+        defer self.allocator.free(channelNames);
+        for (args.channels, 0..) |c, i| channelNames[i] = c;
+
+        const sub = self.pubsub.subscribe(channelNames, pubsubmod.defaultCapacity) catch {
+            return writeErr(stream.writer(), .internal, "failed to register subscription");
+        };
+
+        const ack = try protocol.encodeSubscribeAck(self.allocator, sub.id, @intCast(channelNames.len));
+        defer self.allocator.free(ack);
+        protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Status.ok), ack) catch {
+            self.pubsub.closeSubscriber(sub);
+            self.pubsub.destroySubscriber(sub);
+            return error.SubscriptionEnded;
+        };
+
+        const watcher = try std.Thread.spawn(.{}, watchForDisconnect, .{ &self.pubsub, sub, stream });
+
+        while (sub.waitMessage()) |msg| {
+            defer msg.deinit(self.allocator);
+            const framePayload = protocol.encodePubSubMessage(self.allocator, msg.channel, msg.payload) catch break;
+            defer self.allocator.free(framePayload);
+            protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Status.ok), framePayload) catch break;
+        }
+
+        std.posix.shutdown(stream.handle, .both) catch {};
+        watcher.join();
+        self.pubsub.closeSubscriber(sub);
+        self.pubsub.destroySubscriber(sub);
+        return error.SubscriptionEnded;
+    }
+
+    /// The watcher half of `handleSubscribe`: blocks on exactly one read
+    /// attempt, then closes `sub` regardless of the outcome (data, EOF, or
+    /// an error - all three mean "stop pushing to this connection"). Runs
+    /// on its own thread so `handleSubscribe`'s push loop can block
+    /// independently on `sub.waitMessage()` - see that function's doc
+    /// comment for why this is a single read, not a loop.
+    fn watchForDisconnect(hub: *pubsubmod.Hub, sub: *pubsubmod.Subscriber, stream: std.net.Stream) void {
+        var buf: [1]u8 = undefined;
+        _ = stream.read(&buf) catch {};
+        hub.closeSubscriber(sub);
+    }
+
+    /// Executes a `publish` request: any connection may call this
+    /// regardless of whether it has ever subscribed to anything (see
+    /// `protocol.encodePublish`'s doc comment). Delivery is fire-and-forget
+    /// from this handler's point of view - `pubsub.Hub.publish` never
+    /// blocks on a slow subscriber, so this returns as soon as every
+    /// currently-registered subscriber's mailbox has been handed its own
+    /// copy (or dropped one, under `Subscriber.push`'s backpressure policy).
+    fn handlePublish(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodePublish(payload) catch {
+            return writeErr(writer, .bad_request, "malformed publish payload");
+        };
+        const count = self.pubsub.publish(self.allocator, args.channel, args.message) catch {
+            return writeErr(writer, .internal, "failed to publish message");
+        };
+        if (count > 0) self.messagesPublishedTotal.incrBy(@intCast(count));
+        const resp = try protocol.encodePublishResult(self.allocator, @intCast(count));
+        defer self.allocator.free(resp);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), resp);
+    }
+
+    /// Executes an `unsubscribe` request: unlike `subscribe`, this is a
+    /// plain request/response opcode that returns like any other - it never
+    /// touches the connection that originally subscribed, because that
+    /// connection became receive-only the moment its ack arrived (see
+    /// `handleSubscribe`'s doc comment) and this one is always a separate
+    /// connection entirely (see `protocol.encodeUnsubscribe`'s doc
+    /// comment). `pubsub.Hub.unsubscribe`'s `error.UnknownSubscriber` (a
+    /// stale id, a typo, or a subscriber that already disconnected on its
+    /// own - all indistinguishable from here, see that function's doc
+    /// comment) is the caller's mistake, `bad_request`, the same treatment
+    /// `table_window` gives a `MissingField` from a bad field name.
+    fn handleUnsubscribe(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeUnsubscribe(self.allocator, payload) catch {
+            return writeErr(writer, .bad_request, "malformed unsubscribe payload");
+        };
+        defer args.deinit(self.allocator);
+        if (args.channels.len == 0) {
+            return writeErr(writer, .bad_request, "unsubscribe needs at least one channel");
+        }
+
+        const channelNames = try self.allocator.alloc([]const u8, args.channels.len);
+        defer self.allocator.free(channelNames);
+        for (args.channels, 0..) |c, i| channelNames[i] = c;
+
+        const removed = self.pubsub.unsubscribe(args.subscriberId, channelNames) catch |err| {
+            return switch (err) {
+                error.UnknownSubscriber => writeErr(writer, .bad_request, "unknown subscriber id"),
+                else => writeErr(writer, .internal, @errorName(err)),
+            };
+        };
+
+        const resp = try protocol.encodeUnsubscribeResult(self.allocator, @intCast(removed));
+        defer self.allocator.free(resp);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), resp);
+    }
+
+    fn handleTableWindow(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableWindow(self.allocator, payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_window payload");
+        };
+        defer self.allocator.free(args.specs);
+        defer self.allocator.free(args.partitionBy);
+        defer self.allocator.free(args.orderBy);
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (args.exprText.len > 0) {
+            parsed = exprmod.parse(self.allocator, args.exprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const rows = table.select(pred) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer querymod.freeRows(self.allocator, rows);
+
+        const results = windowmod.computeMany(self.allocator, rows, args.partitionBy, args.orderBy, args.specs, args.frame) catch |err| {
+            return switch (err) {
+                error.NonNumericField, error.Overflow, error.MissingField, error.RangeNotApplicable => writeErr(writer, .bad_request, @errorName(err)),
+                else => writeErr(writer, .internal, @errorName(err)),
+            };
+        };
+        defer windowmod.freeManyResults(self.allocator, results);
+
+        const displayOrder = windowmod.orderedIndices(self.allocator, rows, args.partitionBy, args.orderBy) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(displayOrder);
+
+        const total = displayOrder.len;
+        const pageStart = @min(args.offset, total);
+        const end = if (args.limit == 0) total else @min(pageStart + args.limit, total);
+
+        // `out`'s WindowRow.values arrays hold SHALLOW copies borrowed from
+        // `results` (safe: `encodeWindowRows` below only reads them to
+        // serialize, never frees them) - `results` stays the true owner,
+        // freed by the `defer` above; only the borrowing arrays themselves
+        // get freed here, same "shallow copy into a throwaway wire-shape
+        // struct, one true owner frees the contents" pattern
+        // `handleTableAggregate`'s `GroupRow`-to-wire path already relies on.
+        var out = std.ArrayList(protocol.WindowRow).init(self.allocator);
+        defer {
+            for (out.items) |wr| self.allocator.free(wr.values);
+            out.deinit();
+        }
+        var i: usize = pageStart;
+        while (i < end) : (i += 1) {
+            const idx = displayOrder[i];
+            const values = try self.allocator.alloc(rowmod.Value, args.specs.len);
+            @memcpy(values, results[idx]);
+            try out.append(.{ .row = rows[idx], .values = values });
+        }
+
+        const encoded = protocol.encodeWindowRows(self.allocator, out.items) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(encoded);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), encoded);
+    }
+
+    /// Executes a `table_explain` request: opens the named table over the
+    /// same `*Db` the rest of the server serves, parses the expr text with
+    /// the same grammar `table_select`/`table_join`/`table_aggregate`
+    /// already use, then reports which strategy `querymod.Table.explain`
+    /// says a matching `table select`/`table_select` would take - without
+    /// running the query or touching any row. A bad table name or malformed
+    /// expression is a client mistake (`bad_request`), not a server fault.
+    fn handleTableExplain(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableExplain(payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_explain payload");
+        };
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (args.exprText.len > 0) {
+            parsed = exprmod.parse(self.allocator, args.exprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        var plan = table.explain(self.allocator, pred) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer plan.deinit(self.allocator);
+
+        const out = protocol.encodePlan(self.allocator, plan) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `table_update` request: the network counterpart of the
+    /// CLI's local `table update <table> --set ... [expr...]`, running
+    /// `query.Table.updateWhere` against the server's `*Db`. The wire
+    /// `sets` field list arrives pre-encoded with `Row.encode` (the same
+    /// trick `decodeTxnOp`'s `fieldsBytes` uses), so it is decoded into a
+    /// real `Row` here before `updateWhere` ever sees it. The response is a
+    /// bare row count reusing `encodeTtlSweepCount`'s u64 wire shape - the
+    /// same "no new response type, an existing shape already fits"
+    /// precedent `coll_ttl_op` set for `ttl_op`'s result encoding.
+    fn handleTableUpdate(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableUpdate(payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_update payload");
+        };
+
+        var setsRow = rowmod.Row.decode(self.allocator, args.setsBytes) catch {
+            return writeErr(writer, .bad_request, "malformed table_update set fields");
+        };
+        defer setsRow.deinit();
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (args.exprText.len > 0) {
+            parsed = exprmod.parse(self.allocator, args.exprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const updated = table.updateWhere(pred, setsRow.fields.items) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+
+        const out = protocol.encodeTtlSweepCount(self.allocator, @intCast(updated)) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `table_delete` request: the network counterpart of the
+    /// CLI's local `table delete <table> [expr...]`, running
+    /// `query.Table.deleteWhere` against the server's `*Db`. Same wire shape
+    /// as `table_explain` (table + exprText, no `SET` clause) and same
+    /// response shape as `table_update` (a bare row count reusing
+    /// `encodeTtlSweepCount`'s u64 wire shape).
+    fn handleTableDelete(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableDelete(payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_delete payload");
+        };
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        var parsed: ?exprmod.Parsed = null;
+        defer if (parsed) |*p| p.deinit();
+        if (args.exprText.len > 0) {
+            parsed = exprmod.parse(self.allocator, args.exprText) catch |err| {
+                return writeErr(writer, .bad_request, @errorName(err));
+            };
+        }
+        const pred: ?querymod.Predicate = if (parsed) |p| p.predicate else null;
+
+        const deleted = table.deleteWhere(pred) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+
+        const out = protocol.encodeTtlSweepCount(self.allocator, @intCast(deleted)) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `table_export` request: the network counterpart of the
+    /// CLI's local `table export <table> csv|json <path>`, rendering the
+    /// whole table through `dump.zig`'s `exportCsvWriter`/`exportJsonWriter`
+    /// (the same functions the local path calls, just pointed at an
+    /// in-memory `ArrayList` writer instead of a file, since there is no
+    /// filesystem path to write to on the server side of a request) and
+    /// sending the row count plus the rendered bytes back in one frame.
+    fn handleTableExport(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableExport(payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_export payload");
+        };
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        var buf = std.ArrayList(u8).init(self.allocator);
+        defer buf.deinit();
+        const rowCount = switch (args.format) {
+            .csv => dumpmod.exportCsvWriter(self.allocator, &table, buf.writer()),
+            .json => dumpmod.exportJsonWriter(self.allocator, &table, buf.writer()),
+        } catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+
+        const out = protocol.encodeExportResult(self.allocator, @intCast(rowCount), buf.items) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `table_import` request: the network counterpart of the
+    /// CLI's local `table import <table> csv|json <path>`, feeding the
+    /// wire-carried `content` bytes straight into `dump.zig`'s
+    /// `importCsvContent`/`importJsonContent` (the same functions the local
+    /// path calls after reading a file into memory - the client already did
+    /// that reading, so the server only ever sees bytes, never a path)
+    /// against the server's `*Db`. The response is a bare row count, the
+    /// same u64 wire shape `table_update`/`table_delete` already use.
+    fn handleTableImport(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeTableImport(payload) catch {
+            return writeErr(writer, .bad_request, "malformed table_import payload");
+        };
+
+        var table = querymod.Table.open(self.db, self.allocator, args.table) catch |err| {
+            return writeErr(writer, .bad_request, @errorName(err));
+        };
+        defer table.deinit();
+
+        const imported = switch (args.format) {
+            .csv => dumpmod.importCsvContent(self.allocator, &table, args.content),
+            .json => dumpmod.importJsonContent(self.allocator, &table, args.content),
+        } catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+
+        const out = protocol.encodeTtlSweepCount(self.allocator, @intCast(imported)) catch |err| {
+            return writeErr(writer, .internal, @errorName(err));
+        };
+        defer self.allocator.free(out);
+        try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+    }
+
+    /// Executes a `user_admin` request (create/set_password/set_role/delete/
+    /// list) against a fresh `authmod.Store` over the same `*Db` the rest of
+    /// the server serves. Deliberately does NOT consult `self.authStore` -
+    /// that field only controls whether *login enforcement* is turned on
+    /// for this server, not whether the user table exists, so remote user
+    /// management works the same way whether or not `--auth` is active.
+    /// `requiredRole` already gates this opcode behind `admin` whenever
+    /// auth enforcement IS enabled; a server with auth disabled enforces
+    /// nothing on any opcode, this one included, matching every other op's
+    /// documented behavior.
+    fn handleUserAdmin(self: *Server, payload: []const u8, writer: anytype) !void {
+        const args = protocol.decodeUserAdmin(payload) catch {
+            return writeErr(writer, .bad_request, "malformed user_admin payload");
+        };
+        const store = authmod.Store.init(self.db);
+
+        switch (args.action) {
+            .create => {
+                const role = authmod.Role.fromByte(args.roleByte) catch {
+                    return writeErr(writer, .bad_request, "invalid role");
+                };
+                const rounds = if (args.rounds != 0) args.rounds else authmod.recommendedRounds;
+                store.createUser(self.allocator, args.username, args.password, role, rounds) catch |err| {
+                    return switch (err) {
+                        error.UserExists => writeErr(writer, .conflict, "user already exists"),
+                        else => writeErr(writer, .internal, @errorName(err)),
+                    };
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .set_password => {
+                const rounds = if (args.rounds != 0) args.rounds else authmod.recommendedRounds;
+                store.setPassword(self.allocator, args.username, args.password, rounds) catch |err| {
+                    return switch (err) {
+                        error.UserNotFound => writeErr(writer, .not_found, "user not found"),
+                        else => writeErr(writer, .internal, @errorName(err)),
+                    };
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .set_role => {
+                const role = authmod.Role.fromByte(args.roleByte) catch {
+                    return writeErr(writer, .bad_request, "invalid role");
+                };
+                store.setRole(self.allocator, args.username, role) catch |err| {
+                    return switch (err) {
+                        error.UserNotFound => writeErr(writer, .not_found, "user not found"),
+                        else => writeErr(writer, .internal, @errorName(err)),
+                    };
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .delete => {
+                store.deleteUser(self.allocator, args.username) catch |err| {
+                    return switch (err) {
+                        error.UserNotFound => writeErr(writer, .not_found, "user not found"),
+                        else => writeErr(writer, .internal, @errorName(err)),
+                    };
+                };
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), "");
+            },
+
+            .list => {
+                const users = store.listUsers(self.allocator) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer authmod.freeUserList(self.allocator, users);
+                const out = protocol.encodeUserList(self.allocator, users) catch |err| {
+                    return writeErr(writer, .internal, @errorName(err));
+                };
+                defer self.allocator.free(out);
+                try protocol.writeFrame(writer, @intFromEnum(protocol.Status.ok), out);
+            },
+        }
+    }
+
+    /// Stops accepting new connections and waits for the accept loop to
+    /// exit. Closing the listening socket while another thread is
+    /// blocked inside `accept()` on that same fd is a race the standard
+    /// library treats as a bug (it asserts on EBADF), so instead we flip
+    /// `stopping` and connect a throwaway client to our own listen
+    /// address: that wakes the pending `accept()` with a real, briefly
+    /// alive connection, which the loop then discards and exits on. Only
+    /// once the accept thread has rejoined is it safe to close the
+    /// listening socket itself.
+    ///
+    /// Already-accepted connections are `.detach()`ed worker threads this
+    /// struct holds no `std.Thread` handle for, so they cannot be `join`ed
+    /// directly - `drainConnections` below waits on the `active` counter
+    /// instead. This used to be entirely the caller's problem ("leave them
+    /// to finish on their own, call `activeConnections()` first if you need
+    /// to wait"), but every real caller in this codebase - every test in
+    /// this file included - called `stop()` and then immediately tore down
+    /// the `Db`/allocator the detached worker's `dispatch()` still reads
+    /// from, with nothing enforcing that the worker had actually noticed
+    /// its connection closed and returned first. Most of the time the
+    /// worker's blocking read already sees EOF and exits before the caller
+    /// gets around to teardown, so the race stayed invisible for a long
+    /// time; occasionally it does not, and a worker thread touches a freed
+    /// `Db`/`Allocator.VTable`, corrupting the heap in a way that only
+    /// surfaces later as an unrelated test's leak/double-free abort - this
+    /// is exactly the flaky `zig build test` failure the gate re-run in
+    /// this session caught (roughly 1 run in 4-6, always attributed to
+    /// whichever unrelated test happened to run next). Waiting here by
+    /// default, bounded so a genuinely long-lived idle connection (still
+    /// blocked in `stream.reader()` with nothing sent and no EOF) cannot
+    /// hang shutdown forever, closes that gap for every caller instead of
+    /// relying on each one to remember `activeConnections()`.
+    pub fn stop(self: *Server) void {
+        if (self.acceptThread == null) return;
+        self.stopping.store(true, .release);
+        const listenAddr = self.net.listen_address;
+        if (std.net.tcpConnectToAddress(listenAddr)) |s| {
+            s.close();
+        } else |_| {}
+        self.acceptThread.?.join();
+        self.acceptThread = null;
+        if (self.sweeperThread) |t| {
+            t.join();
+            self.sweeperThread = null;
+        }
+        if (self.ttlSweeperThread) |t| {
+            t.join();
+            self.ttlSweeperThread = null;
+        }
+        if (self.collTtlSweeperThread) |t| {
+            t.join();
+            self.collTtlSweeperThread = null;
+        }
+        self.drainConnections(500 * std.time.ns_per_ms);
+        self.net.deinit();
+        // Best-effort, same as `drainConnections` above: a subscriber
+        // connection that never disconnects (client vanished without
+        // closing its socket) is still `active` past the drain timeout, so
+        // its `Subscriber` is never `destroySubscriber`'d and leaks for the
+        // remaining life of the process - this `deinit` only frees `Hub`'s
+        // own channel map, which by then holds no dangling entries for any
+        // subscriber that WAS properly torn down.
+        self.pubsub.deinit();
+    }
+
+    /// Polls `activeConnections()` until it reaches zero or `timeoutNanos`
+    /// elapses, whichever comes first. See the doc comment on `stop()` for
+    /// why this exists and why it is bounded rather than unconditional.
+    fn drainConnections(self: *Server, timeoutNanos: u64) void {
+        const startedAt = std.time.nanoTimestamp();
+        while (self.activeConnections() > 0) {
+            if (std.time.nanoTimestamp() - startedAt >= timeoutNanos) return;
+            std.time.sleep(1 * std.time.ns_per_ms);
+        }
+    }
+};
+
+fn testDb(allocator: Allocator, dir: []const u8) !Db {
+    return Db.open(allocator, dir, .{});
+}
+
+// `drainConnections` only ever touches `self.active`/`self.stopping`, so it
+// can be exercised on a `Server` value that was never `init()`ed with a
+// real `Db`/socket - every other field stays `undefined` and is never
+// read. This isolates the drain/timeout contract itself from the (much
+// harder to force deterministically) real-socket race it exists to close.
+fn undefinedServerForDrainTest() Server {
+    var srv: Server = undefined;
+    srv.active = std.atomic.Value(usize).init(0);
+    srv.stopping = std.atomic.Value(bool).init(false);
+    return srv;
+}
+
+test "drainConnections returns immediately when there is nothing to drain" {
+    var srv = undefinedServerForDrainTest();
+    const start = std.time.nanoTimestamp();
+    srv.drainConnections(2 * std.time.ns_per_s);
+    const elapsedNanos = std.time.nanoTimestamp() - start;
+    try std.testing.expect(elapsedNanos < 200 * std.time.ns_per_ms);
+}
+
+test "drainConnections waits for a connection that finishes before the timeout" {
+    var srv = undefinedServerForDrainTest();
+    srv.active.store(1, .release);
+
+    const Ctx = struct {
+        srv: *Server,
+        fn run(ctx: *@This()) void {
+            std.time.sleep(30 * std.time.ns_per_ms);
+            _ = ctx.srv.active.fetchSub(1, .acq_rel);
+        }
+    };
+    var ctx = Ctx{ .srv = &srv };
+    const t = try std.Thread.spawn(.{}, Ctx.run, .{&ctx});
+    defer t.join();
+
+    const start = std.time.nanoTimestamp();
+    srv.drainConnections(2 * std.time.ns_per_s);
+    const elapsedNanos = std.time.nanoTimestamp() - start;
+
+    try std.testing.expectEqual(@as(usize, 0), srv.activeConnections());
+    // Returned once the worker actually finished, not after burning the
+    // full 2-second timeout - proves this is a real wait-for-drain, not a
+    // fixed sleep in disguise.
+    try std.testing.expect(elapsedNanos < 1 * std.time.ns_per_s);
+}
+
+test "drainConnections gives up after the timeout instead of hanging forever" {
+    var srv = undefinedServerForDrainTest();
+    srv.active.store(1, .release); // never decremented by anyone
+
+    const start = std.time.nanoTimestamp();
+    srv.drainConnections(20 * std.time.ns_per_ms);
+    const elapsedNanos = std.time.nanoTimestamp() - start;
+
+    try std.testing.expect(elapsedNanos >= 20 * std.time.ns_per_ms);
+    // Still stuck at 1 - drainConnections gave up, it did not (and cannot)
+    // force the phantom connection closed itself.
+    try std.testing.expectEqual(@as(usize, 1), srv.activeConnections());
+}
+
+test "server responds to ping, set, get, and delete over loopback" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.ping();
+    try client.set("hello", "world");
+    const got = try client.get(allocator, "hello");
+    defer if (got) |g| allocator.free(g);
+    try std.testing.expectEqualStrings("world", got.?);
+
+    try client.delete("hello");
+    const afterDelete = try client.get(allocator, "hello");
+    try std.testing.expect(afterDelete == null);
+}
+
+test "server scan, prefix, and stats round trip real data" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.set("user:1", "alice");
+    try client.set("user:2", "bob");
+    try client.set("order:1", "widget");
+
+    const prefixed = try client.prefix(allocator, "user:", 0);
+    defer protocol.freeOwnedEntries(allocator, prefixed);
+    try std.testing.expectEqual(@as(usize, 2), prefixed.len);
+
+    const scanned = try client.scan(allocator, .{});
+    defer protocol.freeOwnedEntries(allocator, scanned);
+    try std.testing.expectEqual(@as(usize, 3), scanned.len);
+
+    const s = try client.stats();
+    try std.testing.expectEqual(@as(usize, 3), s.memtableEntries);
+}
+
+test "server batch applies puts and deletes atomically" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.set("keep", "1");
+    const ops = [_]protocol.BatchOp{
+        .{ .put = .{ .key = "a", .value = "1" } },
+        .{ .put = .{ .key = "b", .value = "2" } },
+        .{ .del = "keep" },
+    };
+    try client.batch(&ops);
+
+    const a = try client.get(allocator, "a");
+    defer if (a) |v| allocator.free(v);
+    try std.testing.expectEqualStrings("1", a.?);
+
+    const kept = try client.get(allocator, "keep");
+    try std.testing.expect(kept == null);
+}
+
+test "server rejects a malformed frame with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.set), "not a valid set payload with no length prefix boundary");
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+}
+
+test "server serves multiple concurrent clients without corrupting state" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const WorkerCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        index: usize,
+        ok: bool = false,
+    };
+
+    const worker = struct {
+        fn run(ctx: *WorkerCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var buf: [32]u8 = undefined;
+            const key = std.fmt.bufPrint(&buf, "k{d}", .{ctx.index}) catch return;
+            client.set(key, "v") catch return;
+            const got = client.get(ctx.allocator, key) catch return;
+            defer if (got) |g| ctx.allocator.free(g);
+            ctx.ok = got != null and std.mem.eql(u8, got.?, "v");
+        }
+    }.run;
+
+    var contexts: [8]WorkerCtx = undefined;
+    var threads: [8]std.Thread = undefined;
+    for (0..8) |i| {
+        contexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .index = i };
+        threads[i] = try std.Thread.spawn(.{}, worker, .{&contexts[i]});
+    }
+    for (0..8) |i| threads[i].join();
+    for (0..8) |i| try std.testing.expect(contexts[i].ok);
+}
+
+test "server enforces a token-bucket rate limit and rejects the overflow" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    // Slow refill (1 token/sec): the whole burst below completes in well
+    // under a second of wall-clock time, so refill contributes nowhere
+    // near a full token and the outcome is deterministic.
+    server.enableRateLimit(3, 1);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    var allowed: usize = 0;
+    var rejected: usize = 0;
+    var i: usize = 0;
+    while (i < 6) : (i += 1) {
+        client.ping() catch |err| {
+            try std.testing.expectEqual(client_mod.ClientError.ServerRateLimited, err);
+            rejected += 1;
+            continue;
+        };
+        allowed += 1;
+    }
+
+    try std.testing.expectEqual(@as(usize, 3), allowed);
+    try std.testing.expectEqual(@as(usize, 3), rejected);
+    try std.testing.expectEqual(@as(u64, 6), server.requestsTotal.get());
+    try std.testing.expectEqual(@as(u64, 3), server.rateLimitedTotal.get());
+}
+
+test "server without an enabled rate limit never rejects" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    var i: usize = 0;
+    while (i < 20) : (i += 1) try client.ping();
+    try std.testing.expectEqual(@as(u64, 20), server.requestsTotal.get());
+    try std.testing.expectEqual(@as(u64, 0), server.rateLimitedTotal.get());
+}
+
+test "per-connection rate limit gives each connection its own budget" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enablePerConnectionRateLimit(2, 1);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+
+    var clientA = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer clientA.close();
+    var clientB = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer clientB.close();
+
+    // Exhaust A's private budget first: B must be unaffected because each
+    // connection got its own bucket, not a bucket shared across the server.
+    try clientA.ping();
+    try clientA.ping();
+    try std.testing.expectError(client_mod.ClientError.ServerRateLimited, clientA.ping());
+
+    try clientB.ping();
+    try clientB.ping();
+    try std.testing.expectError(client_mod.ClientError.ServerRateLimited, clientB.ping());
+
+    try std.testing.expectEqual(@as(u64, 2), server.connRateLimitedTotal.get());
+    try std.testing.expectEqual(@as(u64, 0), server.rateLimitedTotal.get());
+}
+
+test "per-connection and global rate limits both apply, connection budget checked first" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enablePerConnectionRateLimit(10, 1);
+    server.enableRateLimit(2, 1);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.ping();
+    try client.ping();
+    try std.testing.expectError(client_mod.ClientError.ServerRateLimited, client.ping());
+
+    // The global bucket was the one that actually ran out, not the
+    // per-connection one (which had plenty of headroom left).
+    try std.testing.expectEqual(@as(u64, 1), server.rateLimitedTotal.get());
+    try std.testing.expectEqual(@as(u64, 0), server.connRateLimitedTotal.get());
+}
+
+test "server table_select executes a remote expr against real rows, using an index when available" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createIndex("city");
+        try table.put(.{ .int = 1 }, &.{
+            .{ .name = "city", .value = .{ .text = "warsaw" } },
+            .{ .name = "age", .value = .{ .int = 20 } },
+        });
+        try table.put(.{ .int = 2 }, &.{
+            .{ .name = "city", .value = .{ .text = "warsaw" } },
+            .{ .name = "age", .value = .{ .int = 40 } },
+        });
+        try table.put(.{ .int = 3 }, &.{
+            .{ .name = "city", .value = .{ .text = "krakow" } },
+            .{ .name = "age", .value = .{ .int = 40 } },
+        });
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const rows = try client.tableSelect(allocator, "users", "city eq s:warsaw and age gte i:30", 0, 0, &.{});
+    defer protocol.freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 1), rows.len);
+    try std.testing.expectEqual(@as(i64, 2), rows[0].get(querymod.pkField).?.int);
+
+    const all = try client.tableSelect(allocator, "users", "", 0, 0, &.{});
+    defer protocol.freeRows(allocator, all);
+    try std.testing.expectEqual(@as(usize, 3), all.len);
+}
+
+test "server table_explain reports index_eq, composite_eq, and full_scan over real TCP, matching what table_select would actually use" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createIndex("age");
+        try table.createCompositeIndex("city_age", &.{ "city", "age" });
+        try table.put(.{ .int = 1 }, &.{
+            .{ .name = "city", .value = .{ .text = "warsaw" } },
+            .{ .name = "age", .value = .{ .int = 30 } },
+        });
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // Single-field index eq on `age`.
+    var agePlan = try client.tableExplain(allocator, "users", "age eq i:30");
+    defer agePlan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.index_eq, agePlan.kind);
+    try std.testing.expectEqualStrings("age", agePlan.indexName.?);
+
+    // Composite index, full prefix matched by equality on both columns.
+    var compositePlan = try client.tableExplain(allocator, "users", "city eq s:warsaw and age eq i:30");
+    defer compositePlan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.composite_eq, compositePlan.kind);
+    try std.testing.expectEqualStrings("city_age", compositePlan.indexName.?);
+    try std.testing.expectEqual(@as(usize, 2), compositePlan.matchedFields);
+    try std.testing.expectEqual(@as(usize, 2), compositePlan.totalFields);
+
+    // No predicate on an indexed field anywhere -> full scan.
+    var scanPlan = try client.tableExplain(allocator, "users", "city eq s:warsaw");
+    defer scanPlan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.full_scan, scanPlan.kind);
+
+    // Cross-check: what table_explain reports for the composite query is
+    // exactly what table_select actually finds when it runs it - the whole
+    // point of an explain feature is not lying about what execution does.
+    const rows = try client.tableSelect(allocator, "users", "city eq s:warsaw and age eq i:30", 0, 0, &.{});
+    defer protocol.freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 1), rows.len);
+}
+
+test "server table_explain rejects a malformed expr with bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const err = client.tableExplain(allocator, "users", "city bogus s:warsaw");
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+
+    // The connection survives a bad_request and can still serve a good
+    // request right after - same expectation `table_select`'s malformed-expr
+    // test above holds for its own opcode.
+    var plan = try client.tableExplain(allocator, "users", "");
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.full_scan, plan.kind);
+}
+
+test "server table_update applies a set clause to matching rows over real TCP, keeping an index in sync" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createIndex("city");
+        try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "active", .value = .{ .int = 0 } } });
+        try table.put(.{ .int = 2 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "active", .value = .{ .int = 0 } } });
+        try table.put(.{ .int = 3 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "active", .value = .{ .int = 0 } } });
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const sets = [_]rowmod.Field{.{ .name = "city", .value = .{ .text = "gdansk" } }};
+    const updated = try client.tableUpdate("users", &sets, "city eq s:warsaw");
+    try std.testing.expectEqual(@as(u64, 2), updated);
+
+    // The old index entry is gone for both moved rows...
+    const stale = try client.tableSelect(allocator, "users", "city eq s:warsaw", 0, 0, &.{});
+    defer protocol.freeRows(allocator, stale);
+    try std.testing.expectEqual(@as(usize, 0), stale.len);
+
+    // ...a fresh one under the new value finds them, and the row not
+    // matched by the predicate (pk 3, krakow) was left untouched.
+    const moved = try client.tableSelect(allocator, "users", "city eq s:gdansk", 0, 0, &.{});
+    defer protocol.freeRows(allocator, moved);
+    try std.testing.expectEqual(@as(usize, 2), moved.len);
+
+    const untouched = try client.tableSelect(allocator, "users", "city eq s:krakow", 0, 0, &.{});
+    defer protocol.freeRows(allocator, untouched);
+    try std.testing.expectEqual(@as(usize, 1), untouched.len);
+}
+
+test "server table_update rejects a malformed expr with bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const sets = [_]rowmod.Field{.{ .name = "active", .value = .{ .int = 1 } }};
+    const err = client.tableUpdate("users", &sets, "city bogus s:warsaw");
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+
+    // The connection survives a bad_request and can still serve a good
+    // request right after - same expectation `table_explain`'s malformed
+    // test above holds for its own opcode.
+    const updated = try client.tableUpdate("users", &sets, "");
+    try std.testing.expectEqual(@as(u64, 1), updated);
+}
+
+test "server rejects a malformed table_update frame (bad set fields) with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    // A well-formed table name ("users"), then a "set fields" byte string
+    // that decodeTableUpdate happily hands back as opaque bytes but
+    // Row.decode rejects (a field count of 0xFFFFFFFF with nothing behind
+    // it) - the decode failure `handleTableUpdate` itself must catch,
+    // unlike `decodeTableUpdate`'s own malformed-frame check above it.
+    var payload = std.ArrayList(u8).init(allocator);
+    defer payload.deinit();
+    var lenBuf: [4]u8 = undefined;
+    std.mem.writeInt(u32, &lenBuf, 5, .little);
+    try payload.appendSlice(&lenBuf);
+    try payload.appendSlice("users");
+    std.mem.writeInt(u32, &lenBuf, 4, .little);
+    try payload.appendSlice(&lenBuf);
+    std.mem.writeInt(u32, &lenBuf, 0xFFFFFFFF, .little);
+    try payload.appendSlice(&lenBuf);
+
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.table_update), payload.items);
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+
+    // The connection must still be usable afterward.
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.ping), "");
+    var pingFrame = try protocol.readFrame(allocator, stream.reader());
+    defer pingFrame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.ok), pingFrame.tag);
+}
+
+// `table_update` shares the same underlying-sstable-reshaping hazard as
+// `table_select`/`table_join`/`table_aggregate` above, but with a sharper
+// edge: `updateWhere` both READS (via `selectAllMatches`) and WRITES (via
+// `put`) in the same request, while those three only read. `self.mutex` in
+// `Server.dispatch` still serializes every request end-to-end including
+// `flush`/`compact`, so no single request can observe a torn sstable set -
+// what this test actually proves is that real structural reshaping,
+// interleaved via real OS threads through the real TCP/dispatch path, never
+// desyncs `updateWhere`'s read-then-write from the index it must keep in
+// sync, and that a single updater thread's own sequence of writes lands
+// exactly where expected once every other thread has stopped.
+//
+// Thirty rows split evenly three ways by `@mod(pk, 3)` (same helper as the
+// `table_aggregate` concurrency test above) so the "city" index always
+// holds exactly 10 rows per bucket - that count must never move, because
+// this test's single updater thread only ever touches the "epoch" field,
+// never "city" itself, so index population is an invariant a reader can
+// check at every single snapshot, not just at the end.
+test "table_update survives concurrent flush and compact reshaping the underlying sstables" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    // Small target size so a handful of `flush`/`compact` calls do real
+    // structural work instead of needing megabytes of data first - same
+    // trick as the `table_select`/`table_join`/`table_aggregate`
+    // concurrency tests above.
+    var db = try Db.open(allocator, path, .{ .sstableTargetBytes = 512 });
+    defer db.close();
+
+    const rowCount = 30;
+    {
+        var accounts = try querymod.Table.open(&db, allocator, "accounts");
+        defer accounts.deinit();
+        try accounts.createIndex("city");
+        var pk: i64 = 1;
+        while (pk <= rowCount) : (pk += 1) {
+            const city: []const u8 = switch (@mod(pk, 3)) {
+                0 => "warsaw",
+                1 => "krakow",
+                else => "gdansk",
+            };
+            try accounts.put(.{ .int = pk }, &.{
+                .{ .name = "city", .value = .{ .text = city } },
+                .{ .name = "epoch", .value = .{ .int = 0 } },
+            });
+        }
+        try db.flush();
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const readerThreads = 4;
+    const readerIters = 20;
+    const reshapeThreads = 2;
+    const reshapeIters = 15;
+    const updaterIters = 20;
+
+    const ReaderCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const readerWorker = struct {
+        fn run(ctx: *ReaderCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < readerIters) : (i += 1) {
+                inline for (.{ "warsaw", "krakow", "gdansk" }) |city| {
+                    const buf = std.fmt.allocPrint(ctx.allocator, "city eq s:{s}", .{city}) catch return;
+                    defer ctx.allocator.free(buf);
+                    const rows = client.tableSelect(ctx.allocator, "accounts", buf, 0, 0, &.{}) catch return;
+                    defer protocol.freeRows(ctx.allocator, rows);
+                    if (rows.len != 10) return;
+                    for (rows) |row| {
+                        const got = row.get("city") orelse return;
+                        if (!std.mem.eql(u8, got.text, city)) return;
+                    }
+                }
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const ReshapeCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+    const reshapeWorker = struct {
+        fn run(ctx: *ReshapeCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < reshapeIters) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const key = std.fmt.bufPrint(&buf, "update-churn-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.set(key, "x") catch return;
+                client.flush() catch return;
+                client.compact() catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const UpdaterCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const updaterWorker = struct {
+        fn run(ctx: *UpdaterCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: i64 = 0;
+            while (i < updaterIters) : (i += 1) {
+                const target: []const u8 = if (@mod(i, 2) == 0) "krakow" else "gdansk";
+                const expr = std.fmt.allocPrint(ctx.allocator, "city eq s:{s}", .{target}) catch return;
+                defer ctx.allocator.free(expr);
+                const sets = [_]rowmod.Field{.{ .name = "epoch", .value = .{ .int = i } }};
+                const updated = client.tableUpdate("accounts", &sets, expr) catch return;
+                if (updated != 10) return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var readerContexts: [readerThreads]ReaderCtx = undefined;
+    var readerHandles: [readerThreads]std.Thread = undefined;
+    for (0..readerThreads) |i| {
+        readerContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        readerHandles[i] = try std.Thread.spawn(.{}, readerWorker, .{&readerContexts[i]});
+    }
+    var reshapeContexts: [reshapeThreads]ReshapeCtx = undefined;
+    var reshapeHandles: [reshapeThreads]std.Thread = undefined;
+    for (0..reshapeThreads) |i| {
+        reshapeContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        reshapeHandles[i] = try std.Thread.spawn(.{}, reshapeWorker, .{&reshapeContexts[i]});
+    }
+    var updaterContext = UpdaterCtx{ .allocator = allocator, .addr = server.boundAddress() };
+    const updaterHandle = try std.Thread.spawn(.{}, updaterWorker, .{&updaterContext});
+
+    for (0..readerThreads) |i| readerHandles[i].join();
+    for (0..reshapeThreads) |i| reshapeHandles[i].join();
+    updaterHandle.join();
+    for (0..readerThreads) |i| try std.testing.expect(readerContexts[i].ok);
+    for (0..reshapeThreads) |i| try std.testing.expect(reshapeContexts[i].ok);
+    try std.testing.expect(updaterContext.ok);
+
+    // Final sanity check on a fresh connection: the updater alternated
+    // krakow/gdansk, so the last krakow write was iteration 18 (last even
+    // below 20) and the last gdansk write was iteration 19 (last odd) -
+    // warsaw was never touched by any predicate and must still read 0.
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const krakowRows = try client.tableSelect(allocator, "accounts", "city eq s:krakow", 0, 0, &.{});
+    defer protocol.freeRows(allocator, krakowRows);
+    try std.testing.expectEqual(@as(usize, 10), krakowRows.len);
+    for (krakowRows) |row| try std.testing.expectEqual(@as(i64, 18), row.get("epoch").?.int);
+
+    const gdanskRows = try client.tableSelect(allocator, "accounts", "city eq s:gdansk", 0, 0, &.{});
+    defer protocol.freeRows(allocator, gdanskRows);
+    try std.testing.expectEqual(@as(usize, 10), gdanskRows.len);
+    for (gdanskRows) |row| try std.testing.expectEqual(@as(i64, 19), row.get("epoch").?.int);
+
+    const warsawRows = try client.tableSelect(allocator, "accounts", "city eq s:warsaw", 0, 0, &.{});
+    defer protocol.freeRows(allocator, warsawRows);
+    try std.testing.expectEqual(@as(usize, 10), warsawRows.len);
+    for (warsawRows) |row| try std.testing.expectEqual(@as(i64, 0), row.get("epoch").?.int);
+}
+
+// Same shape as the test above, but the index guarding the concurrent
+// reads/updates is a COMPOSITE one (`city_age`, two columns) instead of a
+// single-column `city` index - `updateWhere` reached through
+// `composite_eq` was only proven correct single-threaded so far (see
+// query.zig's "updateWhere keeps a composite index in sync" test); this
+// proves the same code path survives real `flush`/`compact` reshaping the
+// underlying sstables while other connections read and write through it.
+test "table_update survives concurrent flush and compact reshaping a composite index" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try Db.open(allocator, path, .{ .sstableTargetBytes = 512 });
+    defer db.close();
+
+    // 30 rows: 3 cities x 2 age bands x 5 rows each. Every (city, age) pair
+    // is a full-tuple equality match against `city_age`, so
+    // `Table.selectPage`/`updateWhere` both reach it through `composite_eq`
+    // (see query.zig's "createCompositeIndex backfills then full-tuple eq
+    // select" test for the same match shape single-threaded).
+    const rowCount = 30;
+    {
+        var accounts = try querymod.Table.open(&db, allocator, "accounts");
+        defer accounts.deinit();
+        try accounts.createCompositeIndex("city_age", &.{ "city", "age" });
+        var pk: i64 = 1;
+        while (pk <= rowCount) : (pk += 1) {
+            const city: []const u8 = switch (@mod(pk, 3)) {
+                0 => "warsaw",
+                1 => "krakow",
+                else => "gdansk",
+            };
+            const age: i64 = if (@mod(@divTrunc(pk - 1, 3), 2) == 0) 30 else 40;
+            try accounts.put(.{ .int = pk }, &.{
+                .{ .name = "city", .value = .{ .text = city } },
+                .{ .name = "age", .value = .{ .int = age } },
+                .{ .name = "epoch", .value = .{ .int = 0 } },
+            });
+        }
+        try db.flush();
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const readerThreads = 4;
+    const readerIters = 20;
+    const reshapeThreads = 2;
+    const reshapeIters = 15;
+    const updaterIters = 20;
+
+    const Combo = struct { city: []const u8, age: i64 };
+    const combos = [_]Combo{
+        .{ .city = "warsaw", .age = 30 },
+        .{ .city = "warsaw", .age = 40 },
+        .{ .city = "krakow", .age = 30 },
+        .{ .city = "krakow", .age = 40 },
+        .{ .city = "gdansk", .age = 30 },
+        .{ .city = "gdansk", .age = 40 },
+    };
+
+    const ReaderCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const readerWorker = struct {
+        fn run(ctx: *ReaderCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < readerIters) : (i += 1) {
+                for (combos) |combo| {
+                    const buf = std.fmt.allocPrint(ctx.allocator, "city eq s:{s} and age eq i:{d}", .{ combo.city, combo.age }) catch return;
+                    defer ctx.allocator.free(buf);
+                    const rows = client.tableSelect(ctx.allocator, "accounts", buf, 0, 0, &.{}) catch return;
+                    defer protocol.freeRows(ctx.allocator, rows);
+                    if (rows.len != 5) return;
+                    for (rows) |row| {
+                        const gotCity = row.get("city") orelse return;
+                        if (!std.mem.eql(u8, gotCity.text, combo.city)) return;
+                        const gotAge = row.get("age") orelse return;
+                        if (gotAge.int != combo.age) return;
+                    }
+                }
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const ReshapeCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+    const reshapeWorker = struct {
+        fn run(ctx: *ReshapeCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < reshapeIters) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const key = std.fmt.bufPrint(&buf, "update-composite-churn-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.set(key, "x") catch return;
+                client.flush() catch return;
+                client.compact() catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const UpdaterCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const updaterWorker = struct {
+        fn run(ctx: *UpdaterCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: i64 = 0;
+            while (i < updaterIters) : (i += 1) {
+                // Alternates between two full-tuple matches on the composite
+                // index, never touching `city`/`age` themselves, so the
+                // (5, 5, 5, 5, 5, 5) population split is a checkable
+                // invariant on every single reader iteration in flight.
+                const combo = if (@mod(i, 2) == 0) Combo{ .city = "krakow", .age = 30 } else Combo{ .city = "gdansk", .age = 40 };
+                const expr = std.fmt.allocPrint(ctx.allocator, "city eq s:{s} and age eq i:{d}", .{ combo.city, combo.age }) catch return;
+                defer ctx.allocator.free(expr);
+                const sets = [_]rowmod.Field{.{ .name = "epoch", .value = .{ .int = i } }};
+                const updated = client.tableUpdate("accounts", &sets, expr) catch return;
+                if (updated != 5) return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var readerContexts: [readerThreads]ReaderCtx = undefined;
+    var readerHandles: [readerThreads]std.Thread = undefined;
+    for (0..readerThreads) |i| {
+        readerContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        readerHandles[i] = try std.Thread.spawn(.{}, readerWorker, .{&readerContexts[i]});
+    }
+    var reshapeContexts: [reshapeThreads]ReshapeCtx = undefined;
+    var reshapeHandles: [reshapeThreads]std.Thread = undefined;
+    for (0..reshapeThreads) |i| {
+        reshapeContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        reshapeHandles[i] = try std.Thread.spawn(.{}, reshapeWorker, .{&reshapeContexts[i]});
+    }
+    var updaterContext = UpdaterCtx{ .allocator = allocator, .addr = server.boundAddress() };
+    const updaterHandle = try std.Thread.spawn(.{}, updaterWorker, .{&updaterContext});
+
+    for (0..readerThreads) |i| readerHandles[i].join();
+    for (0..reshapeThreads) |i| reshapeHandles[i].join();
+    updaterHandle.join();
+    for (0..readerThreads) |i| try std.testing.expect(readerContexts[i].ok);
+    for (0..reshapeThreads) |i| try std.testing.expect(reshapeContexts[i].ok);
+    try std.testing.expect(updaterContext.ok);
+
+    // Final sanity check on a fresh connection: the updater alternated
+    // krakow/30 and gdansk/40, so the last krakow/30 write was iteration 18
+    // (last even below 20) and the last gdansk/40 write was iteration 19
+    // (last odd) - the other four (city, age) combos were never touched by
+    // any predicate and must still read epoch 0.
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    for (combos) |combo| {
+        const expr = try std.fmt.allocPrint(allocator, "city eq s:{s} and age eq i:{d}", .{ combo.city, combo.age });
+        defer allocator.free(expr);
+        const rows = try client.tableSelect(allocator, "accounts", expr, 0, 0, &.{});
+        defer protocol.freeRows(allocator, rows);
+        try std.testing.expectEqual(@as(usize, 5), rows.len);
+        const wantEpoch: i64 = if (std.mem.eql(u8, combo.city, "krakow") and combo.age == 30)
+            18
+        else if (std.mem.eql(u8, combo.city, "gdansk") and combo.age == 40)
+            19
+        else
+            0;
+        for (rows) |row| try std.testing.expectEqual(wantEpoch, row.get("epoch").?.int);
+
+        // The composite index must still be the strategy actually used
+        // after all this churn, not a fallback to a full scan.
+        var plan = try client.tableExplain(allocator, "accounts", expr);
+        defer plan.deinit(allocator);
+        try std.testing.expectEqual(querymod.PlanKind.composite_eq, plan.kind);
+    }
+}
+
+test "server table_delete removes matching rows over real TCP, keeping an index in sync" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createIndex("city");
+        try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+        try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+        try table.put(.{ .int = 3 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const deleted = try client.tableDelete("users", "city eq s:warsaw");
+    try std.testing.expectEqual(@as(u64, 2), deleted);
+
+    // The index entries for both deleted rows are gone, not just the rows -
+    // a stale entry here would surface as a phantom in a later select.
+    const gone = try client.tableSelect(allocator, "users", "city eq s:warsaw", 0, 0, &.{});
+    defer protocol.freeRows(allocator, gone);
+    try std.testing.expectEqual(@as(usize, 0), gone.len);
+
+    // The row not matched by the predicate (pk 3, krakow) was left untouched.
+    const untouched = try client.tableSelect(allocator, "users", "city eq s:krakow", 0, 0, &.{});
+    defer protocol.freeRows(allocator, untouched);
+    try std.testing.expectEqual(@as(usize, 1), untouched.len);
+
+    // A fresh row can reuse the "warsaw" value without colliding with a
+    // leftover index entry from the deleted rows.
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.put(.{ .int = 4 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    }
+    const reused = try client.tableSelect(allocator, "users", "city eq s:warsaw", 0, 0, &.{});
+    defer protocol.freeRows(allocator, reused);
+    try std.testing.expectEqual(@as(usize, 1), reused.len);
+    try std.testing.expectEqual(@as(i64, 4), reused[0].get(querymod.pkField).?.int);
+}
+
+test "server table_delete with an empty expr removes every row" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "counters");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{.{ .name = "n", .value = .{ .int = 5 } }});
+        try table.put(.{ .int = 2 }, &.{.{ .name = "n", .value = .{ .int = 7 } }});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const deleted = try client.tableDelete("counters", "");
+    try std.testing.expectEqual(@as(u64, 2), deleted);
+
+    const everyone = try client.tableSelect(allocator, "counters", "", 0, 0, &.{});
+    defer protocol.freeRows(allocator, everyone);
+    try std.testing.expectEqual(@as(usize, 0), everyone.len);
+}
+
+test "server table_delete rejects a malformed expr with bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const err = client.tableDelete("users", "city bogus s:warsaw");
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+
+    // The connection survives a bad_request and can still serve a good
+    // request right after - same expectation `table_update`'s malformed
+    // test above holds for its own opcode.
+    const deleted = try client.tableDelete("users", "");
+    try std.testing.expectEqual(@as(u64, 1), deleted);
+}
+
+// `handleTableDelete` calls `Table.deleteWhere` directly (see its own
+// source), the exact function `Table.delete`'s ON DELETE RESTRICT check
+// (query.zig, backed by `ReferencedBySet`) is wired into - so this was
+// never a separate opcode to teach about FOREIGN KEY, only a round trip to
+// prove the wire path actually reaches it, the same "real dispatch, not
+// just the in-process unit test" shape the CHECK/FK/UNIQUE `txn_op` tests
+// elsewhere in this file already are.
+test "server table_delete rejects a FOREIGN KEY RESTRICT violation over the wire and leaves the row in place" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var customers = try querymod.Table.open(&db, allocator, "customers");
+        defer customers.deinit();
+        try customers.put(.{ .int = 1 }, &.{});
+
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createForeignKey("customer_id", "customers", querymod.pkField, .restrict);
+        try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const err = client.tableDelete("customers", "");
+    try std.testing.expectError(client_mod.ClientError.ServerInternal, err);
+
+    var customers = try querymod.Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    var stillThere = (try customers.get(.{ .int = 1 })).?;
+    defer stillThere.deinit();
+
+    // Once the referencing order is gone, the same request succeeds.
+    _ = try client.tableDelete("orders", "");
+    const deleted = try client.tableDelete("customers", "");
+    try std.testing.expectEqual(@as(u64, 1), deleted);
+}
+
+test "server rejects a malformed table_delete frame (bad table name) with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    // A length prefix (0xFFFFFFFF) claiming far more table-name bytes than
+    // the payload actually carries - `decodeTableDelete`'s own malformed-frame
+    // check must catch this before `Table.open` is ever reached.
+    var payload = std.ArrayList(u8).init(allocator);
+    defer payload.deinit();
+    var lenBuf: [4]u8 = undefined;
+    std.mem.writeInt(u32, &lenBuf, 0xFFFFFFFF, .little);
+    try payload.appendSlice(&lenBuf);
+
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.table_delete), payload.items);
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+
+    // The connection must still be usable afterward.
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.ping), "");
+    var pingFrame = try protocol.readFrame(allocator, stream.reader());
+    defer pingFrame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.ok), pingFrame.tag);
+}
+
+test "server table_export renders a real table to csv and json over TCP, matching the local dump.zig output" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "people");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "age", .value = .{ .int = 30 } } });
+        try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    var csvResult = try client.tableExport(allocator, "people", .csv);
+    defer csvResult.deinit(allocator);
+    try std.testing.expectEqual(@as(u64, 2), csvResult.rowCount);
+
+    var localCsv = std.ArrayList(u8).init(allocator);
+    defer localCsv.deinit();
+    {
+        var table = try querymod.Table.open(&db, allocator, "people");
+        defer table.deinit();
+        const n = try dumpmod.exportCsvWriter(allocator, &table, localCsv.writer());
+        try std.testing.expectEqual(@as(usize, 2), n);
+    }
+    try std.testing.expectEqualStrings(localCsv.items, csvResult.content);
+
+    var jsonResult = try client.tableExport(allocator, "people", .json);
+    defer jsonResult.deinit(allocator);
+    try std.testing.expectEqual(@as(u64, 2), jsonResult.rowCount);
+    // Every row's primary key shows up somewhere in the rendered JSON -
+    // enough to prove the server actually rendered real content instead
+    // of an empty/placeholder body, without re-parsing JSON here too.
+    try std.testing.expect(std.mem.indexOf(u8, jsonResult.content, "warsaw") != null);
+    try std.testing.expect(std.mem.indexOf(u8, jsonResult.content, "krakow") != null);
+}
+
+test "server table_import loads csv and json content sent over TCP into a real table" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const csvImported = try client.tableImport("from_csv", .csv, "__pk,city\ni:1,s:warsaw\ni:2,s:krakow\n");
+    try std.testing.expectEqual(@as(u64, 2), csvImported);
+
+    const jsonImported = try client.tableImport("from_json", .json, "[{\"__pk\": \"i:1\", \"city\": \"s:gdansk\"}]");
+    try std.testing.expectEqual(@as(u64, 1), jsonImported);
+
+    const csvRows = try client.tableSelect(allocator, "from_csv", "", 0, 0, &.{});
+    defer protocol.freeRows(allocator, csvRows);
+    try std.testing.expectEqual(@as(usize, 2), csvRows.len);
+
+    const jsonRows = try client.tableSelect(allocator, "from_json", "city eq s:gdansk", 0, 0, &.{});
+    defer protocol.freeRows(allocator, jsonRows);
+    try std.testing.expectEqual(@as(usize, 1), jsonRows.len);
+}
+
+test "server table_export then table_import round trips a real table over two TCP round trips" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "source");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "score", .value = .{ .float = 4.5 } } });
+        try table.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "lodz" } }});
+        try table.put(.{ .int = 3 }, &.{});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    var exported = try client.tableExport(allocator, "source", .json);
+    defer exported.deinit(allocator);
+    try std.testing.expectEqual(@as(u64, 3), exported.rowCount);
+
+    const imported = try client.tableImport("dest", .json, exported.content);
+    try std.testing.expectEqual(@as(u64, 3), imported);
+
+    const warsawRows = try client.tableSelect(allocator, "dest", "city eq s:warsaw", 0, 0, &.{});
+    defer protocol.freeRows(allocator, warsawRows);
+    try std.testing.expectEqual(@as(usize, 1), warsawRows.len);
+    try std.testing.expectEqual(@as(f64, 4.5), warsawRows[0].get("score").?.float);
+
+    const untouched = try client.tableSelect(allocator, "dest", "city eq s:lodz", 0, 0, &.{});
+    defer protocol.freeRows(allocator, untouched);
+    try std.testing.expectEqual(@as(usize, 1), untouched.len);
+
+    const allRows = try client.tableSelect(allocator, "dest", "", 0, 0, &.{});
+    defer protocol.freeRows(allocator, allRows);
+    try std.testing.expectEqual(@as(usize, 3), allRows.len);
+}
+
+test "server table_export succeeds on a never-written table (schemaless tables have no declare step), table_import rejects malformed content without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // `table` is just a keyspace prefix, never declared ahead of time (see
+    // `query.Table.open`), so exporting one nothing has ever put a row into
+    // is a valid zero-row export, not an error.
+    var exported = try client.tableExport(allocator, "nosuch", .csv);
+    defer exported.deinit(allocator);
+    try std.testing.expectEqual(@as(u64, 0), exported.rowCount);
+
+    const badImport = client.tableImport("nosuch", .json, "not json");
+    try std.testing.expectError(client_mod.ClientError.ServerInternal, badImport);
+
+    // The connection survives an internal error and can still serve a
+    // good request right after.
+    const rowCount = try client.tableImport("nosuch", .json, "[]");
+    try std.testing.expectEqual(@as(u64, 0), rowCount);
+}
+
+test "server rejects a malformed table_export frame (bad format byte) with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "people");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    // A well-formed table name ("people") followed by a format byte
+    // outside the DumpFormat enum (99) - `decodeTableExport` itself must
+    // reject this before `Table.open` is ever reached.
+    var payload = std.ArrayList(u8).init(allocator);
+    defer payload.deinit();
+    var lenBuf: [4]u8 = undefined;
+    std.mem.writeInt(u32, &lenBuf, 6, .little);
+    try payload.appendSlice(&lenBuf);
+    try payload.appendSlice("people");
+    try payload.append(99);
+
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.table_export), payload.items);
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+
+    // The connection must still be usable afterward.
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.ping), "");
+    var pingFrame = try protocol.readFrame(allocator, stream.reader());
+    defer pingFrame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.ok), pingFrame.tag);
+}
+
+test "table_export requires only readonly role, table_import requires readwrite" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    {
+        var table = try querymod.Table.open(&db, allocator, "people");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{});
+    }
+
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "viewer", "pass", .readonly, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    try client.authenticate("viewer", "pass");
+
+    var exported = try client.tableExport(allocator, "people", .csv);
+    defer exported.deinit(allocator);
+    try std.testing.expectEqual(@as(u64, 1), exported.rowCount);
+
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, client.tableImport("people", .csv, exported.content));
+}
+
+// `table_delete` shares the same underlying-sstable-reshaping hazard as
+// `table_update` above (see that test's header comment for the full
+// rationale), but where `updateWhere` reads-then-writes each matched row in
+// place, `deleteWhere` reads-then-REMOVES it - a sharper edge again, since a
+// removed row's index entries must never resurface even if a `flush`/
+// `compact` reshapes the underlying sstables mid-scan. Three buckets
+// (warsaw/krakow/gdansk) stay untouched for the whole test and are the
+// reader threads' stable invariant (always exactly 10 rows each); a fourth
+// bucket (poznan) is what the deleter thread progressively drains one row
+// at a time via a "seq" field unrelated to the "city" index, so every
+// delete is a distinct, real structural change rather than a no-op repeat.
+test "table_delete survives concurrent flush and compact reshaping the underlying sstables" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    // Small target size so a handful of `flush`/`compact` calls do real
+    // structural work instead of needing megabytes of data first - same
+    // trick as `table_update`'s own concurrency test above.
+    var db = try Db.open(allocator, path, .{ .sstableTargetBytes = 512 });
+    defer db.close();
+
+    const stableBucketRows = 10;
+    const poznanRows = 10;
+    {
+        var accounts = try querymod.Table.open(&db, allocator, "accounts");
+        defer accounts.deinit();
+        try accounts.createIndex("city");
+        var pk: i64 = 1;
+        var i: i64 = 0;
+        while (i < stableBucketRows) : (i += 1) {
+            inline for (.{ "warsaw", "krakow", "gdansk" }) |city| {
+                try accounts.put(.{ .int = pk }, &.{.{ .name = "city", .value = .{ .text = city } }});
+                pk += 1;
+            }
+        }
+        var seq: i64 = 0;
+        while (seq < poznanRows) : (seq += 1) {
+            try accounts.put(.{ .int = pk }, &.{
+                .{ .name = "city", .value = .{ .text = "poznan" } },
+                .{ .name = "seq", .value = .{ .int = seq } },
+            });
+            pk += 1;
+        }
+        try db.flush();
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const readerThreads = 4;
+    const readerIters = 20;
+    const reshapeThreads = 2;
+    const reshapeIters = 15;
+
+    const ReaderCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const readerWorker = struct {
+        fn run(ctx: *ReaderCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < readerIters) : (i += 1) {
+                inline for (.{ "warsaw", "krakow", "gdansk" }) |city| {
+                    const buf = std.fmt.allocPrint(ctx.allocator, "city eq s:{s}", .{city}) catch return;
+                    defer ctx.allocator.free(buf);
+                    const rows = client.tableSelect(ctx.allocator, "accounts", buf, 0, 0, &.{}) catch return;
+                    defer protocol.freeRows(ctx.allocator, rows);
+                    if (rows.len != stableBucketRows) return;
+                    for (rows) |row| {
+                        const got = row.get("city") orelse return;
+                        if (!std.mem.eql(u8, got.text, city)) return;
+                    }
+                }
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const ReshapeCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+    const reshapeWorker = struct {
+        fn run(ctx: *ReshapeCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < reshapeIters) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const key = std.fmt.bufPrint(&buf, "delete-churn-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.set(key, "x") catch return;
+                client.flush() catch return;
+                client.compact() catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const DeleterCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const deleterWorker = struct {
+        fn run(ctx: *DeleterCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var seq: i64 = 0;
+            while (seq < poznanRows) : (seq += 1) {
+                const expr = std.fmt.allocPrint(ctx.allocator, "city eq s:poznan and seq eq i:{d}", .{seq}) catch return;
+                defer ctx.allocator.free(expr);
+                const deleted = client.tableDelete("accounts", expr) catch return;
+                if (deleted != 1) return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var readerContexts: [readerThreads]ReaderCtx = undefined;
+    var readerHandles: [readerThreads]std.Thread = undefined;
+    for (0..readerThreads) |i| {
+        readerContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        readerHandles[i] = try std.Thread.spawn(.{}, readerWorker, .{&readerContexts[i]});
+    }
+    var reshapeContexts: [reshapeThreads]ReshapeCtx = undefined;
+    var reshapeHandles: [reshapeThreads]std.Thread = undefined;
+    for (0..reshapeThreads) |i| {
+        reshapeContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        reshapeHandles[i] = try std.Thread.spawn(.{}, reshapeWorker, .{&reshapeContexts[i]});
+    }
+    var deleterContext = DeleterCtx{ .allocator = allocator, .addr = server.boundAddress() };
+    const deleterHandle = try std.Thread.spawn(.{}, deleterWorker, .{&deleterContext});
+
+    for (0..readerThreads) |i| readerHandles[i].join();
+    for (0..reshapeThreads) |i| reshapeHandles[i].join();
+    deleterHandle.join();
+    for (0..readerThreads) |i| try std.testing.expect(readerContexts[i].ok);
+    for (0..reshapeThreads) |i| try std.testing.expect(reshapeContexts[i].ok);
+    try std.testing.expect(deleterContext.ok);
+
+    // Final sanity check on a fresh connection: the three stable buckets are
+    // still exactly 10 rows each, poznan is completely gone (not just its
+    // index entries - real rows too), and no phantom entry survives under
+    // the "poznan" index bucket for a later put to collide with.
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    inline for (.{ "warsaw", "krakow", "gdansk" }) |city| {
+        const buf = try std.fmt.allocPrint(allocator, "city eq s:{s}", .{city});
+        defer allocator.free(buf);
+        const rows = try client.tableSelect(allocator, "accounts", buf, 0, 0, &.{});
+        defer protocol.freeRows(allocator, rows);
+        try std.testing.expectEqual(@as(usize, stableBucketRows), rows.len);
+    }
+
+    const poznanRowsLeft = try client.tableSelect(allocator, "accounts", "city eq s:poznan", 0, 0, &.{});
+    defer protocol.freeRows(allocator, poznanRowsLeft);
+    try std.testing.expectEqual(@as(usize, 0), poznanRowsLeft.len);
+
+    var plan = try client.tableExplain(allocator, "accounts", "city eq s:poznan");
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.index_eq, plan.kind);
+}
+
+test "server table_select pages a remote result with offset and limit" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        var pk: i64 = 1;
+        while (pk <= 5) : (pk += 1) try table.put(.{ .int = pk }, &.{});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const page = try client.tableSelect(allocator, "users", "", 1, 2, &.{});
+    defer protocol.freeRows(allocator, page);
+    try std.testing.expectEqual(@as(usize, 2), page.len);
+    try std.testing.expectEqual(@as(i64, 2), page[0].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 3), page[1].get(querymod.pkField).?.int);
+
+    const rest = try client.tableSelect(allocator, "users", "", 3, 0, &.{});
+    defer protocol.freeRows(allocator, rest);
+    try std.testing.expectEqual(@as(usize, 2), rest.len);
+    try std.testing.expectEqual(@as(i64, 4), rest[0].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 5), rest[1].get(querymod.pkField).?.int);
+}
+
+// `table_explain` reports which strategy `selectPage` would use, but
+// `table_select`'s own `--order-by` is the one place the network protocol
+// carries a sort key: `handleTableSelect` forwards `args.orderBy` into
+// `Table.selectPageOrdered`, which must sort BEFORE windowing by
+// offset/limit (see query.zig's "applies offset/limit after sorting"
+// test). This exercises that ordering end to end over a real socket,
+// including on a field that has an index (`age`) - `selectAllMatches`
+// still narrows through the index, it just cannot early-stop while a sort
+// is pending, and the wire round trip must not lose that.
+test "server table_select orders a remote result by a field before windowing it, ascending and descending" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.createIndex("age");
+        // pk order deliberately not age order: pk 1 has the highest age
+        // (50), pk 5 the lowest (10) - a bug that sorted only within pk
+        // scan order would fail every assertion below.
+        var pk: i64 = 1;
+        while (pk <= 5) : (pk += 1) {
+            try table.put(.{ .int = pk }, &.{.{ .name = "age", .value = .{ .int = 60 - pk * 10 } }});
+        }
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const asc = try client.tableSelect(allocator, "users", "", 0, 0, &.{.{ .field = "age" }});
+    defer protocol.freeRows(allocator, asc);
+    try std.testing.expectEqual(@as(usize, 5), asc.len);
+    try std.testing.expectEqual(@as(i64, 5), asc[0].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 10), asc[0].get("age").?.int);
+    try std.testing.expectEqual(@as(i64, 1), asc[4].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 50), asc[4].get("age").?.int);
+
+    // Descending, windowed to the middle page (offset 1, limit 2). Age
+    // decreases as pk increases here, so descending-by-age happens to land
+    // on the same row order as ascending pk (pk1..5 = ages 50,40,30,20,10)
+    // - the offset/limit window (pk 2, pk 3) is still only correct if the
+    // full 5-row set was sorted first and THEN windowed, not windowed off
+    // the raw scan and left unsorted (which would coincidentally return
+    // the same two rows here, but in the ascending-age windowed case below
+    // would not).
+    const midDesc = try client.tableSelect(allocator, "users", "", 1, 2, &.{.{ .field = "age", .descending = true }});
+    defer protocol.freeRows(allocator, midDesc);
+    try std.testing.expectEqual(@as(usize, 2), midDesc.len);
+    try std.testing.expectEqual(@as(i64, 2), midDesc[0].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 40), midDesc[0].get("age").?.int);
+    try std.testing.expectEqual(@as(i64, 3), midDesc[1].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 30), midDesc[1].get("age").?.int);
+
+    // Ascending, same window (offset 1, limit 2): ascending-by-age order is
+    // pk 5,4,3,2,1 (ages 10,20,30,40,50), so offset 1..3 is pk 4 then pk 3
+    // - a DIFFERENT pair than the descending window above, which a
+    // window-before-sort bug (paging the raw pk scan, then sorting only
+    // the already-cut window) would fail to distinguish.
+    const midAsc = try client.tableSelect(allocator, "users", "", 1, 2, &.{.{ .field = "age" }});
+    defer protocol.freeRows(allocator, midAsc);
+    try std.testing.expectEqual(@as(usize, 2), midAsc.len);
+    try std.testing.expectEqual(@as(i64, 4), midAsc[0].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 20), midAsc[0].get("age").?.int);
+    try std.testing.expectEqual(@as(i64, 3), midAsc[1].get(querymod.pkField).?.int);
+    try std.testing.expectEqual(@as(i64, 30), midAsc[1].get("age").?.int);
+
+    // Cross-check: table_explain reports the `age` index is used for the
+    // predicate that would narrow this query, same as the ordered path's
+    // `selectAllMatches` internally reuses.
+    var plan = try client.tableExplain(allocator, "users", "age gte i:0");
+    defer plan.deinit(allocator);
+    try std.testing.expectEqual(querymod.PlanKind.index_range, plan.kind);
+}
+
+// A second, INDEPENDENT `orderBy` column exercises a path the single-column
+// test above cannot: `handleTableSelect` decoding a wire count > 1 and
+// `sortRowsBy`'s tie-breaking chain, both new with multi-column support.
+test "server table_select orders a remote result by two columns, sorting then breaking ties" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "people");
+        defer table.deinit();
+        // Two cities, scores deliberately NOT already grouped by city in
+        // scan order, so a single-column `city` sort alone would leave
+        // each city's rows unsorted by `score` - only a real tiebreak
+        // fixes that.
+        try table.put(.{ .int = 1 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "score", .value = .{ .int = 30 } } });
+        try table.put(.{ .int = 2 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "score", .value = .{ .int = 20 } } });
+        try table.put(.{ .int = 3 }, &.{ .{ .name = "city", .value = .{ .text = "warsaw" } }, .{ .name = "score", .value = .{ .int = 10 } } });
+        try table.put(.{ .int = 4 }, &.{ .{ .name = "city", .value = .{ .text = "krakow" } }, .{ .name = "score", .value = .{ .int = 40 } } });
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const rows = try client.tableSelect(allocator, "people", "", 0, 0, &.{ .{ .field = "city" }, .{ .field = "score" } });
+    defer protocol.freeRows(allocator, rows);
+    try std.testing.expectEqual(@as(usize, 4), rows.len);
+    try std.testing.expectEqual(@as(i64, 2), rows[0].get(querymod.pkField).?.int); // krakow/20
+    try std.testing.expectEqual(@as(i64, 4), rows[1].get(querymod.pkField).?.int); // krakow/40
+    try std.testing.expectEqual(@as(i64, 3), rows[2].get(querymod.pkField).?.int); // warsaw/10
+    try std.testing.expectEqual(@as(i64, 1), rows[3].get(querymod.pkField).?.int); // warsaw/30
+}
+
+test "server table_select rejects a malformed expr with bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var table = try querymod.Table.open(&db, allocator, "users");
+        defer table.deinit();
+        try table.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const err = client.tableSelect(allocator, "users", "city bogus s:warsaw", 0, 0, &.{});
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+fn seedAggregateOrders(allocator: Allocator, db: *Db) !void {
+    var orders = try querymod.Table.open(db, allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 1 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "total", .value = .{ .int = 100 } },
+    });
+    try orders.put(.{ .int = 2 }, &.{
+        .{ .name = "city", .value = .{ .text = "warsaw" } },
+        .{ .name = "total", .value = .{ .int = 250 } },
+    });
+    try orders.put(.{ .int = 3 }, &.{
+        .{ .name = "city", .value = .{ .text = "krakow" } },
+        .{ .name = "total", .value = .{ .int = 40 } },
+    });
+}
+
+test "server table_aggregate groups remote rows by field with count/sum, matching the local library result" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+    };
+    const groups = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "", "");
+    defer protocol.freeAggGroupRows(allocator, groups);
+
+    try std.testing.expectEqual(@as(usize, 2), groups.len);
+    try std.testing.expectEqualStrings("warsaw", groups[0].group.text);
+    try std.testing.expectEqual(@as(i64, 2), groups[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, 350), groups[0].values[1].int);
+    try std.testing.expectEqualStrings("krakow", groups[1].group.text);
+    try std.testing.expectEqual(@as(i64, 1), groups[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 40), groups[1].values[1].int);
+}
+
+test "server table_aggregate honors offset/limit to window the result groups server-side" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+    var orders = try querymod.Table.open(&db, allocator, "orders");
+    try orders.put(.{ .int = 4 }, &.{
+        .{ .name = "city", .value = .{ .text = "gdansk" } },
+        .{ .name = "total", .value = .{ .int = 5 } },
+    });
+    orders.deinit();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{.{ .field = "", .kind = .count }};
+
+    // Unpaged baseline: 3 distinct cities in first-seen order (warsaw twice
+    // seeded first, then krakow, then gdansk added above).
+    const all = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "", "");
+    defer protocol.freeAggGroupRows(allocator, all);
+    try std.testing.expectEqual(@as(usize, 3), all.len);
+
+    const paged = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 1, 1, &.{}, "", "");
+    defer protocol.freeAggGroupRows(allocator, paged);
+    try std.testing.expectEqual(@as(usize, 1), paged.len);
+    try std.testing.expectEqualStrings(all[1].group.text, paged[0].group.text);
+}
+
+test "server table_aggregate with no groupField runs a single global aggregate and honors the expr filter" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+    };
+    const all = try client.tableAggregateGlobal(allocator, "orders", &specs, "", "");
+    defer protocol.freeAggValues(allocator, all);
+    try std.testing.expectEqual(@as(i64, 3), all[0].int);
+    try std.testing.expectEqual(@as(i64, 390), all[1].int);
+
+    const filtered = try client.tableAggregateGlobal(allocator, "orders", &specs, "", "total gt i:50");
+    defer protocol.freeAggValues(allocator, filtered);
+    try std.testing.expectEqual(@as(i64, 2), filtered[0].int);
+    try std.testing.expectEqual(@as(i64, 350), filtered[1].int);
+}
+
+test "server table_aggregate applies a HAVING clause to result groups after aggregation, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db); // warsaw: count=2 sum=350, krakow: count=1 sum=40
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+    };
+
+    // Referencing the printed aggregate label (sum_total): only warsaw's
+    // group sum clears 100.
+    const bySum = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "sum_total gt i:100", "");
+    defer protocol.freeAggGroupRows(allocator, bySum);
+    try std.testing.expectEqual(@as(usize, 1), bySum.len);
+    try std.testing.expectEqualStrings("warsaw", bySum[0].group.text);
+
+    // Referencing the group key itself (city), not just an aggregate result.
+    const byGroup = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "city eq s:krakow", "");
+    defer protocol.freeAggGroupRows(allocator, byGroup);
+    try std.testing.expectEqual(@as(usize, 1), byGroup.len);
+    try std.testing.expectEqualStrings("krakow", byGroup[0].group.text);
+
+    // A HAVING clause that excludes every group comes back as zero groups,
+    // not an error.
+    const none = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "count gt i:1000", "");
+    defer protocol.freeAggGroupRows(allocator, none);
+    try std.testing.expectEqual(@as(usize, 0), none.len);
+}
+
+test "server table_aggregate HAVING narrows groups before LIMIT/OFFSET windows them, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+    var orders = try querymod.Table.open(&db, allocator, "orders");
+    try orders.put(.{ .int = 4 }, &.{
+        .{ .name = "city", .value = .{ .text = "gdansk" } },
+        .{ .name = "total", .value = .{ .int = 500 } },
+    });
+    orders.deinit();
+    // Groups in first-seen order: warsaw(count=2 sum=350), krakow(count=1
+    // sum=40), gdansk(count=1 sum=500). HAVING count gt 0 keeps all three,
+    // but HAVING sum_total gt i:100 keeps only warsaw and gdansk (in that
+    // order) - a limit of 1 must then return warsaw, not krakow (which
+    // would be first if the window applied before HAVING).
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+    };
+    const paged = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 1, &.{}, "sum_total gt i:100", "");
+    defer protocol.freeAggGroupRows(allocator, paged);
+    try std.testing.expectEqual(@as(usize, 1), paged.len);
+    try std.testing.expectEqualStrings("warsaw", paged[0].group.text);
+
+    const pagedOffset = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 1, 1, &.{}, "sum_total gt i:100", "");
+    defer protocol.freeAggGroupRows(allocator, pagedOffset);
+    try std.testing.expectEqual(@as(usize, 1), pagedOffset.len);
+    try std.testing.expectEqualStrings("gdansk", pagedOffset[0].group.text);
+}
+
+test "server table_aggregate HAVING on the global (no groupField) path excludes the single row without erroring, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db); // global: count=3 sum=390
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "total", .kind = .sum },
+    };
+
+    const passing = try client.tableAggregateGlobal(allocator, "orders", &specs, "sum_total gt i:100", "");
+    defer protocol.freeAggValues(allocator, passing);
+    try std.testing.expectEqual(@as(usize, 2), passing.len);
+    try std.testing.expectEqual(@as(i64, 390), passing[1].int);
+
+    const excluded = try client.tableAggregateGlobal(allocator, "orders", &specs, "sum_total gt i:100000", "");
+    defer protocol.freeAggValues(allocator, excluded);
+    try std.testing.expectEqual(@as(usize, 0), excluded.len);
+}
+
+test "server table_aggregate reports a malformed HAVING expr as bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{.{ .field = "", .kind = .count }};
+    const err = client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "count bogus i:1", "");
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+test "server table_aggregate count_distinct collapses repeated field values, locally and globally, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    {
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        // Both warsaw rows share the same region on purpose - the whole
+        // point of this test is that COUNT(DISTINCT region) collapses them
+        // to 1, unlike plain COUNT which would report 2.
+        try orders.put(.{ .int = 1 }, &.{
+            .{ .name = "city", .value = .{ .text = "warsaw" } },
+            .{ .name = "region", .value = .{ .text = "mazovia" } },
+        });
+        try orders.put(.{ .int = 2 }, &.{
+            .{ .name = "city", .value = .{ .text = "warsaw" } },
+            .{ .name = "region", .value = .{ .text = "mazovia" } },
+        });
+        try orders.put(.{ .int = 3 }, &.{
+            .{ .name = "city", .value = .{ .text = "krakow" } },
+            .{ .name = "region", .value = .{ .text = "malopolska" } },
+        });
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{
+        .{ .field = "", .kind = .count },
+        .{ .field = "region", .kind = .count_distinct },
+    };
+    const groups = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "", "");
+    defer protocol.freeAggGroupRows(allocator, groups);
+    try std.testing.expectEqual(@as(usize, 2), groups.len);
+    try std.testing.expectEqualStrings("warsaw", groups[0].group.text);
+    try std.testing.expectEqual(@as(i64, 2), groups[0].values[0].int); // COUNT(*)
+    try std.testing.expectEqual(@as(i64, 1), groups[0].values[1].int); // COUNT(DISTINCT region)
+    try std.testing.expectEqualStrings("krakow", groups[1].group.text);
+    try std.testing.expectEqual(@as(i64, 1), groups[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 1), groups[1].values[1].int);
+
+    const globalSpecs = [_]aggregatemod.AggSpec{.{ .field = "region", .kind = .count_distinct }};
+    const global = try client.tableAggregateGlobal(allocator, "orders", &globalSpecs, "", "");
+    defer protocol.freeAggValues(allocator, global);
+    try std.testing.expectEqual(@as(i64, 2), global[0].int); // mazovia + malopolska
+}
+
+test "server table_aggregate reports a non-numeric sum field as bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]aggregatemod.AggSpec{.{ .field = "city", .kind = .sum }};
+    const err = client.tableAggregateGlobal(allocator, "orders", &specs, "", "");
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+test "server table_window annotates remote rows with row_number, partition-then-order matching the local library result" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const partitionBy = [_][]const u8{"city"};
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .row_number }};
+    const results = try client.tableWindow(allocator, "orders", &specs, &partitionBy, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    // First-seen partition order (warsaw at pk1, krakow at pk3), sorted by
+    // total within each partition: warsaw 100 then 250, krakow 40 alone.
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    try std.testing.expectEqualStrings("warsaw", results[0].row.get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 100), results[0].row.get("total").?.int);
+    try std.testing.expectEqual(@as(i64, 1), results[0].values[0].int);
+    try std.testing.expectEqualStrings("warsaw", results[1].row.get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 250), results[1].row.get("total").?.int);
+    try std.testing.expectEqual(@as(i64, 2), results[1].values[0].int);
+    try std.testing.expectEqualStrings("krakow", results[2].row.get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 1), results[2].values[0].int);
+}
+
+test "server table_window honors offset/limit to page rows in partition-then-order display order, not raw scan order" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const partitionBy = [_][]const u8{"city"};
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .row_number }};
+
+    const all = try client.tableWindow(allocator, "orders", &specs, &partitionBy, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, all);
+    try std.testing.expectEqual(@as(usize, 3), all.len);
+
+    const paged = try client.tableWindow(allocator, "orders", &specs, &partitionBy, &orderBy, 1, 1, "", .rows);
+    defer protocol.freeWindowRows(allocator, paged);
+    try std.testing.expectEqual(@as(usize, 1), paged.len);
+    try std.testing.expectEqual(all[1].values[0].int, paged[0].values[0].int);
+    try std.testing.expectEqual(all[1].row.get("total").?.int, paged[0].row.get("total").?.int);
+}
+
+test "server table_window with MULTIPLE specs returns one WindowRow.values entry per spec, in request order, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const partitionBy = [_][]const u8{"city"};
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "", .kind = .row_number },
+        .{ .field = "total", .kind = .sum },
+    };
+    const results = try client.tableWindow(allocator, "orders", &specs, &partitionBy, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    try std.testing.expectEqual(@as(usize, 2), results[0].values.len);
+    // warsaw: total 100 then 250 (running sum), krakow: total 40 alone.
+    try std.testing.expectEqualStrings("warsaw", results[0].row.get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 1), results[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, 100), results[0].values[1].int);
+    try std.testing.expectEqualStrings("warsaw", results[1].row.get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 2), results[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 350), results[1].values[1].int);
+    try std.testing.expectEqualStrings("krakow", results[2].row.get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 1), results[2].values[0].int);
+    try std.testing.expectEqual(@as(i64, 40), results[2].values[1].int);
+}
+
+test "server table_window with a partition but no order runs a whole-partition sum, matching sum:field semantics" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const partitionBy = [_][]const u8{"city"};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "total", .kind = .sum }};
+    const results = try client.tableWindow(allocator, "orders", &specs, &partitionBy, &.{}, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    for (results) |wr| {
+        const expected: i64 = if (std.mem.eql(u8, wr.row.get("city").?.text, "warsaw")) 350 else 40;
+        try std.testing.expectEqual(expected, wr.values[0].int);
+    }
+}
+
+test "server table_window RANGE frame groups tied rows by day, ROWS gives each row its own running total, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    {
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        // Two rows tied at day=1 (10, 20), then one row at day=2 (5).
+        try orders.put(.{ .int = 1 }, &.{
+            .{ .name = "day", .value = .{ .int = 1 } },
+            .{ .name = "amount", .value = .{ .int = 10 } },
+        });
+        try orders.put(.{ .int = 2 }, &.{
+            .{ .name = "day", .value = .{ .int = 1 } },
+            .{ .name = "amount", .value = .{ .int = 20 } },
+        });
+        try orders.put(.{ .int = 3 }, &.{
+            .{ .name = "day", .value = .{ .int = 2 } },
+            .{ .name = "amount", .value = .{ .int = 5 } },
+        });
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const orderBy = [_]querymod.OrderBy{.{ .field = "day", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "amount", .kind = .sum }};
+
+    const rangeResults = try client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .range);
+    defer protocol.freeWindowRows(allocator, rangeResults);
+    try std.testing.expectEqual(@as(usize, 3), rangeResults.len);
+    // Both day=1 rows share the tie group's combined total (10+20=30).
+    try std.testing.expectEqual(@as(i64, 30), rangeResults[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, 30), rangeResults[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 35), rangeResults[2].values[0].int);
+
+    const rowsResults = try client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, rowsResults);
+    try std.testing.expectEqual(@as(usize, 3), rowsResults.len);
+    // ROWS: each physical row gets its own running total, even tied ones.
+    try std.testing.expectEqual(@as(i64, 10), rowsResults[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, 30), rowsResults[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 35), rowsResults[2].values[0].int);
+}
+
+test "server table_window rejects a RANGE frame combined with row_number as bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .row_number }};
+    const err = client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .range);
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+test "server table_window lag/lead read the adjacent row's value along order, NULL at the sequence edge, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "total", .kind = .lag },
+        .{ .field = "total", .kind = .lead },
+    };
+    const results = try client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    // Sorted by total ascending: krakow/40, warsaw/100, warsaw/250.
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    try std.testing.expectEqual(@as(i64, 40), results[0].row.get("total").?.int);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, results[0].values[0]));
+    try std.testing.expectEqual(@as(i64, 100), results[0].values[1].int);
+    try std.testing.expectEqual(@as(i64, 100), results[1].row.get("total").?.int);
+    try std.testing.expectEqual(@as(i64, 40), results[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 250), results[1].values[1].int);
+    try std.testing.expectEqual(@as(i64, 250), results[2].row.get("total").?.int);
+    try std.testing.expectEqual(@as(i64, 100), results[2].values[0].int);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, results[2].values[1]));
+}
+
+test "server table_window lag with an explicit offset and a caller-supplied default, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "total", .kind = .lag, .offset = 2, .default = .{ .int = -1 } }};
+    const results = try client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    // Sorted: krakow/40, warsaw/100, warsaw/250 - lag offset 2 reaches back
+    // two physical positions, so only the LAST row has a real source (40);
+    // the first two fall outside the sequence and get the -1 default.
+    try std.testing.expectEqual(@as(i64, -1), results[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, -1), results[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 40), results[2].values[0].int);
+}
+
+test "server table_window rejects a RANGE frame combined with lag as bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "total", .kind = .lead }};
+    const err = client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .range);
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+test "server table_window first_value/last_value read the current RANGE tie group's edges, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{
+        .{ .field = "total", .kind = .first_value },
+        .{ .field = "total", .kind = .last_value },
+    };
+    const results = try client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .range);
+    defer protocol.freeWindowRows(allocator, results);
+
+    // Sorted by total ascending: krakow/40, warsaw/100, warsaw/250 - no ties,
+    // so RANGE reduces to one tie group per row (same as ROWS): first_value
+    // is always the partition's first row (40, frame start is unaffected by
+    // ties), but last_value is each row's OWN value since it is its own
+    // singleton tie group.
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    for (results) |r| try std.testing.expectEqual(@as(i64, 40), r.values[0].int);
+    try std.testing.expectEqual(@as(i64, 40), results[0].values[1].int);
+    try std.testing.expectEqual(@as(i64, 100), results[1].values[1].int);
+    try std.testing.expectEqual(@as(i64, 250), results[2].values[1].int);
+}
+
+test "server table_window nth_value reads a fixed frame position, default at the sequence edge, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "total", .kind = .nth_value, .offset = 2, .default = .{ .int = -1 } }};
+    const results = try client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    // Sorted: krakow/40, warsaw/100, warsaw/250. Position 2 (n=2) needs a
+    // frame of at least size 2 - the first row's ROWS frame is still just
+    // itself (size 1), so it falls back to the caller's default (-1); the
+    // remaining two rows both see position 2's value, 100.
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    try std.testing.expectEqual(@as(i64, -1), results[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, 100), results[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 100), results[2].values[0].int);
+}
+
+test "server table_window count_distinct runs a distinct-city total over real TCP, matching local semantics" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // Sorted by total ascending: krakow/40, warsaw/100, warsaw/250 - distinct
+    // "city" running count grows 1 (krakow), 2 (warsaw joins), then stays 2
+    // (warsaw repeats).
+    const orderBy = [_]querymod.OrderBy{.{ .field = "total", .descending = false }};
+    const specs = [_]windowmod.WindowSpec{.{ .field = "city", .kind = .count_distinct }};
+    const results = try client.tableWindow(allocator, "orders", &specs, &.{}, &orderBy, 0, 0, "", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    try std.testing.expectEqual(@as(i64, 1), results[0].values[0].int);
+    try std.testing.expectEqual(@as(i64, 2), results[1].values[0].int);
+    try std.testing.expectEqual(@as(i64, 2), results[2].values[0].int);
+}
+
+test "server table_window applies the expr filter before annotating, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .count }};
+    const results = try client.tableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "city eq s:warsaw", .rows);
+    defer protocol.freeWindowRows(allocator, results);
+
+    try std.testing.expectEqual(@as(usize, 2), results.len);
+    for (results) |wr| try std.testing.expectEqual(@as(i64, 2), wr.values[0].int);
+}
+
+test "server table_window reports a malformed expr as bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .count }};
+    const err = client.tableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "city bogus s:warsaw", .rows);
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+test "server table_window reports a non-numeric sum field as bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const specs = [_]windowmod.WindowSpec{.{ .field = "city", .kind = .sum }};
+    const err = client.tableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "", .rows);
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+test "server table_window reports a sum spec with no field as bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedAggregateOrders(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // The CLI's `parseWindowSpec` would reject this before ever sending it,
+    // but nothing on the wire itself stops a client from asking for it -
+    // `window.computeMany`'s `MissingField` must come back as
+    // `bad_request`, not an internal server error.
+    const specs = [_]windowmod.WindowSpec{.{ .field = "", .kind = .sum }};
+    const err = client.tableWindow(allocator, "orders", &specs, &.{}, &.{}, 0, 0, "", .rows);
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+// `table_aggregate` shares the exact same underlying-sstable-reshaping
+// hazard as `table_select`/`table_join` above (see the `table_select`
+// concurrency test's header comment): `flush`/`compact` swap `Db.sstables`
+// out from under any in-flight reader while `Server.dispatch`'s `self.mutex`
+// is what keeps an aggregate's full-table scan (and the grouping/windowing
+// on top of it in `aggregate.zig`) from tearing. Thirty rows split evenly
+// three ways by `@mod(pk, 3)` so every group lands on an independently
+// checkable count and sum: pk%3==0 -> "warsaw" (pks 3,6,..,30, count 10, sum
+// 165), pk%3==1 -> "krakow" (pks 1,4,..,28, count 10, sum 145), pk%3==2 ->
+// "gdansk" (pks 2,5,..,29, count 10, sum 155) - global count 30, sum 465.
+test "table_aggregate survives concurrent flush and compact reshaping the underlying sstables" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    // Small target size so a handful of `flush`/`compact` calls do real
+    // structural work instead of needing megabytes of data first - same
+    // trick as the `table_select`/`table_join` concurrency tests above.
+    var db = try Db.open(allocator, path, .{ .sstableTargetBytes = 512 });
+    defer db.close();
+
+    const rowCount = 30;
+    {
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        var pk: i64 = 1;
+        while (pk <= rowCount) : (pk += 1) {
+            const city: []const u8 = switch (@mod(pk, 3)) {
+                0 => "warsaw",
+                1 => "krakow",
+                else => "gdansk",
+            };
+            try orders.put(.{ .int = pk }, &.{
+                .{ .name = "city", .value = .{ .text = city } },
+                .{ .name = "total", .value = .{ .int = pk } },
+            });
+        }
+        try db.flush();
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const readerThreads = 4;
+    const readerIters = 20;
+    const mutatorThreads = 2;
+    const mutatorIters = 15;
+
+    const expectedCount = struct {
+        fn get(city: []const u8) i64 {
+            return if (std.mem.eql(u8, city, "warsaw") or std.mem.eql(u8, city, "krakow") or std.mem.eql(u8, city, "gdansk")) 10 else -1;
+        }
+    }.get;
+    const expectedSum = struct {
+        fn get(city: []const u8) i64 {
+            if (std.mem.eql(u8, city, "warsaw")) return 165;
+            if (std.mem.eql(u8, city, "krakow")) return 145;
+            if (std.mem.eql(u8, city, "gdansk")) return 155;
+            return -1;
+        }
+    }.get;
+
+    const ReaderCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const readerWorker = struct {
+        fn run(ctx: *ReaderCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < readerIters) : (i += 1) {
+                const specs = [_]aggregatemod.AggSpec{
+                    .{ .field = "", .kind = .count },
+                    .{ .field = "total", .kind = .sum },
+                };
+                const groups = client.tableAggregateGroups(ctx.allocator, "orders", "city", &specs, 0, 0, &.{}, "", "") catch return;
+                defer protocol.freeAggGroupRows(ctx.allocator, groups);
+                if (groups.len != 3) return;
+                for (groups) |g| {
+                    if (g.values[0].int != expectedCount(g.group.text)) return;
+                    if (g.values[1].int != expectedSum(g.group.text)) return;
+                }
+
+                const global = client.tableAggregateGlobal(ctx.allocator, "orders", &specs, "", "") catch return;
+                defer protocol.freeAggValues(ctx.allocator, global);
+                if (global[0].int != rowCount) return;
+                if (global[1].int != 465) return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const MutatorCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+    const mutatorWorker = struct {
+        fn run(ctx: *MutatorCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < mutatorIters) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const key = std.fmt.bufPrint(&buf, "agg-churn-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.set(key, "x") catch return;
+                client.flush() catch return;
+                client.compact() catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var readerContexts: [readerThreads]ReaderCtx = undefined;
+    var readerHandles: [readerThreads]std.Thread = undefined;
+    for (0..readerThreads) |i| {
+        readerContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        readerHandles[i] = try std.Thread.spawn(.{}, readerWorker, .{&readerContexts[i]});
+    }
+    var mutatorContexts: [mutatorThreads]MutatorCtx = undefined;
+    var mutatorHandles: [mutatorThreads]std.Thread = undefined;
+    for (0..mutatorThreads) |i| {
+        mutatorContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        mutatorHandles[i] = try std.Thread.spawn(.{}, mutatorWorker, .{&mutatorContexts[i]});
+    }
+
+    for (0..readerThreads) |i| readerHandles[i].join();
+    for (0..mutatorThreads) |i| mutatorHandles[i].join();
+    for (0..readerThreads) |i| try std.testing.expect(readerContexts[i].ok);
+    for (0..mutatorThreads) |i| try std.testing.expect(mutatorContexts[i].ok);
+
+    // Final sanity check on a fresh connection: after all the concurrent
+    // churn, the aggregate results are still exactly what they were before
+    // the server ever started - the churn wrote only unrelated
+    // `agg-churn-*` keys and reshaped physical sstable layout, never touched
+    // `orders` values.
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    const specs = [_]aggregatemod.AggSpec{.{ .field = "", .kind = .count }};
+    const finalGroups = try client.tableAggregateGroups(allocator, "orders", "city", &specs, 0, 0, &.{}, "", "");
+    defer protocol.freeAggGroupRows(allocator, finalGroups);
+    try std.testing.expectEqual(@as(usize, 3), finalGroups.len);
+    for (finalGroups) |g| try std.testing.expectEqual(expectedCount(g.group.text), g.values[0].int);
+}
+
+fn seedJoinTables(allocator: Allocator, db: *Db) !void {
+    var customers = try querymod.Table.open(db, allocator, "customers");
+    defer customers.deinit();
+    try customers.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "alice" } }});
+    try customers.put(.{ .int = 2 }, &.{.{ .name = "name", .value = .{ .text = "bob" } }});
+    try customers.put(.{ .int = 3 }, &.{.{ .name = "name", .value = .{ .text = "carol" } }});
+
+    var orders = try querymod.Table.open(db, allocator, "orders");
+    defer orders.deinit();
+    try orders.put(.{ .int = 101 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 1 } },
+        .{ .name = "total", .value = .{ .int = 50 } },
+    });
+    try orders.put(.{ .int = 102 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 1 } },
+        .{ .name = "total", .value = .{ .int = 30 } },
+    });
+    try orders.put(.{ .int = 103 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 999 } },
+        .{ .name = "total", .value = .{ .int = 999 } },
+    });
+}
+
+test "server table_join runs a remote inner join, using an index when available" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedJoinTables(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const noIndex = try client.tableJoin(allocator, .inner, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, noIndex);
+    try std.testing.expectEqual(@as(usize, 2), noIndex.len);
+    for (noIndex) |p| {
+        try std.testing.expect(p.left != null);
+        try std.testing.expect(p.right != null);
+        try std.testing.expectEqualStrings("alice", p.left.?.get("name").?.text);
+    }
+
+    {
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createIndex("customer_id");
+    }
+    const withIndex = try client.tableJoin(allocator, .inner, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, withIndex);
+    try std.testing.expectEqual(@as(usize, 2), withIndex.len);
+}
+
+test "server table_join runs left, right, and full outer variants with predicates" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedJoinTables(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const left = try client.tableJoin(allocator, .left, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, left);
+    try std.testing.expectEqual(@as(usize, 4), left.len);
+    var carolUnmatched = false;
+    for (left) |p| {
+        if (p.left) |l| {
+            if (std.mem.eql(u8, l.get("name").?.text, "carol")) {
+                try std.testing.expect(p.right == null);
+                carolUnmatched = true;
+            }
+        }
+    }
+    try std.testing.expect(carolUnmatched);
+
+    const right = try client.tableJoin(allocator, .right, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, right);
+    try std.testing.expectEqual(@as(usize, 3), right.len);
+    var orphanOrderUnmatched = false;
+    for (right) |p| {
+        if (p.left == null) orphanOrderUnmatched = true;
+    }
+    try std.testing.expect(orphanOrderUnmatched);
+
+    const full = try client.tableJoin(allocator, .full, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, full);
+    try std.testing.expectEqual(@as(usize, 5), full.len);
+
+    // rightExprText filters the orders side before the join runs, same as
+    // `innerJoin`'s `rightPred` - narrowing to `total gt i:40` drops one of
+    // alice's two orders.
+    const filtered = try client.tableJoin(allocator, .inner, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "total gt i:40");
+    defer protocol.freeJoinPairs(allocator, filtered);
+    try std.testing.expectEqual(@as(usize, 1), filtered.len);
+    try std.testing.expectEqual(@as(i64, 50), filtered[0].right.?.get("total").?.int);
+}
+
+test "server table_join windows a real TCP result through offset and limit" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedJoinTables(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // Unpaged left outer join order: (alice,101) (alice,102) (bob,nil) (carol,nil).
+    const unpaged = try client.tableJoin(allocator, .left, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, unpaged);
+    try std.testing.expectEqual(@as(usize, 4), unpaged.len);
+
+    const windowed = try client.tableJoin(allocator, .left, "customers", querymod.pkField, "orders", "customer_id", 1, 2, "", "");
+    defer protocol.freeJoinPairs(allocator, windowed);
+    try std.testing.expectEqual(@as(usize, 2), windowed.len);
+    try std.testing.expectEqual(@as(i64, 30), windowed[0].right.?.get("total").?.int);
+    try std.testing.expectEqualStrings("bob", windowed[1].left.?.get("name").?.text);
+    try std.testing.expect(windowed[1].right == null);
+
+    const pastEnd = try client.tableJoin(allocator, .left, "customers", querymod.pkField, "orders", "customer_id", 50, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, pastEnd);
+    try std.testing.expectEqual(@as(usize, 0), pastEnd.len);
+}
+
+test "server table_join rejects a malformed expr with bad_request, not a crash" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    try seedJoinTables(allocator, &db);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const err = client.tableJoin(allocator, .inner, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "name bogus s:alice", "");
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, err);
+}
+
+// `table_select` is the only networked table opcode - rows can only be
+// written locally (CLI `table put`), never over the wire - so this cannot
+// reuse the coll_op "many writers, one shared counter" shape. What it CAN
+// share with a live server is the sstable storage underneath: `flush` and
+// `compact` (both real networked opcodes) mutate `Db.sstables` in place,
+// closing and destroying old `Reader`s and swapping in new ones while
+// `compact` in particular collapses the whole list down to a single file.
+// A `table_select` cursor concurrently mid-scan over those same readers is
+// exactly the use-after-free/torn-read shape a missing lock around
+// `Server.dispatch` would produce - `self.mutex` must serialize every
+// request regardless of which opcode it is, not just same-opcode traffic.
+test "table_select survives concurrent flush and compact reshaping the underlying sstables" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    // A small target size so a handful of `flush`/`compact` calls do real
+    // structural work instead of needing megabytes of data first.
+    var db = try Db.open(allocator, path, .{ .sstableTargetBytes = 512 });
+    defer db.close();
+
+    const rowCount = 30;
+    {
+        var table = try querymod.Table.open(&db, allocator, "people");
+        defer table.deinit();
+        var pk: i64 = 1;
+        while (pk <= rowCount) : (pk += 1) {
+            const city: []const u8 = switch (@mod(pk, 3)) {
+                0 => "warsaw",
+                1 => "krakow",
+                else => "gdansk",
+            };
+            try table.put(.{ .int = pk }, &.{
+                .{ .name = "city", .value = .{ .text = city } },
+                .{ .name = "age", .value = .{ .int = pk * 2 } },
+            });
+        }
+        try db.flush();
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const readerThreads = 4;
+    const readerIters = 40;
+    const mutatorThreads = 2;
+    const mutatorIters = 15;
+
+    const ReaderCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    // A multi-element order-by (city ascending, then age descending as a
+    // tiebreak within each city) - `handleTableSelect` decodes a wire
+    // orderBy count > 1 into `Table.selectPageOrdered`, which cannot
+    // early-stop mid-scan the way an unordered `selectPage` can, so it reads
+    // more of the table before sorting. This proves that path survives real
+    // `flush`/`compact` reshaping the underlying sstables mid-scan, not just
+    // the single-column order-by already covered by
+    // "orders a remote result by a field before windowing it" above.
+    const cityOrderBy = [_]querymod.OrderBy{
+        .{ .field = "city" },
+        .{ .field = "age", .descending = true },
+    };
+
+    const readerWorker = struct {
+        fn run(ctx: *ReaderCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < readerIters) : (i += 1) {
+                const warsawRows = client.tableSelect(ctx.allocator, "people", "city eq s:warsaw", 0, 0, &.{}) catch return;
+                defer protocol.freeRows(ctx.allocator, warsawRows);
+                if (warsawRows.len != rowCount / 3) return;
+
+                const allRows = client.tableSelect(ctx.allocator, "people", "", 0, 0, &.{}) catch return;
+                defer protocol.freeRows(ctx.allocator, allRows);
+                if (allRows.len != rowCount) return;
+                for (allRows) |row| {
+                    const pk = row.get(querymod.pkField) orelse return;
+                    const age = row.get("age") orelse return;
+                    if (age.int != pk.int * 2) return;
+                }
+
+                const ordered = client.tableSelect(ctx.allocator, "people", "", 0, 0, &cityOrderBy) catch return;
+                defer protocol.freeRows(ctx.allocator, ordered);
+                if (ordered.len != rowCount) return;
+                var prevCity: ?[]const u8 = null;
+                var prevAge: i64 = std.math.maxInt(i64);
+                for (ordered) |row| {
+                    const city = (row.get("city") orelse return).text;
+                    const age = (row.get("age") orelse return).int;
+                    if (prevCity) |pc| {
+                        const cmp = std.mem.order(u8, pc, city);
+                        if (cmp == .gt) return;
+                        if (cmp == .eq and age > prevAge) return;
+                        if (cmp != .eq) prevAge = std.math.maxInt(i64);
+                    }
+                    prevCity = city;
+                    prevAge = age;
+                }
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const MutatorCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+    const mutatorWorker = struct {
+        fn run(ctx: *MutatorCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < mutatorIters) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const key = std.fmt.bufPrint(&buf, "churn-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.set(key, "x") catch return;
+                client.flush() catch return;
+                client.compact() catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var readerContexts: [readerThreads]ReaderCtx = undefined;
+    var readerHandles: [readerThreads]std.Thread = undefined;
+    for (0..readerThreads) |i| {
+        readerContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        readerHandles[i] = try std.Thread.spawn(.{}, readerWorker, .{&readerContexts[i]});
+    }
+    var mutatorContexts: [mutatorThreads]MutatorCtx = undefined;
+    var mutatorHandles: [mutatorThreads]std.Thread = undefined;
+    for (0..mutatorThreads) |i| {
+        mutatorContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        mutatorHandles[i] = try std.Thread.spawn(.{}, mutatorWorker, .{&mutatorContexts[i]});
+    }
+
+    for (0..readerThreads) |i| readerHandles[i].join();
+    for (0..mutatorThreads) |i| mutatorHandles[i].join();
+    for (0..readerThreads) |i| try std.testing.expect(readerContexts[i].ok);
+    for (0..mutatorThreads) |i| try std.testing.expect(mutatorContexts[i].ok);
+
+    // Final sanity check on a fresh connection: after all the concurrent
+    // churn, the table data itself must be byte-for-byte what was written
+    // before the server ever started - `flush`/`compact` change physical
+    // layout, never live values.
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    const finalAll = try client.tableSelect(allocator, "people", "", 0, 0, &.{});
+    defer protocol.freeRows(allocator, finalAll);
+    try std.testing.expectEqual(@as(usize, rowCount), finalAll.len);
+    const finalWarsaw = try client.tableSelect(allocator, "people", "city eq s:warsaw", 0, 0, &.{});
+    defer protocol.freeRows(allocator, finalWarsaw);
+    try std.testing.expectEqual(@as(usize, rowCount / 3), finalWarsaw.len);
+
+    // Precise check of the multi-column order-by: city groups sorted
+    // alphabetically (gdansk < krakow < warsaw), each group internally by
+    // age (== pk*2) descending. pk%3 maps 2->gdansk, 1->krakow, 0->warsaw,
+    // so each group's highest pk (== highest age) leads that group.
+    const finalOrdered = try client.tableSelect(allocator, "people", "", 0, 0, &cityOrderBy);
+    defer protocol.freeRows(allocator, finalOrdered);
+    try std.testing.expectEqual(@as(usize, rowCount), finalOrdered.len);
+    try std.testing.expectEqualStrings("gdansk", finalOrdered[0].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 29), finalOrdered[0].get(querymod.pkField).?.int);
+    try std.testing.expectEqualStrings("gdansk", finalOrdered[9].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 2), finalOrdered[9].get(querymod.pkField).?.int);
+    try std.testing.expectEqualStrings("krakow", finalOrdered[10].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 28), finalOrdered[10].get(querymod.pkField).?.int);
+    try std.testing.expectEqualStrings("krakow", finalOrdered[19].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 1), finalOrdered[19].get(querymod.pkField).?.int);
+    try std.testing.expectEqualStrings("warsaw", finalOrdered[20].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 30), finalOrdered[20].get(querymod.pkField).?.int);
+    try std.testing.expectEqualStrings("warsaw", finalOrdered[29].get("city").?.text);
+    try std.testing.expectEqual(@as(i64, 3), finalOrdered[29].get(querymod.pkField).?.int);
+}
+
+// `table_join` shares the exact same underlying-sstable-reshaping hazard as
+// `table_select` above (see that test's header comment) - `flush`/`compact`
+// swap `Db.sstables` out from under any in-flight reader while
+// `Server.dispatch`'s `self.mutex` is what keeps a join's two-table scan
+// from tearing. Ten customers / ten orders, deliberately NOT 1:1: two
+// customers (9, 10) never appear in `orders`, and two orders (9, 10) carry a
+// `customer_id` nobody has, so inner/left/right/full each land on a
+// different, independently-checkable pair count instead of degenerating to
+// the same number.
+fn seedJoinConcurrencyTables(allocator: Allocator, db: *Db) !void {
+    var customers = try querymod.Table.open(db, allocator, "customers");
+    defer customers.deinit();
+    var pk: i64 = 1;
+    while (pk <= 10) : (pk += 1) {
+        var buf: [16]u8 = undefined;
+        const name = try std.fmt.bufPrint(&buf, "cust{d}", .{pk});
+        try customers.put(.{ .int = pk }, &.{.{ .name = "name", .value = .{ .text = name } }});
+    }
+
+    var orders = try querymod.Table.open(db, allocator, "orders");
+    defer orders.deinit();
+    pk = 1;
+    while (pk <= 8) : (pk += 1) {
+        try orders.put(.{ .int = pk }, &.{
+            .{ .name = "customer_id", .value = .{ .int = pk } },
+            .{ .name = "total", .value = .{ .int = pk * 10 } },
+        });
+    }
+    try orders.put(.{ .int = 9 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 999 } },
+        .{ .name = "total", .value = .{ .int = 900 } },
+    });
+    try orders.put(.{ .int = 10 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 998 } },
+        .{ .name = "total", .value = .{ .int = 800 } },
+    });
+}
+
+test "table_join survives concurrent flush and compact reshaping the underlying sstables" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    // Small target size so a handful of `flush`/`compact` calls do real
+    // structural work instead of needing megabytes of data first - same
+    // trick as the `table_select` concurrency test above.
+    var db = try Db.open(allocator, path, .{ .sstableTargetBytes = 512 });
+    defer db.close();
+    try seedJoinConcurrencyTables(allocator, &db);
+    try db.flush();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const readerThreads = 4;
+    const readerIters = 20;
+    const mutatorThreads = 2;
+    const mutatorIters = 15;
+    const matchedCount = 8;
+    const customerCount = 10;
+
+    const ReaderCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+    const readerWorker = struct {
+        fn run(ctx: *ReaderCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < readerIters) : (i += 1) {
+                const inner = client.tableJoin(ctx.allocator, .inner, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "") catch return;
+                defer protocol.freeJoinPairs(ctx.allocator, inner);
+                if (inner.len != matchedCount) return;
+                for (inner) |pair| {
+                    const left = pair.left orelse return;
+                    const right = pair.right orelse return;
+                    const pk = left.get(querymod.pkField) orelse return;
+                    const total = right.get("total") orelse return;
+                    if (total.int != pk.int * 10) return;
+                }
+
+                const left = client.tableJoin(ctx.allocator, .left, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "") catch return;
+                defer protocol.freeJoinPairs(ctx.allocator, left);
+                if (left.len != customerCount) return;
+
+                const right = client.tableJoin(ctx.allocator, .right, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "") catch return;
+                defer protocol.freeJoinPairs(ctx.allocator, right);
+                if (right.len != matchedCount + 2) return;
+
+                const full = client.tableJoin(ctx.allocator, .full, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "") catch return;
+                defer protocol.freeJoinPairs(ctx.allocator, full);
+                if (full.len != customerCount + 2) return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const MutatorCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+    const mutatorWorker = struct {
+        fn run(ctx: *MutatorCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < mutatorIters) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const key = std.fmt.bufPrint(&buf, "join-churn-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.set(key, "x") catch return;
+                client.flush() catch return;
+                client.compact() catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var readerContexts: [readerThreads]ReaderCtx = undefined;
+    var readerHandles: [readerThreads]std.Thread = undefined;
+    for (0..readerThreads) |i| {
+        readerContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        readerHandles[i] = try std.Thread.spawn(.{}, readerWorker, .{&readerContexts[i]});
+    }
+    var mutatorContexts: [mutatorThreads]MutatorCtx = undefined;
+    var mutatorHandles: [mutatorThreads]std.Thread = undefined;
+    for (0..mutatorThreads) |i| {
+        mutatorContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        mutatorHandles[i] = try std.Thread.spawn(.{}, mutatorWorker, .{&mutatorContexts[i]});
+    }
+
+    for (0..readerThreads) |i| readerHandles[i].join();
+    for (0..mutatorThreads) |i| mutatorHandles[i].join();
+    for (0..readerThreads) |i| try std.testing.expect(readerContexts[i].ok);
+    for (0..mutatorThreads) |i| try std.testing.expect(mutatorContexts[i].ok);
+
+    // Final sanity check on a fresh connection: all four join shapes are
+    // still exactly what they were before the server ever started - the
+    // concurrent churn wrote only unrelated `join-churn-*` keys and
+    // reshaped physical sstable layout, never touched `customers`/`orders`
+    // values.
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    const finalInner = try client.tableJoin(allocator, .inner, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, finalInner);
+    try std.testing.expectEqual(@as(usize, matchedCount), finalInner.len);
+    const finalFull = try client.tableJoin(allocator, .full, "customers", querymod.pkField, "orders", "customer_id", 0, 0, "", "");
+    defer protocol.freeJoinPairs(allocator, finalFull);
+    try std.testing.expectEqual(@as(usize, customerCount + 2), finalFull.len);
+}
+
+test "server without enableAuth accepts any auth attempt and every op" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.authenticate("nobody", "wrong");
+    try client.set("k", "v");
+}
+
+test "server with auth enabled rejects unauthenticated requests, ping excepted" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.ping();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, client.get(allocator, "k"));
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, client.set("k", "v"));
+    try std.testing.expectEqual(@as(u64, 2), server.unauthorizedTotal.get());
+}
+
+test "server rejects a bad password and accepts the correct one, then serves requests" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, client.authenticate("alice", "wrong"));
+    try client.authenticate("alice", "hunter2");
+
+    try client.set("k", "v");
+    const got = try client.get(allocator, "k");
+    defer if (got) |g| allocator.free(g);
+    try std.testing.expectEqualStrings("v", got.?);
+}
+
+test "server enforces readonly role: reads succeed, writes are forbidden" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "viewer", "pass", .readonly, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.authenticate("viewer", "pass");
+    const got = try client.get(allocator, "missing");
+    try std.testing.expect(got == null);
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, client.set("k", "v"));
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, client.delete("k"));
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, client.compact());
+    const txnEntries = [_]protocol.TxnOpEntry{
+        .{ .verb = .put, .table = "accounts", .pk = .{ .int = 1 } },
+    };
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, client.txnOp(&txnEntries));
+    try std.testing.expectEqual(@as(u64, 4), server.forbiddenTotal.get());
+}
+
+test "server without enableSessions returns no token from authenticate" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.authenticate("alice", "hunter2");
+    try std.testing.expect(client.sessionToken() == null);
+}
+
+test "a session token from one connection authenticates a brand new connection without a password" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    var sessions = sessionmod.SessionStore.init(allocator);
+    defer sessions.deinit();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    server.enableSessions(&sessions, 60 * std.time.ns_per_s);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+
+    var first = try client_mod.Client.connect(allocator, server.boundAddress());
+    try first.authenticate("alice", "hunter2");
+    const token = try allocator.dupe(u8, first.sessionToken().?);
+    defer allocator.free(token);
+    first.close();
+
+    // A fully independent second connection, never given the password.
+    var second = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer second.close();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, second.get(allocator, "k"));
+    try second.authenticateWithToken(token);
+    try second.set("k", "v");
+    const got = try second.get(allocator, "k");
+    defer if (got) |g| allocator.free(g);
+    try std.testing.expectEqualStrings("v", got.?);
+}
+
+test "auth_token is rejected as unauthorized when sessions are not enabled" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, client.authenticateWithToken("whatever"));
+}
+
+test "an unknown or garbage session token is rejected" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    var sessions = sessionmod.SessionStore.init(allocator);
+    defer sessions.deinit();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    server.enableSessions(&sessions, 60 * std.time.ns_per_s);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, client.authenticateWithToken("not-a-real-token"));
+}
+
+test "an expired session forces re-authentication even on the same open connection" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    var sessions = sessionmod.SessionStore.init(allocator);
+    defer sessions.deinit();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    server.enableSessions(&sessions, 500 * std.time.ns_per_ms);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.authenticate("alice", "hunter2");
+    try client.set("k", "v");
+
+    std.time.sleep(700 * std.time.ns_per_ms);
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, client.get(allocator, "k"));
+    try std.testing.expectEqual(@as(u64, 1), server.sessionExpiredTotal.get());
+
+    // The very same connection re-authenticates and keeps working - the
+    // socket itself was never the thing that expired, only the session.
+    try client.authenticate("alice", "hunter2");
+    const got = try client.get(allocator, "k");
+    defer if (got) |g| allocator.free(g);
+    try std.testing.expectEqualStrings("v", got.?);
+}
+
+test "each connection authenticates independently under auth enforcement" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var clientA = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer clientA.close();
+    var clientB = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer clientB.close();
+
+    try clientA.authenticate("alice", "hunter2");
+    try clientA.set("shared", "1");
+
+    // clientB never authenticated - a separate socket does not inherit
+    // clientA's role even though it hits the exact same server/store.
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, clientB.get(allocator, "shared"));
+}
+
+test "server without auth enabled allows user_admin to create and list users" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.adminCreateUser("alice", "hunter2", .readwrite, 16);
+    const users = try client.adminListUsers(allocator);
+    defer authmod.freeUserList(allocator, users);
+    try std.testing.expectEqual(@as(usize, 1), users.len);
+    try std.testing.expectEqualStrings("alice", users[0].username);
+    try std.testing.expectEqual(authmod.Role.readwrite, users[0].role);
+
+    // The account just created over the wire really works for real auth.
+    var second = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer second.close();
+    try second.authenticate("alice", "hunter2");
+}
+
+test "user_admin requires admin role once auth is enabled" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "root", "toor", .admin, 16);
+    try store.createUser(allocator, "viewer", "pass", .readonly, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+
+    var viewer = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer viewer.close();
+    try viewer.authenticate("viewer", "pass");
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, viewer.adminCreateUser("nobody", "x", .readonly, 16));
+
+    var admin = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer admin.close();
+    try admin.authenticate("root", "toor");
+    try admin.adminCreateUser("bob", "b-pass", .readwrite, 16);
+
+    const users = try admin.adminListUsers(allocator);
+    defer authmod.freeUserList(allocator, users);
+    try std.testing.expectEqual(@as(usize, 3), users.len);
+}
+
+test "user_admin set_password, set_role, and delete round trip over the wire, enforced by real auth" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "root", "toor", .admin, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var admin = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer admin.close();
+    try admin.authenticate("root", "toor");
+
+    try admin.adminCreateUser("alice", "old-pass", .readonly, 16);
+
+    // The freshly created account really authenticates against the live,
+    // enforced auth store - not just written to a table nobody checks.
+    var probe = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer probe.close();
+    try probe.authenticate("alice", "old-pass");
+
+    try admin.adminSetPassword("alice", "new-pass", 16);
+    var probe2 = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer probe2.close();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, probe2.authenticate("alice", "old-pass"));
+    try probe2.authenticate("alice", "new-pass");
+
+    try admin.adminSetRole("alice", .admin);
+    const users = try admin.adminListUsers(allocator);
+    defer authmod.freeUserList(allocator, users);
+    var sawAlice = false;
+    for (users) |u| {
+        if (std.mem.eql(u8, u.username, "alice")) {
+            try std.testing.expectEqual(authmod.Role.admin, u.role);
+            sawAlice = true;
+        }
+    }
+    try std.testing.expect(sawAlice);
+
+    try admin.adminDeleteUser("alice");
+    var probe3 = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer probe3.close();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, probe3.authenticate("alice", "new-pass"));
+}
+
+test "user_admin reports conflict on duplicate create and not-found on missing user" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.adminCreateUser("alice", "hunter2", .readonly, 16);
+    try std.testing.expectError(client_mod.ClientError.ServerConflict, client.adminCreateUser("alice", "other", .admin, 16));
+    try std.testing.expectError(client_mod.ClientError.ServerUserNotFound, client.adminSetPassword("ghost", "x", 16));
+    try std.testing.expectError(client_mod.ClientError.ServerUserNotFound, client.adminSetRole("ghost", .admin));
+    try std.testing.expectError(client_mod.ClientError.ServerUserNotFound, client.adminDeleteUser("ghost"));
+}
+
+test "server rejects a malformed user_admin frame with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.user_admin), "\x00");
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+}
+
+test "server metrics register into an external Prometheus registry" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableRateLimit(1, 1000);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    try client.ping();
+    client.ping() catch {};
+
+    var reg = metrics.Registry.init(allocator);
+    defer reg.deinit();
+    try server.registerMetrics(&reg);
+
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    try reg.exportText(allocator, buf.writer());
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_requests_total 2\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_rate_limited_total 1\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_conn_rate_limited_total 0\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_unauthorized_total 0\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_forbidden_total 0\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_session_expired_total 0\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_sessions_swept_total 0\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, buf.items, "cobalt_server_ttl_swept_total 0\n") != null);
+}
+
+test "client.metricsText fetches the server's own counters and db stats over the wire in one payload" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.set("a", "1");
+    try client.set("b", "2");
+    try client.ping();
+
+    const text = try client.metricsText(allocator);
+    defer allocator.free(text);
+
+    // Server's own request counter: 2 sets + 1 ping + this very metrics
+    // request itself, all counted in `requestsTotal` before dispatch even
+    // looks at the opcode.
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_server_requests_total 4\n") != null);
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_server_rate_limited_total 0\n") != null);
+    // Db stats rendered by the same `formatDbStats` `stats --prom` uses
+    // locally, appended after the server's own counters in one response.
+    try std.testing.expect(std.mem.indexOf(u8, text, "cobalt_memtable_entries 2\n") != null);
+}
+
+test "server gates the metrics opcode behind readonly role like every other read op" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "reader", "pw", .readonly, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var unauthed = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer unauthed.close();
+    try std.testing.expectError(error.ServerUnauthorized, unauthed.metricsText(allocator));
+
+    var reader = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer reader.close();
+    try reader.authenticate("reader", "pw");
+    const text = try reader.metricsText(allocator);
+    allocator.free(text);
+}
+
+test "enableSessionSweep periodically drops expired sessions nobody ever presents again" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    var sessions = sessionmod.SessionStore.init(allocator);
+    defer sessions.deinit();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    // A short-lived session that nobody will ever present again: without
+    // the sweeper, this sits in `sessions` forever since `validate()` only
+    // cleans up a token someone actually tries to use.
+    server.enableSessions(&sessions, 100 * std.time.ns_per_ms);
+    server.enableSessionSweep(50 * std.time.ns_per_ms);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    try client.authenticate("alice", "hunter2");
+    client.close();
+
+    try std.testing.expectEqual(@as(usize, 1), sessions.count());
+
+    // Long enough for the session to expire (100ms) and for at least one
+    // sweep tick (every 50ms) to have run past that point.
+    std.time.sleep(400 * std.time.ns_per_ms);
+
+    try std.testing.expectEqual(@as(usize, 0), sessions.count());
+    try std.testing.expect(server.sessionsSweptTotal.get() >= 1);
+}
+
+test "a server with sessions enabled but no sweep interval never sweeps" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "alice", "hunter2", .readwrite, 16);
+
+    var sessions = sessionmod.SessionStore.init(allocator);
+    defer sessions.deinit();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    server.enableSessions(&sessions, 50 * std.time.ns_per_ms);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    try client.authenticate("alice", "hunter2");
+    client.close();
+
+    std.time.sleep(200 * std.time.ns_per_ms);
+
+    // The session expired a while ago, but with no sweeper running it is
+    // still sitting in the store's map until something calls `validate` on
+    // it - `count()` still sees it, unlike the sweeper test above.
+    try std.testing.expectEqual(@as(usize, 1), sessions.count());
+    try std.testing.expectEqual(@as(u64, 0), server.sessionsSweptTotal.get());
+}
+
+test "ttl_op over the wire: expire, query, persist, and sweep round trip against a real server" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // A key with no ttl at all reads back .noExpiry, not .noKey.
+    try client.set("plain", "v");
+    try std.testing.expectEqual(ttlmod.TtlResult.noExpiry, try client.ttlQuery("plain"));
+
+    // expire on a key that does not exist is a real, distinct failure.
+    try std.testing.expectError(client_mod.ClientError.ServerKeyNotFound, client.ttlExpire("ghost", 60));
+
+    // expire on an existing key sets a marker the query action can see.
+    // Real wall-clock time (both `expire` and `query` stamp their own
+    // `std.time.nanoTimestamp()` server-side) can shave a second off by
+    // the time the second round trip lands, so accept 59 or 60 rather
+    // than pinning an exact value.
+    try client.ttlExpire("plain", 60);
+    const withTtl = try client.ttlQuery("plain");
+    try std.testing.expect(withTtl.seconds == 59 or withTtl.seconds == 60);
+
+    // persist removes the marker again, back to .noExpiry.
+    try client.ttlPersist("plain");
+    try std.testing.expectEqual(ttlmod.TtlResult.noExpiry, try client.ttlQuery("plain"));
+
+    // sweep over a key that is already due for expiry reaps exactly it,
+    // and a real subsequent get proves the delete was real, not marker-only.
+    try client.set("doomed", "x");
+    try client.ttlExpire("doomed", 0);
+    std.time.sleep(5 * std.time.ns_per_ms);
+    const reaped = try client.ttlSweep();
+    try std.testing.expectEqual(@as(u64, 1), reaped);
+    try std.testing.expectEqual(@as(?[]u8, null), try client.get(allocator, "doomed"));
+
+    // querying a key that was never there at all (not merely expired) is
+    // .noKey, distinct from .noExpiry.
+    try std.testing.expectEqual(ttlmod.TtlResult.noKey, try client.ttlQuery("never-existed"));
+}
+
+test "ttl_op gates query as readonly and expire as readwrite" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "reader", "pw", .readonly, 16);
+    try store.createUser(allocator, "writer", "pw", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+
+    var writer = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer writer.close();
+    try writer.authenticate("writer", "pw");
+    try writer.set("k", "v");
+
+    var reader = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer reader.close();
+    try reader.authenticate("reader", "pw");
+
+    // query is readonly: a readonly connection can run it.
+    try std.testing.expectEqual(ttlmod.TtlResult.noExpiry, try reader.ttlQuery("k"));
+
+    // expire/persist/sweep all mutate: forbidden for a readonly connection.
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, reader.ttlExpire("k", 30));
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, reader.ttlPersist("k"));
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, reader.ttlSweep());
+
+    // The readwrite connection can do all four.
+    try writer.ttlExpire("k", 30);
+    try writer.ttlPersist("k");
+    _ = try writer.ttlSweep();
+}
+
+test "server rejects a malformed ttl_op frame with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.ttl_op), "\x09");
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+}
+
+test "enableTtlSweep periodically reaps due keys nobody ever reads again" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableTtlSweep(50 * std.time.ns_per_ms);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.set("a", "1");
+    try client.ttlExpire("a", 0);
+
+    // Long enough for the key to be due and for at least one sweep tick
+    // (every 50ms) to run past that point - nobody ever reads "a" again,
+    // so without the background sweeper it would sit there forever (only
+    // `ttl.getLive`'s lazy path or an explicit sweep would ever catch it).
+    std.time.sleep(300 * std.time.ns_per_ms);
+
+    try std.testing.expectEqual(@as(?[]u8, null), try client.get(allocator, "a"));
+    try std.testing.expect(server.ttlSweptTotal.get() >= 1);
+}
+
+test "a server with no ttl sweep interval never runs the ttl sweeper" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.set("a", "1");
+    try client.ttlExpire("a", 0);
+    std.time.sleep(100 * std.time.ns_per_ms);
+
+    // Nothing swept it in the background, but the key IS logically due -
+    // client.get goes straight through db.get (not the lazy ttl path), so
+    // the underlying value is still physically present until something
+    // sweeps it.
+    try std.testing.expectEqual(@as(u64, 0), server.ttlSweptTotal.get());
+    const v = (try client.get(allocator, "a")).?;
+    allocator.free(v);
+}
+
+test "coll_ttl_op over the wire: expire, query, persist, and sweep round trip against a real server" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // A hash with no ttl at all reads back .noExpiry, not .noKey - the
+    // collection itself has to actually exist server-side first, created
+    // directly through `db` here for brevity (the `coll_op` opcode below
+    // is this same test file's own coverage for reaching it remotely).
+    _ = try collmod.Hash.set(&db, allocator, "profile", "name", "ada");
+    try std.testing.expectEqual(ttlmod.TtlResult.noExpiry, try client.collTtlQuery(.hash, "profile"));
+
+    // expire on a collection that does not exist is a real, distinct failure.
+    try std.testing.expectError(client_mod.ClientError.ServerCollectionNotFound, client.collTtlExpire(.hash, "ghost", 60));
+
+    // expire on an existing collection sets a marker the query action can
+    // see. Real wall-clock time can shave a second off by the time the
+    // second round trip lands, so accept 59 or 60 rather than an exact value.
+    try client.collTtlExpire(.hash, "profile", 60);
+    const withTtl = try client.collTtlQuery(.hash, "profile");
+    try std.testing.expect(withTtl.seconds == 59 or withTtl.seconds == 60);
+
+    // persist removes the marker again, back to .noExpiry.
+    try client.collTtlPersist(.hash, "profile");
+    try std.testing.expectEqual(ttlmod.TtlResult.noExpiry, try client.collTtlQuery(.hash, "profile"));
+
+    // sweep over a collection that is already due for expiry reaps exactly
+    // it, and the whole hash (not just one field) is really gone afterwards.
+    _ = try collmod.Hash.set(&db, allocator, "doomed", "k", "v");
+    try client.collTtlExpire(.hash, "doomed", 0);
+    std.time.sleep(5 * std.time.ns_per_ms);
+    const reaped = try client.collTtlSweep();
+    try std.testing.expectEqual(@as(u64, 1), reaped);
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .hash, "doomed"));
+
+    // querying a collection that was never there at all (not merely
+    // expired) is .noKey, distinct from .noExpiry.
+    try std.testing.expectEqual(ttlmod.TtlResult.noKey, try client.collTtlQuery(.set, "never-existed"));
+}
+
+test "coll_ttl_op gates query as readonly and expire as readwrite" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    _ = try collmod.Hash.set(&db, allocator, "k", "f", "v");
+
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "reader", "pw", .readonly, 16);
+    try store.createUser(allocator, "writer", "pw", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+
+    var writer = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer writer.close();
+    try writer.authenticate("writer", "pw");
+
+    var reader = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer reader.close();
+    try reader.authenticate("reader", "pw");
+
+    // query is readonly: a readonly connection can run it.
+    try std.testing.expectEqual(ttlmod.TtlResult.noExpiry, try reader.collTtlQuery(.hash, "k"));
+
+    // expire/persist/sweep all mutate: forbidden for a readonly connection.
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, reader.collTtlExpire(.hash, "k", 30));
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, reader.collTtlPersist(.hash, "k"));
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, reader.collTtlSweep());
+
+    // The readwrite connection can do all four.
+    try writer.collTtlExpire(.hash, "k", 30);
+    try writer.collTtlPersist(.hash, "k");
+    _ = try writer.collTtlSweep();
+}
+
+test "server rejects a malformed coll_ttl_op frame with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    // A single byte is enough for an action but not the kind byte that
+    // must follow it, so `decodeCollTtlOp` fails on the second `takeByte`.
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.coll_ttl_op), "\x02");
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+}
+
+test "enableCollTtlSweep periodically reaps due collections nobody ever touches again" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableCollTtlSweep(50 * std.time.ns_per_ms);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    _ = try collmod.ZSet.add(&db, allocator, "board", "alice", 10);
+    try client.collTtlExpire(.zset, "board", 0);
+
+    // Long enough for the collection to be due and for at least one sweep
+    // tick (every 50ms) to run past that point - nobody ever reads "board"
+    // again, so without the background sweeper it would sit there forever.
+    std.time.sleep(300 * std.time.ns_per_ms);
+
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .zset, "board"));
+    try std.testing.expect(server.collTtlSweptTotal.get() >= 1);
+}
+
+test "a server with no coll ttl sweep interval never runs the coll ttl sweeper" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    _ = try collmod.Set.add(&db, allocator, "tags", "zig");
+    try client.collTtlExpire(.set, "tags", 0);
+    std.time.sleep(100 * std.time.ns_per_ms);
+
+    // Nothing swept it in the background, but the collection IS logically
+    // due - it is still physically present until something sweeps it.
+    try std.testing.expectEqual(@as(u64, 0), server.collTtlSweptTotal.get());
+    try std.testing.expect(try collmod.collectionExists(&db, allocator, .set, "tags"));
+}
+
+test "a server with the flat ttl sweeper and the coll ttl sweeper enabled at once runs both independently" {
+    // Every prior session's notes on both sweepers flagged the same gap:
+    // `enableTtlSweep` and `enableCollTtlSweep` start two structurally
+    // independent background threads on the same `Server` (separate
+    // fields, separate `std.Thread.spawn` calls, separate join calls in
+    // `stop()`), but nothing had ever exercised them running at the same
+    // time. This proves three things at once: a flat key due for
+    // expiry and a whole collection due for expiry both get reaped by
+    // their OWN sweeper without either one starving or double-counting
+    // the other's target, and `stop()` cleanly joins both sweeper threads
+    // (the exact bug class caught and fixed in session #28, where a
+    // missing join on one sweeper thread left it alive past `db.close()`
+    // and segfaulted the next test).
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableTtlSweep(50 * std.time.ns_per_ms);
+    server.enableCollTtlSweep(50 * std.time.ns_per_ms);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try client.set("flatkey", "1");
+    try client.ttlExpire("flatkey", 0);
+    _ = try collmod.Hash.set(&db, allocator, "session:1", "user", "ada");
+    try client.collTtlExpire(.hash, "session:1", 0);
+
+    // Poll rather than sleep a single fixed window: two background
+    // sweeper threads plus the accept/connection threads contending for
+    // `self.mutex` on a loaded host can occasionally push either sweeper's
+    // tick past a fixed 300ms, which is not a correctness bug in the
+    // sweeper - it is exactly the kind of host-load flakiness this
+    // project's own frostbyte sessions document repeatedly. Waiting up to
+    // 3s in 50ms increments keeps the assertion meaningful (still fails
+    // for real if a sweeper never runs) without being a coin flip on a
+    // busy machine.
+    var waited: u64 = 0;
+    while (waited < 3000 and (server.ttlSweptTotal.get() == 0 or server.collTtlSweptTotal.get() == 0)) {
+        std.time.sleep(50 * std.time.ns_per_ms);
+        waited += 50;
+    }
+
+    try std.testing.expectEqual(@as(?[]u8, null), try client.get(allocator, "flatkey"));
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .hash, "session:1"));
+    try std.testing.expect(server.ttlSweptTotal.get() >= 1);
+    try std.testing.expect(server.collTtlSweptTotal.get() >= 1);
+
+    // Neither sweeper's counter absorbed the other's reap: exactly one
+    // flat key was due and exactly one collection was due, so each
+    // counter reads exactly 1, not a shared/blended total.
+    try std.testing.expectEqual(@as(u64, 1), server.ttlSweptTotal.get());
+    try std.testing.expectEqual(@as(u64, 1), server.collTtlSweptTotal.get());
+}
+
+test "coll_op over the wire exercises all five collection kinds against a real server" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // Counter: get on a name nobody ever touched defaults to 0, set
+    // pins an exact value, incrby accumulates - the same three-step
+    // shape `collections.test.counter incrBy accumulates` already
+    // covers locally, now round-tripped over the wire.
+    {
+        var got = try client.collOp(allocator, .counter_get, "visits", &.{});
+        defer got.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 0), got.int);
+
+        var setReply = try client.collOp(allocator, .counter_set, "visits", &[_][]const u8{"10"});
+        defer setReply.deinit(allocator);
+        try std.testing.expect(setReply == .ok);
+
+        var incrReply = try client.collOp(allocator, .counter_incrby, "visits", &[_][]const u8{"5"});
+        defer incrReply.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 15), incrReply.int);
+    }
+
+    // Hash: set reports created vs updated as 1/0, get returns the
+    // value or nil, del removes a field, len/getall reflect what remains.
+    {
+        var created = try client.collOp(allocator, .hash_set, "profile", &[_][]const u8{ "name", "ada" });
+        defer created.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 1), created.int);
+
+        var updated = try client.collOp(allocator, .hash_set, "profile", &[_][]const u8{ "name", "grace" });
+        defer updated.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 0), updated.int);
+
+        _ = try client.collOp(allocator, .hash_set, "profile", &[_][]const u8{ "age", "36" });
+
+        var got = try client.collOp(allocator, .hash_get, "profile", &[_][]const u8{"name"});
+        defer got.deinit(allocator);
+        try std.testing.expectEqualStrings("grace", got.bytes);
+
+        var missing = try client.collOp(allocator, .hash_get, "profile", &[_][]const u8{"ghost"});
+        defer missing.deinit(allocator);
+        try std.testing.expect(missing == .nil);
+
+        var lenReply = try client.collOp(allocator, .hash_len, "profile", &.{});
+        defer lenReply.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 2), lenReply.int);
+
+        var delReply = try client.collOp(allocator, .hash_del, "profile", &[_][]const u8{"age"});
+        defer delReply.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 1), delReply.int);
+
+        var all = try client.collOp(allocator, .hash_getall, "profile", &.{});
+        defer all.deinit(allocator);
+        try std.testing.expectEqual(@as(usize, 1), all.pairList.len);
+        try std.testing.expectEqualStrings("name", all.pairList[0].field);
+        try std.testing.expectEqualStrings("grace", all.pairList[0].value);
+    }
+
+    // Set: add/rem/ismember/card/members plus the three multi-set ops,
+    // where `name` is the first set and the extra `args` are the rest -
+    // the same split `runColl` uses locally for `args[0]` vs `args[1..]`.
+    {
+        _ = try client.collOp(allocator, .set_add, "a", &[_][]const u8{"x"});
+        _ = try client.collOp(allocator, .set_add, "a", &[_][]const u8{"y"});
+        _ = try client.collOp(allocator, .set_add, "b", &[_][]const u8{"y"});
+        _ = try client.collOp(allocator, .set_add, "b", &[_][]const u8{"z"});
+
+        var isMem = try client.collOp(allocator, .set_ismember, "a", &[_][]const u8{"x"});
+        defer isMem.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 1), isMem.int);
+
+        var card = try client.collOp(allocator, .set_card, "a", &.{});
+        defer card.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 2), card.int);
+
+        var inter = try client.collOp(allocator, .set_inter, "a", &[_][]const u8{"b"});
+        defer inter.deinit(allocator);
+        try std.testing.expectEqual(@as(usize, 1), inter.stringList.len);
+        try std.testing.expectEqualStrings("y", inter.stringList[0]);
+
+        var uni = try client.collOp(allocator, .set_union, "a", &[_][]const u8{"b"});
+        defer uni.deinit(allocator);
+        try std.testing.expectEqual(@as(usize, 3), uni.stringList.len);
+
+        var diff = try client.collOp(allocator, .set_diff, "a", &[_][]const u8{"b"});
+        defer diff.deinit(allocator);
+        try std.testing.expectEqual(@as(usize, 1), diff.stringList.len);
+        try std.testing.expectEqualStrings("x", diff.stringList[0]);
+
+        var rem = try client.collOp(allocator, .set_rem, "a", &[_][]const u8{"x"});
+        defer rem.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 1), rem.int);
+    }
+
+    // List: push both ends, pop both ends, range with a redis-style
+    // negative index, len reflecting what remains.
+    {
+        _ = try client.collOp(allocator, .list_rpush, "queue", &[_][]const u8{"one"});
+        _ = try client.collOp(allocator, .list_rpush, "queue", &[_][]const u8{"two"});
+        _ = try client.collOp(allocator, .list_lpush, "queue", &[_][]const u8{"zero"});
+
+        var ranged = try client.collOp(allocator, .list_range, "queue", &[_][]const u8{ "0", "-1" });
+        defer ranged.deinit(allocator);
+        try std.testing.expectEqual(@as(usize, 3), ranged.stringList.len);
+        try std.testing.expectEqualStrings("zero", ranged.stringList[0]);
+        try std.testing.expectEqualStrings("two", ranged.stringList[2]);
+
+        var popped = try client.collOp(allocator, .list_lpop, "queue", &.{});
+        defer popped.deinit(allocator);
+        try std.testing.expectEqualStrings("zero", popped.bytes);
+
+        var lenReply = try client.collOp(allocator, .list_len, "queue", &.{});
+        defer lenReply.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 2), lenReply.int);
+
+        var emptyPop = try client.collOp(allocator, .list_rpop, "never-existed", &.{});
+        defer emptyPop.deinit(allocator);
+        try std.testing.expect(emptyPop == .nil);
+    }
+
+    // ZSet: add/incrby/score/rank/card/rangebyrank/rangebyscore, with a
+    // real fractional score to exercise the f64 wire encoding end to end.
+    {
+        _ = try client.collOp(allocator, .zset_add, "board", &[_][]const u8{ "alice", "10.5" });
+        _ = try client.collOp(allocator, .zset_add, "board", &[_][]const u8{ "bob", "20" });
+
+        var score = try client.collOp(allocator, .zset_score, "board", &[_][]const u8{"alice"});
+        defer score.deinit(allocator);
+        try std.testing.expectEqual(@as(f64, 10.5), score.real);
+
+        var incr = try client.collOp(allocator, .zset_incrby, "board", &[_][]const u8{ "alice", "1.5" });
+        defer incr.deinit(allocator);
+        try std.testing.expectEqual(@as(f64, 12.0), incr.real);
+
+        var rank = try client.collOp(allocator, .zset_rank, "board", &[_][]const u8{"alice"});
+        defer rank.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 0), rank.int);
+
+        var byRank = try client.collOp(allocator, .zset_rangebyrank, "board", &[_][]const u8{ "0", "-1" });
+        defer byRank.deinit(allocator);
+        try std.testing.expectEqual(@as(usize, 2), byRank.scorePairList.len);
+        try std.testing.expectEqualStrings("alice", byRank.scorePairList[0].member);
+        try std.testing.expectEqualStrings("bob", byRank.scorePairList[1].member);
+
+        var byScore = try client.collOp(allocator, .zset_rangebyscore, "board", &[_][]const u8{ "15", "25" });
+        defer byScore.deinit(allocator);
+        try std.testing.expectEqual(@as(usize, 1), byScore.scorePairList.len);
+        try std.testing.expectEqualStrings("bob", byScore.scorePairList[0].member);
+
+        var card = try client.collOp(allocator, .zset_card, "board", &.{});
+        defer card.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 2), card.int);
+
+        var removed = try client.collOp(allocator, .zset_rem, "board", &[_][]const u8{"bob"});
+        defer removed.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 1), removed.int);
+    }
+}
+
+// Closes the gap every `coll_op` session note since #30 has flagged and
+// deferred: every existing `coll_op` test drives ONE connection at a
+// time, so nothing has ever proven that many independent TCP connections
+// hammering `coll_op` against the SAME named collection concurrently are
+// safe - `Server.dispatch` takes `self.mutex` once per request exactly
+// like every other opcode, but that claim had never been exercised here
+// with real OS threads and real sockets the way `concurrent.zig`'s
+// `GuardedDb` tests already exercise `Db`/`TableTxn` directly.
+test "coll_op survives many real concurrent connections hammering the same counter" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const threadCount = 8;
+    const perThread = 50;
+
+    const IncrCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+
+    const incrWorker = struct {
+        fn run(ctx: *IncrCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < perThread) : (i += 1) {
+                var reply = client.collOp(ctx.allocator, .counter_incrby, "shared-counter", &[_][]const u8{"1"}) catch return;
+                reply.deinit(ctx.allocator);
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var incrContexts: [threadCount]IncrCtx = undefined;
+    var incrThreads: [threadCount]std.Thread = undefined;
+    for (0..threadCount) |i| {
+        incrContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        incrThreads[i] = try std.Thread.spawn(.{}, incrWorker, .{&incrContexts[i]});
+    }
+    for (0..threadCount) |i| incrThreads[i].join();
+    for (0..threadCount) |i| try std.testing.expect(incrContexts[i].ok);
+
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    var total = try client.collOp(allocator, .counter_get, "shared-counter", &.{});
+    defer total.deinit(allocator);
+    // Every increment is a separate request from a separate connection, so
+    // a missing lock around `runColl`'s read-modify-write would show up
+    // here as a total strictly less than threadCount*perThread (lost
+    // updates), not as a crash - the mutex in `Server.dispatch` must make
+    // this land on the exact total every single run.
+    try std.testing.expectEqual(@as(i64, threadCount * perThread), total.int);
+}
+
+// Same shape as the counter test above but for a structural collection
+// (`Set`) instead of a single scalar: many connections each add their OWN
+// disjoint members to one shared set, so a race would show up as a
+// missing member (an add silently lost to a concurrent writer) rather
+// than a wrong total, which is a different failure mode than incrBy's
+// lost-update and worth its own proof.
+test "coll_op survives many real concurrent connections adding disjoint members to the same set" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const threadCount = 8;
+    const perThread = 50;
+
+    const AddCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+
+    const addWorker = struct {
+        fn run(ctx: *AddCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < perThread) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const member = std.fmt.bufPrint(&buf, "t{d}-m{d}", .{ ctx.thread, i }) catch return;
+                var reply = client.collOp(ctx.allocator, .set_add, "shared-set", &[_][]const u8{member}) catch return;
+                reply.deinit(ctx.allocator);
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var addContexts: [threadCount]AddCtx = undefined;
+    var addThreads: [threadCount]std.Thread = undefined;
+    for (0..threadCount) |i| {
+        addContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        addThreads[i] = try std.Thread.spawn(.{}, addWorker, .{&addContexts[i]});
+    }
+    for (0..threadCount) |i| addThreads[i].join();
+    for (0..threadCount) |i| try std.testing.expect(addContexts[i].ok);
+
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    var card = try client.collOp(allocator, .set_card, "shared-set", &.{});
+    defer card.deinit(allocator);
+    try std.testing.expectEqual(@as(i64, threadCount * perThread), card.int);
+
+    // Spot-check a member from every thread, not just the aggregate count -
+    // a bug that dropped exactly one member per thread but "gained" one
+    // duplicate elsewhere could still pass the cardinality check above.
+    for (0..threadCount) |t| {
+        var buf: [32]u8 = undefined;
+        const member = try std.fmt.bufPrint(&buf, "t{d}-m0", .{t});
+        var isMem = try client.collOp(allocator, .set_ismember, "shared-set", &[_][]const u8{member});
+        defer isMem.deinit(allocator);
+        try std.testing.expectEqual(@as(i64, 1), isMem.int);
+    }
+}
+
+test "coll_op applies the same lazy-expiry check as coll_ttl_op before every dispatch" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    _ = try collmod.Hash.set(&db, allocator, "session", "user", "ada");
+    try client.collTtlExpire(.hash, "session", 0);
+    std.time.sleep(5 * std.time.ns_per_ms);
+
+    // The lazy check in `handleCollOp` reaps "session" before hash_get
+    // ever runs, so the field reads back as gone, not as its old value.
+    var got = try client.collOp(allocator, .hash_get, "session", &[_][]const u8{"user"});
+    defer got.deinit(allocator);
+    try std.testing.expect(got == .nil);
+    try std.testing.expect(!try collmod.collectionExists(&db, allocator, .hash, "session"));
+}
+
+test "coll_op set_inter/union/diff lazily expire every extra set name, not just the first" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    _ = try collmod.Set.add(&db, allocator, "a", "x");
+    _ = try collmod.Set.add(&db, allocator, "b", "x");
+    try client.collTtlExpire(.set, "b", 0);
+    std.time.sleep(5 * std.time.ns_per_ms);
+
+    // "b" is due but is only referenced through `args`, never `name` - if
+    // the handler only checked `name` (like it does for every single-name
+    // action), "b" would still look alive here and `intersect` would see
+    // its stale "x" member. It must come back empty instead.
+    var inter = try client.collOp(allocator, .set_inter, "a", &[_][]const u8{"b"});
+    defer inter.deinit(allocator);
+    try std.testing.expectEqual(@as(usize, 0), inter.stringList.len);
+}
+
+test "coll_op gates a read action as readonly and a write action as readwrite" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    _ = try collmod.Hash.set(&db, allocator, "k", "f", "v");
+
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "reader", "pw", .readonly, 16);
+    try store.createUser(allocator, "writer", "pw", .readwrite, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+
+    var writer = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer writer.close();
+    try writer.authenticate("writer", "pw");
+
+    var reader = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer reader.close();
+    try reader.authenticate("reader", "pw");
+
+    // hash_get is read-only: a readonly connection can run it.
+    var got = try reader.collOp(allocator, .hash_get, "k", &[_][]const u8{"f"});
+    defer got.deinit(allocator);
+    try std.testing.expectEqualStrings("v", got.bytes);
+
+    // hash_set mutates: forbidden for a readonly connection.
+    try std.testing.expectError(client_mod.ClientError.ServerForbidden, reader.collOp(allocator, .hash_set, "k", &[_][]const u8{ "f", "v2" }));
+
+    // The readwrite connection can do it. "f" already exists, so hash_set
+    // reports it as updated (0), not created (1) - same int-flag shape as
+    // set_add/set_rem/hash_del elsewhere in this opcode, not `.ok`.
+    var setReply = try writer.collOp(allocator, .hash_set, "k", &[_][]const u8{ "f", "v2" });
+    defer setReply.deinit(allocator);
+    try std.testing.expectEqual(@as(i64, 0), setReply.int);
+}
+
+test "server rejects a malformed coll_op frame with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    // A single action byte is not enough to decode the length-prefixed
+    // name that must follow it.
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.coll_op), "\x00");
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+}
+
+test "server answers coll_op with bad_request when an action gets too few arguments" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // counter_set needs a value argument - a well-formed frame that omits
+    // it should come back as a clean bad_request, not an internal error or
+    // a crash from indexing into an empty args slice.
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, client.collOp(allocator, .counter_set, "n", &.{}));
+}
+
+// Same ksztalt of proof as the two `coll_op` concurrency tests above
+// (many real OS threads, each its own TCP connection, hammering shared
+// server state) but for `ttl_op` instead - the next direction flagged at
+// the end of session solo #32 (cobalt-postep.md). `ttl_op` has no shared
+// mutable VALUE the way a counter or set does (each writer's key is its
+// own, disjoint from every other writer's), so the race worth proving
+// here is different: writer connections racing `set`+`expire` against
+// sweeper connections racing `sweep`, all against the SAME `Db.sstables`/
+// memtable underneath. `ttl.sweepExpired` reads its own prefix scan and
+// deletes what it found within a single `handleTtlOp` call, which the
+// `self.mutex` in `Server.dispatch` executes atomically end-to-end, so a
+// key can never be swept twice and no swept count can double-count - the
+// grand total across every sweep response plus one final mop-up sweep
+// must land on exactly the number of keys written, with zero lost and
+// zero duplicated, no matter how the OS interleaves the connections.
+test "ttl_op survives many real concurrent connections racing writes against sweeps" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const writerCount = 6;
+    const perWriter = 40;
+    const sweeperCount = 3;
+    const sweepsPerSweeper = 200;
+
+    const WriteCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+
+    const writeWorker = struct {
+        fn run(ctx: *WriteCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < perWriter) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const key = std.fmt.bufPrint(&buf, "ttl-conc-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.set(key, "v") catch return;
+                client.ttlExpire(key, 0) catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const SweepCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        reaped: std.atomic.Value(u64) = std.atomic.Value(u64).init(0),
+        ok: bool = false,
+    };
+
+    const sweepWorker = struct {
+        fn run(ctx: *SweepCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < sweepsPerSweeper) : (i += 1) {
+                const n = client.ttlSweep() catch return;
+                _ = ctx.reaped.fetchAdd(n, .monotonic);
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var writeContexts: [writerCount]WriteCtx = undefined;
+    var writeThreads: [writerCount]std.Thread = undefined;
+    var sweepContexts: [sweeperCount]SweepCtx = undefined;
+    var sweepThreads: [sweeperCount]std.Thread = undefined;
+
+    for (0..sweeperCount) |i| {
+        sweepContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        sweepThreads[i] = try std.Thread.spawn(.{}, sweepWorker, .{&sweepContexts[i]});
+    }
+    for (0..writerCount) |i| {
+        writeContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        writeThreads[i] = try std.Thread.spawn(.{}, writeWorker, .{&writeContexts[i]});
+    }
+    for (0..writerCount) |i| writeThreads[i].join();
+    for (0..sweeperCount) |i| sweepThreads[i].join();
+    for (0..writerCount) |i| try std.testing.expect(writeContexts[i].ok);
+    for (0..sweeperCount) |i| try std.testing.expect(sweepContexts[i].ok);
+
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    // Any key that lost the race against every sweeper (written after the
+    // last sweep call landed) is mopped up by one final sweep here.
+    const finalReaped = try client.ttlSweep();
+
+    var total: u64 = finalReaped;
+    for (0..sweeperCount) |i| total += sweepContexts[i].reaped.load(.monotonic);
+    try std.testing.expectEqual(@as(u64, writerCount * perWriter), total);
+
+    // Spot-check one key from every writer thread: all must be truly gone
+    // (not just marker-cleared), proving the sweeps were real deletes.
+    for (0..writerCount) |t| {
+        var buf: [32]u8 = undefined;
+        const key = try std.fmt.bufPrint(&buf, "ttl-conc-{d}-0", .{t});
+        try std.testing.expectEqual(@as(?[]u8, null), try client.get(allocator, key));
+        try std.testing.expectEqual(ttlmod.TtlResult.noKey, try client.ttlQuery(key));
+    }
+}
+
+// Mirrors the `ttl_op` concurrency test above but against `coll_ttl_op`
+// and a real collection (`Counter`) instead of a flat key - the sibling
+// gap the same end-of-#32 note called out explicitly ("ttl_op dziala na
+// plaskim keyspace... analogiczny test... jest wykonalny, ale odlozony").
+// `collttl.sweepExpired` (collttl.zig) shares the exact same
+// scan-then-delete-within-one-call shape as `ttl.sweepExpired`, so the
+// same exactly-once accounting argument applies.
+test "coll_ttl_op survives many real concurrent connections racing writes against sweeps" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const writerCount = 6;
+    const perWriter = 40;
+    const sweeperCount = 3;
+    const sweepsPerSweeper = 200;
+
+    const WriteCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+
+    const writeWorker = struct {
+        fn run(ctx: *WriteCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < perWriter) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const name = std.fmt.bufPrint(&buf, "ttlcoll-conc-{d}-{d}", .{ ctx.thread, i }) catch return;
+                var reply = client.collOp(ctx.allocator, .counter_incrby, name, &[_][]const u8{"1"}) catch return;
+                reply.deinit(ctx.allocator);
+                client.collTtlExpire(.counter, name, 0) catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const SweepCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        reaped: std.atomic.Value(u64) = std.atomic.Value(u64).init(0),
+        ok: bool = false,
+    };
+
+    const sweepWorker = struct {
+        fn run(ctx: *SweepCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < sweepsPerSweeper) : (i += 1) {
+                const n = client.collTtlSweep() catch return;
+                _ = ctx.reaped.fetchAdd(n, .monotonic);
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var writeContexts: [writerCount]WriteCtx = undefined;
+    var writeThreads: [writerCount]std.Thread = undefined;
+    var sweepContexts: [sweeperCount]SweepCtx = undefined;
+    var sweepThreads: [sweeperCount]std.Thread = undefined;
+
+    for (0..sweeperCount) |i| {
+        sweepContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        sweepThreads[i] = try std.Thread.spawn(.{}, sweepWorker, .{&sweepContexts[i]});
+    }
+    for (0..writerCount) |i| {
+        writeContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        writeThreads[i] = try std.Thread.spawn(.{}, writeWorker, .{&writeContexts[i]});
+    }
+    for (0..writerCount) |i| writeThreads[i].join();
+    for (0..sweeperCount) |i| sweepThreads[i].join();
+    for (0..writerCount) |i| try std.testing.expect(writeContexts[i].ok);
+    for (0..sweeperCount) |i| try std.testing.expect(sweepContexts[i].ok);
+
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const finalReaped = try client.collTtlSweep();
+
+    var total: u64 = finalReaped;
+    for (0..sweeperCount) |i| total += sweepContexts[i].reaped.load(.monotonic);
+    try std.testing.expectEqual(@as(u64, writerCount * perWriter), total);
+
+    // Spot-check one collection from every writer thread: the WHOLE
+    // counter namespace must be gone, not merely its TTL marker.
+    for (0..writerCount) |t| {
+        var buf: [32]u8 = undefined;
+        const name = try std.fmt.bufPrint(&buf, "ttlcoll-conc-{d}-0", .{t});
+        try std.testing.expect(!try collmod.collectionExists(&db, allocator, .counter, name));
+        try std.testing.expectEqual(ttlmod.TtlResult.noKey, try client.collTtlQuery(.counter, name));
+    }
+}
+
+// `coll_op`/`ttl_op`/`coll_ttl_op`/`table_select` above all have their own
+// concurrency proof now (#31/#32/#33's end-of-session notes tracked this
+// gap explicitly); `user_admin` was the one opcode still missing one. Its
+// shared mutable state is `auth.Store` (auth.zig), itself just a thin
+// get/put layer over the same `*Db` - `createUser` is a plain
+// check-then-write (`db.get` then `db.put`, no compare-and-swap), so a
+// missing lock around it would let two concurrent `create` calls for the
+// SAME username both observe "absent" and both write, silently doubling
+// the account (or worse, interleaving two different `UserRecord.encode()`
+// outputs into one key). `self.mutex` in `Server.dispatch` is the only
+// thing standing between that and reality here, same as every other
+// opcode's concurrency test in this file.
+test "user_admin survives many real concurrent connections racing to create the same username" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const threadCount = 8;
+
+    const CreateCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        created: bool = false,
+        conflicted: bool = false,
+        ok: bool = false,
+    };
+
+    const createWorker = struct {
+        fn run(ctx: *CreateCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var buf: [16]u8 = undefined;
+            const password = std.fmt.bufPrint(&buf, "pw-{d}", .{ctx.thread}) catch return;
+            if (client.adminCreateUser("shared-user", password, .readwrite, 4)) |_| {
+                ctx.created = true;
+            } else |err| {
+                if (err != client_mod.ClientError.ServerConflict) return;
+                ctx.conflicted = true;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var contexts: [threadCount]CreateCtx = undefined;
+    var threads: [threadCount]std.Thread = undefined;
+    for (0..threadCount) |i| {
+        contexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        threads[i] = try std.Thread.spawn(.{}, createWorker, .{&contexts[i]});
+    }
+    for (0..threadCount) |i| threads[i].join();
+
+    var createdCount: usize = 0;
+    var conflictedCount: usize = 0;
+    for (0..threadCount) |i| {
+        try std.testing.expect(contexts[i].ok);
+        if (contexts[i].created) createdCount += 1;
+        if (contexts[i].conflicted) conflictedCount += 1;
+    }
+    // A missing lock around the check-then-write in `createUser` would let
+    // more than one racer observe "absent" and both succeed, so this must
+    // land on EXACTLY one winner - not "at least one".
+    try std.testing.expectEqual(@as(usize, 1), createdCount);
+    try std.testing.expectEqual(@as(usize, threadCount - 1), conflictedCount);
+
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+    const users = try client.adminListUsers(allocator);
+    defer authmod.freeUserList(allocator, users);
+    // Guards against the OTHER failure mode a lost lock could produce: the
+    // two racing `db.put` calls interleaving their encoded bytes into one
+    // corrupted record instead of cleanly overwriting each other, which
+    // would still leave exactly one key but might fail to decode, or a
+    // duplicate row under the same key if compaction ever saw two
+    // physically distinct writes land as one logically doubled entry.
+    try std.testing.expectEqual(@as(usize, 1), users.len);
+    try std.testing.expectEqualStrings("shared-user", users[0].username);
+}
+
+// Same shared-mutex proof as the create-race test above, but for the
+// read-modify-write shape (`setPassword`/`setRole`, each its own
+// `mustGet` then `db.put`) rather than the check-then-write shape of
+// `create`, plus a concurrent reader (`list`) racing the writers - the
+// third distinct access pattern `user_admin` exposes over the wire.
+test "user_admin survives many real concurrent connections mutating and listing the same account" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+
+    var setup = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer setup.close();
+    try setup.adminCreateUser("shared-admin", "init-pw", .readonly, 4);
+
+    const writerCount = 6;
+    const perWriter = 40;
+    const readerCount = 3;
+    const readsPerReader = 200;
+
+    const WriteCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: usize,
+        ok: bool = false,
+    };
+
+    const writeWorker = struct {
+        fn run(ctx: *WriteCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < perWriter) : (i += 1) {
+                var buf: [32]u8 = undefined;
+                const password = std.fmt.bufPrint(&buf, "pw-{d}-{d}", .{ ctx.thread, i }) catch return;
+                client.adminSetPassword("shared-admin", password, 4) catch return;
+                const role: authmod.Role = if (i % 2 == 0) .readwrite else .readonly;
+                client.adminSetRole("shared-admin", role) catch return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    const ReadCtx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        ok: bool = false,
+    };
+
+    const readWorker = struct {
+        fn run(ctx: *ReadCtx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var i: usize = 0;
+            while (i < readsPerReader) : (i += 1) {
+                // Any decode failure inside the server (a torn/corrupted
+                // record) surfaces here as `error.ServerInternal`, not a
+                // silently wrong answer, since `handleUserAdmin` maps every
+                // `UserRecord.decode` error straight to an `internal`
+                // status frame.
+                const users = client.adminListUsers(ctx.allocator) catch return;
+                defer authmod.freeUserList(ctx.allocator, users);
+                if (users.len != 1) return;
+                if (!std.mem.eql(u8, users[0].username, "shared-admin")) return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var writeContexts: [writerCount]WriteCtx = undefined;
+    var writeThreads: [writerCount]std.Thread = undefined;
+    var readContexts: [readerCount]ReadCtx = undefined;
+    var readThreads: [readerCount]std.Thread = undefined;
+
+    for (0..readerCount) |i| {
+        readContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress() };
+        readThreads[i] = try std.Thread.spawn(.{}, readWorker, .{&readContexts[i]});
+    }
+    for (0..writerCount) |i| {
+        writeContexts[i] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = i };
+        writeThreads[i] = try std.Thread.spawn(.{}, writeWorker, .{&writeContexts[i]});
+    }
+    for (0..writerCount) |i| writeThreads[i].join();
+    for (0..readerCount) |i| readThreads[i].join();
+    for (0..writerCount) |i| try std.testing.expect(writeContexts[i].ok);
+    for (0..readerCount) |i| try std.testing.expect(readContexts[i].ok);
+
+    // A final, deterministic write from the main thread after every racer
+    // has joined, then verified through `auth.Store.verify` directly
+    // (bypassing the network entirely) against the SAME `*Db` the server
+    // just hammered concurrently: this proves the record surviving on disk
+    // is not merely "decodable" (the readers above already checked that)
+    // but functionally intact - the exact salt/rounds/hash triple that
+    // `setPassword` wrote is still paired correctly with the role
+    // `setRole` wrote after it, not a torn mix of two different racers'
+    // writes.
+    try setup.adminSetPassword("shared-admin", "final-known-pw", 4);
+    try setup.adminSetRole("shared-admin", .admin);
+
+    const store = authmod.Store.init(&db);
+    const role = try store.verify(allocator, "shared-admin", "final-known-pw");
+    try std.testing.expectEqual(authmod.Role.admin, role);
+
+    const finalUsers = try setup.adminListUsers(allocator);
+    defer authmod.freeUserList(allocator, finalUsers);
+    try std.testing.expectEqual(@as(usize, 1), finalUsers.len);
+    try std.testing.expectEqual(authmod.Role.admin, finalUsers[0].role);
+}
+
+// `txn_op` is the network counterpart of the local CLI's `txn <script>`
+// (main.zig's `runTxn`) - until now atomic multi-row/multi-table commits
+// were reachable only from a process holding the `Db` directly, the same
+// gap `table_select`/`coll_op`/`ttl_op` already closed for their own
+// subsystems. This round trip exercises both verbs across two tables in
+// one commit, including a pre-existing secondary index, to prove the field
+// list and primary key survive the wire encoding (`Row.encode`/
+// `rowmod.encodeValue`) intact enough for `TableTxn.put`'s index
+// maintenance to run correctly on the decoded side, not just for the raw
+// bytes to round-trip in isolation the way protocol.zig's own unit tests
+// already check.
+test "server txn_op commits put and del atomically across two tables, keeping an index in sync" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var accounts = try querymod.Table.open(&db, allocator, "accounts");
+        defer accounts.deinit();
+        try accounts.put(.{ .int = 1 }, &.{.{ .name = "balance", .value = .{ .int = 100 } }});
+        try accounts.put(.{ .int = 2 }, &.{.{ .name = "balance", .value = .{ .int = 5 } }});
+
+        var people = try querymod.Table.open(&db, allocator, "people");
+        defer people.deinit();
+        try people.createIndex("city");
+        try people.put(.{ .int = 10 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const peopleFields = [_]rowmod.Field{.{ .name = "city", .value = .{ .text = "warsaw" } }};
+    const entries = [_]protocol.TxnOpEntry{
+        .{ .verb = .put, .table = "accounts", .pk = .{ .int = 2 }, .fields = &.{.{ .name = "balance", .value = .{ .int = 999 } }} },
+        .{ .verb = .put, .table = "people", .pk = .{ .int = 11 }, .fields = &peopleFields },
+        .{ .verb = .del, .table = "accounts", .pk = .{ .int = 1 } },
+    };
+    const applied = try client.txnOp(&entries);
+    try std.testing.expectEqual(@as(u32, 3), applied);
+
+    var accounts = try querymod.Table.open(&db, allocator, "accounts");
+    defer accounts.deinit();
+    try std.testing.expect((try accounts.get(.{ .int = 1 })) == null);
+    var row2 = (try accounts.get(.{ .int = 2 })).?;
+    defer row2.deinit();
+    try std.testing.expectEqual(@as(i64, 999), row2.get("balance").?.int);
+
+    var people = try querymod.Table.open(&db, allocator, "people");
+    defer people.deinit();
+    const warsaw = try people.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer querymod.freeRows(allocator, warsaw);
+    try std.testing.expectEqual(@as(usize, 2), warsaw.len);
+}
+
+// Closes a gap left open by the CHECK constraint's introduction alongside
+// UNIQUE/FOREIGN KEY: `TableTxn.put` enforces all three identically (see
+// txn_table.zig), and this server's only write path (`handleTxnOp`) already
+// runs every entry through `TableTxn.put` - so a remote `txn_op` rejecting a
+// CHECK violation was already true the moment `TableTxn.put` gained the
+// check, never separately wired. This test is the same kind of "prove the
+// wire path actually exercises it, not just the in-process unit test" round
+// trip the FK/UNIQUE `txn_op` test above already is.
+test "server txn_op rejects a CHECK constraint violation over the wire and commits nothing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createCheckConstraint("qty_positive", "qty gt i:0");
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const entries = [_]protocol.TxnOpEntry{
+        .{ .verb = .put, .table = "orders", .pk = .{ .int = 1 }, .fields = &.{.{ .name = "qty", .value = .{ .int = 5 } }} },
+        .{ .verb = .put, .table = "orders", .pk = .{ .int = 2 }, .fields = &.{.{ .name = "qty", .value = .{ .int = -1 } }} },
+    };
+    try std.testing.expectError(client_mod.ClientError.ServerInternal, client.txnOp(&entries));
+
+    // Whole transaction is atomic across both entries: the earlier,
+    // individually-valid row 1 must not have been committed either.
+    var orders = try querymod.Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try std.testing.expect((try orders.get(.{ .int = 1 })) == null);
+    try std.testing.expect((try orders.get(.{ .int = 2 })) == null);
+}
+
+// `handleTxnOp` runs every entry through `TableTxn.put`/`TableTxn.delete`
+// (see txn_table.zig), which now enforce ON DELETE RESTRICT exactly like
+// CHECK/UNIQUE/FOREIGN KEY on put above - never separately wired for this
+// opcode either. The interesting case a plain `table_delete` test cannot
+// cover: both the child insert AND the restricted parent delete are only
+// staged within this ONE `txn_op` batch, never durable on their own -
+// `TableTxn.delete`'s RESTRICT check has to see the child through
+// `Transaction.scanPrefix`'s same-transaction visibility (see
+// txn_table.zig's own unit test for this), not a plain Db scan, or this
+// would wrongly let the delete through.
+test "server txn_op rejects an ON DELETE RESTRICT violation over the wire, seeing a child staged earlier in the same batch" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var customers = try querymod.Table.open(&db, allocator, "customers");
+        defer customers.deinit();
+        try customers.put(.{ .int = 1 }, &.{});
+
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createForeignKey("customer_id", "customers", querymod.pkField, .restrict);
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    const entries = [_]protocol.TxnOpEntry{
+        .{ .verb = .put, .table = "orders", .pk = .{ .int = 100 }, .fields = &.{.{ .name = "customer_id", .value = .{ .int = 1 } }} },
+        .{ .verb = .del, .table = "customers", .pk = .{ .int = 1 } },
+    };
+    try std.testing.expectError(client_mod.ClientError.ServerInternal, client.txnOp(&entries));
+
+    // Nothing committed: neither the staged order nor the rejected delete.
+    var orders = try querymod.Table.open(&db, allocator, "orders");
+    defer orders.deinit();
+    try std.testing.expect((try orders.get(.{ .int = 100 })) == null);
+
+    var customers = try querymod.Table.open(&db, allocator, "customers");
+    defer customers.deinit();
+    var stillThere = (try customers.get(.{ .int = 1 })).?;
+    stillThere.deinit();
+}
+
+test "server txn_op rejects an empty operation list with bad_request" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, client.txnOp(&.{}));
+}
+
+test "server rejects a malformed txn_op frame with bad_request without crashing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const stream = try std.net.tcpConnectToAddress(server.boundAddress());
+    defer stream.close();
+
+    // A u32 entry count of 1 promises one full entry, but the payload ends
+    // right after it - not even a verb byte follows.
+    var payload: [4]u8 = undefined;
+    std.mem.writeInt(u32, &payload, 1, .little);
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.txn_op), &payload);
+    var frame = try protocol.readFrame(allocator, stream.reader());
+    defer frame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.bad_request), frame.tag);
+
+    // The connection must still be usable afterward - a malformed frame is
+    // a client mistake, not a fatal error for the server.
+    try protocol.writeFrame(stream.writer(), @intFromEnum(protocol.Op.ping), "");
+    var pingFrame = try protocol.readFrame(allocator, stream.reader());
+    defer pingFrame.deinit();
+    try std.testing.expectEqual(@intFromEnum(protocol.Status.ok), pingFrame.tag);
+}
+
+// Proves the `txn_op` code path (decode -> `Transaction`/`TableTxn` ->
+// index maintenance -> commit, all under `Server.dispatch`'s single
+// `self.mutex`) holds up under real concurrent OS threads each on their
+// own real TCP connection - the same rigor `coll_op`'s/`table_select`'s
+// own concurrency tests apply, but for the table+index layer instead of
+// the flat keyspace or the Redis-like collections, which is a genuinely
+// different code path (this is the first concurrency test to drive
+// `TableTxn`/index maintenance through a live socket at all;
+// `concurrent.zig`'s own `TableTxn` concurrency test bypasses the network
+// entirely via `GuardedDb`). Each worker writes into two disjoint rows per
+// round (its own row in `widgets`, indexed by `owner`, and a companion row
+// in `tags`) so a lost or duplicated write from bad interleaving would
+// show up as a wrong row count or a wrong index membership, not just a
+// wrong number.
+test "server txn_op survives many real concurrent connections writing disjoint rows across two tables" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    {
+        var widgets = try querymod.Table.open(&db, allocator, "widgets");
+        defer widgets.deinit();
+        try widgets.createIndex("owner");
+    }
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    const threadCount = 6;
+    const perThread = 40;
+
+    const Ctx = struct {
+        allocator: Allocator,
+        addr: std.net.Address,
+        thread: i64,
+        ok: bool = false,
+    };
+
+    const worker = struct {
+        fn run(ctx: *Ctx) void {
+            var client = client_mod.Client.connect(ctx.allocator, ctx.addr) catch return;
+            defer client.close();
+            var buf: [32]u8 = undefined;
+            var i: i64 = 0;
+            while (i < perThread) : (i += 1) {
+                const ownerTag = std.fmt.bufPrint(&buf, "owner-{d}", .{ctx.thread}) catch return;
+                const widgetPk: i64 = ctx.thread * 1_000_000 + i;
+                const entries = [_]protocol.TxnOpEntry{
+                    .{ .verb = .put, .table = "widgets", .pk = .{ .int = widgetPk }, .fields = &.{.{ .name = "owner", .value = .{ .text = ownerTag } }} },
+                    .{ .verb = .put, .table = "tags", .pk = .{ .int = widgetPk }, .fields = &.{.{ .name = "seq", .value = .{ .int = i } }} },
+                };
+                const applied = client.txnOp(&entries) catch return;
+                if (applied != 2) return;
+            }
+            ctx.ok = true;
+        }
+    }.run;
+
+    var contexts: [threadCount]Ctx = undefined;
+    var threads: [threadCount]std.Thread = undefined;
+    for (0..threadCount) |t| {
+        contexts[t] = .{ .allocator = allocator, .addr = server.boundAddress(), .thread = @intCast(t) };
+        threads[t] = try std.Thread.spawn(.{}, worker, .{&contexts[t]});
+    }
+    for (0..threadCount) |t| threads[t].join();
+    for (0..threadCount) |t| try std.testing.expect(contexts[t].ok);
+
+    var widgets = try querymod.Table.open(&db, allocator, "widgets");
+    defer widgets.deinit();
+    var tags = try querymod.Table.open(&db, allocator, "tags");
+    defer tags.deinit();
+
+    var total: usize = 0;
+    for (0..threadCount) |t| {
+        var buf: [32]u8 = undefined;
+        const ownerTag = try std.fmt.bufPrint(&buf, "owner-{d}", .{t});
+        const owned = try widgets.select(.{ .eq = .{ .field = "owner", .value = .{ .text = ownerTag } } });
+        defer querymod.freeRows(allocator, owned);
+        // Every widget this thread wrote must show up under its own index
+        // entry, exactly `perThread` of them - not fewer (a lost write)
+        // and not more (a duplicated one).
+        try std.testing.expectEqual(@as(usize, perThread), owned.len);
+        total += owned.len;
+    }
+    try std.testing.expectEqual(@as(usize, threadCount * perThread), total);
+
+    const allTags = try tags.select(null);
+    defer querymod.freeRows(allocator, allTags);
+    try std.testing.expectEqual(@as(usize, threadCount * perThread), allTags.len);
+}
+
+test "server delivers a published message to a subscriber over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var sub = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer sub.close();
+    _ = try sub.subscribe(&.{"weather"});
+
+    var pub_ = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer pub_.close();
+    const delivered = try pub_.publish("weather", "sunny");
+    try std.testing.expectEqual(@as(u64, 1), delivered);
+
+    const msg = (try sub.nextMessage(allocator)).?;
+    defer msg.deinit(allocator);
+    try std.testing.expectEqualStrings("weather", msg.channel);
+    try std.testing.expectEqualStrings("sunny", msg.payload);
+    try std.testing.expectEqual(@as(u64, 1), server.messagesPublishedTotal.get());
+}
+
+test "server delivers to a subscriber's own copy per channel it named, every subscriber on a channel reached" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var subA = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer subA.close();
+    _ = try subA.subscribe(&.{ "orders", "alerts" });
+
+    var subB = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer subB.close();
+    _ = try subB.subscribe(&.{"orders"});
+
+    var pub_ = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer pub_.close();
+    try std.testing.expectEqual(@as(u64, 2), try pub_.publish("orders", "order-1"));
+    try std.testing.expectEqual(@as(u64, 1), try pub_.publish("alerts", "disk-full"));
+
+    const aFirst = (try subA.nextMessage(allocator)).?;
+    defer aFirst.deinit(allocator);
+    try std.testing.expectEqualStrings("orders", aFirst.channel);
+    try std.testing.expectEqualStrings("order-1", aFirst.payload);
+    const aSecond = (try subA.nextMessage(allocator)).?;
+    defer aSecond.deinit(allocator);
+    try std.testing.expectEqualStrings("alerts", aSecond.channel);
+    try std.testing.expectEqualStrings("disk-full", aSecond.payload);
+
+    const bOnly = (try subB.nextMessage(allocator)).?;
+    defer bOnly.deinit(allocator);
+    try std.testing.expectEqualStrings("orders", bOnly.channel);
+    try std.testing.expectEqualStrings("order-1", bOnly.payload);
+}
+
+test "server publish to a channel with no subscribers returns 0 without crashing, over real TCP" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try std.testing.expectEqual(@as(u64, 0), try client.publish("nobody-home", "hello"));
+    // A no-receiver publish is not a mutation of anything - `ping` still
+    // works on the same connection right after, proving `publish` never
+    // left the connection or the server in some half-dispatched state.
+    try client.ping();
+}
+
+test "server rejects an empty subscribe channel list as bad_request, connection stays diagnosable" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, client.subscribe(&.{}));
+}
+
+test "closing a subscriber's connection unregisters it - a later publish no longer reaches it" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var sub = try client_mod.Client.connect(allocator, server.boundAddress());
+    _ = try sub.subscribe(&.{"ch"});
+    try std.testing.expectEqual(@as(usize, 1), server.pubsub.channelSubscriberCount("ch"));
+    sub.close();
+
+    // The watcher thread's disconnect detection runs asynchronously - poll
+    // with a bounded timeout instead of a fixed sleep, the same style
+    // `drainConnections` already uses elsewhere in this file.
+    const startedAt = std.time.nanoTimestamp();
+    while (server.pubsub.channelSubscriberCount("ch") != 0) {
+        if (std.time.nanoTimestamp() - startedAt > 2 * std.time.ns_per_s) break;
+        std.time.sleep(5 * std.time.ns_per_ms);
+    }
+    try std.testing.expectEqual(@as(usize, 0), server.pubsub.channelSubscriberCount("ch"));
+
+    var pub_ = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer pub_.close();
+    try std.testing.expectEqual(@as(u64, 0), try pub_.publish("ch", "too-late"));
+}
+
+test "server with auth enabled requires authentication before subscribe or publish, readonly role suffices" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "viewer", "hunter2", .readonly, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var anon = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer anon.close();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, anon.subscribe(&.{"ch"}));
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, anon.publish("ch", "x"));
+
+    var viewer = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer viewer.close();
+    try viewer.authenticate("viewer", "hunter2");
+    _ = try viewer.subscribe(&.{"ch"});
+
+    var writer_ = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer writer_.close();
+    try writer_.authenticate("viewer", "hunter2");
+    try std.testing.expectEqual(@as(u64, 1), try writer_.publish("ch", "hi"));
+
+    const msg = (try viewer.nextMessage(allocator)).?;
+    defer msg.deinit(allocator);
+    try std.testing.expectEqualStrings("hi", msg.payload);
+}
+
+test "server unsubscribe over real TCP drops one channel while the other keeps flowing" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var sub = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer sub.close();
+    const subId = try sub.subscribe(&.{ "orders", "alerts" });
+
+    // The subscribe connection itself never answers another request (see
+    // `handleSubscribe`'s doc comment) - unsubscribe always goes over its
+    // own, separate connection.
+    var ctrl = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer ctrl.close();
+    const removed = try ctrl.unsubscribe(subId, &.{"orders"});
+    try std.testing.expectEqual(@as(u32, 1), removed);
+    // `ctrl` is an ordinary connection - it must still answer further
+    // requests normally after an unsubscribe, proving `handleUnsubscribe`
+    // returns like any other opcode rather than hijacking the connection.
+    try ctrl.ping();
+
+    var pub_ = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer pub_.close();
+    try std.testing.expectEqual(@as(u64, 0), try pub_.publish("orders", "too-late"));
+    try std.testing.expectEqual(@as(u64, 1), try pub_.publish("alerts", "fire"));
+
+    const msg = (try sub.nextMessage(allocator)).?;
+    defer msg.deinit(allocator);
+    try std.testing.expectEqualStrings("alerts", msg.channel);
+    try std.testing.expectEqualStrings("fire", msg.payload);
+}
+
+test "server unsubscribe from every remaining channel ends the subscription like a disconnect" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var sub = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer sub.close();
+    const subId = try sub.subscribe(&.{"ch"});
+
+    var ctrl = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer ctrl.close();
+    try std.testing.expectEqual(@as(u32, 1), try ctrl.unsubscribe(subId, &.{"ch"}));
+
+    // The push loop must notice the close exactly like a real disconnect -
+    // `nextMessage` returns `null`, never blocks forever or errors.
+    try std.testing.expect((try sub.nextMessage(allocator)) == null);
+
+    const startedAt = std.time.nanoTimestamp();
+    while (server.pubsub.channelSubscriberCount("ch") != 0) {
+        if (std.time.nanoTimestamp() - startedAt > 2 * std.time.ns_per_s) break;
+        std.time.sleep(5 * std.time.ns_per_ms);
+    }
+    try std.testing.expectEqual(@as(usize, 0), server.pubsub.channelSubscriberCount("ch"));
+}
+
+test "server rejects unsubscribe with an unknown subscriber id as bad_request" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var client = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer client.close();
+
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, client.unsubscribe(999999, &.{"ch"}));
+    // A rejected unsubscribe must not leave the connection in some
+    // half-dispatched state - `ping` still works right after.
+    try client.ping();
+}
+
+test "server rejects an empty unsubscribe channel list as bad_request" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var sub = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer sub.close();
+    const subId = try sub.subscribe(&.{"ch"});
+
+    var ctrl = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer ctrl.close();
+    try std.testing.expectError(client_mod.ClientError.ServerBadRequest, ctrl.unsubscribe(subId, &.{}));
+}
+
+test "server with auth enabled requires authentication before unsubscribe, readonly role suffices" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const path = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(path);
+
+    var db = try testDb(allocator, path);
+    defer db.close();
+    const store = authmod.Store.init(&db);
+    try store.createUser(allocator, "viewer", "hunter2", .readonly, 16);
+
+    const address = try std.net.Address.parseIp("127.0.0.1", 0);
+    var server = try Server.init(allocator, &db, address);
+    server.enableAuth(store);
+    try server.start();
+    defer server.stop();
+
+    const client_mod = @import("client.zig");
+    var sub = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer sub.close();
+    try sub.authenticate("viewer", "hunter2");
+    const subId = try sub.subscribe(&.{"ch"});
+
+    var anon = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer anon.close();
+    try std.testing.expectError(client_mod.ClientError.ServerUnauthorized, anon.unsubscribe(subId, &.{"ch"}));
+
+    var ctrl = try client_mod.Client.connect(allocator, server.boundAddress());
+    defer ctrl.close();
+    try ctrl.authenticate("viewer", "hunter2");
+    try std.testing.expectEqual(@as(u32, 1), try ctrl.unsubscribe(subId, &.{"ch"}));
+}
diff --git a/src/session.zig b/src/session.zig
new file mode 100644
index 0000000..74baf7a
--- /dev/null
+++ b/src/session.zig
@@ -0,0 +1,213 @@
+const std = @import("std");
+const authmod = @import("auth.zig");
+
+const Allocator = std.mem.Allocator;
+
+/// Random session tokens with expiration, independent of any one TCP
+/// connection - the layer that replaces "authenticated for as long as this
+/// socket stays open" (server.zig's `connRole`) with "authenticated until
+/// this token expires or is revoked". A client that authenticates once,
+/// gets a token back, and disconnects can reconnect later and resume the
+/// same role by presenting the token (`auth_token` opcode in protocol.zig)
+/// instead of the password again - and the token stops working on its own
+/// after its TTL elapses even if the same connection stays open the whole
+/// time, unlike plain password auth which never expires mid-connection.
+pub const tokenBytes = 24;
+pub const tokenHexLen = tokenBytes * 2;
+
+fn generateTokenHex() [tokenHexLen]u8 {
+    var raw: [tokenBytes]u8 = undefined;
+    std.crypto.random.bytes(&raw);
+    return std.fmt.bytesToHex(raw, .lower);
+}
+
+pub const Session = struct {
+    role: authmod.Role,
+    expiresAtNanos: i128,
+};
+
+/// In-memory only (never persisted to Db - a session is a login artifact,
+/// not application data): thread-safe via its own mutex since `server.zig`
+/// dispatches requests from one worker thread per connection and any of
+/// them may issue, validate, or revoke a token concurrently.
+pub const SessionStore = struct {
+    allocator: Allocator,
+    mutex: std.Thread.Mutex = .{},
+    sessions: std.StringHashMapUnmanaged(Session) = .{},
+
+    pub fn init(allocator: Allocator) SessionStore {
+        return .{ .allocator = allocator };
+    }
+
+    pub fn deinit(self: *SessionStore) void {
+        var it = self.sessions.iterator();
+        while (it.next()) |entry| self.allocator.free(entry.key_ptr.*);
+        self.sessions.deinit(self.allocator);
+    }
+
+    /// Issues a fresh random token bound to `role`, valid until
+    /// `nowNanos + ttlNanos`. Caller owns the returned slice.
+    pub fn issue(self: *SessionStore, role: authmod.Role, ttlNanos: i128, nowNanos: i128) ![]u8 {
+        const hex = generateTokenHex();
+        const keyOwned = try self.allocator.dupe(u8, &hex);
+        errdefer self.allocator.free(keyOwned);
+        const returned = try self.allocator.dupe(u8, &hex);
+        errdefer self.allocator.free(returned);
+
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        try self.sessions.put(self.allocator, keyOwned, .{ .role = role, .expiresAtNanos = nowNanos + ttlNanos });
+        return returned;
+    }
+
+    /// Returns the session bound to `token` (role and expiry) if it exists
+    /// and has not expired as of `nowNanos`. An expired session is deleted
+    /// right here (lazy cleanup) rather than left around for
+    /// `sweepExpired` to eventually find - a token that has expired must
+    /// never again validate as live, so the deletion happens on the same
+    /// lookup that discovers it. Returning the expiry (not just the role)
+    /// lets a caller such as `server.zig` re-check the same session later
+    /// against a fresh clock without a second store lookup.
+    pub fn validate(self: *SessionStore, token: []const u8, nowNanos: i128) ?Session {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const entry = self.sessions.getEntry(token) orelse return null;
+        if (entry.value_ptr.expiresAtNanos <= nowNanos) {
+            const key = entry.key_ptr.*;
+            _ = self.sessions.remove(token);
+            self.allocator.free(key);
+            return null;
+        }
+        return entry.value_ptr.*;
+    }
+
+    /// Explicit logout: removes a token before it would naturally expire.
+    /// Returns whether a session was actually present.
+    pub fn revoke(self: *SessionStore, token: []const u8) bool {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        const kv = self.sessions.fetchRemove(token) orelse return false;
+        self.allocator.free(kv.key);
+        return true;
+    }
+
+    /// Removes every session expired as of `nowNanos`, returning how many
+    /// were dropped. `validate` already deletes an expired session the
+    /// moment someone tries to use it, but a token nobody ever presents
+    /// again would otherwise sit in memory forever - this is the
+    /// housekeeping sweep a long-lived server can run periodically.
+    pub fn sweepExpired(self: *SessionStore, nowNanos: i128) usize {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+
+        var doomed = std.ArrayList([]const u8).init(self.allocator);
+        defer doomed.deinit();
+        var it = self.sessions.iterator();
+        while (it.next()) |entry| {
+            if (entry.value_ptr.expiresAtNanos <= nowNanos) {
+                doomed.append(entry.key_ptr.*) catch continue;
+            }
+        }
+        for (doomed.items) |key| {
+            _ = self.sessions.remove(key);
+            self.allocator.free(key);
+        }
+        return doomed.items.len;
+    }
+
+    pub fn count(self: *SessionStore) usize {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+        return self.sessions.count();
+    }
+};
+
+test "issue then validate returns the bound role before expiry" {
+    var store = SessionStore.init(std.testing.allocator);
+    defer store.deinit();
+
+    const token = try store.issue(.readwrite, 1_000_000_000, 0);
+    defer std.testing.allocator.free(token);
+
+    try std.testing.expectEqual(@as(usize, tokenHexLen), token.len);
+    try std.testing.expectEqual(authmod.Role.readwrite, store.validate(token, 500_000_000).?.role);
+    try std.testing.expectEqual(@as(usize, 1), store.count());
+}
+
+test "validate returns null once past expiry and removes the session" {
+    var store = SessionStore.init(std.testing.allocator);
+    defer store.deinit();
+
+    const token = try store.issue(.admin, 1_000, 0);
+    defer std.testing.allocator.free(token);
+
+    try std.testing.expect(store.validate(token, 1_000) == null);
+    try std.testing.expectEqual(@as(usize, 0), store.count());
+    // A second lookup of the same (already-removed) token still misses cleanly.
+    try std.testing.expect(store.validate(token, 1_000) == null);
+}
+
+test "unknown token never validates" {
+    var store = SessionStore.init(std.testing.allocator);
+    defer store.deinit();
+    try std.testing.expect(store.validate("does-not-exist", 0) == null);
+}
+
+test "revoke removes a session before its natural expiry" {
+    var store = SessionStore.init(std.testing.allocator);
+    defer store.deinit();
+
+    const token = try store.issue(.readonly, 1_000_000_000, 0);
+    defer std.testing.allocator.free(token);
+
+    try std.testing.expect(store.revoke(token));
+    try std.testing.expect(store.validate(token, 0) == null);
+    // Revoking an already-gone token is a clean no-op, not an error.
+    try std.testing.expect(!store.revoke(token));
+}
+
+test "two tokens for different roles are independent" {
+    var store = SessionStore.init(std.testing.allocator);
+    defer store.deinit();
+
+    const a = try store.issue(.readonly, 1_000_000_000, 0);
+    defer std.testing.allocator.free(a);
+    const b = try store.issue(.admin, 1_000_000_000, 0);
+    defer std.testing.allocator.free(b);
+
+    try std.testing.expect(!std.mem.eql(u8, a, b));
+    try std.testing.expectEqual(authmod.Role.readonly, store.validate(a, 0).?.role);
+    try std.testing.expectEqual(authmod.Role.admin, store.validate(b, 0).?.role);
+
+    try std.testing.expect(store.revoke(a));
+    try std.testing.expect(store.validate(a, 0) == null);
+    // Revoking `a` must never touch `b`'s still-live session.
+    try std.testing.expectEqual(authmod.Role.admin, store.validate(b, 0).?.role);
+}
+
+test "sweepExpired drops only expired sessions and reports the count" {
+    var store = SessionStore.init(std.testing.allocator);
+    defer store.deinit();
+
+    const stale1 = try store.issue(.readonly, 100, 0);
+    defer std.testing.allocator.free(stale1);
+    const stale2 = try store.issue(.readwrite, 100, 0);
+    defer std.testing.allocator.free(stale2);
+    const fresh = try store.issue(.admin, 1_000_000_000, 0);
+    defer std.testing.allocator.free(fresh);
+
+    try std.testing.expectEqual(@as(usize, 3), store.count());
+    try std.testing.expectEqual(@as(usize, 2), store.sweepExpired(200));
+    try std.testing.expectEqual(@as(usize, 1), store.count());
+    try std.testing.expectEqual(authmod.Role.admin, store.validate(fresh, 200).?.role);
+
+    // A second sweep at the same time has nothing left to remove.
+    try std.testing.expectEqual(@as(usize, 0), store.sweepExpired(200));
+}
+
+test "generateTokenHex produces distinct, fully hex-encoded tokens" {
+    const a = generateTokenHex();
+    const b = generateTokenHex();
+    try std.testing.expect(!std.mem.eql(u8, &a, &b));
+    for (a) |c| try std.testing.expect(std.ascii.isHex(c));
+}
diff --git a/src/sstable.zig b/src/sstable.zig
index e53598d..f523bfc 100644
--- a/src/sstable.zig
+++ b/src/sstable.zig
@@ -24,11 +24,26 @@ fn order(a: []const u8, b: []const u8) std.math.Order {
 }
 
 const magic: u32 = 0xC0BA1701;
-const version: u32 = 1;
+const version: u32 = 2;
 const footerLen = 4 + 4 + 8 + 4 + 8 + 4 + 8 + 8;
 const recordHeader = 1 + 8 + 4 + 4;
 const defaultBlockTarget = 4096;
 
+/// Every Nth record in a data block is a "restart point": stored with its
+/// full key (shared == 0) instead of a shared-prefix delta against the
+/// previous key. This bounds how many deltas must be re-applied to recover
+/// any one key (never more than `restartInterval - 1`) and, more
+/// importantly here, gives block expansion a cheap, structural corruption
+/// check: a real restart offset must always land on a shared == 0 record.
+const restartInterval: usize = 16;
+
+fn commonPrefixLen(a: []const u8, b: []const u8) usize {
+    const n = @min(a.len, b.len);
+    var i: usize = 0;
+    while (i < n and a[i] == b[i]) : (i += 1) {}
+    return i;
+}
+
 pub const Builder = struct {
     allocator: Allocator,
     file: std.fs.File,
@@ -36,6 +51,9 @@ pub const Builder = struct {
     blockBuf: std.ArrayList(u8),
     blockFirstKey: std.ArrayList(u8),
     indexBuf: std.ArrayList(u8),
+    lastKey: std.ArrayList(u8),
+    blockRestarts: std.ArrayList(u32),
+    blockRecordCount: usize,
     numEntries: u64,
     logicalBytes: u64,
     maxSeq: u64,
@@ -51,6 +69,9 @@ pub const Builder = struct {
             .blockBuf = std.ArrayList(u8).init(allocator),
             .blockFirstKey = std.ArrayList(u8).init(allocator),
             .indexBuf = std.ArrayList(u8).init(allocator),
+            .lastKey = std.ArrayList(u8).init(allocator),
+            .blockRestarts = std.ArrayList(u32).init(allocator),
+            .blockRecordCount = 0,
             .numEntries = 0,
             .logicalBytes = 0,
             .maxSeq = 0,
@@ -63,6 +84,8 @@ pub const Builder = struct {
         self.blockBuf.deinit();
         self.blockFirstKey.deinit();
         self.indexBuf.deinit();
+        self.lastKey.deinit();
+        self.blockRestarts.deinit();
         self.bloom.deinit();
         self.file.close();
     }
@@ -72,14 +95,25 @@ pub const Builder = struct {
             self.blockFirstKey.clearRetainingCapacity();
             try self.blockFirstKey.appendSlice(record.key);
         }
+
+        const isRestart = self.blockRecordCount % restartInterval == 0;
+        const shared: u32 = if (isRestart) 0 else @intCast(commonPrefixLen(self.lastKey.items, record.key));
+        const unshared = record.key[shared..];
+        if (isRestart) try self.blockRestarts.append(@intCast(self.blockBuf.items.len));
+
         const writer = encode.ByteWriter.init(&self.blockBuf);
         try writer.byte(@intFromEnum(record.kind));
         try writer.putU64(record.seq);
-        try writer.putU32(@intCast(record.key.len));
+        try writer.putU32(shared);
+        try writer.putU32(@intCast(unshared.len));
         try writer.putU32(@intCast(record.value.len));
-        try writer.slice(record.key);
+        try writer.slice(unshared);
         try writer.slice(record.value);
 
+        self.lastKey.clearRetainingCapacity();
+        try self.lastKey.appendSlice(record.key);
+        self.blockRecordCount += 1;
+
         self.bloom.add(record.key);
         self.numEntries += 1;
         self.logicalBytes += recordHeader + record.key.len + record.value.len;
@@ -90,6 +124,15 @@ pub const Builder = struct {
 
     fn flushBlock(self: *Builder) !void {
         if (self.blockBuf.items.len == 0) return;
+
+        // The restart-offset trailer rides inside the same logical block
+        // bytes as the records themselves, so it survives compression and
+        // is immediately available to `expandBlock` on the read side
+        // without a separate on-disk section or footer entry.
+        const trailerWriter = encode.ByteWriter.init(&self.blockBuf);
+        for (self.blockRestarts.items) |restartOffset| try trailerWriter.putU32(restartOffset);
+        try trailerWriter.putU32(@intCast(self.blockRestarts.items.len));
+
         const originalLen: u32 = @intCast(self.blockBuf.items.len);
 
         const encoded = try compress.encode(self.allocator, self.blockBuf.items);
@@ -116,6 +159,9 @@ pub const Builder = struct {
 
         self.offset += physLen + 4;
         self.blockBuf.clearRetainingCapacity();
+        self.blockRestarts.clearRetainingCapacity();
+        self.blockRecordCount = 0;
+        self.lastKey.clearRetainingCapacity();
     }
 
     pub fn finish(self: *Builder) !void {
@@ -160,6 +206,13 @@ const IndexEntry = struct {
     offset: u64,
     blockLen: u32,
     firstKey: []const u8,
+    // Offsets (relative to this block's own bytes, i.e. usable directly
+    // against the slice `blockBytes()` returns) of every restart record in
+    // the flattened block, in ascending order. restarts[0] is always 0.
+    // Lets point lookups binary-search straight to the <= restartInterval
+    // records that could hold the key instead of linear-scanning the whole
+    // block from position 0.
+    restarts: []u32,
 };
 
 const blockPrefix = 1 + 4;
@@ -188,6 +241,7 @@ pub const Reader = struct {
         if (buffer.len < footerLen) return error.CorruptSstable;
         const footerStart = buffer.len - footerLen;
         if (readU32(buffer, footerStart) != magic) return error.CorruptSstable;
+        if (readU32(buffer, footerStart + 4) != version) return error.UnsupportedSstableVersion;
         const indexOffset = readU64(buffer, footerStart + 8);
         const indexLen = readU32(buffer, footerStart + 16);
         const bloomOffset = readU64(buffer, footerStart + 20);
@@ -204,7 +258,10 @@ pub const Reader = struct {
         var decoded = std.ArrayList(u8).init(allocator);
         errdefer decoded.deinit();
         var entries = std.ArrayList(IndexEntry).init(allocator);
-        errdefer entries.deinit();
+        errdefer {
+            for (entries.items) |e| allocator.free(e.restarts);
+            entries.deinit();
+        }
 
         var pos: usize = 0;
         while (pos < indexData.len) {
@@ -221,11 +278,19 @@ pub const Reader = struct {
             const payload = physical[blockPrefix..];
             const plainBlock = try compress.decode(allocator, codec, payload, originalLen);
             defer allocator.free(plainBlock);
+            const expanded = try expandBlock(allocator, plainBlock);
+            defer allocator.free(expanded.bytes);
+            errdefer allocator.free(expanded.restarts);
 
             const decOffset = decoded.items.len;
-            try decoded.appendSlice(plainBlock);
+            try decoded.appendSlice(expanded.bytes);
 
-            try entries.append(.{ .offset = decOffset, .blockLen = @intCast(plainBlock.len), .firstKey = firstKey });
+            try entries.append(.{
+                .offset = decOffset,
+                .blockLen = @intCast(expanded.bytes.len),
+                .firstKey = firstKey,
+                .restarts = expanded.restarts,
+            });
             pos = keyStart + firstKeyLen;
         }
 
@@ -265,6 +330,7 @@ pub const Reader = struct {
     }
 
     pub fn deinit(self: *Reader) void {
+        for (self.index) |e| self.allocator.free(e.restarts);
         self.allocator.free(self.index);
         self.bloom.deinit();
         self.allocator.free(self.dataBuf);
@@ -279,7 +345,7 @@ pub const Reader = struct {
         if (!self.bloom.mayContain(key)) return null;
         const blockIdx = self.findBlock(key) orelse return null;
         const block = self.blockBytes(blockIdx);
-        var pos: usize = 0;
+        var pos: usize = Reader.seekInBlock(block, self.index[blockIdx].restarts, key);
         while (pos < block.len) {
             const decoded = decodeRecord(block, pos);
             switch (order(decoded.record.key, key)) {
@@ -307,7 +373,7 @@ pub const Reader = struct {
         const block = cached orelse self.dataBuf[entry.offset .. entry.offset + entry.blockLen];
         if (cached == null) try blockCache.put(blockKey, block);
 
-        var pos: usize = 0;
+        var pos: usize = Reader.seekInBlock(block, entry.restarts, key);
         while (pos < block.len) {
             const decoded = decodeRecord(block, pos);
             switch (order(decoded.record.key, key)) {
@@ -329,7 +395,10 @@ pub const Reader = struct {
     pub fn cursor(self: *const Reader, start: ?[]const u8) Cursor {
         var c = Cursor{ .reader = self, .blockIdx = 0, .pos = 0, .nextPos = 0, .cur = null };
         if (self.index.len == 0) return c;
-        c.blockIdx = if (start) |s| (self.findBlock(s) orelse 0) else 0;
+        if (start) |s| {
+            c.blockIdx = self.findBlock(s) orelse 0;
+            c.pos = Reader.seekInBlock(self.blockBytes(c.blockIdx), self.index[c.blockIdx].restarts, s);
+        }
         c.refresh();
         if (start) |s| {
             while (c.valid() and order(c.cur.?.key, s) == .lt) c.advance();
@@ -400,6 +469,30 @@ pub const Reader = struct {
         return ans;
     }
 
+    /// Binary-searches `restarts` (each entry the flat-block offset of a
+    /// restart record, ascending by key since keys are sorted within a
+    /// block) for the rightmost restart whose key is <= `key`, and returns
+    /// its offset. Callers then linear-scan forward from there instead of
+    /// from position 0, bounding the scan to at most `restartInterval`
+    /// records regardless of how many records the block holds. Returns 0
+    /// (restarts[0], always the block's first record) when `key` sorts
+    /// before every restart.
+    fn seekInBlock(block: []const u8, restarts: []const u32, key: []const u8) usize {
+        if (restarts.len == 0) return 0;
+        var lo: usize = 0;
+        var hi: usize = restarts.len;
+        while (lo < hi) {
+            const mid = lo + (hi - lo) / 2;
+            const rec = decodeRecord(block, restarts[mid]);
+            if (order(rec.record.key, key) != .gt) {
+                lo = mid + 1;
+            } else {
+                hi = mid;
+            }
+        }
+        return if (lo == 0) 0 else restarts[lo - 1];
+    }
+
     fn blockBytes(self: *const Reader, idx: usize) []const u8 {
         const entry = self.index[idx];
         return self.dataBuf[entry.offset .. entry.offset + entry.blockLen];
@@ -519,6 +612,113 @@ const Decoded = struct {
     next: usize,
 };
 
+const ExpandedBlock = struct {
+    bytes: []u8,
+    // Flat-block offsets (into `bytes`) of every restart record, ascending.
+    // Consumed by `Reader.seekInBlock` for binary-search point lookups.
+    restarts: []u32,
+};
+
+/// Reconstructs a physical block (prefix-compressed records plus its
+/// restart-offset trailer, as written by `Builder`) back into the flat
+/// every-record-carries-its-full-key layout that `decodeRecord` and every
+/// cursor in this file expect. Expansion happens once, right after
+/// decompression in `Reader.open`, so `dataBuf`/the block cache keep
+/// storing fully materialized blocks and the rest of the reader never has
+/// to know keys were delta-encoded on disk - in particular this preserves
+/// the invariant `db.zig`'s k-way merge relies on, that a cursor's current
+/// key slice stays valid until that same cursor is advanced again.
+///
+/// Also validates the restart trailer against the record stream: every
+/// declared restart offset must land exactly on a record whose `shared`
+/// field is 0, and every record with `shared` 0 at that exact interval
+/// must have a matching restart entry. This catches a truncated or
+/// shifted restart table that a whole-block CRC would not (the CRC only
+/// proves the compressed bytes were not corrupted in transit/on disk, not
+/// that this structural relationship inside them still holds).
+///
+/// Also re-derives, in the *flattened* block's own coordinates, the offset
+/// of each restart record (`ExpandedBlock.restarts`) so the read side can
+/// still binary-search to a restart-sized (<= restartInterval records)
+/// linear-scan window even though the on-disk shared/unshared deltas are
+/// gone post-expansion.
+fn expandBlock(allocator: Allocator, physical: []const u8) !ExpandedBlock {
+    if (physical.len < 4) return error.CorruptSstable;
+    const numRestarts = readU32(physical, physical.len - 4);
+    const restartTableBytes = @as(usize, numRestarts) * 4;
+    if (restartTableBytes + 4 > physical.len) return error.CorruptSstable;
+    const recordsEnd = physical.len - 4 - restartTableBytes;
+    const restartTable = physical[recordsEnd .. recordsEnd + restartTableBytes];
+
+    var out = std.ArrayList(u8).init(allocator);
+    errdefer out.deinit();
+
+    var flatRestarts = std.ArrayList(u32).init(allocator);
+    errdefer flatRestarts.deinit();
+
+    var prevKey = std.ArrayList(u8).init(allocator);
+    defer prevKey.deinit();
+
+    const perRecordFixed = 1 + 8 + 4 + 4 + 4;
+    var pos: usize = 0;
+    var restartIdx: usize = 0;
+    var recordIdx: usize = 0;
+    while (pos < recordsEnd) {
+        if (pos + perRecordFixed > recordsEnd) return error.CorruptSstable;
+        const kind = physical[pos];
+        const seq = readU64(physical, pos + 1);
+        const shared = readU32(physical, pos + 9);
+        const unshared = readU32(physical, pos + 13);
+        const valLen = readU32(physical, pos + 17);
+        const keyStart = pos + perRecordFixed;
+        if (shared > prevKey.items.len) return error.CorruptSstable;
+        if (keyStart + @as(usize, unshared) + @as(usize, valLen) > recordsEnd) return error.CorruptSstable;
+
+        // A genuine block (as `Builder` writes it) marks exactly every
+        // `restartInterval`-th record (by position within the block) as a
+        // restart, in order, with shared == 0. Checking both directions -
+        // a restart-interval position must be declared, and a declared
+        // offset must fall on a restart-interval position - catches a
+        // restart table that is present but shifted, truncated, or
+        // fabricated, not just one that is structurally impossible.
+        const shouldBeRestart = recordIdx % restartInterval == 0;
+        const isDeclaredRestart = restartIdx < numRestarts and readU32(restartTable, restartIdx * 4) == pos;
+        if (shouldBeRestart != isDeclaredRestart) return error.CorruptSstable;
+        if (shouldBeRestart) {
+            if (shared != 0) return error.CorruptSstable;
+            restartIdx += 1;
+            try flatRestarts.append(@intCast(out.items.len));
+        }
+
+        const unsharedBytes = physical[keyStart .. keyStart + unshared];
+        const valStart = keyStart + unshared;
+        const value = physical[valStart .. valStart + valLen];
+
+        const fullKey = try allocator.alloc(u8, shared + unshared);
+        defer allocator.free(fullKey);
+        @memcpy(fullKey[0..shared], prevKey.items[0..shared]);
+        @memcpy(fullKey[shared..], unsharedBytes);
+
+        const writer = encode.ByteWriter.init(&out);
+        try writer.byte(kind);
+        try writer.putU64(seq);
+        try writer.putU32(@intCast(fullKey.len));
+        try writer.putU32(valLen);
+        try writer.slice(fullKey);
+        try writer.slice(value);
+
+        prevKey.clearRetainingCapacity();
+        try prevKey.appendSlice(fullKey);
+
+        pos = valStart + valLen;
+        recordIdx += 1;
+    }
+    if (pos != recordsEnd) return error.CorruptSstable;
+    if (restartIdx != numRestarts) return error.CorruptSstable;
+
+    return .{ .bytes = try out.toOwnedSlice(), .restarts = try flatRestarts.toOwnedSlice() };
+}
+
 fn decodeRecord(block: []const u8, pos: usize) Decoded {
     const kind: Kind = @enumFromInt(block[pos]);
     const seq = readU64(block, pos + 1);
@@ -604,6 +804,73 @@ test "sstable cursor seek" {
     try std.testing.expect(!beyond.valid());
 }
 
+test "restart index lets point lookups skip straight past earlier records in a block" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    try buildFixture(allocator, tmp.dir, "test.sst", 500);
+    var reader = try Reader.open(allocator, tmp.dir, "test.sst", 1);
+    defer reader.deinit();
+
+    // Every block must have carried its restart offsets through expansion:
+    // the first is always the block's own first record, and multi-restart
+    // blocks (any block with more than restartInterval records) must have
+    // strictly increasing keys at each restart, matching overall key order.
+    var sawMultiRestartBlock = false;
+    var blockIdx: usize = 0;
+    while (blockIdx < reader.index.len) : (blockIdx += 1) {
+        const entry = reader.index[blockIdx];
+        try std.testing.expect(entry.restarts.len >= 1);
+        try std.testing.expectEqual(@as(u32, 0), entry.restarts[0]);
+        if (entry.restarts.len > 1) sawMultiRestartBlock = true;
+
+        const block = reader.blockBytes(blockIdx);
+        var prevKey: []const u8 = &.{};
+        for (entry.restarts) |r| {
+            const rec = decodeRecord(block, r);
+            if (prevKey.len > 0) try std.testing.expect(order(prevKey, rec.record.key) == .lt);
+            prevKey = rec.record.key;
+        }
+    }
+    // 500 records at ~87/block (blockTarget 4096 / ~47 bytes/record) and
+    // restartInterval 16 guarantees at least one block with several
+    // restarts - if this ever goes false the fixture stopped exercising
+    // the multi-restart path the rest of this test relies on.
+    try std.testing.expect(sawMultiRestartBlock);
+
+    // A probe exactly equal to a later restart's key must land on that
+    // restart's own offset (the binary search must not undershoot to an
+    // earlier restart when there is an exact match).
+    const entry0 = reader.index[0];
+    try std.testing.expect(entry0.restarts.len > 2);
+    const block0 = reader.blockBytes(0);
+    const secondRestartOffset = entry0.restarts[1];
+    const secondRestartKey = decodeRecord(block0, secondRestartOffset).record.key;
+    try std.testing.expectEqual(secondRestartOffset, Reader.seekInBlock(block0, entry0.restarts, secondRestartKey));
+
+    // A probe strictly between the first and second restart's keys must
+    // stay on the first restart (must not overshoot to the second).
+    const firstRestartKey = decodeRecord(block0, entry0.restarts[0]).record.key;
+    var midBuf: [16]u8 = undefined;
+    @memcpy(midBuf[0..firstRestartKey.len], firstRestartKey);
+    midBuf[firstRestartKey.len - 1] += 1; // one key past first restart's key
+    try std.testing.expect(order(midBuf[0..firstRestartKey.len], secondRestartKey) == .lt);
+    try std.testing.expectEqual(entry0.restarts[0], Reader.seekInBlock(block0, entry0.restarts, midBuf[0..firstRestartKey.len]));
+
+    // A probe past every restart's key must resolve to the last restart.
+    const lastRestartKey = decodeRecord(block0, entry0.restarts[entry0.restarts.len - 1]).record.key;
+    var pastBuf: [16]u8 = undefined;
+    @memcpy(pastBuf[0..lastRestartKey.len], lastRestartKey);
+    pastBuf[lastRestartKey.len - 1] += 1;
+    try std.testing.expectEqual(entry0.restarts[entry0.restarts.len - 1], Reader.seekInBlock(block0, entry0.restarts, pastBuf[0..lastRestartKey.len]));
+
+    // End to end: lookups still resolve correctly for keys sitting right at
+    // and around restart boundaries, now that the scan starts mid-block.
+    try std.testing.expectEqualStrings("payload-value", reader.find(firstRestartKey).?.value);
+    try std.testing.expectEqualStrings("payload-value", reader.find(secondRestartKey).?.value);
+}
+
 test "sstable reverse cursor descends fully" {
     const allocator = std.testing.allocator;
     var tmp = std.testing.tmpDir(.{});
@@ -648,3 +915,198 @@ test "sstable reverse cursor honors upper bound" {
     defer below.deinit();
     try std.testing.expect(!below.valid());
 }
+
+fn writeRawRecord(w: encode.ByteWriter, kind: Kind, seq: u64, shared: u32, unshared: []const u8, value: []const u8) !void {
+    try w.byte(@intFromEnum(kind));
+    try w.putU64(seq);
+    try w.putU32(shared);
+    try w.putU32(@intCast(unshared.len));
+    try w.putU32(@intCast(value.len));
+    try w.slice(unshared);
+    try w.slice(value);
+}
+
+test "expandBlock reconstructs prefix-compressed records" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+
+    try writeRawRecord(w, .value, 1, 0, "apple", "1");
+    try writeRawRecord(w, .value, 2, 3, "ly", "2"); // "app" + "ly" = "apply"
+    try writeRawRecord(w, .tombstone, 3, 2, "ricot", ""); // "ap" + "ricot" = "apricot"
+    try w.putU32(0); // one restart, at offset 0
+    try w.putU32(1);
+
+    const expanded = try expandBlock(allocator, buf.items);
+    defer allocator.free(expanded.bytes);
+    defer allocator.free(expanded.restarts);
+
+    const d0 = decodeRecord(expanded.bytes, 0);
+    try std.testing.expectEqualStrings("apple", d0.record.key);
+    try std.testing.expectEqualStrings("1", d0.record.value);
+    try std.testing.expectEqual(Kind.value, d0.record.kind);
+
+    const d1 = decodeRecord(expanded.bytes, d0.next);
+    try std.testing.expectEqualStrings("apply", d1.record.key);
+    try std.testing.expectEqualStrings("2", d1.record.value);
+
+    const d2 = decodeRecord(expanded.bytes, d1.next);
+    try std.testing.expectEqualStrings("apricot", d2.record.key);
+    try std.testing.expectEqual(Kind.tombstone, d2.record.kind);
+    try std.testing.expectEqual(d2.next, expanded.bytes.len);
+
+    // Only the first record is a restart in this fixture (interval=16,
+    // 3 records) - `flatRestarts` must record exactly its flat offset (0).
+    try std.testing.expectEqualSlices(u32, &.{0}, expanded.restarts);
+}
+
+test "expandBlock rejects a restart declared at the wrong record" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+
+    const record0End = 1 + 8 + 4 + 4 + 4 + 5 + 1; // header + "apple" + "1"
+    try writeRawRecord(w, .value, 1, 0, "apple", "1");
+    try writeRawRecord(w, .value, 2, 3, "ly", "2");
+    try w.putU32(@intCast(record0End)); // restart claims record 1's offset, not record 0's
+    try w.putU32(1);
+
+    try std.testing.expectError(error.CorruptSstable, expandBlock(allocator, buf.items));
+}
+
+test "expandBlock rejects a missing restart declaration" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+
+    try writeRawRecord(w, .value, 1, 0, "apple", "1");
+    try w.putU32(0); // trailer present but claims zero restarts
+
+    try std.testing.expectError(error.CorruptSstable, expandBlock(allocator, buf.items));
+}
+
+test "expandBlock rejects shared length exceeding the previous key" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+
+    try writeRawRecord(w, .value, 1, 0, "ab", "1"); // prevKey becomes "ab", len 2
+    try writeRawRecord(w, .value, 2, 5, "xyz", "2"); // shared=5 > len("ab")
+    try w.putU32(0);
+    try w.putU32(1);
+
+    try std.testing.expectError(error.CorruptSstable, expandBlock(allocator, buf.items));
+}
+
+test "expandBlock rejects a record stream that overruns its declared lengths" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+
+    try w.byte(@intFromEnum(Kind.value));
+    try w.putU64(1);
+    try w.putU32(0);
+    try w.putU32(100); // claims 100 unshared key bytes that are never written
+    try w.putU32(0);
+    try w.putU32(0);
+    try w.putU32(1);
+
+    try std.testing.expectError(error.CorruptSstable, expandBlock(allocator, buf.items));
+}
+
+test "expandBlock rejects trailing bytes that do not form a full record" {
+    const allocator = std.testing.allocator;
+    var buf = std.ArrayList(u8).init(allocator);
+    defer buf.deinit();
+    const w = encode.ByteWriter.init(&buf);
+
+    try writeRawRecord(w, .value, 1, 0, "apple", "1");
+    try w.byte(0xff); // stray byte before the restart trailer
+    try w.putU32(0);
+    try w.putU32(1);
+
+    try std.testing.expectError(error.CorruptSstable, expandBlock(allocator, buf.items));
+}
+
+test "Reader.open rejects an sstable written by an unsupported format version" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    try buildFixture(allocator, tmp.dir, "test.sst", 10);
+
+    {
+        var file = try tmp.dir.openFile("test.sst", .{ .mode = .read_write });
+        defer file.close();
+        const size = try file.getEndPos();
+        // version u32 sits right after the magic u32 at the footer's start.
+        try file.seekTo(size - footerLen + 4);
+        var bogus: [4]u8 = undefined;
+        std.mem.writeInt(u32, &bogus, version + 1, encode.endian);
+        try file.writeAll(&bogus);
+    }
+
+    try std.testing.expectError(error.UnsupportedSstableVersion, Reader.open(allocator, tmp.dir, "test.sst", 1));
+}
+
+test "prefix compression measurably shrinks sstables with a shared key prefix" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    const count = 3000;
+
+    {
+        var builder = try Builder.init(allocator, tmp.dir, "shared.sst", count);
+        defer builder.deinit();
+        var buf: [64]u8 = undefined;
+        var i: usize = 0;
+        while (i < count) : (i += 1) {
+            const key = try std.fmt.bufPrint(&buf, "users\x00city\x00warsaw\x00pk{d:0>8}", .{i});
+            try builder.add(.{ .key = key, .value = "v", .seq = i + 1, .kind = .value });
+        }
+        try builder.finish();
+    }
+    {
+        var builder = try Builder.init(allocator, tmp.dir, "distinct.sst", count);
+        defer builder.deinit();
+        var buf: [64]u8 = undefined;
+        var i: usize = 0;
+        while (i < count) : (i += 1) {
+            // Same value payload and roughly the same key length as above,
+            // but scrambled so consecutive keys share no meaningful prefix -
+            // isolates the saving to prefix compression rather than the
+            // block-level RLE codec, which would compress a repeated value
+            // just as well in both files.
+            const scrambled = i *% 2654435761;
+            const key = try std.fmt.bufPrint(&buf, "{d:0>20}", .{scrambled});
+            try builder.add(.{ .key = key, .value = "v", .seq = i + 1, .kind = .value });
+        }
+        try builder.finish();
+    }
+
+    var sharedReader = try Reader.open(allocator, tmp.dir, "shared.sst", 1);
+    defer sharedReader.deinit();
+    var distinctReader = try Reader.open(allocator, tmp.dir, "distinct.sst", 2);
+    defer distinctReader.deinit();
+
+    try std.testing.expectEqual(@as(u64, count), sharedReader.numEntries);
+    try std.testing.expectEqual(@as(u64, count), distinctReader.numEntries);
+    // Prefix compression must shrink the file meaningfully below the
+    // no-shared-prefix baseline (measured ~25% smaller at this fixture
+    // size), not just avoid growing it. Bloom filter and index overhead
+    // is identical in both files, so the margin here comes entirely from
+    // smaller data blocks.
+    try std.testing.expect(sharedReader.physicalBytes * 5 < distinctReader.physicalBytes * 4);
+
+    // Correctness survives the smaller on-disk encoding.
+    try std.testing.expectEqualStrings("v", sharedReader.find("users\x00city\x00warsaw\x00pk00000000").?.value);
+    try std.testing.expectEqualStrings("v", sharedReader.find("users\x00city\x00warsaw\x00pk00000150").?.value);
+    try std.testing.expectEqualStrings("v", sharedReader.find("users\x00city\x00warsaw\x00pk00000299").?.value);
+    try std.testing.expectEqual(@as(?Record, null), sharedReader.find("users\x00city\x00warsaw\x00pk99999999"));
+}
diff --git a/src/ttl.zig b/src/ttl.zig
new file mode 100644
index 0000000..f5c1cf1
--- /dev/null
+++ b/src/ttl.zig
@@ -0,0 +1,293 @@
+const std = @import("std");
+const dbmod = @import("db.zig");
+
+const Allocator = std.mem.Allocator;
+const Db = dbmod.Db;
+
+/// Per-key expiry markers layered over the flat KV keyspace, sharing one Db
+/// with tables/collections/auth (row.zig/index.zig use 'R'/'I'/'J'/'M',
+/// collections.zig uses 'X', auth.zig uses 'A'; every key here starts with
+/// 'T' so none of the namespaces collide):
+///   "T" <key>  -> raw i128 (expiresAtNanos, big-endian)
+/// The marker lives in the SAME Db as the key it guards (same WAL, same
+/// flush/compaction lifecycle, same crash-durability boundary) but expiry
+/// is enforced lazily: nothing here runs a background clock itself. A
+/// caller must present nowNanos, either on every read (expireIfDue/getLive)
+/// or through an explicit sweep (sweepExpired) - matching how session.zig's
+/// SessionStore already treats "now" as an input rather than ambient state
+/// (and uses the same i128 type std.time.nanoTimestamp() returns), so both
+/// are trivially testable without sleeping in unit tests.
+pub const nsTag: u8 = 'T';
+
+pub const secondNanos: i128 = 1_000_000_000;
+
+fn markerKey(allocator: Allocator, key: []const u8) ![]u8 {
+    const out = try allocator.alloc(u8, key.len + 1);
+    out[0] = nsTag;
+    @memcpy(out[1..], key);
+    return out;
+}
+
+fn putI128(out: *std.ArrayList(u8), v: i128) !void {
+    var b: [16]u8 = undefined;
+    std.mem.writeInt(i128, &b, v, .big);
+    try out.appendSlice(&b);
+}
+
+fn readI128(data: []const u8) !i128 {
+    if (data.len != 16) return error.Malformed;
+    return std.mem.readInt(i128, data[0..16], .big);
+}
+
+/// Sets (or replaces) an absolute expiry deadline on `key`. Does not verify
+/// `key` currently exists in the main keyspace - callers that need
+/// existence-checked semantics (the CLI `expire` command) check db.get
+/// first, same as Redis distinguishes EXPIRE from the looser PEXPIREAT.
+pub fn setExpireAt(db: *Db, allocator: Allocator, key: []const u8, expiresAtNanos: i128) !void {
+    const k = try markerKey(allocator, key);
+    defer allocator.free(k);
+    var out = std.ArrayList(u8).init(allocator);
+    defer out.deinit();
+    try putI128(&out, expiresAtNanos);
+    try db.put(k, out.items);
+}
+
+pub fn setExpireSeconds(db: *Db, allocator: Allocator, key: []const u8, nowNanos: i128, seconds: u64) !void {
+    try setExpireAt(db, allocator, key, nowNanos + @as(i128, @intCast(seconds)) * secondNanos);
+}
+
+pub fn getExpiresAt(db: *Db, allocator: Allocator, key: []const u8) !?i128 {
+    const k = try markerKey(allocator, key);
+    defer allocator.free(k);
+    const raw = try db.get(allocator, k) orelse return null;
+    defer allocator.free(raw);
+    return try readI128(raw);
+}
+
+pub fn clearExpire(db: *Db, allocator: Allocator, key: []const u8) !void {
+    const k = try markerKey(allocator, key);
+    defer allocator.free(k);
+    try db.delete(k);
+}
+
+pub fn isDue(expiresAtNanos: i128, nowNanos: i128) bool {
+    return nowNanos >= expiresAtNanos;
+}
+
+/// Redis TTL(2) semantics for the CLI: `.noKey` mirrors return -2 (the key
+/// itself is absent), `.noExpiry` mirrors -1 (it exists but carries no
+/// expiry), `.seconds` is the whole seconds left, floored at 0 so a marker
+/// that is due but not yet reaped never reports a negative remainder.
+pub const TtlResult = union(enum) {
+    noKey,
+    noExpiry,
+    seconds: u64,
+};
+
+pub fn remaining(db: *Db, allocator: Allocator, key: []const u8, nowNanos: i128) !TtlResult {
+    const existing = try db.get(allocator, key) orelse return .noKey;
+    allocator.free(existing);
+    const expiresAt = try getExpiresAt(db, allocator, key) orelse return .noExpiry;
+    if (nowNanos >= expiresAt) return .{ .seconds = 0 };
+    return .{ .seconds = @intCast(@divFloor(expiresAt - nowNanos, secondNanos)) };
+}
+
+/// Lazily enforces expiry on read: if `key` carries a due marker, deletes
+/// both the marker and the underlying key (a real delete through the normal
+/// WAL/tombstone path, not just "pretend it's gone") and reports true.
+pub fn expireIfDue(db: *Db, allocator: Allocator, key: []const u8, nowNanos: i128) !bool {
+    const expiresAt = try getExpiresAt(db, allocator, key) orelse return false;
+    if (!isDue(expiresAt, nowNanos)) return false;
+    try db.delete(key);
+    try clearExpire(db, allocator, key);
+    return true;
+}
+
+/// db.get with lazy expiry applied first - the read-path counterpart of
+/// putWithTtl, so a caller never observes a logically-expired value just
+/// because no sweep has run yet.
+pub fn getLive(db: *Db, allocator: Allocator, key: []const u8, nowNanos: i128) !?[]u8 {
+    _ = try expireIfDue(db, allocator, key, nowNanos);
+    return db.get(allocator, key);
+}
+
+pub fn putWithTtl(db: *Db, allocator: Allocator, key: []const u8, value: []const u8, nowNanos: i128, seconds: u64) !void {
+    try db.put(key, value);
+    try setExpireSeconds(db, allocator, key, nowNanos, seconds);
+}
+
+/// Active sweep: scans every marker under the 'T' namespace and reaps every
+/// one that is due, deleting both the underlying key and its marker.
+/// Returns the number reaped. Two passes on purpose - a RangeIterator's
+/// merge heap holds live cursor positions directly into the memtable being
+/// walked (only the Entry it hands back through next() is arena-copied),
+/// so issuing db.delete mid-scan would mutate the very structure the
+/// iterator's cursors are threaded through. Collect the due keys first,
+/// mutate only after the iterator (and its cursors) are closed.
+pub fn sweepExpired(db: *Db, allocator: Allocator, nowNanos: i128) !usize {
+    var due = std.ArrayList([]u8).init(allocator);
+    defer {
+        for (due.items) |k| allocator.free(k);
+        due.deinit();
+    }
+    {
+        const prefix = &[_]u8{nsTag};
+        var iter = try db.scanPrefix(allocator, prefix);
+        defer iter.deinit();
+        while (try iter.next()) |entry| {
+            const expiresAt = try readI128(entry.value);
+            if (isDue(expiresAt, nowNanos)) {
+                try due.append(try allocator.dupe(u8, entry.key[1..]));
+            }
+        }
+    }
+    for (due.items) |userKey| {
+        try db.delete(userKey);
+        try clearExpire(db, allocator, userKey);
+    }
+    return due.items.len;
+}
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    var pathBuf: [std.fs.max_path_bytes]u8 = undefined;
+    const base = try tmp.dir.realpath(".", &pathBuf);
+    var dbPathBuf: [std.fs.max_path_bytes]u8 = undefined;
+    const dbPath = try std.fmt.bufPrint(&dbPathBuf, "{s}/store", .{base});
+    return Db.open(allocator, dbPath, .{});
+}
+
+test "remaining reports noKey, noExpiry, and counted seconds" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try std.testing.expectEqual(TtlResult.noKey, try remaining(&db, allocator, "missing", 0));
+
+    try db.put("plain", "v");
+    try std.testing.expectEqual(TtlResult.noExpiry, try remaining(&db, allocator, "plain", 0));
+
+    try setExpireSeconds(&db, allocator, "plain", 1000, 30);
+    const r = try remaining(&db, allocator, "plain", 1000);
+    try std.testing.expectEqual(@as(u64, 30), r.seconds);
+}
+
+test "expireIfDue removes value and marker only once due" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try db.put("session:1", "payload");
+    try setExpireSeconds(&db, allocator, "session:1", 0, 5);
+
+    try std.testing.expect(!try expireIfDue(&db, allocator, "session:1", 4 * secondNanos));
+    const stillThere = (try db.get(allocator, "session:1")).?;
+    allocator.free(stillThere);
+
+    try std.testing.expect(try expireIfDue(&db, allocator, "session:1", 5 * secondNanos));
+    try std.testing.expectEqual(@as(?[]u8, null), try db.get(allocator, "session:1"));
+    try std.testing.expectEqual(@as(?i128, null), try getExpiresAt(&db, allocator, "session:1"));
+}
+
+test "getLive lazily expires exactly at the deadline" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try putWithTtl(&db, allocator, "cache:x", "hot", 0, 2);
+
+    const before = (try getLive(&db, allocator, "cache:x", 1 * secondNanos)).?;
+    defer allocator.free(before);
+    try std.testing.expectEqualStrings("hot", before);
+
+    try std.testing.expectEqual(@as(?[]u8, null), try getLive(&db, allocator, "cache:x", 2 * secondNanos));
+    // A plain db.get after the lazy expiry proves the delete was real, not
+    // getLive-only bookkeeping - the tombstone is now the source of truth.
+    try std.testing.expectEqual(@as(?[]u8, null), try db.get(allocator, "cache:x"));
+}
+
+test "clearExpire makes a key immortal again" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try putWithTtl(&db, allocator, "note", "keep me", 0, 1);
+    try clearExpire(&db, allocator, "note");
+
+    try std.testing.expectEqual(TtlResult.noExpiry, try remaining(&db, allocator, "note", 100 * secondNanos));
+    const v = (try getLive(&db, allocator, "note", 100 * secondNanos)).?;
+    defer allocator.free(v);
+    try std.testing.expectEqualStrings("keep me", v);
+}
+
+test "sweepExpired reaps every due key without touching live or unrelated keys" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try putWithTtl(&db, allocator, "a", "1", 0, 1);
+    try putWithTtl(&db, allocator, "b", "2", 0, 100);
+    try putWithTtl(&db, allocator, "c", "3", 0, 1);
+    try db.put("d", "forever");
+
+    const reaped = try sweepExpired(&db, allocator, 2 * secondNanos);
+    try std.testing.expectEqual(@as(usize, 2), reaped);
+
+    try std.testing.expectEqual(@as(?[]u8, null), try db.get(allocator, "a"));
+    try std.testing.expectEqual(@as(?[]u8, null), try db.get(allocator, "c"));
+
+    const b = (try db.get(allocator, "b")).?;
+    defer allocator.free(b);
+    try std.testing.expectEqualStrings("2", b);
+
+    const d = (try db.get(allocator, "d")).?;
+    defer allocator.free(d);
+    try std.testing.expectEqualStrings("forever", d);
+
+    // Idempotent: a second sweep at the same instant finds nothing left.
+    try std.testing.expectEqual(@as(usize, 0), try sweepExpired(&db, allocator, 2 * secondNanos));
+}
+
+test "sweep survives a wal reopen: markers are durable, not in-memory bookkeeping" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    {
+        var db = try openTemp(&tmp, allocator);
+        defer db.close();
+        try putWithTtl(&db, allocator, "durable-ttl", "v", 0, 5);
+    }
+
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+    const r = try remaining(&db, allocator, "durable-ttl", 1 * secondNanos);
+    try std.testing.expectEqual(@as(u64, 4), r.seconds);
+
+    try std.testing.expectEqual(@as(usize, 1), try sweepExpired(&db, allocator, 10 * secondNanos));
+    try std.testing.expectEqual(@as(?[]u8, null), try db.get(allocator, "durable-ttl"));
+}
+
+test "setExpireAt on a nonexistent key is a real marker, not silently rejected" {
+    // Documents the PEXPIREAT-like looseness of setExpireAt directly (the
+    // CLI layer is what adds the Redis EXPIRE existence check on top).
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try setExpireSeconds(&db, allocator, "ghost", 0, 10);
+    try std.testing.expectEqual(TtlResult.noKey, try remaining(&db, allocator, "ghost", 0));
+    const expiresAt = (try getExpiresAt(&db, allocator, "ghost")).?;
+    try std.testing.expectEqual(@as(i128, 10 * secondNanos), expiresAt);
+}
diff --git a/src/txn.zig b/src/txn.zig
index 0c06b77..828b55c 100644
--- a/src/txn.zig
+++ b/src/txn.zig
@@ -81,6 +81,62 @@ pub const Transaction = struct {
         try self.reads.put(keyCopy, {});
     }
 
+    /// One key/value pair from `scanPrefix`, owned by the caller (free with
+    /// `freeEntries`).
+    pub const Entry = struct {
+        key: []u8,
+        value: []u8,
+
+        fn free(self: Entry, allocator: Allocator) void {
+            allocator.free(self.key);
+            allocator.free(self.value);
+        }
+    };
+
+    pub fn freeEntries(allocator: Allocator, entries: []Entry) void {
+        for (entries) |e| e.free(allocator);
+        allocator.free(entries);
+    }
+
+    /// Prefix scan that reflects this transaction's own uncommitted writes,
+    /// the same read-your-writes promise `get` makes for a single key
+    /// extended to a whole key range: a row staged here shadows whatever the
+    /// committed snapshot has under that exact key (a staged tombstone hides
+    /// it entirely, a staged value replaces it), and a brand-new key staged
+    /// here that falls under `prefix` shows up even though the underlying
+    /// `Db` has never durably seen it. Every entry the underlying snapshot
+    /// contributes is also recorded as a read for OCC purposes, same as
+    /// `get` - a concurrent external write to one of those existing keys
+    /// between now and `commit()` is still caught as `error.Conflict`. A
+    /// concurrent external INSERT of a brand-new key under `prefix` is not
+    /// caught (there is no key to register a read against before it
+    /// exists) - the same phantom-read gap every OCC scheme without
+    /// range-locks has, not something specific to this method.
+    pub fn scanPrefix(self: *Transaction, allocator: Allocator, prefix: []const u8) ![]Entry {
+        var results = std.ArrayList(Entry).init(allocator);
+        errdefer {
+            for (results.items) |e| e.free(allocator);
+            results.deinit();
+        }
+
+        var it = try self.db.scanPrefixAsOf(allocator, prefix, self.snapshotSeq);
+        defer it.deinit();
+        while (try it.next()) |entry| {
+            if (self.writes.contains(entry.key)) continue;
+            try self.recordRead(entry.key);
+            try results.append(.{ .key = try allocator.dupe(u8, entry.key), .value = try allocator.dupe(u8, entry.value) });
+        }
+
+        var writeEntries = self.writes.iterator();
+        while (writeEntries.next()) |entry| {
+            if (!std.mem.startsWith(u8, entry.key_ptr.*, prefix)) continue;
+            if (entry.value_ptr.kind == .tombstone) continue;
+            try results.append(.{ .key = try allocator.dupe(u8, entry.key_ptr.*), .value = try allocator.dupe(u8, entry.value_ptr.value) });
+        }
+
+        return results.toOwnedSlice();
+    }
+
     pub fn commit(self: *Transaction) !void {
         var readKeys = self.reads.keyIterator();
         while (readKeys.next()) |key| {
@@ -186,3 +242,74 @@ test "conflicting commit is rejected but clean commit succeeds" {
     defer allocator.free(note);
     try std.testing.expectEqualStrings("ok", note);
 }
+
+test "scanPrefix sees committed rows and a staged brand-new key under the same prefix" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try db.put("idx:a", "1");
+    try db.put("idx:b", "2");
+    try db.put("other:z", "9");
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    try txn.put("idx:c", "3");
+
+    const entries = try txn.scanPrefix(allocator, "idx:");
+    defer Transaction.freeEntries(allocator, entries);
+    try std.testing.expectEqual(@as(usize, 3), entries.len);
+
+    var seenC = false;
+    for (entries) |e| {
+        if (std.mem.eql(u8, e.key, "idx:c")) {
+            try std.testing.expectEqualStrings("3", e.value);
+            seenC = true;
+        }
+    }
+    try std.testing.expect(seenC);
+}
+
+test "scanPrefix shadows a committed key with its staged replacement and hides a staged tombstone" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try db.put("idx:a", "old-a");
+    try db.put("idx:b", "old-b");
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    try txn.put("idx:a", "new-a");
+    try txn.delete("idx:b");
+
+    const entries = try txn.scanPrefix(allocator, "idx:");
+    defer Transaction.freeEntries(allocator, entries);
+    try std.testing.expectEqual(@as(usize, 1), entries.len);
+    try std.testing.expectEqualStrings("idx:a", entries[0].key);
+    try std.testing.expectEqualStrings("new-a", entries[0].value);
+}
+
+test "scanPrefix registers committed keys as reads, so a concurrent external write under it still conflicts at commit" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    try db.put("idx:a", "1");
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    const entries = try txn.scanPrefix(allocator, "idx:");
+    Transaction.freeEntries(allocator, entries);
+
+    try db.put("idx:a", "external-change");
+
+    try txn.put("unrelated", "1");
+    try std.testing.expectError(error.Conflict, txn.commit());
+}
diff --git a/src/txn_table.zig b/src/txn_table.zig
new file mode 100644
index 0000000..4fdbd54
--- /dev/null
+++ b/src/txn_table.zig
@@ -0,0 +1,1029 @@
+const std = @import("std");
+const txnmod = @import("txn.zig");
+const dbmod = @import("db.zig");
+const rowmod = @import("row.zig");
+const idx = @import("index.zig");
+const querymod = @import("query.zig");
+const exprmod = @import("expr.zig");
+
+const Allocator = std.mem.Allocator;
+const Transaction = txnmod.Transaction;
+const Db = dbmod.Db;
+const Value = rowmod.Value;
+const Row = rowmod.Row;
+const Field = rowmod.Field;
+const IndexSet = idx.IndexSet;
+const UniqueSet = idx.UniqueSet;
+const ForeignKeySet = idx.ForeignKeySet;
+const CheckConstraintSet = idx.CheckConstraintSet;
+
+/// Same reserved primary-key field name query.zig's Table uses, so rows
+/// written through a TableTxn and rows written through a plain Table are
+/// wire-compatible: both land in the same "R\x00table\x00pk" keyspace and
+/// decode identically.
+pub const pkField = querymod.pkField;
+
+/// A Table view bound to one in-flight Transaction. Where query.zig's Table
+/// writes each row and its index entries directly to the Db (each `put`/
+/// `delete` call is independently durable the moment it returns), TableTxn
+/// stages every row write and every index-entry write into the Transaction's
+/// write set instead. Nothing is visible to other readers, and nothing can
+/// conflict with a concurrent writer, until the caller calls `Transaction.
+/// commit()` - at which point every staged row and index mutation across
+/// every TableTxn.put/delete call made against this Transaction becomes
+/// visible atomically in a single WriteBatch, or none of it does (OCC
+/// conflict -> error.Conflict, no partial application).
+///
+/// Index membership itself (which fields are indexed) is read directly from
+/// the Db when a TableTxn is opened, not through the Transaction - creating
+/// or dropping an index is a schema change made through query.zig's Table,
+/// not through TableTxn. A TableTxn only keeps *existing* indexes in sync
+/// for the rows it writes.
+pub const TableTxn = struct {
+    txn: *Transaction,
+    allocator: Allocator,
+    name: []u8,
+    indexes: IndexSet,
+    unique: UniqueSet,
+    foreignKeys: ForeignKeySet,
+    checks: CheckConstraintSet,
+
+    pub fn open(txn: *Transaction, allocator: Allocator, name: []const u8) !TableTxn {
+        if (!idx.validIdentifier(name)) return error.InvalidIdentifier;
+        return .{
+            .txn = txn,
+            .allocator = allocator,
+            .name = try allocator.dupe(u8, name),
+            .indexes = try IndexSet.load(allocator, txn.db, name),
+            .unique = try UniqueSet.load(allocator, txn.db, name),
+            .foreignKeys = try ForeignKeySet.load(allocator, txn.db, name),
+            .checks = try CheckConstraintSet.load(allocator, txn.db, name),
+        };
+    }
+
+    pub fn deinit(self: *TableTxn) void {
+        self.allocator.free(self.name);
+        self.indexes.deinit();
+        self.unique.deinit();
+        self.foreignKeys.deinit();
+        self.checks.deinit();
+    }
+
+    pub fn hasIndex(self: *const TableTxn, field: []const u8) bool {
+        return self.indexes.has(field);
+    }
+
+    pub fn hasUniqueIndex(self: *const TableTxn, field: []const u8) bool {
+        return self.unique.has(field);
+    }
+
+    pub fn hasForeignKey(self: *const TableTxn, field: []const u8) bool {
+        return self.foreignKeys.has(field);
+    }
+
+    pub fn hasCheckConstraint(self: *const TableTxn, name: []const u8) bool {
+        return self.checks.has(name);
+    }
+
+    /// Whether `value` names an existing row of `spec.refTable` under
+    /// `spec.refField`, mirroring `query.zig`'s `Table.foreignKeyTargetExists`
+    /// with one difference: both branches go through the bound `Transaction`
+    /// instead of a plain `Db` call, so a parent row (or a unique-field FK
+    /// target) staged earlier in the SAME uncommitted transaction already
+    /// satisfies a child's FK check before either is durable -
+    /// read-your-writes across tables, not just within one, via
+    /// `Transaction.get` for the `pkField` case and `Transaction.scanPrefix`
+    /// (see its doc comment) for the non-pk case.
+    fn foreignKeyTargetExists(self: *TableTxn, refTableName: []const u8, refField: []const u8, value: Value) !bool {
+        if (std.mem.eql(u8, refField, pkField)) {
+            const key = try idx.rowKey(self.allocator, refTableName, value);
+            defer self.allocator.free(key);
+            const raw = try self.txn.get(self.allocator, key) orelse return false;
+            self.allocator.free(raw);
+            return true;
+        }
+        const prefix = try idx.indexValueBound(self.allocator, refTableName, refField, value);
+        defer self.allocator.free(prefix);
+        const entries = try self.txn.scanPrefix(self.allocator, prefix);
+        defer txnmod.Transaction.freeEntries(self.allocator, entries);
+        return entries.len > 0;
+    }
+
+    /// Reads through the bound Transaction, so this sees the Transaction's
+    /// own uncommitted writes (read-your-writes) and registers the row key
+    /// as read for OCC conflict detection at commit time.
+    pub fn get(self: *TableTxn, pk: Value) !?Row {
+        const key = try idx.rowKey(self.allocator, self.name, pk);
+        defer self.allocator.free(key);
+        const raw = try self.txn.get(self.allocator, key) orelse return null;
+        defer self.allocator.free(raw);
+        return try Row.decode(self.allocator, raw);
+    }
+
+    /// Stages a full-row replace of `pk` plus every index-entry add/remove
+    /// needed to keep currently-registered indexes consistent with the new
+    /// row, all as buffered Transaction writes. None of it is visible or
+    /// durable until commit.
+    pub fn put(self: *TableTxn, pk: Value, fields: []const Field) !void {
+        var old = try self.get(pk);
+        defer if (old) |*o| o.deinit();
+
+        var newRow = Row.init(self.allocator);
+        defer newRow.deinit();
+        try newRow.set(pkField, pk);
+        for (fields) |f| try newRow.set(f.name, f.value);
+
+        const encoded = try newRow.encode(self.allocator);
+        defer self.allocator.free(encoded);
+        const key = try idx.rowKey(self.allocator, self.name, pk);
+        defer self.allocator.free(key);
+
+        // CHECK constraints run first, ahead of UNIQUE/FOREIGN KEY - same
+        // ordering and same "reparse on every put" cost as `query.zig`'s
+        // `Table.put`. Purely local to `newRow`, so unlike UNIQUE/FOREIGN
+        // KEY below this needs no `Transaction.scanPrefix` read-your-writes
+        // handling at all.
+        for (self.checks.specs.items) |spec| {
+            var parsed = exprmod.parse(self.allocator, spec.source) catch return error.InvalidCheckExpression;
+            defer parsed.deinit();
+            if (!parsed.predicate.evaluate(&newRow)) return error.CheckViolation;
+        }
+
+        // UNIQUE and FOREIGN KEY checks run before any staged mutation
+        // below, same all-or-nothing placement as `query.zig`'s `Table.put`:
+        // a violation leaves the transaction's write set exactly as it was
+        // before this call, not staged with a partial row. Both checks go
+        // through `Transaction.scanPrefix`, so a UNIQUE value or FK target
+        // staged by an EARLIER `put` call in this same still-open
+        // transaction (a different row, possibly a different `TableTxn`
+        // bound to the same `Transaction`) is caught here already, not left
+        // to surface as `error.Conflict` at `commit()`.
+        for (self.unique.fields.items) |field| {
+            const newValue = newRow.get(field) orelse continue;
+            const oldValue = if (old) |*o| o.get(field) else null;
+            if (oldValue != null and Value.eql(oldValue.?, newValue)) continue;
+            const prefix = try idx.indexValueBound(self.allocator, self.name, field, newValue);
+            defer self.allocator.free(prefix);
+            const entries = try self.txn.scanPrefix(self.allocator, prefix);
+            defer txnmod.Transaction.freeEntries(self.allocator, entries);
+            for (entries) |e| {
+                const ownerPk = try rowmod.decodeValue(self.allocator, e.value);
+                defer ownerPk.free(self.allocator);
+                if (!Value.eql(ownerPk, pk)) return error.UniqueViolation;
+            }
+        }
+
+        for (self.foreignKeys.specs.items) |spec| {
+            const newValue = newRow.get(spec.field) orelse continue;
+            if (newValue == .none) continue;
+            if (!try self.foreignKeyTargetExists(spec.refTable, spec.refField, newValue)) return error.ForeignKeyViolation;
+        }
+
+        // ON DELETE RESTRICT's update-side counterpart, see
+        // `updateRestrictedByForeignKey`'s doc comment - same all-or-nothing
+        // placement as every other constraint check above.
+        if (try self.updateRestrictedByForeignKey(pk, if (old) |*o| o else null, &newRow)) return error.ForeignKeyInUse;
+
+        for (self.indexes.fields.items) |indexedField| {
+            const newValue = newRow.get(indexedField);
+            const oldValue = if (old) |*o| o.get(indexedField) else null;
+            if (oldValue != null and (newValue == null or !Value.eql(oldValue.?, newValue.?))) {
+                try self.stageIndexRemove(indexedField, oldValue.?, pk);
+            }
+            if (newValue) |nv| {
+                if (oldValue == null or !Value.eql(oldValue.?, nv)) {
+                    try self.stageIndexAdd(indexedField, nv, pk);
+                }
+            }
+        }
+
+        try self.txn.put(key, encoded);
+    }
+
+    /// Mirrors `query.zig`'s `Table.deletionRestrictedByForeignKey` (SQL's
+    /// `ON DELETE RESTRICT`), reading through `self.txn.scanPrefix` instead
+    /// of a plain `Db` scan - the one thing this version can do that the
+    /// plain `Table` path cannot: a child row staged earlier in this SAME
+    /// uncommitted transaction (via a sibling `TableTxn` on the child
+    /// table, sharing this `Transaction`) already counts as a live
+    /// reference, not just whatever is durably committed. `referencedBy`
+    /// itself is still loaded fresh from `self.txn.db` rather than cached
+    /// (schema metadata - like `indexes`/`unique`/`foreignKeys` above - is
+    /// only ever mutated through `query.zig`'s `Table`, never through a
+    /// `TableTxn`, but unlike those, `ReferencedBySet` is written by some
+    /// OTHER table's `createForeignKey` call, so a `TableTxn` opened before
+    /// that ran cannot rely on whatever it loaded at `open()` time either -
+    /// see `Table.createForeignKey`'s doc comment for the same reasoning).
+    fn deletionRestrictedByForeignKey(self: *TableTxn, pk: Value, old: *const Row) !bool {
+        var referencedBy = try idx.ReferencedBySet.load(self.allocator, self.txn.db, self.name);
+        defer referencedBy.deinit();
+
+        for (referencedBy.specs.items) |spec| {
+            const value = old.get(spec.refField) orelse continue;
+            if (value == .none) continue;
+
+            const prefix = try idx.rowPrefix(self.allocator, spec.childTable);
+            defer self.allocator.free(prefix);
+            const entries = try self.txn.scanPrefix(self.allocator, prefix);
+            defer Transaction.freeEntries(self.allocator, entries);
+
+            const selfReferencing = std.mem.eql(u8, spec.childTable, self.name);
+            for (entries) |entry| {
+                var r = try Row.decode(self.allocator, entry.value);
+                defer r.deinit();
+                if (selfReferencing) {
+                    if (r.get(pkField)) |rowPk| {
+                        if (Value.eql(rowPk, pk)) continue;
+                    }
+                }
+                const childValue = r.get(spec.childField) orelse continue;
+                if (childValue == .none) continue;
+                if (Value.eql(childValue, value)) return true;
+            }
+        }
+        return false;
+    }
+
+    /// `TableTxn.put`'s counterpart to `deletionRestrictedByForeignKey`,
+    /// mirroring `query.zig`'s `Table.updateRestrictedByForeignKey` (see its
+    /// doc comment for why an update needs the same RESTRICT as a delete)
+    /// but reading through `self.txn.scanPrefix` like the delete-restrict
+    /// version above it, so a child row staged earlier in this same
+    /// uncommitted transaction already counts as a live reference. `old` may
+    /// be null (a fresh insert has nothing to pull out from under anyone),
+    /// and a `refField` whose new value equals its old value is exempt, the
+    /// same exemption `put`'s own UNIQUE check above makes.
+    fn updateRestrictedByForeignKey(self: *TableTxn, pk: Value, old: ?*const Row, newRow: *const Row) !bool {
+        var referencedBy = try idx.ReferencedBySet.load(self.allocator, self.txn.db, self.name);
+        defer referencedBy.deinit();
+
+        for (referencedBy.specs.items) |spec| {
+            const oldValue = if (old) |o| o.get(spec.refField) else null;
+            if (oldValue == null or oldValue.? == .none) continue;
+            const newValue = newRow.get(spec.refField);
+            if (newValue != null and Value.eql(oldValue.?, newValue.?)) continue;
+
+            const prefix = try idx.rowPrefix(self.allocator, spec.childTable);
+            defer self.allocator.free(prefix);
+            const entries = try self.txn.scanPrefix(self.allocator, prefix);
+            defer Transaction.freeEntries(self.allocator, entries);
+
+            const selfReferencing = std.mem.eql(u8, spec.childTable, self.name);
+            for (entries) |entry| {
+                var r = try Row.decode(self.allocator, entry.value);
+                defer r.deinit();
+                if (selfReferencing) {
+                    if (r.get(pkField)) |rowPk| {
+                        if (Value.eql(rowPk, pk)) continue;
+                    }
+                }
+                const childValue = r.get(spec.childField) orelse continue;
+                if (childValue == .none) continue;
+                if (Value.eql(childValue, oldValue.?)) return true;
+            }
+        }
+        return false;
+    }
+
+    pub fn delete(self: *TableTxn, pk: Value) !void {
+        var old = try self.get(pk) orelse return;
+        defer old.deinit();
+
+        if (try self.deletionRestrictedByForeignKey(pk, &old)) return error.ForeignKeyInUse;
+
+        for (self.indexes.fields.items) |indexedField| {
+            if (old.get(indexedField)) |v| {
+                try self.stageIndexRemove(indexedField, v, pk);
+            }
+        }
+
+        const key = try idx.rowKey(self.allocator, self.name, pk);
+        defer self.allocator.free(key);
+        try self.txn.delete(key);
+    }
+
+    fn stageIndexAdd(self: *TableTxn, field: []const u8, value: Value, pk: Value) !void {
+        const key = try idx.indexEntryKey(self.allocator, self.name, field, value, pk);
+        defer self.allocator.free(key);
+        const pkBytes = try rowmod.encodeValue(self.allocator, pk);
+        defer self.allocator.free(pkBytes);
+        try self.txn.put(key, pkBytes);
+    }
+
+    fn stageIndexRemove(self: *TableTxn, field: []const u8, value: Value, pk: Value) !void {
+        const key = try idx.indexEntryKey(self.allocator, self.name, field, value, pk);
+        defer self.allocator.free(key);
+        try self.txn.delete(key);
+    }
+};
+
+fn openTemp(tmp: *std.testing.TmpDir, allocator: Allocator) !Db {
+    const dbPath = try tmp.dir.realpathAlloc(allocator, ".");
+    defer allocator.free(dbPath);
+    return Db.open(allocator, dbPath, .{});
+}
+
+test "TableTxn commits multiple rows atomically" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+
+    var t = try TableTxn.open(&txn, allocator, "accounts");
+    defer t.deinit();
+
+    try t.put(.{ .int = 1 }, &.{.{ .name = "balance", .value = .{ .int = 100 } }});
+    try t.put(.{ .int = 2 }, &.{.{ .name = "balance", .value = .{ .int = 50 } }});
+
+    // Nothing visible outside the transaction yet.
+    const probeKey = try idx.rowKey(allocator, "accounts", .{ .int = 1 });
+    defer allocator.free(probeKey);
+    try std.testing.expect((try db.get(allocator, probeKey)) == null);
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "accounts");
+    defer plain.deinit();
+    var row1 = (try plain.get(.{ .int = 1 })).?;
+    defer row1.deinit();
+    var row2 = (try plain.get(.{ .int = 2 })).?;
+    defer row2.deinit();
+    try std.testing.expectEqual(@as(i64, 100), row1.get("balance").?.int);
+    try std.testing.expectEqual(@as(i64, 50), row2.get("balance").?.int);
+}
+
+test "TableTxn transfer is all-or-nothing on conflict" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "accounts");
+        defer setup.deinit();
+        try setup.put(.{ .int = 1 }, &.{.{ .name = "balance", .value = .{ .int = 100 } }});
+        try setup.put(.{ .int = 2 }, &.{.{ .name = "balance", .value = .{ .int = 50 } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "accounts");
+    defer t.deinit();
+
+    // Move 30 from account 1 to account 2, staged but not yet committed.
+    var from = (try t.get(.{ .int = 1 })).?;
+    defer from.deinit();
+    var to = (try t.get(.{ .int = 2 })).?;
+    defer to.deinit();
+    try t.put(.{ .int = 1 }, &.{.{ .name = "balance", .value = .{ .int = from.get("balance").?.int - 30 } }});
+    try t.put(.{ .int = 2 }, &.{.{ .name = "balance", .value = .{ .int = to.get("balance").?.int + 30 } }});
+
+    // An external writer touches account 1 before the transfer commits.
+    {
+        var external = try querymod.Table.open(&db, allocator, "accounts");
+        defer external.deinit();
+        try external.put(.{ .int = 1 }, &.{.{ .name = "balance", .value = .{ .int = 999 } }});
+    }
+
+    try std.testing.expectError(error.Conflict, txn.commit());
+
+    // Neither leg of the transfer applied: account 2 must be untouched,
+    // and account 1 must show the external writer's value, not the stale
+    // transfer's.
+    var verify = try querymod.Table.open(&db, allocator, "accounts");
+    defer verify.deinit();
+    var row1 = (try verify.get(.{ .int = 1 })).?;
+    defer row1.deinit();
+    var row2 = (try verify.get(.{ .int = 2 })).?;
+    defer row2.deinit();
+    try std.testing.expectEqual(@as(i64, 999), row1.get("balance").?.int);
+    try std.testing.expectEqual(@as(i64, 50), row2.get("balance").?.int);
+}
+
+test "TableTxn keeps a pre-existing index in sync across commit" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "users");
+        defer setup.deinit();
+        try setup.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+        try setup.createIndex("city");
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "users");
+    defer t.deinit();
+    try std.testing.expect(t.hasIndex("city"));
+
+    try t.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "krakow" } }});
+    try t.put(.{ .int = 2 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "users");
+    defer plain.deinit();
+    const warsaw = try plain.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer querymod.freeRows(allocator, warsaw);
+    try std.testing.expectEqual(@as(usize, 1), warsaw.len);
+    try std.testing.expectEqual(@as(i64, 2), warsaw[0].get(pkField).?.int);
+
+    const krakow = try plain.select(.{ .eq = .{ .field = "city", .value = .{ .text = "krakow" } } });
+    defer querymod.freeRows(allocator, krakow);
+    try std.testing.expectEqual(@as(usize, 1), krakow.len);
+    try std.testing.expectEqual(@as(i64, 1), krakow[0].get(pkField).?.int);
+}
+
+test "TableTxn delete removes row and index entries only on commit" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "users");
+        defer setup.deinit();
+        try setup.createIndex("city");
+        try setup.put(.{ .int = 1 }, &.{.{ .name = "city", .value = .{ .text = "warsaw" } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "users");
+    defer t.deinit();
+    try t.delete(.{ .int = 1 });
+
+    // Not yet committed: still visible outside the transaction.
+    {
+        var outside = try querymod.Table.open(&db, allocator, "users");
+        defer outside.deinit();
+        var stillThere = (try outside.get(.{ .int = 1 })).?;
+        stillThere.deinit();
+    }
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "users");
+    defer plain.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 1 })) == null);
+    const warsaw = try plain.select(.{ .eq = .{ .field = "city", .value = .{ .text = "warsaw" } } });
+    defer querymod.freeRows(allocator, warsaw);
+    try std.testing.expectEqual(@as(usize, 0), warsaw.len);
+}
+
+test "TableTxn rejects invalid table identifier" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    try std.testing.expectError(error.InvalidIdentifier, TableTxn.open(&txn, allocator, ""));
+}
+
+test "TableTxn read-your-writes sees staged rows before commit" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "users");
+    defer t.deinit();
+
+    try t.put(.{ .int = 1 }, &.{.{ .name = "name", .value = .{ .text = "ada" } }});
+    var seen = (try t.get(.{ .int = 1 })).?;
+    defer seen.deinit();
+    try std.testing.expectEqualStrings("ada", seen.get("name").?.text);
+
+    try t.delete(.{ .int = 1 });
+    try std.testing.expect((try t.get(.{ .int = 1 })) == null);
+}
+
+test "TableTxn put enforces UNIQUE constraint against committed data" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "users");
+        defer setup.deinit();
+        try setup.createUniqueIndex("email");
+        try setup.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@example.com" } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "users");
+    defer t.deinit();
+    try std.testing.expect(t.hasUniqueIndex("email"));
+
+    try std.testing.expectError(error.UniqueViolation, t.put(.{ .int = 2 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@example.com" } },
+    }));
+
+    // The rejected put staged nothing: committing now applies zero rows.
+    try txn.commit();
+    var plain = try querymod.Table.open(&db, allocator, "users");
+    defer plain.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 2 })) == null);
+}
+
+test "TableTxn put UNIQUE check exempts a row keeping its own previous value" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "users");
+        defer setup.deinit();
+        try setup.createUniqueIndex("email");
+        try setup.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@example.com" } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "users");
+    defer t.deinit();
+
+    // Updating an unrelated field on row 1 keeps its own email unchanged -
+    // must not spuriously conflict with itself.
+    try t.put(.{ .int = 1 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@example.com" } },
+        .{ .name = "name", .value = .{ .text = "ada" } },
+    });
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "users");
+    defer plain.deinit();
+    var row = (try plain.get(.{ .int = 1 })).?;
+    defer row.deinit();
+    try std.testing.expectEqualStrings("ada", row.get("name").?.text);
+}
+
+test "TableTxn put enforces FOREIGN KEY against committed data and rejects a dangling reference" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var customers = try querymod.Table.open(&db, allocator, "customers");
+        defer customers.deinit();
+        try customers.put(.{ .int = 1 }, &.{});
+
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "orders");
+    defer t.deinit();
+    try std.testing.expect(t.hasForeignKey("customer_id"));
+
+    // customer 1 exists (committed) -> allowed.
+    try t.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    // customer 999 does not exist anywhere -> rejected.
+    try std.testing.expectError(error.ForeignKeyViolation, t.put(.{ .int = 101 }, &.{
+        .{ .name = "customer_id", .value = .{ .int = 999 } },
+    }));
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "orders");
+    defer plain.deinit();
+    var row = (try plain.get(.{ .int = 100 })).?;
+    defer row.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 101 })) == null);
+}
+
+test "TableTxn put FOREIGN KEY on pkField sees a parent staged earlier in the same uncommitted transaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        // Self-referencing table (an org chart: manager_id -> employees.pk),
+        // installed while empty so no existing-row check gets in the way.
+        var employees = try querymod.Table.open(&db, allocator, "employees");
+        defer employees.deinit();
+        try employees.createForeignKey("manager_id", "employees", pkField, .restrict);
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "employees");
+    defer t.deinit();
+
+    // Neither row is committed yet. The manager (pk=1) is only staged in
+    // this same transaction's write set, but the FK check on the report
+    // (pk=2) must see it via `Transaction.get`'s read-your-writes, not
+    // just via the underlying Db.
+    try t.put(.{ .int = 1 }, &.{});
+    try t.put(.{ .int = 2 }, &.{.{ .name = "manager_id", .value = .{ .int = 1 } }});
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "employees");
+    defer plain.deinit();
+    var report = (try plain.get(.{ .int = 2 })).?;
+    defer report.deinit();
+    try std.testing.expectEqual(@as(i64, 1), report.get("manager_id").?.int);
+}
+
+test "TableTxn put FOREIGN KEY on a non-pk unique field sees a target staged earlier in the same uncommitted transaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var products = try querymod.Table.open(&db, allocator, "products");
+        defer products.deinit();
+        try products.createUniqueIndex("sku");
+
+        var lineItems = try querymod.Table.open(&db, allocator, "line_items");
+        defer lineItems.deinit();
+        try lineItems.createForeignKey("product_sku", "products", "sku", .restrict);
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+
+    // Stage a brand-new product in the same transaction as the line item
+    // that references it. `foreignKeyTargetExists`'s non-pk branch now
+    // goes through `Transaction.scanPrefix`, which sees the product's
+    // staged index-entry write even though neither row is committed yet -
+    // same read-your-writes guarantee the pkField branch above already had.
+    var products = try TableTxn.open(&txn, allocator, "products");
+    defer products.deinit();
+    try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+
+    var lineItems = try TableTxn.open(&txn, allocator, "line_items");
+    defer lineItems.deinit();
+    try lineItems.put(.{ .int = 1 }, &.{
+        .{ .name = "product_sku", .value = .{ .text = "WIDGET-1" } },
+    });
+
+    // A dangling reference in the same transaction is still rejected.
+    try std.testing.expectError(error.ForeignKeyViolation, lineItems.put(.{ .int = 2 }, &.{
+        .{ .name = "product_sku", .value = .{ .text = "NO-SUCH-SKU" } },
+    }));
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "line_items");
+    defer plain.deinit();
+    var row = (try plain.get(.{ .int = 1 })).?;
+    defer row.deinit();
+    try std.testing.expectEqualStrings("WIDGET-1", row.get("product_sku").?.text);
+}
+
+test "TableTxn put UNIQUE constraint catches a conflict staged earlier in the same uncommitted transaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "users");
+        defer setup.deinit();
+        try setup.createUniqueIndex("email");
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "users");
+    defer t.deinit();
+
+    // First row claims the email; nothing committed yet.
+    try t.put(.{ .int = 1 }, &.{.{ .name = "email", .value = .{ .text = "a@example.com" } }});
+
+    // A second, different row in the SAME still-open transaction tries to
+    // claim the same email. Before `Transaction.scanPrefix`, the UNIQUE
+    // check ran `idx.scanEq` straight against `Db` and never saw the first
+    // row's staged index entry, so this put would have wrongly succeeded
+    // and only failed later as a generic OCC conflict at commit (or not at
+    // all, since the two rows touch disjoint keys and would not conflict).
+    try std.testing.expectError(error.UniqueViolation, t.put(.{ .int = 2 }, &.{
+        .{ .name = "email", .value = .{ .text = "a@example.com" } },
+    }));
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "users");
+    defer plain.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 2 })) == null);
+    var row1 = (try plain.get(.{ .int = 1 })).?;
+    defer row1.deinit();
+    try std.testing.expectEqualStrings("a@example.com", row1.get("email").?.text);
+}
+
+test "TableTxn put enforces a CHECK constraint installed through query.zig's Table" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "orders");
+        defer setup.deinit();
+        try setup.createCheckConstraint("qty_positive", "qty gt i:0");
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "orders");
+    defer t.deinit();
+    try std.testing.expect(t.hasCheckConstraint("qty_positive"));
+
+    try t.put(.{ .int = 1 }, &.{.{ .name = "qty", .value = .{ .int = 5 } }});
+    try std.testing.expectError(error.CheckViolation, t.put(.{ .int = 2 }, &.{
+        .{ .name = "qty", .value = .{ .int = 0 } },
+    }));
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "orders");
+    defer plain.deinit();
+    var row1 = (try plain.get(.{ .int = 1 })).?;
+    defer row1.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 2 })) == null);
+}
+
+test "TableTxn `txn <script>` shape: a CHECK violation on the second put leaves the whole transaction uncommitted" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var setup = try querymod.Table.open(&db, allocator, "orders");
+        defer setup.deinit();
+        try setup.createCheckConstraint("qty_positive", "qty gt i:0");
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "orders");
+    defer t.deinit();
+
+    try t.put(.{ .int = 1 }, &.{.{ .name = "qty", .value = .{ .int = 5 } }});
+    try std.testing.expectError(error.CheckViolation, t.put(.{ .int = 2 }, &.{
+        .{ .name = "qty", .value = .{ .int = -5 } },
+    }));
+
+    // A real `txn <script>` dispatch (main.zig's `runTxn`/server.zig's
+    // `handleTxnOp`) aborts the whole script on the first line that fails
+    // instead of continuing - `t.deinit()`/`txn.deinit()` above discard the
+    // transaction without ever calling `commit()`, so even row 1 (which was
+    // individually valid) must never become visible.
+    var plain = try querymod.Table.open(&db, allocator, "orders");
+    defer plain.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 1 })) == null);
+}
+
+test "TableTxn delete enforces ON DELETE RESTRICT against a committed child row" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var customers = try querymod.Table.open(&db, allocator, "customers");
+        defer customers.deinit();
+        try customers.put(.{ .int = 1 }, &.{});
+
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+        try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "customers");
+    defer t.deinit();
+
+    try std.testing.expectError(error.ForeignKeyInUse, t.delete(.{ .int = 1 }));
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "customers");
+    defer plain.deinit();
+    var stillThere = (try plain.get(.{ .int = 1 })).?;
+    stillThere.deinit();
+}
+
+test "TableTxn delete RESTRICT sees a child row staged earlier in the same uncommitted transaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var customers = try querymod.Table.open(&db, allocator, "customers");
+        defer customers.deinit();
+        try customers.put(.{ .int = 1 }, &.{});
+
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+
+    // The order referencing customer 1 is only staged in this SAME
+    // transaction's write set (via a sibling TableTxn on "orders"), never
+    // committed - `Transaction.scanPrefix` (not a plain Db scan, which
+    // would see nothing under the orders row prefix yet) is what makes
+    // this count as a live reference before the transaction ever commits.
+    var ordersTxn = try TableTxn.open(&txn, allocator, "orders");
+    defer ordersTxn.deinit();
+    try ordersTxn.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+
+    var customersTxn = try TableTxn.open(&txn, allocator, "customers");
+    defer customersTxn.deinit();
+    try std.testing.expectError(error.ForeignKeyInUse, customersTxn.delete(.{ .int = 1 }));
+}
+
+test "TableTxn delete RESTRICT does not block deleting a parent once its only child is deleted in the same transaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var customers = try querymod.Table.open(&db, allocator, "customers");
+        defer customers.deinit();
+        try customers.put(.{ .int = 1 }, &.{});
+
+        var orders = try querymod.Table.open(&db, allocator, "orders");
+        defer orders.deinit();
+        try orders.createForeignKey("customer_id", "customers", pkField, .restrict);
+        try orders.put(.{ .int = 100 }, &.{.{ .name = "customer_id", .value = .{ .int = 1 } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+
+    var ordersTxn = try TableTxn.open(&txn, allocator, "orders");
+    defer ordersTxn.deinit();
+    try ordersTxn.delete(.{ .int = 100 });
+
+    var customersTxn = try TableTxn.open(&txn, allocator, "customers");
+    defer customersTxn.deinit();
+    try customersTxn.delete(.{ .int = 1 });
+
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "customers");
+    defer plain.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 1 })) == null);
+}
+
+test "TableTxn delete RESTRICT excludes the row being deleted from its own self-referencing check" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var employees = try querymod.Table.open(&db, allocator, "employees");
+        defer employees.deinit();
+        try employees.put(.{ .int = 1 }, &.{});
+        try employees.createForeignKey("manager_id", "employees", pkField, .restrict);
+        try employees.put(.{ .int = 2 }, &.{.{ .name = "manager_id", .value = .{ .int = 1 } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "employees");
+    defer t.deinit();
+
+    // The manager (pk 1) has a report (pk 2) -> restricted.
+    try std.testing.expectError(error.ForeignKeyInUse, t.delete(.{ .int = 1 }));
+    // The report itself has no reports of its own -> deletes cleanly,
+    // scanning the same table it belongs to without restricting itself.
+    try t.delete(.{ .int = 2 });
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "employees");
+    defer plain.deinit();
+    try std.testing.expect((try plain.get(.{ .int = 2 })) == null);
+}
+
+test "TableTxn put is restricted from changing a UNIQUE foreign key target a committed child still references" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var products = try querymod.Table.open(&db, allocator, "products");
+        defer products.deinit();
+        try products.createUniqueIndex("sku");
+        try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+
+        var lineItems = try querymod.Table.open(&db, allocator, "line_items");
+        defer lineItems.deinit();
+        try lineItems.createForeignKey("product_sku", "products", "sku", .restrict);
+        try lineItems.put(.{ .int = 1 }, &.{.{ .name = "product_sku", .value = .{ .text = "WIDGET-1" } }});
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+    var t = try TableTxn.open(&txn, allocator, "products");
+    defer t.deinit();
+
+    try std.testing.expectError(error.ForeignKeyInUse, t.put(.{ .int = 1 }, &.{
+        .{ .name = "sku", .value = .{ .text = "WIDGET-2" } },
+    }));
+    // Unchanged is always exempt.
+    try t.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "products");
+    defer plain.deinit();
+    var stillThere = (try plain.get(.{ .int = 1 })).?;
+    defer stillThere.deinit();
+    try std.testing.expectEqualStrings("WIDGET-1", stillThere.get("sku").?.text);
+}
+
+test "TableTxn put update-restrict sees a child row staged earlier in the same uncommitted transaction" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var db = try openTemp(&tmp, allocator);
+    defer db.close();
+
+    {
+        var products = try querymod.Table.open(&db, allocator, "products");
+        defer products.deinit();
+        try products.createUniqueIndex("sku");
+        try products.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-1" } }});
+
+        var lineItems = try querymod.Table.open(&db, allocator, "line_items");
+        defer lineItems.deinit();
+        try lineItems.createForeignKey("product_sku", "products", "sku", .restrict);
+    }
+
+    var txn = Transaction.begin(&db);
+    defer txn.deinit();
+
+    // The line item referencing "WIDGET-1" is only staged in this SAME
+    // transaction's write set, never committed - `Transaction.scanPrefix`
+    // is what makes this count as a live reference before commit.
+    var lineItemsTxn = try TableTxn.open(&txn, allocator, "line_items");
+    defer lineItemsTxn.deinit();
+    try lineItemsTxn.put(.{ .int = 1 }, &.{.{ .name = "product_sku", .value = .{ .text = "WIDGET-1" } }});
+
+    var productsTxn = try TableTxn.open(&txn, allocator, "products");
+    defer productsTxn.deinit();
+    try std.testing.expectError(error.ForeignKeyInUse, productsTxn.put(.{ .int = 1 }, &.{
+        .{ .name = "sku", .value = .{ .text = "WIDGET-2" } },
+    }));
+
+    // Once the referencing line item is removed in the same transaction,
+    // the rename goes through.
+    try lineItemsTxn.delete(.{ .int = 1 });
+    try productsTxn.put(.{ .int = 1 }, &.{.{ .name = "sku", .value = .{ .text = "WIDGET-2" } }});
+    try txn.commit();
+
+    var plain = try querymod.Table.open(&db, allocator, "products");
+    defer plain.deinit();
+    var renamed = (try plain.get(.{ .int = 1 })).?;
+    defer renamed.deinit();
+    try std.testing.expectEqualStrings("WIDGET-2", renamed.get("sku").?.text);
+}
diff --git a/src/version.zig b/src/version.zig
new file mode 100644
index 0000000..c564449
--- /dev/null
+++ b/src/version.zig
@@ -0,0 +1,658 @@
+const std = @import("std");
+const encode = @import("encode.zig");
+
+const Allocator = std.mem.Allocator;
+
+// VersionSet/VersionEdit: append-only log of incremental changes to the
+// live sstable set (fileId -> level), replacing a full-state rewrite on
+// every flush/compact. Modeled on LevelDB's VersionSet: a CURRENT file
+// names the active manifest log, the log holds a sequence of edit
+// records, and recovery replays them into a map. The log is periodically
+// rotated (a single snapshot record replaces the whole history) so it
+// never grows without bound.
+
+pub const VersionError = error{
+    Corrupt,
+    Truncated,
+};
+
+pub const FileEdit = struct {
+    fileId: u64,
+    level: u32,
+};
+
+pub const VersionEdit = struct {
+    allocator: Allocator,
+    added: std.ArrayList(FileEdit),
+    deleted: std.ArrayList(u64),
+    /// Optional counter watermarks, stamped by the caller alongside a file
+    /// add/delete: the exact `Db.nextFileId`/`Db.nextSeq` value in effect
+    /// right after this edit was built. Recorded so recovery can recover
+    /// these counters from the manifest instead of relying solely on
+    /// scanning which sstable files currently happen to be on disk - a scan
+    /// alone regresses whenever a compaction fully garbage-collects a run of
+    /// tombstones into zero output files (see runMerge: no output file means
+    /// no fresh fileId is minted, and if the GC'd inputs held the highest
+    /// seq/fileId ever used, a post-restart scan would compute a lower
+    /// floor than what was really already consumed, risking seq reuse
+    /// across a restart).
+    nextFileId: ?u64 = null,
+    nextSeq: ?u64 = null,
+
+    pub fn init(allocator: Allocator) VersionEdit {
+        return .{
+            .allocator = allocator,
+            .added = std.ArrayList(FileEdit).init(allocator),
+            .deleted = std.ArrayList(u64).init(allocator),
+        };
+    }
+
+    pub fn deinit(self: *VersionEdit) void {
+        self.added.deinit();
+        self.deleted.deinit();
+    }
+
+    pub fn addFile(self: *VersionEdit, fileId: u64, level: usize) !void {
+        try self.added.append(.{ .fileId = fileId, .level = @intCast(level) });
+    }
+
+    pub fn deleteFile(self: *VersionEdit, fileId: u64) !void {
+        try self.deleted.append(fileId);
+    }
+
+    pub fn setNextFileId(self: *VersionEdit, nextFileId: u64) void {
+        self.nextFileId = nextFileId;
+    }
+
+    pub fn setNextSeq(self: *VersionEdit, nextSeq: u64) void {
+        self.nextSeq = nextSeq;
+    }
+
+    pub fn isEmpty(self: *const VersionEdit) bool {
+        return self.added.items.len == 0 and self.deleted.items.len == 0;
+    }
+
+    fn encode_(self: *const VersionEdit, out: *std.ArrayList(u8)) !void {
+        const writer = encode.ByteWriter.init(out);
+        try writer.putU32(@intCast(self.added.items.len));
+        for (self.added.items) |f| {
+            try writer.putU64(f.fileId);
+            try writer.putU32(f.level);
+        }
+        try writer.putU32(@intCast(self.deleted.items.len));
+        for (self.deleted.items) |id| try writer.putU64(id);
+        try writer.byte(if (self.nextFileId != null) 1 else 0);
+        if (self.nextFileId) |v| try writer.putU64(v);
+        try writer.byte(if (self.nextSeq != null) 1 else 0);
+        if (self.nextSeq) |v| try writer.putU64(v);
+    }
+};
+
+/// Applies an edit's added/deleted entries onto a live fileId->level map.
+pub fn applyEdit(state: *std.AutoHashMap(u64, usize), added: []const FileEdit, deleted: []const u64) !void {
+    for (deleted) |id| _ = state.remove(id);
+    for (added) |f| try state.put(f.fileId, f.level);
+}
+
+/// Recovered counter watermarks, threaded out of `VersionSet.open`'s replay
+/// so `Db.open` can fold them into its own directory-scan-based recovery
+/// (taking the max of both sources - see `VersionEdit.nextFileId`/`nextSeq`
+/// doc comment for why the scan alone is not always sufficient).
+pub const Counters = struct {
+    nextFileId: ?u64 = null,
+    nextSeq: ?u64 = null,
+};
+
+const currentName = "CURRENT";
+const manifestPrefix = "MANIFEST-";
+
+fn manifestFileName(buf: []u8, id: u64) ![]const u8 {
+    return std.fmt.bufPrint(buf, "{s}{d:0>10}", .{ manifestPrefix, id });
+}
+
+pub const VersionSet = struct {
+    allocator: Allocator,
+    dir: std.fs.Dir,
+    file: std.fs.File,
+    manifestId: u64,
+    /// Number of edit records appended to the current log since the last
+    /// rotation (used as the rotation heuristic).
+    pendingRecords: usize,
+    /// Latest counter watermarks seen across every replayed (or since
+    /// applied) edit - see `VersionEdit.nextFileId`/`nextSeq`. Carried
+    /// forward into `rotate`'s snapshot record so they survive log rotation
+    /// even though the individual edits that set them get discarded.
+    counters: Counters,
+
+    /// Opens (or bootstraps) the version set, replaying the active
+    /// manifest log into a fresh fileId->level map that the caller owns.
+    pub fn open(allocator: Allocator, dir: std.fs.Dir) !struct { set: VersionSet, state: std.AutoHashMap(u64, usize) } {
+        var state = std.AutoHashMap(u64, usize).init(allocator);
+        errdefer state.deinit();
+
+        const currentContents = dir.readFileAlloc(allocator, currentName, 256) catch |err| switch (err) {
+            error.FileNotFound => {
+                const set = try bootstrap(allocator, dir);
+                return .{ .set = set, .state = state };
+            },
+            else => return err,
+        };
+        defer allocator.free(currentContents);
+
+        const trimmed = std.mem.trim(u8, currentContents, " \t\r\n");
+        const id = parseManifestId(trimmed) orelse return VersionError.Corrupt;
+
+        const file = dir.openFile(trimmed, .{ .mode = .read_write }) catch |err| switch (err) {
+            error.FileNotFound => {
+                const set = try bootstrap(allocator, dir);
+                return .{ .set = set, .state = state };
+            },
+            else => return err,
+        };
+        errdefer file.close();
+
+        const data = try file.readToEndAlloc(allocator, std.math.maxInt(usize));
+        defer allocator.free(data);
+
+        var pos: usize = 0;
+        var goodEnd: usize = 0;
+        var records: usize = 0;
+        var counters = Counters{};
+        while (pos + 8 <= data.len) {
+            const storedCrc = encode.readU32(data, pos);
+            const bodyStart = pos + 4;
+            const bodyLen = recordBodyLen(data, bodyStart) orelse break;
+            if (bodyStart + bodyLen > data.len) break;
+            const body = data[bodyStart .. bodyStart + bodyLen];
+            if (encode.crc(body) != storedCrc) break;
+
+            try replayRecord(&state, &counters, body);
+            records += 1;
+            pos = bodyStart + bodyLen;
+            goodEnd = pos;
+        }
+
+        if (goodEnd != data.len) {
+            try file.setEndPos(goodEnd);
+            try file.sync();
+        }
+        try file.seekFromEnd(0);
+
+        return .{
+            .set = .{
+                .allocator = allocator,
+                .dir = dir,
+                .file = file,
+                .manifestId = id,
+                .pendingRecords = records,
+                .counters = counters,
+            },
+            .state = state,
+        };
+    }
+
+    fn bootstrap(allocator: Allocator, dir: std.fs.Dir) !VersionSet {
+        var nameBuf: [64]u8 = undefined;
+        const name = try manifestFileName(&nameBuf, 1);
+        const file = try dir.createFile(name, .{ .read = true, .truncate = true });
+        errdefer file.close();
+        try writeCurrent(dir, name);
+        return .{
+            .allocator = allocator,
+            .dir = dir,
+            .file = file,
+            .manifestId = 1,
+            .pendingRecords = 0,
+            .counters = .{},
+        };
+    }
+
+    pub fn close(self: *VersionSet) void {
+        self.file.close();
+    }
+
+    /// Applies `edit` to `state` and durably appends it to the manifest
+    /// log. Rotates (compacts the log to a single snapshot record) once
+    /// the number of pending records grows past the live file count.
+    pub fn logAndApply(self: *VersionSet, edit: *const VersionEdit, state: *std.AutoHashMap(u64, usize)) !void {
+        if (edit.isEmpty()) return;
+        try applyEdit(state, edit.added.items, edit.deleted.items);
+        if (edit.nextFileId) |v| self.counters.nextFileId = v;
+        if (edit.nextSeq) |v| self.counters.nextSeq = v;
+        try self.appendRecord(edit);
+        self.pendingRecords += 1;
+
+        const liveCount = state.count();
+        if (self.pendingRecords > @max(liveCount, 4) * 2) {
+            try self.rotate(state);
+        }
+    }
+
+    fn appendRecord(self: *VersionSet, edit: *const VersionEdit) !void {
+        var body = std.ArrayList(u8).init(self.allocator);
+        defer body.deinit();
+        try edit.encode_(&body);
+
+        var frame = std.ArrayList(u8).init(self.allocator);
+        defer frame.deinit();
+        const frameWriter = encode.ByteWriter.init(&frame);
+        try frameWriter.putU32(encode.crc(body.items));
+        try frameWriter.slice(body.items);
+
+        try self.file.seekFromEnd(0);
+        try self.file.writeAll(frame.items);
+        try self.file.sync();
+    }
+
+    /// Replaces the whole log history with a single snapshot record that
+    /// reproduces the current live state, then switches CURRENT to it and
+    /// deletes the old log. Bounds manifest size to O(live files) instead
+    /// of O(edits ever applied).
+    fn rotate(self: *VersionSet, state: *const std.AutoHashMap(u64, usize)) !void {
+        var snapshot = std.ArrayList(FileEdit).init(self.allocator);
+        defer snapshot.deinit();
+        var it = state.iterator();
+        while (it.next()) |entry| {
+            try snapshot.append(.{ .fileId = entry.key_ptr.*, .level = @intCast(entry.value_ptr.*) });
+        }
+
+        const newId = self.manifestId + 1;
+        var nameBuf: [64]u8 = undefined;
+        const newName = try manifestFileName(&nameBuf, newId);
+
+        const newFile = try self.dir.createFile(newName, .{ .read = true, .truncate = true });
+        errdefer newFile.close();
+
+        {
+            var body = std.ArrayList(u8).init(self.allocator);
+            defer body.deinit();
+            const writer = encode.ByteWriter.init(&body);
+            try writer.putU32(@intCast(snapshot.items.len));
+            for (snapshot.items) |f| {
+                try writer.putU64(f.fileId);
+                try writer.putU32(f.level);
+            }
+            try writer.putU32(0);
+            // Carry the latest known counters forward into the snapshot so
+            // they survive rotation even though the edits that originally
+            // set them are being discarded along with the old log.
+            try writer.byte(if (self.counters.nextFileId != null) 1 else 0);
+            if (self.counters.nextFileId) |v| try writer.putU64(v);
+            try writer.byte(if (self.counters.nextSeq != null) 1 else 0);
+            if (self.counters.nextSeq) |v| try writer.putU64(v);
+
+            var frame = std.ArrayList(u8).init(self.allocator);
+            defer frame.deinit();
+            const frameWriter = encode.ByteWriter.init(&frame);
+            try frameWriter.putU32(encode.crc(body.items));
+            try frameWriter.slice(body.items);
+            try newFile.writeAll(frame.items);
+            try newFile.sync();
+        }
+
+        try writeCurrent(self.dir, newName);
+
+        var oldNameBuf: [64]u8 = undefined;
+        const oldName = try manifestFileName(&oldNameBuf, self.manifestId);
+        self.file.close();
+        self.dir.deleteFile(oldName) catch {};
+
+        self.file = newFile;
+        self.manifestId = newId;
+        self.pendingRecords = snapshot.items.len;
+    }
+};
+
+fn writeCurrent(dir: std.fs.Dir, manifestName: []const u8) !void {
+    const tmpName = "CURRENT.tmp";
+    {
+        const file = try dir.createFile(tmpName, .{ .truncate = true });
+        defer file.close();
+        try file.writeAll(manifestName);
+        try file.sync();
+    }
+    try dir.rename(tmpName, currentName);
+}
+
+fn parseManifestId(name: []const u8) ?u64 {
+    if (!std.mem.startsWith(u8, name, manifestPrefix)) return null;
+    return std.fmt.parseInt(u64, name[manifestPrefix.len..], 10) catch null;
+}
+
+fn recordBodyLen(data: []const u8, bodyStart: usize) ?usize {
+    if (bodyStart + 4 > data.len) return null;
+    const addedCount = encode.readU32(data, bodyStart);
+    var p = bodyStart + 4;
+    var i: u32 = 0;
+    while (i < addedCount) : (i += 1) {
+        if (p + 12 > data.len) return null;
+        p += 12;
+    }
+    if (p + 4 > data.len) return null;
+    const deletedCount = encode.readU32(data, p);
+    p += 4;
+    var j: u32 = 0;
+    while (j < deletedCount) : (j += 1) {
+        if (p + 8 > data.len) return null;
+        p += 8;
+    }
+    // Trailing counter watermarks: one presence flag byte plus an optional
+    // u64 each, for nextFileId then nextSeq.
+    var k: u32 = 0;
+    while (k < 2) : (k += 1) {
+        if (p + 1 > data.len) return null;
+        const present = data[p];
+        p += 1;
+        if (present != 0) {
+            if (p + 8 > data.len) return null;
+            p += 8;
+        }
+    }
+    return p - bodyStart;
+}
+
+fn replayRecord(state: *std.AutoHashMap(u64, usize), counters: *Counters, body: []const u8) !void {
+    const addedCount = encode.readU32(body, 0);
+    var p: usize = 4;
+    var i: u32 = 0;
+    while (i < addedCount) : (i += 1) {
+        const fileId = encode.readU64(body, p);
+        const level = encode.readU32(body, p + 8);
+        try state.put(fileId, level);
+        p += 12;
+    }
+    const deletedCount = encode.readU32(body, p);
+    p += 4;
+    var j: u32 = 0;
+    while (j < deletedCount) : (j += 1) {
+        const fileId = encode.readU64(body, p);
+        _ = state.remove(fileId);
+        p += 8;
+    }
+    if (p < body.len) {
+        const hasNextFileId = body[p];
+        p += 1;
+        if (hasNextFileId != 0) {
+            counters.nextFileId = encode.readU64(body, p);
+            p += 8;
+        }
+        const hasNextSeq = body[p];
+        p += 1;
+        if (hasNextSeq != 0) {
+            counters.nextSeq = encode.readU64(body, p);
+            p += 8;
+        }
+    }
+}
+
+test "fresh directory bootstraps an empty version set" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var opened = try VersionSet.open(allocator, tmp.dir);
+    defer opened.state.deinit();
+    defer opened.set.close();
+
+    try std.testing.expectEqual(@as(usize, 0), opened.state.count());
+    try std.testing.expectEqual(@as(u64, 1), opened.set.manifestId);
+    try std.testing.expect(tmp.dir.access(currentName, .{}) != error.FileNotFound);
+}
+
+test "logAndApply records adds and survives reopen" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    {
+        var opened = try VersionSet.open(allocator, tmp.dir);
+        defer opened.state.deinit();
+        defer opened.set.close();
+
+        var edit = VersionEdit.init(allocator);
+        defer edit.deinit();
+        try edit.addFile(1, 0);
+        try edit.addFile(2, 0);
+        try opened.set.logAndApply(&edit, &opened.state);
+
+        try std.testing.expectEqual(@as(usize, 2), opened.state.count());
+        try std.testing.expectEqual(@as(usize, 0), opened.state.get(1).?);
+    }
+
+    var reopened = try VersionSet.open(allocator, tmp.dir);
+    defer reopened.state.deinit();
+    defer reopened.set.close();
+    try std.testing.expectEqual(@as(usize, 2), reopened.state.count());
+    try std.testing.expectEqual(@as(usize, 0), reopened.state.get(2).?);
+}
+
+test "logAndApply replaces a deleted file with new outputs (compaction pattern)" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var opened = try VersionSet.open(allocator, tmp.dir);
+    defer opened.state.deinit();
+    defer opened.set.close();
+
+    var e1 = VersionEdit.init(allocator);
+    defer e1.deinit();
+    try e1.addFile(1, 0);
+    try e1.addFile(2, 0);
+    try opened.set.logAndApply(&e1, &opened.state);
+
+    var e2 = VersionEdit.init(allocator);
+    defer e2.deinit();
+    try e2.deleteFile(1);
+    try e2.deleteFile(2);
+    try e2.addFile(3, 1);
+    try opened.set.logAndApply(&e2, &opened.state);
+
+    try std.testing.expectEqual(@as(usize, 1), opened.state.count());
+    try std.testing.expectEqual(@as(usize, 1), opened.state.get(3).?);
+    try std.testing.expectEqual(@as(?usize, null), opened.state.get(1));
+}
+
+test "manifest rotates once pending records outgrow live file count" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var opened = try VersionSet.open(allocator, tmp.dir);
+    defer opened.state.deinit();
+    defer opened.set.close();
+
+    // Simulate steady-state leveled compaction: the live file count stays
+    // fixed at 1 (each round replaces the previous output), but the edit
+    // log keeps growing until it is worth rotating to a fresh snapshot.
+    var fileId: u64 = 1;
+    {
+        var edit = VersionEdit.init(allocator);
+        defer edit.deinit();
+        try edit.addFile(fileId, 0);
+        try opened.set.logAndApply(&edit, &opened.state);
+    }
+
+    var n: usize = 0;
+    while (n < 20) : (n += 1) {
+        var edit = VersionEdit.init(allocator);
+        defer edit.deinit();
+        try edit.deleteFile(fileId);
+        fileId += 1;
+        try edit.addFile(fileId, 0);
+        try opened.set.logAndApply(&edit, &opened.state);
+    }
+
+    try std.testing.expect(opened.set.manifestId > 1);
+    try std.testing.expectEqual(@as(usize, 1), opened.state.count());
+    try std.testing.expectEqual(@as(usize, 0), opened.state.get(fileId).?);
+
+    var nameBuf: [64]u8 = undefined;
+    const oldName = try manifestFileName(&nameBuf, 1);
+    try std.testing.expectError(error.FileNotFound, tmp.dir.access(oldName, .{}));
+}
+
+test "reopen after rotation still reflects live state" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var lastId: u64 = 0;
+    var finalFileId: u64 = 1;
+    {
+        var opened = try VersionSet.open(allocator, tmp.dir);
+        defer opened.state.deinit();
+        defer opened.set.close();
+
+        {
+            var edit = VersionEdit.init(allocator);
+            defer edit.deinit();
+            try edit.addFile(finalFileId, 0);
+            try opened.set.logAndApply(&edit, &opened.state);
+        }
+        var n: usize = 0;
+        while (n < 12) : (n += 1) {
+            var edit = VersionEdit.init(allocator);
+            defer edit.deinit();
+            try edit.deleteFile(finalFileId);
+            finalFileId += 1;
+            try edit.addFile(finalFileId, 0);
+            try opened.set.logAndApply(&edit, &opened.state);
+        }
+        lastId = opened.set.manifestId;
+    }
+
+    try std.testing.expect(lastId > 1);
+
+    var reopened = try VersionSet.open(allocator, tmp.dir);
+    defer reopened.state.deinit();
+    defer reopened.set.close();
+    try std.testing.expectEqual(@as(usize, 1), reopened.state.count());
+    try std.testing.expectEqual(@as(usize, 0), reopened.state.get(finalFileId).?);
+    try std.testing.expectEqual(reopened.set.manifestId, lastId);
+}
+
+test "torn trailing record is ignored on recovery" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    {
+        var opened = try VersionSet.open(allocator, tmp.dir);
+        defer opened.state.deinit();
+        defer opened.set.close();
+
+        var edit = VersionEdit.init(allocator);
+        defer edit.deinit();
+        try edit.addFile(7, 0);
+        try opened.set.logAndApply(&edit, &opened.state);
+
+        try opened.set.file.seekFromEnd(0);
+        try opened.set.file.writeAll(&[_]u8{ 0xde, 0xad, 0xbe });
+        try opened.set.file.sync();
+    }
+
+    var reopened = try VersionSet.open(allocator, tmp.dir);
+    defer reopened.state.deinit();
+    defer reopened.set.close();
+    try std.testing.expectEqual(@as(usize, 1), reopened.state.count());
+    try std.testing.expectEqual(@as(usize, 0), reopened.state.get(7).?);
+}
+
+test "logAndApply persists nextFileId and nextSeq counters across reopen" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    {
+        var opened = try VersionSet.open(allocator, tmp.dir);
+        defer opened.state.deinit();
+        defer opened.set.close();
+        try std.testing.expectEqual(@as(?u64, null), opened.set.counters.nextFileId);
+
+        var edit = VersionEdit.init(allocator);
+        defer edit.deinit();
+        try edit.addFile(1, 0);
+        edit.setNextFileId(2);
+        edit.setNextSeq(500);
+        try opened.set.logAndApply(&edit, &opened.state);
+
+        try std.testing.expectEqual(@as(?u64, 2), opened.set.counters.nextFileId);
+        try std.testing.expectEqual(@as(?u64, 500), opened.set.counters.nextSeq);
+    }
+
+    var reopened = try VersionSet.open(allocator, tmp.dir);
+    defer reopened.state.deinit();
+    defer reopened.set.close();
+    try std.testing.expectEqual(@as(?u64, 2), reopened.set.counters.nextFileId);
+    try std.testing.expectEqual(@as(?u64, 500), reopened.set.counters.nextSeq);
+}
+
+test "counters survive manifest rotation" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var lastId: u64 = 0;
+    {
+        var opened = try VersionSet.open(allocator, tmp.dir);
+        defer opened.state.deinit();
+        defer opened.set.close();
+
+        var fileId: u64 = 1;
+        {
+            var edit = VersionEdit.init(allocator);
+            defer edit.deinit();
+            try edit.addFile(fileId, 0);
+            edit.setNextFileId(fileId + 1);
+            edit.setNextSeq(10);
+            try opened.set.logAndApply(&edit, &opened.state);
+        }
+        // Force rotation the same way the existing rotation test does, each
+        // round bumping the seq counter so the final persisted value is
+        // distinguishable from an earlier one if rotation dropped it.
+        var n: usize = 0;
+        while (n < 20) : (n += 1) {
+            var edit = VersionEdit.init(allocator);
+            defer edit.deinit();
+            try edit.deleteFile(fileId);
+            fileId += 1;
+            try edit.addFile(fileId, 0);
+            edit.setNextFileId(fileId + 1);
+            edit.setNextSeq(10 + n + 1);
+            try opened.set.logAndApply(&edit, &opened.state);
+        }
+        lastId = opened.set.manifestId;
+        try std.testing.expectEqual(@as(?u64, fileId + 1), opened.set.counters.nextFileId);
+        try std.testing.expectEqual(@as(?u64, 30), opened.set.counters.nextSeq);
+    }
+    try std.testing.expect(lastId > 1);
+
+    var reopened = try VersionSet.open(allocator, tmp.dir);
+    defer reopened.state.deinit();
+    defer reopened.set.close();
+    try std.testing.expectEqual(@as(?u64, 30), reopened.set.counters.nextSeq);
+}
+
+test "missing CURRENT after previous run bootstraps fresh, empty state" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    {
+        var opened = try VersionSet.open(allocator, tmp.dir);
+        defer opened.state.deinit();
+        defer opened.set.close();
+        var edit = VersionEdit.init(allocator);
+        defer edit.deinit();
+        try edit.addFile(1, 0);
+        try opened.set.logAndApply(&edit, &opened.state);
+    }
+
+    try tmp.dir.deleteFile(currentName);
+
+    var reopened = try VersionSet.open(allocator, tmp.dir);
+    defer reopened.state.deinit();
+    defer reopened.set.close();
+    try std.testing.expectEqual(@as(usize, 0), reopened.state.count());
+}
diff --git a/src/wal.zig b/src/wal.zig
index d52edb7..66439a1 100644
--- a/src/wal.zig
+++ b/src/wal.zig
@@ -165,6 +165,102 @@ fn applyFrame(memtable: *Memtable, body: []const u8) !u64 {
     return seq;
 }
 
+const genFileName = "wal.gen";
+const genTmpName = "wal.gen.tmp";
+const genMagic = "CGEN";
+const genRecordLen = 4 + 8 + 4;
+
+pub const GenerationError = error{ BadMagic, Truncated, Corrupt };
+
+/// Reads the WAL's current generation counter from a db directory, next to
+/// wal.log itself. Returns 0 (not an error) if the generation file has never
+/// been written - a db that has never truncated its WAL is, by definition,
+/// still on generation 0, the same value any tailer starts at.
+pub fn currentGeneration(dir: std.fs.Dir) !u64 {
+    var buf: [genRecordLen]u8 = undefined;
+    const file = dir.openFile(genFileName, .{}) catch |err| switch (err) {
+        error.FileNotFound => return 0,
+        else => return err,
+    };
+    defer file.close();
+    const n = try file.readAll(&buf);
+    if (n != genRecordLen) return GenerationError.Truncated;
+    if (!std.mem.eql(u8, buf[0..4], genMagic)) return GenerationError.BadMagic;
+    const gen = encode.readU64(&buf, 4);
+    const storedCrc = encode.readU32(&buf, 12);
+    if (encode.crc(buf[0..12]) != storedCrc) return GenerationError.Corrupt;
+    return gen;
+}
+
+/// Bumps and atomically persists the WAL generation counter. Called once per
+/// truncation (see reset(), invoked from Db.flush()) so a tailer that reads
+/// this stamp can tell "same WAL contents since I last looked" from "primary
+/// truncated, and may have already regrown past whatever byte offset I had"
+/// from an explicit marker instead of a byte-size heuristic - a pure
+/// endPos-vs-offset comparison is fooled exactly when the post-truncation
+/// file reaches or exceeds the old offset before the next poll.
+pub fn bumpGeneration(dir: std.fs.Dir) !u64 {
+    const gen = (try currentGeneration(dir)) + 1;
+    var buf: [genRecordLen]u8 = undefined;
+    @memcpy(buf[0..4], genMagic);
+    std.mem.writeInt(u64, buf[4..12], gen, encode.endian);
+    std.mem.writeInt(u32, buf[12..16], encode.crc(buf[0..12]), encode.endian);
+    {
+        const file = try dir.createFile(genTmpName, .{ .truncate = true });
+        defer file.close();
+        try file.writeAll(&buf);
+        try file.sync();
+    }
+    try dir.rename(genTmpName, genFileName);
+    return gen;
+}
+
+test "currentGeneration is 0 before any bump" {
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    try std.testing.expectEqual(@as(u64, 0), try currentGeneration(tmp.dir));
+}
+
+test "bumpGeneration increments and persists across reopen" {
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    try std.testing.expectEqual(@as(u64, 1), try bumpGeneration(tmp.dir));
+    try std.testing.expectEqual(@as(u64, 2), try bumpGeneration(tmp.dir));
+    try std.testing.expectEqual(@as(u64, 3), try bumpGeneration(tmp.dir));
+    try std.testing.expectEqual(@as(u64, 3), try currentGeneration(tmp.dir));
+}
+
+test "currentGeneration rejects a corrupted generation file" {
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    _ = try bumpGeneration(tmp.dir);
+
+    const file = try tmp.dir.openFile(genFileName, .{ .mode = .read_write });
+    defer file.close();
+    try file.seekTo(4);
+    try file.writeAll(&[_]u8{ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF });
+
+    try std.testing.expectError(GenerationError.Corrupt, currentGeneration(tmp.dir));
+}
+
+test "Wal.reset does not itself touch the generation counter" {
+    const allocator = std.testing.allocator;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+
+    var wal = try Wal.open(allocator, tmp.dir, "wal.log");
+    defer wal.close();
+    try wal.append(.value, 1, "k", "v");
+    try wal.reset();
+
+    // reset() only truncates the WAL file itself - generation bumping is a
+    // separate, explicit call made by Db.flush() at the same call site, kept
+    // out of Wal so tests exercising reset() in isolation (elsewhere in this
+    // file) do not need a directory-wide side effect they never asked for.
+    try std.testing.expectEqual(@as(u64, 0), try currentGeneration(tmp.dir));
+}
+
 test "wal append and replay" {
     const allocator = std.testing.allocator;
     var tmp = std.testing.tmpDir(.{});
diff --git a/src/window.zig b/src/window.zig
new file mode 100644
index 0000000..5da7f85
--- /dev/null
+++ b/src/window.zig
@@ -0,0 +1,2222 @@
+const std = @import("std");
+const rowmod = @import("row.zig");
+const querymod = @import("query.zig");
+
+const Allocator = std.mem.Allocator;
+const Value = rowmod.Value;
+const Row = rowmod.Row;
+
+/// Window-function engine over already-materialized `Row` slices (the same
+/// currency `aggregate.zig`/`join.zig` use): callers filter and fetch rows
+/// through `Table.select`/`Table.scanAll` first, then feed the result here.
+/// Unlike `aggregate.zig`'s GROUP BY (which COLLAPSES rows into one per
+/// group), a window function ANNOTATES every input row with a computed
+/// value while keeping all of them - SQL's `expr() OVER (PARTITION BY ...
+/// ORDER BY ...)`. `compute()` returns one `Value` per row, aligned 1:1
+/// with the caller's row order.
+pub const WindowKind = enum {
+    /// Sequential position (1-based) within the partition in `orderBy`
+    /// order. Never skips or repeats, even across ties.
+    row_number,
+    /// 1-based rank within the partition; rows tying on every `orderBy`
+    /// column share a rank, and the NEXT distinct rank skips ahead by the
+    /// tie group's size (SQL's `RANK()`).
+    rank,
+    /// Like `rank`, but the next distinct rank is always exactly one more
+    /// than the previous (SQL's `DENSE_RANK()`, no gaps).
+    dense_rank,
+    sum,
+    avg,
+    count,
+    /// Running count of DISTINCT non-none values of `field` seen so far in
+    /// the current frame (SQL's `COUNT(DISTINCT field) OVER (...)`).
+    /// Mirrors `aggregate.zig`'s `AggKind.count_distinct` (same
+    /// encode-as-hashmap-key dedup via `rowmod.encodeValue`), but as a
+    /// RUNNING total instead of one final count per group: under `.rows` the
+    /// distinct set only ever grows row by row within a partition, so a
+    /// later row's count can never be smaller than an earlier row's. Always
+    /// requires `field` (no `COUNT(*)`-style bare form, unlike plain
+    /// `count`) - counting distinct values of "nothing" is not meaningful.
+    count_distinct,
+    min,
+    max,
+    /// Value of `field` `offset` rows BEFORE the current row, within the
+    /// same partition, walked in `orderBy` order (SQL's `LAG()`). A row
+    /// whose predecessor at that distance does not exist (falls before the
+    /// start of the partition) gets `WindowSpec.default` instead.
+    lag,
+    /// Like `lag`, but `offset` rows AFTER the current row (SQL's `LEAD()`).
+    lead,
+    /// `field`'s value on the FIRST row of the current frame (SQL's
+    /// `FIRST_VALUE()`). Unlike `lag`/`lead`, this DOES respect `frame`: the
+    /// frame's start is always the partition's first row regardless of
+    /// `FrameMode` (both variants share `UNBOUNDED PRECEDING`), so
+    /// `first_value` is constant across an entire partition no matter which
+    /// row is asking.
+    first_value,
+    /// `field`'s value on the LAST row of the current frame (SQL's
+    /// `LAST_VALUE()`). This is the well-known SQL surprise: under `.rows`
+    /// (`ROWS UNBOUNDED PRECEDING .. CURRENT ROW`) the frame's end IS the
+    /// current row, so `last_value` degenerates to the row's own `field` -
+    /// to see the partition's true final value with `orderBy` present, use
+    /// `.range`, whose frame end is instead the current row's whole tie
+    /// group (matching the running-aggregate family's `.range` semantics),
+    /// or omit `orderBy` entirely for the whole-partition frame.
+    last_value,
+    /// `field`'s value on the `WindowSpec.offset`-th row (1-based) of the
+    /// CURRENT frame (SQL's `NTH_VALUE(field, n)`). Shares `first_value`/
+    /// `last_value`'s frame-respecting behavior (same `UNBOUNDED PRECEDING`
+    /// start, same `.rows`/`.range`/no-`orderBy` frame-end split) rather than
+    /// `lag`/`lead`'s fixed physical offset from the CURRENT row - `n` here
+    /// counts from the frame's START, not from "here". A position that falls
+    /// AFTER the current frame's end (including the well-known `.rows`
+    /// degenerate case, where the frame end is the current row itself) gets
+    /// `WindowSpec.default` (SQL NULL unless the caller set one), reusing
+    /// `lag`/`lead`'s out-of-range convention rather than inventing a new one.
+    nth_value,
+};
+
+pub const WindowSpec = struct {
+    /// Ignored for `row_number`/`rank`/`dense_rank` and for `count`'s
+    /// `COUNT(*)` form (pass `""`).
+    field: []const u8,
+    kind: WindowKind,
+    /// `lag`/`lead`: how many rows back (`lag`) or forward (`lead`) within
+    /// the partition's `orderBy` sequence to read from. SQL's default of 1
+    /// (the immediately adjacent row). `0` is legal (reads the current row
+    /// itself). `nth_value`: the 1-based position `n` within the current
+    /// frame to read (SQL's `NTH_VALUE(field, n)` - `n` has no SQL default,
+    /// but the struct default of `1` degenerates to `first_value`, which is
+    /// a sensible fallback rather than a trap). Ignored by every other
+    /// `WindowKind`.
+    offset: u64 = 1,
+    /// `lag`/`lead`/`nth_value`: the value stamped on a row whose target
+    /// falls outside the partition (`lag`/`lead`) or outside the current
+    /// frame (`nth_value`), mirroring SQL's optional third `LAG`/`LEAD`
+    /// argument. Defaults to `.none` (SQL NULL when the argument is
+    /// omitted). Ignored by every other `WindowKind`.
+    default: Value = .{ .none = {} },
+};
+
+pub const WindowError = error{
+    /// `sum`/`avg` observed a field holding a non-numeric `Value` (anything
+    /// but `.int`/`.float`) - same convention as `aggregate.zig`.
+    NonNumericField,
+    /// The running integer sum would not fit in `i64`. Never silently
+    /// wraps or drops precision by switching to float behind the caller's
+    /// back.
+    Overflow,
+    /// `sum`/`avg`/`min`/`max` require a `field`; only the ranking family
+    /// and `count`'s `COUNT(*)` form may omit one.
+    MissingField,
+    /// `FrameMode.range` was requested together with `row_number`/`rank`/
+    /// `dense_rank`. Standard SQL does not accept a frame clause on those at
+    /// all (`row_number` is always ROWS-only; `rank`/`dense_rank` already
+    /// implement their own fixed tie semantics) - `compute()` rejects the
+    /// combination instead of silently ignoring the requested frame.
+    RangeNotApplicable,
+} || Allocator.Error;
+
+/// The frame a running-aggregate `WindowKind` (`sum`/`avg`/`count`/`min`/
+/// `max`) walks when `orderBy` is non-empty - irrelevant when `orderBy` is
+/// empty (both modes reduce to the same whole-partition frame then) and
+/// irrelevant to the ranking family (`compute()` rejects `.range` there, see
+/// `WindowError.RangeNotApplicable`). See `compute()`'s doc comment for the
+/// SQL semantics each variant mirrors.
+pub const FrameMode = enum {
+    /// `ROWS UNBOUNDED PRECEDING .. CURRENT ROW`: a genuine running total,
+    /// walked one physical row at a time regardless of ties.
+    rows,
+    /// `RANGE UNBOUNDED PRECEDING .. CURRENT ROW` (SQL's actual default):
+    /// rows tied on every `orderBy` column share the LAST tied row's value
+    /// instead of each accumulating their own individual running value.
+    range,
+};
+
+fn isRanking(kind: WindowKind) bool {
+    return kind == .row_number or kind == .rank or kind == .dense_rank;
+}
+
+/// `lag`/`lead`: pure positional lookups within the sorted partition. Not a
+/// running aggregate (no `RunningAcc`) and not a ranking (no tie handling) -
+/// its own third family, sharing `RangeNotApplicable` with the ranking
+/// family below since a frame clause has no meaning for either.
+fn isOffsetLookup(kind: WindowKind) bool {
+    return kind == .lag or kind == .lead;
+}
+
+/// `first_value`/`last_value`/`nth_value`: like the running-aggregate
+/// family, these DO respect `frame` (unlike `lag`/`lead`) - so they get
+/// their own predicate rather than folding into `isOffsetLookup`.
+fn isFrameValue(kind: WindowKind) bool {
+    return kind == .first_value or kind == .last_value or kind == .nth_value;
+}
+
+/// The row field name a `compute()` result column is exposed under (e.g.
+/// for CLI/protocol output) - bare `WindowKind` name for the ranking family
+/// and for `count`'s `COUNT(*)` form (`field.len == 0`), otherwise
+/// `"kind_field"`. Format-identical to `aggregate.zig`'s `specLabel`.
+pub fn specLabel(allocator: Allocator, spec: WindowSpec) Allocator.Error![]u8 {
+    if (spec.field.len == 0) return allocator.dupe(u8, @tagName(spec.kind));
+    return std.fmt.allocPrint(allocator, "{s}_{s}", .{ @tagName(spec.kind), spec.field });
+}
+
+/// Streaming per-row accumulator for the running-aggregate family
+/// (`sum`/`avg`/`count`/`min`/`max`). Mirrors `aggregate.zig`'s `AccState`
+/// (same int-exact/float-fallback dual for `sum`/`avg`, same
+/// compare-and-replace for `min`/`max`), minus `count_distinct` (out of
+/// scope here - a running "distinct count so far" is a real SQL feature but
+/// a separate piece of work). The key behavioral difference from
+/// `AccState.take()`: `snapshot()` does NOT transfer ownership of
+/// `minv`/`maxv` out of the accumulator, because a running window emits a
+/// result after EVERY row, not once at the very end - the accumulator must
+/// keep its own copy alive for the next row's snapshot too.
+const RunningAcc = struct {
+    kind: WindowKind,
+    field: []const u8,
+    n: u64 = 0,
+    sumInt: i64 = 0,
+    sumFloat: f64 = 0,
+    allInt: bool = true,
+    minv: ?Value = null,
+    maxv: ?Value = null,
+    /// `.count_distinct` only: encoded-`Value` bytes seen so far, one entry
+    /// per distinct value - same encode-as-hashmap-key trick
+    /// `aggregate.zig`'s `AccState.distinct` uses. Unlike that GROUP BY
+    /// counterpart, `snapshot()` below never drains this (a running window
+    /// needs the set to keep growing across the WHOLE partition walk, not
+    /// just until one final result) - only `deinit` ever frees it.
+    distinct: std.StringHashMapUnmanaged(void) = .{},
+
+    fn observe(self: *RunningAcc, allocator: Allocator, row: *const Row) WindowError!void {
+        switch (self.kind) {
+            .count => {
+                if (self.field.len == 0 or row.get(self.field) != null) self.n += 1;
+            },
+            .count_distinct => {
+                const v = row.get(self.field) orelse return;
+                const key = try rowmod.encodeValue(allocator, v);
+                const res = try self.distinct.getOrPut(allocator, key);
+                if (res.found_existing) allocator.free(key);
+            },
+            .sum, .avg => {
+                const v = row.get(self.field) orelse return;
+                switch (v) {
+                    .int => |i| {
+                        if (self.allInt) {
+                            self.sumInt = std.math.add(i64, self.sumInt, i) catch return error.Overflow;
+                        } else {
+                            self.sumFloat += @floatFromInt(i);
+                        }
+                    },
+                    .float => |f| {
+                        if (self.allInt) {
+                            // First float observed after an int-only run:
+                            // migrate the exact integer sum so far into the
+                            // float accumulator once, then continue in float.
+                            self.sumFloat = @floatFromInt(self.sumInt);
+                            self.allInt = false;
+                        }
+                        self.sumFloat += f;
+                    },
+                    else => return error.NonNumericField,
+                }
+                self.n += 1;
+            },
+            .min => {
+                const v = row.get(self.field) orelse return;
+                if (self.minv == null or rowmod.compare(v, self.minv.?) == .lt) {
+                    if (self.minv) |old| old.free(allocator);
+                    self.minv = try v.dupe(allocator);
+                }
+            },
+            .max => {
+                const v = row.get(self.field) orelse return;
+                if (self.maxv == null or rowmod.compare(v, self.maxv.?) == .gt) {
+                    if (self.maxv) |old| old.free(allocator);
+                    self.maxv = try v.dupe(allocator);
+                }
+            },
+            .row_number, .rank, .dense_rank, .lag, .lead, .first_value, .last_value, .nth_value => unreachable,
+        }
+    }
+
+    /// Returns the accumulator's CURRENT state as a freshly owned `Value`
+    /// (a dupe for `min`/`max`, since the accumulator keeps its own copy
+    /// alive for subsequent rows - see the type doc comment above).
+    /// `.count_distinct` is likewise non-draining - `self.distinct.count()`
+    /// is read, never emptied, so the NEXT row's snapshot still sees every
+    /// value observed so far (only `deinit` ever frees the set).
+    fn snapshot(self: *const RunningAcc, allocator: Allocator) Allocator.Error!Value {
+        return switch (self.kind) {
+            .count => .{ .int = @intCast(self.n) },
+            .count_distinct => .{ .int = @intCast(self.distinct.count()) },
+            .sum => if (self.allInt) .{ .int = self.sumInt } else .{ .float = self.sumFloat },
+            .avg => blk: {
+                if (self.n == 0) break :blk .{ .none = {} };
+                const total: f64 = if (self.allInt) @floatFromInt(self.sumInt) else self.sumFloat;
+                break :blk .{ .float = total / @as(f64, @floatFromInt(self.n)) };
+            },
+            .min => if (self.minv) |v| try v.dupe(allocator) else .{ .none = {} },
+            .max => if (self.maxv) |v| try v.dupe(allocator) else .{ .none = {} },
+            .row_number, .rank, .dense_rank, .lag, .lead, .first_value, .last_value, .nth_value => unreachable,
+        };
+    }
+
+    fn deinit(self: *RunningAcc, allocator: Allocator) void {
+        if (self.minv) |v| v.free(allocator);
+        if (self.maxv) |v| v.free(allocator);
+        var it = self.distinct.keyIterator();
+        while (it.next()) |k| allocator.free(k.*);
+        self.distinct.deinit(allocator);
+    }
+};
+
+/// Groups row indices `0..rows.len` by `partitionBy` (empty = a single
+/// partition covering every row), preserving first-seen partition order -
+/// the window-function analogue of `aggregate.zig`'s `GroupBy` grouping,
+/// except every member index is kept instead of collapsed into one result.
+/// Multi-column partition keys are built with `row.appendOrdered`
+/// (concatenation-safe and unambiguous by construction), the same
+/// primitive `index.zig` uses for composite index keys - a row missing one
+/// of the `partitionBy` fields contributes `.none` for that column rather
+/// than being excluded (unlike `aggregate.zig`'s GROUP BY, which drops rows
+/// missing the group field entirely: a window function must still annotate
+/// every input row with SOME result, so there is no row to drop it from).
+/// Caller owns the returned slice of slices AND each inner slice
+/// (`allocator.free` each inner slice, then the outer one).
+fn buildPartitions(allocator: Allocator, rows: []const Row, partitionBy: []const []const u8) Allocator.Error![][]usize {
+    var order: std.ArrayListUnmanaged([]const u8) = .{};
+    defer {
+        for (order.items) |k| allocator.free(k);
+        order.deinit(allocator);
+    }
+    var map: std.StringHashMapUnmanaged(std.ArrayListUnmanaged(usize)) = .{};
+    defer {
+        var it = map.iterator();
+        while (it.next()) |e| e.value_ptr.deinit(allocator);
+        map.deinit(allocator);
+    }
+
+    for (rows, 0..) |*r, i| {
+        var keyBuf = std.ArrayList(u8).init(allocator);
+        defer keyBuf.deinit();
+        for (partitionBy) |f| {
+            const v = r.get(f) orelse Value{ .none = {} };
+            try rowmod.appendOrdered(&keyBuf, v);
+        }
+
+        if (map.getPtr(keyBuf.items)) |list| {
+            try list.append(allocator, i);
+            continue;
+        }
+        const key = try allocator.dupe(u8, keyBuf.items);
+        errdefer allocator.free(key);
+        var list: std.ArrayListUnmanaged(usize) = .{};
+        errdefer list.deinit(allocator);
+        try list.append(allocator, i);
+        // `map.putAssumeCapacity`/`order.appendAssumeCapacity` below are
+        // INFALLIBLE (capacity reserved just above) and back to back with
+        // no fallible statement between them - a bug caught by
+        // `computeMany`'s exhaustive OOM sweep test: with plain fallible
+        // `map.put` then `order.append`, a failure in `order.append` AFTER
+        // `map.put` already succeeded left `key`/`list` reachable from BOTH
+        // this iteration's still-armed `errdefer list.deinit(allocator)`
+        // AND the function-level `map` cleanup `defer` above (which iterates
+        // every entry, including the one just inserted) - both would then
+        // free the SAME `list` backing array. Reserving capacity for both
+        // `map` and `order` up front and using the assume-capacity variants
+        // means nothing fallible can happen between the two inserts, so
+        // there is no window for a failure to leave `key`/`list` owned by
+        // one structure while their local errdefers are still armed.
+        try map.ensureUnusedCapacity(allocator, 1);
+        try order.ensureUnusedCapacity(allocator, 1);
+        map.putAssumeCapacity(key, list);
+        order.appendAssumeCapacity(key);
+    }
+
+    const result = try allocator.alloc([]usize, order.items.len);
+    var filled: usize = 0;
+    errdefer {
+        for (result[0..filled]) |p| allocator.free(p);
+        allocator.free(result);
+    }
+    for (order.items, 0..) |key, idx| {
+        const list = map.getPtr(key).?;
+        result[idx] = try list.toOwnedSlice(allocator);
+        filled += 1;
+    }
+    return result;
+}
+
+/// Stable in-place sort of a partition's row INDICES by `orderBy` - the
+/// window-function analogue of `query.zig`'s `sortRowsBy`/`aggregate.zig`'s
+/// `sortGroupsBy`, but sorting `usize` indices into `rows` rather than the
+/// rows themselves (so the caller's row order and `results`' index
+/// alignment are never disturbed). `orderBy.len == 0` is a no-op, leaving
+/// `indices` in first-seen (input) order.
+fn sortPartitionByOrder(rows: []const Row, indices: []usize, orderBy: []const querymod.OrderBy) void {
+    if (orderBy.len == 0) return;
+    const Ctx = struct {
+        rows: []const Row,
+        orderBy: []const querymod.OrderBy,
+
+        fn lessThan(ctx: @This(), a: usize, b: usize) bool {
+            for (ctx.orderBy) |ob| {
+                const av = ctx.rows[a].get(ob.field) orelse Value{ .none = {} };
+                const bv = ctx.rows[b].get(ob.field) orelse Value{ .none = {} };
+                const cmp = rowmod.compare(av, bv);
+                if (cmp == .eq) continue;
+                return if (ob.descending) cmp == .gt else cmp == .lt;
+            }
+            return false;
+        }
+    };
+    std.sort.block(usize, indices, Ctx{ .rows = rows, .orderBy = orderBy }, Ctx.lessThan);
+}
+
+/// Whether `rows[curIdx]` ties `rows[prevIdx]` on every `orderBy` column -
+/// the tie-group boundary `rank`/`dense_rank` need to decide whether to
+/// advance. Only meaningful once `indices` has already been sorted by the
+/// same `orderBy`.
+fn tiesWithPrev(rows: []const Row, orderBy: []const querymod.OrderBy, prevIdx: usize, curIdx: usize) bool {
+    for (orderBy) |ob| {
+        const av = rows[curIdx].get(ob.field) orelse Value{ .none = {} };
+        const bv = rows[prevIdx].get(ob.field) orelse Value{ .none = {} };
+        if (rowmod.compare(av, bv) != .eq) return false;
+    }
+    return true;
+}
+
+/// `buildPartitions` followed by sorting every partition in place by
+/// `orderBy` - the shared prep step `compute()` and `orderedIndices()` both
+/// need, factored out so the flattened display order `orderedIndices`
+/// exposes is GUARANTEED to match the partition walk `compute()` uses
+/// internally (computed once, not two independently-written sorts that
+/// could drift apart).
+fn partitionedAndSorted(allocator: Allocator, rows: []const Row, partitionBy: []const []const u8, orderBy: []const querymod.OrderBy) Allocator.Error![][]usize {
+    const partitions = try buildPartitions(allocator, rows, partitionBy);
+    for (partitions) |indices| sortPartitionByOrder(rows, indices, orderBy);
+    return partitions;
+}
+
+/// Returns the row-index walk order `compute()` uses internally, flattened:
+/// every partition's member indices (each sorted by `orderBy`), partitions
+/// concatenated in first-seen order. `compute()`'s own results stay aligned
+/// to `rows`' ORIGINAL order regardless of this - this exists for callers
+/// (namely `table window`'s CLI) that want to PAGE or DISPLAY results in
+/// the same order the window computation itself walked, rather than raw
+/// scan order, which is what plain `[start..end]` slicing of `rows` would
+/// give instead. Caller owns the returned slice.
+pub fn orderedIndices(allocator: Allocator, rows: []const Row, partitionBy: []const []const u8, orderBy: []const querymod.OrderBy) Allocator.Error![]usize {
+    const partitions = try partitionedAndSorted(allocator, rows, partitionBy, orderBy);
+    defer {
+        for (partitions) |p| allocator.free(p);
+        allocator.free(partitions);
+    }
+    const out = try allocator.alloc(usize, rows.len);
+    var pos: usize = 0;
+    for (partitions) |indices| {
+        @memcpy(out[pos..][0..indices.len], indices);
+        pos += indices.len;
+    }
+    return out;
+}
+
+/// Computes one window-function result `Value` per input row, returned in
+/// the SAME order as `rows` (never reorders the caller's data) - the window
+/// counterpart of `aggregate.zig`'s `run`, which collapses rows into one
+/// per group instead of annotating every one. `partitionBy` splits `rows`
+/// into independent groups exactly like GROUP BY (first-seen order, empty
+/// = a single partition covering every row); `orderBy` decides the
+/// ranking/running-total walk WITHIN each partition.
+///
+/// Frame semantics follow standard SQL defaults, decided entirely by
+/// whether `orderBy` is empty:
+///   - `orderBy.len == 0`: `rank`/`dense_rank` treat the whole partition as
+///     one tie (every row gets 1); `row_number` still assigns 1..n in
+///     first-seen order, since it needs no ordering key to number rows.
+///     The running-aggregate family uses the whole-partition frame
+///     (`UNBOUNDED PRECEDING .. UNBOUNDED FOLLOWING`) - every row in the
+///     partition sees the SAME final total, mirroring `SUM(x) OVER
+///     (PARTITION BY p)` with no `ORDER BY` inside the `OVER` clause.
+///   - `orderBy.len > 0`: `frame` picks the running-aggregate family's frame
+///     along the sorted sequence. `.rows` walks one physical row at a time
+///     (`ROWS UNBOUNDED PRECEDING .. CURRENT ROW`) - every row gets its own
+///     individual running value, even a row tied with its predecessor.
+///     `.range` (SQL's actual default, `RANGE UNBOUNDED PRECEDING ..
+///     CURRENT ROW`) instead advances the accumulator by a whole tie group
+///     at once and stamps every row in that group with the SAME value (the
+///     group's combined total, not each member's own position within it) -
+///     the same tie test `rank`/`dense_rank` already use
+///     (`tiesWithPrev`), just driving accumulation instead of a rank
+///     counter. `frame` is ignored (both variants agree) when `orderBy` is
+///     empty, and rejected outright (`error.RangeNotApplicable`) for the
+///     ranking family - see `WindowError.RangeNotApplicable`.
+///
+/// `lag`/`lead` (`spec.offset`/`spec.default`) ignore `frame` entirely (also
+/// `error.RangeNotApplicable` under `.range`, same as the ranking family -
+/// SQL does not accept a frame clause on either) and read a fixed physical
+/// position `spec.offset` rows before (`lag`) or after (`lead`) each row
+/// within the sorted partition sequence (first-seen order when `orderBy` is
+/// empty) - unlike the running-aggregate family, a tie on `orderBy` does NOT
+/// collapse two rows into one lookup target; each remains its own distinct
+/// position. A row whose target position falls outside the partition gets
+/// `spec.default` (SQL NULL, `.none`, unless the caller set one).
+///
+/// `first_value`/`last_value` DO respect `frame`, unlike `lag`/`lead`: the
+/// frame's start is always the partition's first row regardless of
+/// `FrameMode` (so `first_value` is constant across a whole partition), but
+/// the frame's END for `last_value` follows the running-aggregate family's
+/// same split - `.rows` ends the frame at the CURRENT row (so `last_value`
+/// degenerates to that row's own field, SQL's well-known gotcha), `.range`
+/// ends it at the current row's whole tie group, and no `orderBy` at all
+/// means the whole-partition frame (so `last_value` is the last row in
+/// first-seen order, same value for every row). Requires `field` like the
+/// running-aggregate family (`error.MissingField` if omitted).
+///
+/// `nth_value` shares that same frame (start/end identical to
+/// `first_value`/`last_value`) but reads the `spec.offset`-th row (1-based)
+/// counted from the frame's start rather than always the first or always the
+/// last; a position past the frame's current end gets `spec.default`.
+///
+/// Caller owns the returned slice; free each `Value` (`.free(allocator)`)
+/// and the slice itself, or call `freeResults`.
+pub fn compute(allocator: Allocator, rows: []const Row, partitionBy: []const []const u8, orderBy: []const querymod.OrderBy, spec: WindowSpec, frame: FrameMode) WindowError![]Value {
+    const partitions = try partitionedAndSorted(allocator, rows, partitionBy, orderBy);
+    defer {
+        for (partitions) |p| allocator.free(p);
+        allocator.free(partitions);
+    }
+    return computeOneSpec(allocator, rows, partitions, orderBy, spec, frame);
+}
+
+/// The single-`WindowSpec` body of `compute()`, factored out so
+/// `computeMany()` can run it once per spec against partitions it already
+/// built ONCE - the window-function counterpart of why `aggregate.zig`'s
+/// `GroupBy` groups rows once and folds every spec into the same pass,
+/// rather than re-grouping per spec. Takes already-partitioned-and-sorted
+/// row indices (`partitionedAndSorted`'s output) instead of building them
+/// itself.
+fn computeOneSpec(allocator: Allocator, rows: []const Row, partitions: []const []usize, orderBy: []const querymod.OrderBy, spec: WindowSpec, frame: FrameMode) WindowError![]Value {
+    if (!isRanking(spec.kind) and spec.kind != .count and spec.field.len == 0) return error.MissingField;
+    if (frame == .range and (isRanking(spec.kind) or isOffsetLookup(spec.kind))) return error.RangeNotApplicable;
+
+    const results = try allocator.alloc(Value, rows.len);
+    for (results) |*r| r.* = .{ .none = {} };
+    errdefer freeResults(allocator, results);
+
+    for (partitions) |indices| {
+        if (isRanking(spec.kind)) {
+            var rank: usize = 0;
+            var dense: usize = 0;
+            for (indices, 0..) |idx, pos| {
+                const tied = pos > 0 and (orderBy.len == 0 or tiesWithPrev(rows, orderBy, indices[pos - 1], idx));
+                switch (spec.kind) {
+                    .row_number => results[idx] = .{ .int = @intCast(pos + 1) },
+                    .rank => {
+                        if (pos == 0 or !tied) rank = pos + 1;
+                        results[idx] = .{ .int = @intCast(rank) };
+                    },
+                    .dense_rank => {
+                        if (pos == 0 or !tied) dense += 1;
+                        results[idx] = .{ .int = @intCast(dense) };
+                    },
+                    else => unreachable,
+                }
+            }
+            continue;
+        }
+
+        if (isOffsetLookup(spec.kind)) {
+            // Pure positional lookup along the sorted partition sequence -
+            // no accumulator, no tie handling (a row tied with its neighbor
+            // on `orderBy` is still a DISTINCT physical position for
+            // `lag`/`lead`, unlike the ranking family above).
+            const delta: i64 = @intCast(spec.offset);
+            for (indices, 0..) |idx, pos| {
+                const srcPos: i64 = @as(i64, @intCast(pos)) + (if (spec.kind == .lag) -delta else delta);
+                if (srcPos >= 0 and srcPos < @as(i64, @intCast(indices.len))) {
+                    const srcIdx = indices[@intCast(srcPos)];
+                    const v = rows[srcIdx].get(spec.field) orelse Value{ .none = {} };
+                    results[idx] = try v.dupe(allocator);
+                } else {
+                    results[idx] = try spec.default.dupe(allocator);
+                }
+            }
+            continue;
+        }
+
+        if (spec.kind == .nth_value) {
+            // Positional lookup within the CURRENT frame (start is always
+            // the partition's first row, end follows the same
+            // whole-partition/.rows/.range split `first_value`/`last_value`
+            // use below) - `n` counts from the frame's start, unlike
+            // `lag`/`lead`'s offset from the current row. `n < 1` never
+            // resolves (WindowSpec.offset defaults to 1, never 0, but a
+            // caller reaching this directly - e.g. over the wire - could
+            // still send 0).
+            if (indices.len == 0) continue;
+            const n = spec.offset;
+            if (orderBy.len == 0) {
+                const frameEnd: u64 = @intCast(indices.len - 1);
+                const v = if (n >= 1 and n - 1 <= frameEnd)
+                    rows[indices[@intCast(n - 1)]].get(spec.field) orelse Value{ .none = {} }
+                else
+                    spec.default;
+                for (indices) |idx| results[idx] = try v.dupe(allocator);
+            } else if (frame == .rows) {
+                for (indices, 0..) |idx, pos| {
+                    const frameEnd: u64 = @intCast(pos);
+                    const v = if (n >= 1 and n - 1 <= frameEnd)
+                        rows[indices[@intCast(n - 1)]].get(spec.field) orelse Value{ .none = {} }
+                    else
+                        spec.default;
+                    results[idx] = try v.dupe(allocator);
+                }
+            } else {
+                var pos: usize = 0;
+                while (pos < indices.len) {
+                    var end = pos + 1;
+                    while (end < indices.len and tiesWithPrev(rows, orderBy, indices[end - 1], indices[end])) : (end += 1) {}
+                    const frameEnd: u64 = @intCast(end - 1);
+                    const v = if (n >= 1 and n - 1 <= frameEnd)
+                        rows[indices[@intCast(n - 1)]].get(spec.field) orelse Value{ .none = {} }
+                    else
+                        spec.default;
+                    for (indices[pos..end]) |idx| results[idx] = try v.dupe(allocator);
+                    pos = end;
+                }
+            }
+            continue;
+        }
+
+        if (isFrameValue(spec.kind)) {
+            if (indices.len == 0) continue;
+            if (orderBy.len == 0) {
+                // Whole-partition frame: first/last row of the partition in
+                // first-seen order, same value stamped on every member.
+                const firstV = rows[indices[0]].get(spec.field) orelse Value{ .none = {} };
+                const lastV = rows[indices[indices.len - 1]].get(spec.field) orelse Value{ .none = {} };
+                const v = if (spec.kind == .first_value) firstV else lastV;
+                for (indices) |idx| results[idx] = try v.dupe(allocator);
+            } else if (frame == .rows) {
+                // ROWS frame: start is always the partition's first row;
+                // end is the CURRENT row (SQL's well-known LAST_VALUE
+                // surprise under the ROWS default).
+                const firstV = rows[indices[0]].get(spec.field) orelse Value{ .none = {} };
+                for (indices) |idx| {
+                    const v = if (spec.kind == .first_value) firstV else (rows[idx].get(spec.field) orelse Value{ .none = {} });
+                    results[idx] = try v.dupe(allocator);
+                }
+            } else {
+                // RANGE frame: end is the current row's whole tie group -
+                // every row in the group shares that group's LAST member's
+                // value, same tie-group walk the running-aggregate family's
+                // `.range` branch uses.
+                const firstV = rows[indices[0]].get(spec.field) orelse Value{ .none = {} };
+                var pos: usize = 0;
+                while (pos < indices.len) {
+                    var end = pos + 1;
+                    while (end < indices.len and tiesWithPrev(rows, orderBy, indices[end - 1], indices[end])) : (end += 1) {}
+                    const groupLastV = rows[indices[end - 1]].get(spec.field) orelse Value{ .none = {} };
+                    for (indices[pos..end]) |idx| {
+                        const v = if (spec.kind == .first_value) firstV else groupLastV;
+                        results[idx] = try v.dupe(allocator);
+                    }
+                    pos = end;
+                }
+            }
+            continue;
+        }
+
+        var acc = RunningAcc{ .kind = spec.kind, .field = spec.field };
+        defer acc.deinit(allocator);
+
+        if (orderBy.len == 0) {
+            // Whole-partition frame: accumulate everything first, THEN
+            // stamp the same final value onto every row in the partition.
+            for (indices) |idx| try acc.observe(allocator, &rows[idx]);
+            for (indices) |idx| results[idx] = try acc.snapshot(allocator);
+        } else if (frame == .rows) {
+            // ROWS frame: emit the accumulator's state after EACH row,
+            // walked in sorted order, even a row tied with its predecessor.
+            for (indices) |idx| {
+                try acc.observe(allocator, &rows[idx]);
+                results[idx] = try acc.snapshot(allocator);
+            }
+        } else {
+            // RANGE frame: advance the accumulator by a whole tie GROUP at
+            // once (same `tiesWithPrev` test the ranking family uses to
+            // find its own tie boundaries), then stamp every row in that
+            // group with the group's combined value - mirroring the
+            // whole-partition branch above, just re-run once per group
+            // instead of once for the whole partition.
+            var pos: usize = 0;
+            while (pos < indices.len) {
+                var end = pos + 1;
+                while (end < indices.len and tiesWithPrev(rows, orderBy, indices[end - 1], indices[end])) : (end += 1) {}
+                for (indices[pos..end]) |idx| try acc.observe(allocator, &rows[idx]);
+                for (indices[pos..end]) |idx| results[idx] = try acc.snapshot(allocator);
+                pos = end;
+            }
+        }
+    }
+
+    return results;
+}
+
+/// Computes MULTIPLE window-function columns over the SAME shared
+/// `PARTITION BY`/`ORDER BY`/`frame` in one pass - SQL's `SELECT sum(x)
+/// OVER w, avg(y) OVER w, rank() OVER w FROM t WINDOW w AS (...)` (every
+/// column sharing one window definition), the window-function counterpart
+/// of `aggregate.zig`'s multi-`AggSpec` GROUP BY. `partitionedAndSorted` is
+/// built exactly ONCE and reused for every spec - unlike calling `compute()`
+/// in a loop, which would redo that O(n log n) sort per spec for no reason.
+///
+/// Returns one entry PER ROW (aligned 1:1 with `rows`, like `compute()`'s
+/// result), each entry an independently-owned `[]Value` of length
+/// `specs.len` in the SAME order as `specs` - row-major, not the
+/// column-major shape the per-spec computation happens in internally,
+/// because that is the shape every caller (CLI printing, wire encoding)
+/// actually wants: all of one row's annotations together. Caller owns the
+/// returned slice; free each inner slice (`.free(allocator)` on every
+/// `Value`, then `allocator.free` the slice), or call `freeManyResults`.
+pub fn computeMany(allocator: Allocator, rows: []const Row, partitionBy: []const []const u8, orderBy: []const querymod.OrderBy, specs: []const WindowSpec, frame: FrameMode) WindowError![][]Value {
+    const partitions = try partitionedAndSorted(allocator, rows, partitionBy, orderBy);
+    defer {
+        for (partitions) |p| allocator.free(p);
+        allocator.free(partitions);
+    }
+
+    var columns = try allocator.alloc([]Value, specs.len);
+    var filledCols: usize = 0;
+    errdefer {
+        for (columns[0..filledCols]) |c| freeResults(allocator, c);
+        allocator.free(columns);
+    }
+    for (specs) |spec| {
+        columns[filledCols] = try computeOneSpec(allocator, rows, partitions, orderBy, spec, frame);
+        filledCols += 1;
+    }
+
+    const results = try allocator.alloc([]Value, rows.len);
+    var filledRows: usize = 0;
+    errdefer {
+        for (results[0..filledRows]) |r| freeResults(allocator, r);
+        allocator.free(results);
+    }
+    for (0..rows.len) |rowIdx| {
+        const rowValues = try allocator.alloc(Value, specs.len);
+        var filledVals: usize = 0;
+        errdefer {
+            for (rowValues[0..filledVals]) |v| v.free(allocator);
+            allocator.free(rowValues);
+        }
+        for (columns, 0..) |col, specIdx| {
+            rowValues[specIdx] = try col[rowIdx].dupe(allocator);
+            filledVals += 1;
+        }
+        results[rowIdx] = rowValues;
+        filledRows += 1;
+    }
+
+    // Every column stays independently owned by `columns` up to this
+    // point - `results` above holds its OWN dupe of every `Value` (min/max
+    // may hold heap-owned text/bytes), never a shared pointer - so it is
+    // always safe to free `columns` in full here, on the success path only:
+    // the `errdefer` right after `columns` was allocated already covers
+    // EVERY error path (early, mid-build, or during the transpose loop
+    // above) using the same `filledCols`, which by now equals `specs.len` -
+    // a second, unconditional `defer` registered after that `errdefer`
+    // would double-free `columns` on any error occurring after it, since an
+    // `errdefer` stays armed for the rest of the enclosing scope regardless
+    // of what runs after it, not just the statements immediately following.
+    for (columns) |c| freeResults(allocator, c);
+    allocator.free(columns);
+
+    return results;
+}
+
+pub fn freeManyResults(allocator: Allocator, results: [][]Value) void {
+    for (results) |r| freeResults(allocator, r);
+    allocator.free(results);
+}
+
+pub fn freeResults(allocator: Allocator, results: []Value) void {
+    for (results) |v| v.free(allocator);
+    allocator.free(results);
+}
+
+fn makeRow(allocator: Allocator, fields: []const rowmod.Field) !Row {
+    var r = Row.init(allocator);
+    for (fields) |f| try r.set(f.name, f.value);
+    return r;
+}
+
+fn threeRowsOnePartition(allocator: Allocator) !std.ArrayList(Row) {
+    var rows = std.ArrayList(Row).init(allocator);
+    errdefer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { team: []const u8, score: i64 }{
+        .{ .team = "a", .score = 30 },
+        .{ .team = "a", .score = 10 },
+        .{ .team = "a", .score = 20 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "team", .value = .{ .text = d.team } },
+            .{ .name = "score", .value = .{ .int = d.score } },
+        }));
+    }
+    return rows;
+}
+
+test "row_number assigns 1..n within a single implicit partition, ordered" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    const results = try compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .row_number }, .rows);
+    defer freeResults(allocator, results);
+
+    // Input order: score 30, 10, 20 -> ascending rank order is row1=10
+    // (input index 1), row2=20 (index 2), row3=30 (index 0). Results stay
+    // aligned to INPUT row order, not the sorted walk order.
+    try std.testing.expectEqual(@as(i64, 3), results[0].int); // score 30 -> 3rd
+    try std.testing.expectEqual(@as(i64, 1), results[1].int); // score 10 -> 1st
+    try std.testing.expectEqual(@as(i64, 2), results[2].int); // score 20 -> 2nd
+}
+
+test "row_number restarts at 1 per partition" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { city: []const u8, score: i64 }{
+        .{ .city = "warsaw", .score = 5 },
+        .{ .city = "krakow", .score = 9 },
+        .{ .city = "warsaw", .score = 1 },
+        .{ .city = "krakow", .score = 2 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "score", .value = .{ .int = d.score } },
+        }));
+    }
+
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    const results = try compute(allocator, rows.items, &partition, &order, .{ .field = "", .kind = .row_number }, .rows);
+    defer freeResults(allocator, results);
+
+    // warsaw: score 5 (idx0), score 1 (idx2) -> sorted asc: idx2=1st, idx0=2nd.
+    try std.testing.expectEqual(@as(i64, 2), results[0].int);
+    try std.testing.expectEqual(@as(i64, 1), results[2].int);
+    // krakow: score 9 (idx1), score 2 (idx3) -> sorted asc: idx3=1st, idx1=2nd.
+    try std.testing.expectEqual(@as(i64, 2), results[1].int);
+    try std.testing.expectEqual(@as(i64, 1), results[3].int);
+}
+
+test "rank skips over ties, dense_rank does not" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // Scores: 10, 10, 20, 30, 30, 30 (already in ascending order so the
+    // sort is a no-op tie-preserving identity, keeping the expected
+    // positions easy to reason about).
+    const scores = [_]i64{ 10, 10, 20, 30, 30, 30 };
+    for (scores) |s| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "score", .value = .{ .int = s } },
+        }));
+    }
+
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+
+    const ranks = try compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .rank }, .rows);
+    defer freeResults(allocator, ranks);
+    const expectedRank = [_]i64{ 1, 1, 3, 4, 4, 4 };
+    for (expectedRank, 0..) |want, i| try std.testing.expectEqual(want, ranks[i].int);
+
+    const dense = try compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .dense_rank }, .rows);
+    defer freeResults(allocator, dense);
+    const expectedDense = [_]i64{ 1, 1, 2, 3, 3, 3 };
+    for (expectedDense, 0..) |want, i| try std.testing.expectEqual(want, dense[i].int);
+}
+
+test "rank and dense_rank without ORDER BY: whole partition ties, every row is 1" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+
+    const ranks = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .rank }, .rows);
+    defer freeResults(allocator, ranks);
+    for (ranks) |r| try std.testing.expectEqual(@as(i64, 1), r.int);
+
+    const dense = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .dense_rank }, .rows);
+    defer freeResults(allocator, dense);
+    for (dense) |r| try std.testing.expectEqual(@as(i64, 1), r.int);
+
+    // row_number still needs no ORDER BY - just first-seen position.
+    const nums = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .row_number }, .rows);
+    defer freeResults(allocator, nums);
+    try std.testing.expectEqual(@as(i64, 1), nums[0].int);
+    try std.testing.expectEqual(@as(i64, 2), nums[1].int);
+    try std.testing.expectEqual(@as(i64, 3), nums[2].int);
+}
+
+test "running sum walks cumulatively in ORDER BY order, per partition" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // warsaw, in input order: 100, 250 (already ascending by "day").
+    // krakow: 40.
+    const data = [_]struct { city: []const u8, day: i64, amount: i64 }{
+        .{ .city = "warsaw", .day = 1, .amount = 100 },
+        .{ .city = "krakow", .day = 1, .amount = 40 },
+        .{ .city = "warsaw", .day = 2, .amount = 250 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+    const results = try compute(allocator, rows.items, &partition, &order, .{ .field = "amount", .kind = .sum }, .rows);
+    defer freeResults(allocator, results);
+
+    try std.testing.expectEqual(@as(i64, 100), results[0].int); // warsaw day1: running=100
+    try std.testing.expectEqual(@as(i64, 40), results[1].int); // krakow day1: running=40
+    try std.testing.expectEqual(@as(i64, 350), results[2].int); // warsaw day2: running=100+250
+}
+
+test "RANGE frame: rows tied on ORDER BY share the tie group's combined total, ROWS gives each its own" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // One partition, ordered by "day": two rows tied at day=1 (10, 20),
+    // then one row at day=2 (5).
+    const data = [_]struct { day: i64, amount: i64 }{
+        .{ .day = 1, .amount = 10 },
+        .{ .day = 1, .amount = 20 },
+        .{ .day = 2, .amount = 5 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+
+    const rowsResult = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .sum }, .rows);
+    defer freeResults(allocator, rowsResult);
+    // ROWS: each physical row gets its own running total, even tied ones.
+    try std.testing.expectEqual(@as(i64, 10), rowsResult[0].int);
+    try std.testing.expectEqual(@as(i64, 30), rowsResult[1].int);
+    try std.testing.expectEqual(@as(i64, 35), rowsResult[2].int);
+
+    const rangeResult = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .sum }, .range);
+    defer freeResults(allocator, rangeResult);
+    // RANGE: both day=1 rows share the GROUP's combined total (10+20=30),
+    // not their own individual position within the tie; day=2 then adds 5.
+    try std.testing.expectEqual(@as(i64, 30), rangeResult[0].int);
+    try std.testing.expectEqual(@as(i64, 30), rangeResult[1].int);
+    try std.testing.expectEqual(@as(i64, 35), rangeResult[2].int);
+}
+
+test "RANGE frame on count/avg/min/max matches the same tie-group grouping as sum" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { day: i64, amount: i64 }{
+        .{ .day = 1, .amount = 30 },
+        .{ .day = 1, .amount = 10 },
+        .{ .day = 2, .amount = 20 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+
+    const counts = try compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .count }, .range);
+    defer freeResults(allocator, counts);
+    try std.testing.expectEqual(@as(i64, 2), counts[0].int);
+    try std.testing.expectEqual(@as(i64, 2), counts[1].int);
+    try std.testing.expectEqual(@as(i64, 3), counts[2].int);
+
+    const mins = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .min }, .range);
+    defer freeResults(allocator, mins);
+    try std.testing.expectEqual(@as(i64, 10), mins[0].int);
+    try std.testing.expectEqual(@as(i64, 10), mins[1].int);
+    try std.testing.expectEqual(@as(i64, 10), mins[2].int);
+
+    const maxs = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .max }, .range);
+    defer freeResults(allocator, maxs);
+    try std.testing.expectEqual(@as(i64, 30), maxs[0].int);
+    try std.testing.expectEqual(@as(i64, 30), maxs[1].int);
+    try std.testing.expectEqual(@as(i64, 30), maxs[2].int);
+
+    const avgs = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .avg }, .range);
+    defer freeResults(allocator, avgs);
+    try std.testing.expectApproxEqAbs(@as(f64, 20), avgs[0].float, 0.0001);
+    try std.testing.expectApproxEqAbs(@as(f64, 20), avgs[1].float, 0.0001);
+    try std.testing.expectApproxEqAbs(@as(f64, 20), avgs[2].float, 0.0001);
+}
+
+test "RANGE with no ties reduces to the same result as ROWS" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]i64{ 3, 1, 4 };
+    for (data) |amount| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "amount", .value = .{ .int = amount } }}));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "amount" }};
+
+    const rowsResult = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .sum }, .rows);
+    defer freeResults(allocator, rowsResult);
+    const rangeResult = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .sum }, .range);
+    defer freeResults(allocator, rangeResult);
+    for (rowsResult, rangeResult) |r, g| try std.testing.expectEqual(r.int, g.int);
+}
+
+test "RANGE with every row tied gives everyone the whole-partition total, like no ORDER BY at all" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator); // scores 30, 10, 20, all same "team"
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "team" }}; // every row ties on "team"
+
+    const results = try compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .sum }, .range);
+    defer freeResults(allocator, results);
+    for (results) |r| try std.testing.expectEqual(@as(i64, 60), r.int);
+}
+
+test "frame is rejected outright for the ranking family, never silently ignored" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    try std.testing.expectError(error.RangeNotApplicable, compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .row_number }, .range));
+    try std.testing.expectError(error.RangeNotApplicable, compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .rank }, .range));
+    try std.testing.expectError(error.RangeNotApplicable, compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .dense_rank }, .range));
+}
+
+test "compute propagates OutOfMemory without leaking, mid-way through a RANGE tie group" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "mango", "apple" };
+    for (names) |n| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "name", .value = .{ .text = n } }}));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "name" }};
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 4 });
+    try std.testing.expectError(error.OutOfMemory, compute(failing.allocator(), rows.items, &.{}, &order, .{ .field = "name", .kind = .min }, .range));
+}
+
+test "sum without ORDER BY gives every row the whole-partition total" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // scores 30, 10, 20 -> total 60, same value for every row.
+    const results = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .sum }, .rows);
+    defer freeResults(allocator, results);
+    for (results) |r| try std.testing.expectEqual(@as(i64, 60), r.int);
+}
+
+test "avg running and count star running" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const scores = [_]i64{ 10, 20, 30 };
+    for (scores) |s| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "score", .value = .{ .int = s } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+
+    const avgs = try compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .avg }, .rows);
+    defer freeResults(allocator, avgs);
+    try std.testing.expectApproxEqAbs(@as(f64, 10), avgs[0].float, 1e-9);
+    try std.testing.expectApproxEqAbs(@as(f64, 15), avgs[1].float, 1e-9);
+    try std.testing.expectApproxEqAbs(@as(f64, 20), avgs[2].float, 1e-9);
+
+    const counts = try compute(allocator, rows.items, &.{}, &order, .{ .field = "", .kind = .count }, .rows);
+    defer freeResults(allocator, counts);
+    try std.testing.expectEqual(@as(i64, 1), counts[0].int);
+    try std.testing.expectEqual(@as(i64, 2), counts[1].int);
+    try std.testing.expectEqual(@as(i64, 3), counts[2].int);
+}
+
+test "count_distinct runs cumulatively per partition, repeats do not grow it" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // warsaw, in "day" order: tag a, tag b, tag a (repeat) -> distinct count
+    // grows 1, 2, 2 (the third row's "a" was already seen).
+    // krakow: tag c -> distinct count 1.
+    const data = [_]struct { city: []const u8, day: i64, tag: []const u8 }{
+        .{ .city = "warsaw", .day = 1, .tag = "a" },
+        .{ .city = "krakow", .day = 1, .tag = "c" },
+        .{ .city = "warsaw", .day = 2, .tag = "b" },
+        .{ .city = "warsaw", .day = 3, .tag = "a" },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "tag", .value = .{ .text = d.tag } },
+        }));
+    }
+
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+    const results = try compute(allocator, rows.items, &partition, &order, .{ .field = "tag", .kind = .count_distinct }, .rows);
+    defer freeResults(allocator, results);
+
+    try std.testing.expectEqual(@as(i64, 1), results[0].int); // warsaw day1: {a}
+    try std.testing.expectEqual(@as(i64, 1), results[1].int); // krakow day1: {c}
+    try std.testing.expectEqual(@as(i64, 2), results[2].int); // warsaw day2: {a,b}
+    try std.testing.expectEqual(@as(i64, 2), results[3].int); // warsaw day3: {a,b} again, "a" repeats
+}
+
+test "count_distinct without ORDER BY gives every row the whole-partition distinct total" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const tags = [_][]const u8{ "x", "y", "x", "z" };
+    for (tags) |t| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "tag", .value = .{ .text = t } }}));
+    }
+    const results = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "tag", .kind = .count_distinct }, .rows);
+    defer freeResults(allocator, results);
+    for (results) |r| try std.testing.expectEqual(@as(i64, 3), r.int); // {x,y,z}
+}
+
+test "count_distinct RANGE frame: a tied group's members share one snapshot after the WHOLE group is observed" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // Tied at day=1: tags "a","b" (2 distinct together, not counted one at a
+    // time within the tie like ROWS would). Then day=2 adds "a" again (no
+    // growth) then "c" (grows to 3).
+    const data = [_]struct { day: i64, tag: []const u8 }{
+        .{ .day = 1, .tag = "a" },
+        .{ .day = 1, .tag = "b" },
+        .{ .day = 2, .tag = "a" },
+        .{ .day = 2, .tag = "c" },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "tag", .value = .{ .text = d.tag } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+
+    const rowsResult = try compute(allocator, rows.items, &.{}, &order, .{ .field = "tag", .kind = .count_distinct }, .rows);
+    defer freeResults(allocator, rowsResult);
+    // ROWS: each physical row gets its own running distinct count.
+    try std.testing.expectEqual(@as(i64, 1), rowsResult[0].int); // {a}
+    try std.testing.expectEqual(@as(i64, 2), rowsResult[1].int); // {a,b}
+    try std.testing.expectEqual(@as(i64, 2), rowsResult[2].int); // {a,b}, "a" repeats
+    try std.testing.expectEqual(@as(i64, 3), rowsResult[3].int); // {a,b,c}
+
+    const rangeResult = try compute(allocator, rows.items, &.{}, &order, .{ .field = "tag", .kind = .count_distinct }, .range);
+    defer freeResults(allocator, rangeResult);
+    // RANGE: both day=1 rows share the GROUP's combined distinct count (2),
+    // not their own individual position within the tie; day=2 group adds
+    // "c" (a repeats), landing on 3 for both its members.
+    try std.testing.expectEqual(@as(i64, 2), rangeResult[0].int);
+    try std.testing.expectEqual(@as(i64, 2), rangeResult[1].int);
+    try std.testing.expectEqual(@as(i64, 3), rangeResult[2].int);
+    try std.testing.expectEqual(@as(i64, 3), rangeResult[3].int);
+}
+
+test "count_distinct requires a field like sum/avg/min/max, unlike plain count" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .count_distinct }, .rows));
+}
+
+test "count_distinct ignores rows missing the field entirely, never counts none as a value" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{.{ .name = "other", .value = .{ .int = 1 } }})); // missing "tag"
+    try rows.append(try makeRow(allocator, &.{.{ .name = "tag", .value = .{ .text = "a" } }}));
+    const results = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "tag", .kind = .count_distinct }, .rows);
+    defer freeResults(allocator, results);
+    for (results) |r| try std.testing.expectEqual(@as(i64, 1), r.int); // only "a" ever counted
+}
+
+test "count_distinct propagates OutOfMemory without leaking already-tracked distinct keys" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const tags = [_][]const u8{ "mango", "apple", "kiwi" };
+    for (tags) |t| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "tag", .value = .{ .text = t } }}));
+    }
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 6 });
+    try std.testing.expectError(error.OutOfMemory, compute(failing.allocator(), rows.items, &.{}, &.{}, .{ .field = "tag", .kind = .count_distinct }, .rows));
+}
+
+test "count_distinct alongside lag/lead/first_value/running sum/ranking in one computeMany call" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { day: i64, tag: []const u8, amount: i64 }{
+        .{ .day = 1, .tag = "a", .amount = 10 },
+        .{ .day = 2, .tag = "b", .amount = 20 },
+        .{ .day = 3, .tag = "a", .amount = 30 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "tag", .value = .{ .text = d.tag } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+    const specs = [_]WindowSpec{
+        .{ .field = "tag", .kind = .count_distinct },
+        .{ .field = "amount", .kind = .lag },
+        .{ .field = "amount", .kind = .sum },
+        .{ .field = "", .kind = .row_number },
+    };
+    const results = try computeMany(allocator, rows.items, &.{}, &order, &specs, .rows);
+    defer freeManyResults(allocator, results);
+
+    try std.testing.expectEqual(@as(i64, 1), results[0][0].int); // count_distinct {a}
+    try std.testing.expectEqual(Value{ .none = {} }, results[0][1]); // lag: no predecessor
+    try std.testing.expectEqual(@as(i64, 10), results[0][2].int); // running sum
+    try std.testing.expectEqual(@as(i64, 1), results[0][3].int); // row_number
+
+    try std.testing.expectEqual(@as(i64, 2), results[1][0].int); // {a,b}
+    try std.testing.expectEqual(@as(i64, 10), results[1][1].int); // lag -> day1's amount
+    try std.testing.expectEqual(@as(i64, 30), results[1][2].int);
+    try std.testing.expectEqual(@as(i64, 2), results[1][3].int);
+
+    try std.testing.expectEqual(@as(i64, 2), results[2][0].int); // {a,b}, "a" repeats
+    try std.testing.expectEqual(@as(i64, 20), results[2][1].int); // lag -> day2's amount
+    try std.testing.expectEqual(@as(i64, 60), results[2][2].int);
+    try std.testing.expectEqual(@as(i64, 3), results[2][3].int);
+}
+
+test "running min and max over a text field, independently duped per row" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi" };
+    for (names, 0..) |n, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+
+    const mins = try compute(allocator, rows.items, &.{}, &order, .{ .field = "name", .kind = .min }, .rows);
+    defer freeResults(allocator, mins);
+    try std.testing.expectEqualStrings("mango", mins[0].text);
+    try std.testing.expectEqualStrings("apple", mins[1].text);
+    try std.testing.expectEqualStrings("apple", mins[2].text);
+
+    const maxs = try compute(allocator, rows.items, &.{}, &order, .{ .field = "name", .kind = .max }, .rows);
+    defer freeResults(allocator, maxs);
+    try std.testing.expectEqualStrings("mango", maxs[0].text);
+    try std.testing.expectEqualStrings("mango", maxs[1].text);
+    try std.testing.expectEqualStrings("mango", maxs[2].text);
+}
+
+test "sum/avg/min/max require a field, ranking family and COUNT(*) do not" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .sum }, .rows));
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .avg }, .rows));
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .min }, .rows));
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .max }, .rows));
+
+    const stars = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .count }, .rows);
+    defer freeResults(allocator, stars);
+    const nums = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .row_number }, .rows);
+    defer freeResults(allocator, nums);
+}
+
+test "sum on a non-numeric field is NonNumericField, integer overflow is Overflow" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{.{ .name = "x", .value = .{ .text = "nope" } }}));
+    try std.testing.expectError(error.NonNumericField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "x", .kind = .sum }, .rows));
+
+    var overflowRows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (overflowRows.items) |*r| r.deinit();
+        overflowRows.deinit();
+    }
+    try overflowRows.append(try makeRow(allocator, &.{.{ .name = "x", .value = .{ .int = std.math.maxInt(i64) } }}));
+    try overflowRows.append(try makeRow(allocator, &.{.{ .name = "x", .value = .{ .int = 1 } }}));
+    try std.testing.expectError(error.Overflow, compute(allocator, overflowRows.items, &.{}, &.{}, .{ .field = "x", .kind = .sum }, .rows));
+}
+
+test "compute on zero rows returns an empty result, no crash" {
+    const allocator = std.testing.allocator;
+    const rows = [_]Row{};
+    const results = try compute(allocator, &rows, &.{}, &.{}, .{ .field = "", .kind = .row_number }, .rows);
+    defer freeResults(allocator, results);
+    try std.testing.expectEqual(@as(usize, 0), results.len);
+}
+
+test "specLabel matches aggregate.zig's kind_field / bare-kind convention" {
+    const allocator = std.testing.allocator;
+    const bare = try specLabel(allocator, .{ .field = "", .kind = .row_number });
+    defer allocator.free(bare);
+    try std.testing.expectEqualStrings("row_number", bare);
+
+    const withField = try specLabel(allocator, .{ .field = "score", .kind = .sum });
+    defer allocator.free(withField);
+    try std.testing.expectEqualStrings("sum_score", withField);
+}
+
+test "compute propagates OutOfMemory without leaking, at an early allocation" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 0 });
+    try std.testing.expectError(error.OutOfMemory, compute(failing.allocator(), rows.items, &.{}, &.{}, .{ .field = "score", .kind = .sum }, .rows));
+}
+
+test "compute propagates OutOfMemory without leaking, mid-way through partitioned min/max" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi", "banana", "fig" };
+    for (names) |n| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "name", .value = .{ .text = n } }}));
+    }
+
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 4 });
+    try std.testing.expectError(error.OutOfMemory, compute(failing.allocator(), rows.items, &.{}, &.{}, .{ .field = "name", .kind = .min }, .rows));
+}
+
+test "orderedIndices flattens partitions in first-seen order, each sorted by orderBy" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // First-seen partition order: warsaw, krakow. Within each, sort by
+    // score ascending should reorder relative to input.
+    const data = [_]struct { city: []const u8, score: i64 }{
+        .{ .city = "warsaw", .score = 5 },
+        .{ .city = "krakow", .score = 9 },
+        .{ .city = "warsaw", .score = 1 },
+        .{ .city = "krakow", .score = 2 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "score", .value = .{ .int = d.score } },
+        }));
+    }
+
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    const idx = try orderedIndices(allocator, rows.items, &partition, &order);
+    defer allocator.free(idx);
+
+    // warsaw (first-seen) sorted asc: idx2 (score1), idx0 (score5) - then
+    // krakow sorted asc: idx3 (score2), idx1 (score9).
+    try std.testing.expectEqualSlices(usize, &.{ 2, 0, 3, 1 }, idx);
+}
+
+test "orderedIndices on zero rows returns an empty slice" {
+    const allocator = std.testing.allocator;
+    const rows = [_]Row{};
+    const idx = try orderedIndices(allocator, &rows, &.{}, &.{});
+    defer allocator.free(idx);
+    try std.testing.expectEqual(@as(usize, 0), idx.len);
+}
+
+test "orderedIndices propagates OutOfMemory without leaking" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 0 });
+    try std.testing.expectError(error.OutOfMemory, orderedIndices(failing.allocator(), rows.items, &.{}, &.{}));
+}
+
+test "computeMany matches calling compute() once per spec, sharing one partition/order/frame" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { city: []const u8, amount: i64 }{
+        .{ .city = "warsaw", .amount = 10 },
+        .{ .city = "krakow", .amount = 9 },
+        .{ .city = "warsaw", .amount = 20 },
+        .{ .city = "krakow", .amount = 2 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "amount" }};
+    const specs = [_]WindowSpec{
+        .{ .field = "amount", .kind = .sum },
+        .{ .field = "amount", .kind = .avg },
+        .{ .field = "", .kind = .row_number },
+    };
+
+    const many = try computeMany(allocator, rows.items, &partition, &order, &specs, .rows);
+    defer freeManyResults(allocator, many);
+
+    for (specs, 0..) |spec, specIdx| {
+        const solo = try compute(allocator, rows.items, &partition, &order, spec, .rows);
+        defer freeResults(allocator, solo);
+        for (rows.items, 0..) |_, rowIdx| {
+            try std.testing.expect(rowmod.compare(many[rowIdx][specIdx], solo[rowIdx]) == .eq);
+        }
+    }
+}
+
+test "computeMany keeps min/max text results independently owned per row and per spec" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi" };
+    for (names) |n| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "name", .value = .{ .text = n } }}));
+    }
+
+    const specs = [_]WindowSpec{
+        .{ .field = "name", .kind = .min },
+        .{ .field = "name", .kind = .max },
+    };
+    const results = try computeMany(allocator, rows.items, &.{}, &.{}, &specs, .rows);
+    defer freeManyResults(allocator, results);
+
+    for (results) |row| {
+        try std.testing.expectEqualStrings("apple", row[0].text);
+        try std.testing.expectEqualStrings("mango", row[1].text);
+    }
+    // Every row's `min` slice is its own allocation, not a shared pointer -
+    // `freeManyResults` frees each independently, which the testing
+    // allocator would already reject as a double free if they aliased.
+    try std.testing.expect(results[0][0].text.ptr != results[1][0].text.ptr);
+}
+
+test "computeMany with zero specs returns one empty values slice per row, no crash" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const results = try computeMany(allocator, rows.items, &.{}, &.{}, &.{}, .rows);
+    defer freeManyResults(allocator, results);
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    for (results) |row| try std.testing.expectEqual(@as(usize, 0), row.len);
+}
+
+test "computeMany propagates OutOfMemory without leaking, at an early allocation" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const specs = [_]WindowSpec{
+        .{ .field = "score", .kind = .sum },
+        .{ .field = "", .kind = .row_number },
+    };
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 0 });
+    try std.testing.expectError(error.OutOfMemory, computeMany(failing.allocator(), rows.items, &.{}, &.{}, &specs, .rows));
+}
+
+test "computeMany propagates OutOfMemory without leaking, mid-way through the row-major transpose" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const specs = [_]WindowSpec{
+        .{ .field = "score", .kind = .sum },
+        .{ .field = "team", .kind = .min },
+    };
+    // Large enough to run past both columns' own computation (sum has no
+    // extra allocations per row; min dupes a `Value` per row observed) and
+    // into the per-row `rowValues`/`dupe` allocations the transpose loop
+    // itself makes - proven by the assertion below, not by counting by hand.
+    var failIndex: usize = 0;
+    while (failIndex < 40) : (failIndex += 1) {
+        var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = failIndex });
+        const result = computeMany(failing.allocator(), rows.items, &.{}, &.{}, &specs, .rows);
+        if (result) |ok| {
+            freeManyResults(allocator, ok);
+            break;
+        } else |err| {
+            try std.testing.expectEqual(error.OutOfMemory, err);
+        }
+    } else return error.TestUnexpectedResult;
+}
+
+test "lag/lead default offset of 1: NULL (default) at the edge, adjacent value otherwise" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { day: i64, amount: i64 }{
+        .{ .day = 1, .amount = 10 },
+        .{ .day = 2, .amount = 20 },
+        .{ .day = 3, .amount = 30 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+
+    const lag = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .lag }, .rows);
+    defer freeResults(allocator, lag);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, lag[0]));
+    try std.testing.expectEqual(@as(i64, 10), lag[1].int);
+    try std.testing.expectEqual(@as(i64, 20), lag[2].int);
+
+    const lead = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .lead }, .rows);
+    defer freeResults(allocator, lead);
+    try std.testing.expectEqual(@as(i64, 20), lead[0].int);
+    try std.testing.expectEqual(@as(i64, 30), lead[1].int);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, lead[2]));
+}
+
+test "lag/lead with an explicit offset skips that many physical positions" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const amounts = [_]i64{ 10, 20, 30, 40 };
+    for (amounts, 0..) |a, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "amount", .value = .{ .int = a } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+
+    const lag2 = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .lag, .offset = 2 }, .rows);
+    defer freeResults(allocator, lag2);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, lag2[0]));
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, lag2[1]));
+    try std.testing.expectEqual(@as(i64, 10), lag2[2].int);
+    try std.testing.expectEqual(@as(i64, 20), lag2[3].int);
+
+    // offset 0 reads the current row itself.
+    const lagZero = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .lag, .offset = 0 }, .rows);
+    defer freeResults(allocator, lagZero);
+    for (amounts, 0..) |a, i| try std.testing.expectEqual(a, lagZero[i].int);
+}
+
+test "lag/lead use a caller-supplied default instead of NULL at the edge" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "seq", .value = .{ .int = 0 } },
+        .{ .name = "amount", .value = .{ .int = 5 } },
+    }));
+    try rows.append(try makeRow(allocator, &.{
+        .{ .name = "seq", .value = .{ .int = 1 } },
+        .{ .name = "amount", .value = .{ .int = 6 } },
+    }));
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+
+    const lag = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .lag, .default = .{ .int = -1 } }, .rows);
+    defer freeResults(allocator, lag);
+    try std.testing.expectEqual(@as(i64, -1), lag[0].int);
+    try std.testing.expectEqual(@as(i64, 5), lag[1].int);
+}
+
+test "lag/lead restart per partition and treat orderBy ties as distinct physical positions" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // Two rows tied on "day" within "warsaw" - lag/lead must still treat
+    // them as two distinct positions (unlike the RANGE running-aggregate
+    // frame, which would collapse ties into one shared value).
+    const data = [_]struct { city: []const u8, day: i64, amount: i64 }{
+        .{ .city = "warsaw", .day = 1, .amount = 10 },
+        .{ .city = "warsaw", .day = 1, .amount = 20 },
+        .{ .city = "krakow", .day = 1, .amount = 99 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+
+    const lead = try compute(allocator, rows.items, &partition, &order, .{ .field = "amount", .kind = .lead }, .rows);
+    defer freeResults(allocator, lead);
+    // Stable sort keeps warsaw's two tied rows in first-seen order (10 then
+    // 20), so warsaw/10's lead is warsaw/20 (not krakow, a different
+    // partition entirely), and warsaw/20 (the partition's last row) is NULL.
+    try std.testing.expectEqual(@as(i64, 20), lead[0].int);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, lead[1]));
+    // krakow is its own partition of one row - always NULL.
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, lead[2]));
+}
+
+test "lag/lead without ORDER BY walk first-seen input order" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator); // scores 30, 10, 20, first-seen order
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const lag = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .lag }, .rows);
+    defer freeResults(allocator, lag);
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, lag[0]));
+    try std.testing.expectEqual(@as(i64, 30), lag[1].int);
+    try std.testing.expectEqual(@as(i64, 10), lag[2].int);
+}
+
+test "lag/lead on a text field dupes independently per row, no shared pointers" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi" };
+    for (names, 0..) |n, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    const lag = try compute(allocator, rows.items, &.{}, &order, .{ .field = "name", .kind = .lag }, .rows);
+    defer freeResults(allocator, lag);
+    try std.testing.expectEqualStrings("mango", lag[1].text);
+    try std.testing.expectEqualStrings("apple", lag[2].text);
+    try std.testing.expect(lag[1].text.ptr != names[0].ptr);
+}
+
+test "lag/lead require a field, like sum/avg/min/max" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .lag }, .rows));
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .lead }, .rows));
+}
+
+test "lag/lead reject a RANGE frame outright, like the ranking family" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    try std.testing.expectError(error.RangeNotApplicable, compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .lag }, .range));
+    try std.testing.expectError(error.RangeNotApplicable, compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .lead }, .range));
+}
+
+test "lag/lead propagate OutOfMemory without leaking" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi", "banana" };
+    for (names, 0..) |n, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 4 });
+    try std.testing.expectError(error.OutOfMemory, compute(failing.allocator(), rows.items, &.{}, &order, .{ .field = "name", .kind = .lag }, .rows));
+}
+
+test "first_value/last_value without ORDER BY: whole-partition frame, constant per partition" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator); // scores 30, 10, 20, first-seen order
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const first = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .first_value }, .rows);
+    defer freeResults(allocator, first);
+    for (first) |v| try std.testing.expectEqual(@as(i64, 30), v.int); // first-seen row's score
+
+    const last = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .last_value }, .rows);
+    defer freeResults(allocator, last);
+    for (last) |v| try std.testing.expectEqual(@as(i64, 20), v.int); // last-seen row's score
+}
+
+test "first_value/last_value ROWS frame: first stays the partition's first row, last degenerates to the current row" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const scores = [_]i64{ 30, 10, 20 };
+    for (scores) |s| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "score", .value = .{ .int = s } }}));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    // Sorted ascending walk order: 10 (idx1), 20 (idx2), 30 (idx0).
+
+    const first = try compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .first_value }, .rows);
+    defer freeResults(allocator, first);
+    for (first) |v| try std.testing.expectEqual(@as(i64, 10), v.int); // ROWS frame start is always the sorted partition's first row
+
+    const last = try compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .last_value }, .rows);
+    defer freeResults(allocator, last);
+    // ROWS frame end is CURRENT ROW - last_value degenerates to the row's own field.
+    try std.testing.expectEqual(@as(i64, 30), last[0].int);
+    try std.testing.expectEqual(@as(i64, 10), last[1].int);
+    try std.testing.expectEqual(@as(i64, 20), last[2].int);
+}
+
+test "first_value/last_value RANGE frame: last_value shares the current tie group's last member" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // One partition, ordered by "day": two rows tied at day=1 (10, 20), then one row at day=2 (5).
+    const data = [_]struct { day: i64, amount: i64 }{
+        .{ .day = 1, .amount = 10 },
+        .{ .day = 1, .amount = 20 },
+        .{ .day = 2, .amount = 5 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+
+    const first = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .first_value }, .range);
+    defer freeResults(allocator, first);
+    for (first) |v| try std.testing.expectEqual(@as(i64, 10), v.int); // frame start unaffected by RANGE vs ROWS
+
+    const last = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .last_value }, .range);
+    defer freeResults(allocator, last);
+    // Both day=1 rows share their tie group's LAST member (20), day=2 is its own group (5).
+    try std.testing.expectEqual(@as(i64, 20), last[0].int);
+    try std.testing.expectEqual(@as(i64, 20), last[1].int);
+    try std.testing.expectEqual(@as(i64, 5), last[2].int);
+}
+
+test "first_value/last_value restart per partition, RANGE tie group stays within one city" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    // Both rows of EACH city tie on "day" - RANGE must group them separately
+    // per partition, never merging warsaw's tie group with krakow's.
+    const data = [_]struct { city: []const u8, day: i64, amount: i64 }{
+        .{ .city = "warsaw", .day = 1, .amount = 100 },
+        .{ .city = "warsaw", .day = 1, .amount = 250 },
+        .{ .city = "krakow", .day = 1, .amount = 40 },
+        .{ .city = "krakow", .day = 1, .amount = 90 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+
+    const last = try compute(allocator, rows.items, &partition, &order, .{ .field = "amount", .kind = .last_value }, .range);
+    defer freeResults(allocator, last);
+    try std.testing.expectEqual(@as(i64, 250), last[0].int); // warsaw's tie group's last member (250)
+    try std.testing.expectEqual(@as(i64, 250), last[1].int);
+    try std.testing.expectEqual(@as(i64, 90), last[2].int); // krakow's OWN tie group's last member (90), not warsaw's
+    try std.testing.expectEqual(@as(i64, 90), last[3].int);
+}
+
+test "first_value/last_value on a text field dupes independently per row, no shared pointers" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi" };
+    for (names, 0..) |n, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    const first = try compute(allocator, rows.items, &.{}, &order, .{ .field = "name", .kind = .first_value }, .rows);
+    defer freeResults(allocator, first);
+    try std.testing.expectEqualStrings("mango", first[0].text);
+    try std.testing.expectEqualStrings("mango", first[2].text);
+    try std.testing.expect(first[2].text.ptr != names[0].ptr);
+}
+
+test "first_value/last_value require a field, like sum/avg/min/max" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .first_value }, .rows));
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .last_value }, .rows));
+}
+
+test "first_value/last_value accept a RANGE frame, unlike lag/lead" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    const first = try compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .first_value }, .range);
+    defer freeResults(allocator, first);
+    for (first) |v| try std.testing.expectEqual(@as(i64, 10), v.int);
+}
+
+test "first_value/last_value propagate OutOfMemory without leaking" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi", "banana" };
+    for (names, 0..) |n, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 4 });
+    try std.testing.expectError(error.OutOfMemory, compute(failing.allocator(), rows.items, &.{}, &order, .{ .field = "name", .kind = .last_value }, .rows));
+}
+
+test "first_value/last_value on zero rows in a partition does not crash (empty indices guard)" {
+    const allocator = std.testing.allocator;
+    const rows = [_]Row{};
+    const results = try compute(allocator, &rows, &.{}, &.{}, .{ .field = "x", .kind = .first_value }, .rows);
+    defer freeResults(allocator, results);
+    try std.testing.expectEqual(@as(usize, 0), results.len);
+}
+
+test "nth_value without ORDER BY: whole-partition frame, n counts from the first-seen row" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator); // scores 30, 10, 20, first-seen order
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const n1 = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .nth_value, .offset = 1 }, .rows);
+    defer freeResults(allocator, n1);
+    for (n1) |v| try std.testing.expectEqual(@as(i64, 30), v.int); // same as first_value
+
+    const n3 = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .nth_value, .offset = 3 }, .rows);
+    defer freeResults(allocator, n3);
+    for (n3) |v| try std.testing.expectEqual(@as(i64, 20), v.int); // same as last_value (partition has 3 rows)
+
+    // Past the whole-partition frame's end -> spec.default (SQL NULL unless set).
+    const n4 = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .nth_value, .offset = 4 }, .rows);
+    defer freeResults(allocator, n4);
+    for (n4) |v| try std.testing.expectEqual(Value{ .none = {} }, v);
+}
+
+test "nth_value ROWS frame: position visible only once the frame has grown to include it" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const scores = [_]i64{ 30, 10, 20 };
+    for (scores) |s| {
+        try rows.append(try makeRow(allocator, &.{.{ .name = "score", .value = .{ .int = s } }}));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    // Sorted ascending walk order: 10 (idx1, pos0), 20 (idx2, pos1), 30 (idx0, pos2).
+    // `results` stays aligned with the ORIGINAL insertion order [30, 10, 20], not
+    // the sorted walk order - same convention `first_value`/`last_value`'s ROWS
+    // test above uses.
+    const results = try compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .nth_value, .offset = 2 }, .rows);
+    defer freeResults(allocator, results);
+    // idx1 (score 10, pos0): frame is just itself (size 1) - position 2 does not
+    // exist yet -> default.
+    try std.testing.expectEqual(Value{ .none = {} }, results[1]);
+    // idx2 (score 20, pos1): frame now covers pos0-1 (size 2) - position 2 is
+    // this row's own value, 20.
+    try std.testing.expectEqual(@as(i64, 20), results[2].int);
+    // idx0 (score 30, pos2): frame covers pos0-2 (size 3) - position 2 is still
+    // idx2's value, 20 (the frame grew, but the row AT position 2 did not change).
+    try std.testing.expectEqual(@as(i64, 20), results[0].int);
+}
+
+test "nth_value RANGE frame: position resolved against the current tie group's growing frame" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { day: i64, amount: i64 }{
+        .{ .day = 1, .amount = 10 },
+        .{ .day = 1, .amount = 20 },
+        .{ .day = 2, .amount = 5 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+    // RANGE's frame is CUMULATIVE (UNBOUNDED PRECEDING through the current tie
+    // group, same as the running-aggregate family), not limited to the current
+    // group alone - position 3 only becomes reachable once the frame has grown
+    // to include the day=2 group too.
+    const results = try compute(allocator, rows.items, &.{}, &order, .{ .field = "amount", .kind = .nth_value, .offset = 3 }, .range);
+    defer freeResults(allocator, results);
+    // day=1's tie group (2 members): frame size is still only 2 - position 3
+    // does not exist yet -> default for BOTH members.
+    try std.testing.expectEqual(Value{ .none = {} }, results[0]);
+    try std.testing.expectEqual(Value{ .none = {} }, results[1]);
+    // day=2's tie group: frame now covers all 3 rows - position 3 is this row's
+    // own value, 5.
+    try std.testing.expectEqual(@as(i64, 5), results[2].int);
+}
+
+test "nth_value uses a custom default instead of NULL when set" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const results = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .nth_value, .offset = 10, .default = .{ .int = -1 } }, .rows);
+    defer freeResults(allocator, results);
+    for (results) |v| try std.testing.expectEqual(@as(i64, -1), v.int);
+}
+
+test "nth_value with offset 0 never resolves (positions are 1-based)" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const results = try compute(allocator, rows.items, &.{}, &.{}, .{ .field = "score", .kind = .nth_value, .offset = 0 }, .rows);
+    defer freeResults(allocator, results);
+    for (results) |v| try std.testing.expectEqual(Value{ .none = {} }, v);
+}
+
+test "nth_value restart per partition, RANGE tie group stays within one city" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const data = [_]struct { city: []const u8, day: i64, amount: i64 }{
+        .{ .city = "warsaw", .day = 1, .amount = 100 },
+        .{ .city = "warsaw", .day = 1, .amount = 250 },
+        .{ .city = "krakow", .day = 1, .amount = 40 },
+        .{ .city = "krakow", .day = 1, .amount = 90 },
+    };
+    for (data) |d| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "city", .value = .{ .text = d.city } },
+            .{ .name = "day", .value = .{ .int = d.day } },
+            .{ .name = "amount", .value = .{ .int = d.amount } },
+        }));
+    }
+    const partition = [_][]const u8{"city"};
+    const order = [_]querymod.OrderBy{.{ .field = "day" }};
+    const results = try compute(allocator, rows.items, &partition, &order, .{ .field = "amount", .kind = .nth_value, .offset = 2 }, .range);
+    defer freeResults(allocator, results);
+    try std.testing.expectEqual(@as(i64, 250), results[0].int); // warsaw's 2nd member
+    try std.testing.expectEqual(@as(i64, 250), results[1].int);
+    try std.testing.expectEqual(@as(i64, 90), results[2].int); // krakow's OWN 2nd member, not warsaw's
+    try std.testing.expectEqual(@as(i64, 90), results[3].int);
+}
+
+test "nth_value on a text field dupes independently per row, no shared pointers" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi" };
+    for (names, 0..) |n, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    const results = try compute(allocator, rows.items, &.{}, &order, .{ .field = "name", .kind = .nth_value, .offset = 1 }, .rows);
+    defer freeResults(allocator, results);
+    try std.testing.expectEqualStrings("mango", results[0].text);
+    try std.testing.expectEqualStrings("mango", results[2].text);
+    try std.testing.expect(results[2].text.ptr != names[0].ptr);
+}
+
+test "nth_value requires a field, like first_value/last_value" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    try std.testing.expectError(error.MissingField, compute(allocator, rows.items, &.{}, &.{}, .{ .field = "", .kind = .nth_value, .offset = 1 }, .rows));
+}
+
+test "nth_value accepts a RANGE frame, unlike lag/lead" {
+    const allocator = std.testing.allocator;
+    var rows = try threeRowsOnePartition(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "score" }};
+    const results = try compute(allocator, rows.items, &.{}, &order, .{ .field = "score", .kind = .nth_value, .offset = 1 }, .range);
+    defer freeResults(allocator, results);
+    for (results) |v| try std.testing.expectEqual(@as(i64, 10), v.int);
+}
+
+test "nth_value propagates OutOfMemory without leaking" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const names = [_][]const u8{ "mango", "apple", "kiwi", "banana" };
+    for (names, 0..) |n, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "name", .value = .{ .text = n } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    var failing = std.testing.FailingAllocator.init(allocator, .{ .fail_index = 4 });
+    try std.testing.expectError(error.OutOfMemory, compute(failing.allocator(), rows.items, &.{}, &order, .{ .field = "name", .kind = .nth_value, .offset = 2 }, .rows));
+}
+
+test "nth_value on zero rows in a partition does not crash (empty indices guard)" {
+    const allocator = std.testing.allocator;
+    const rows = [_]Row{};
+    const results = try compute(allocator, &rows, &.{}, &.{}, .{ .field = "x", .kind = .nth_value, .offset = 1 }, .rows);
+    defer freeResults(allocator, results);
+    try std.testing.expectEqual(@as(usize, 0), results.len);
+}
+
+test "computeMany mixes nth_value with lag/lead/running aggregates/ranking under one shared window" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const amounts = [_]i64{ 10, 20, 30 };
+    for (amounts, 0..) |a, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "amount", .value = .{ .int = a } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    const specs = [_]WindowSpec{
+        .{ .field = "amount", .kind = .nth_value, .offset = 2 },
+        .{ .field = "amount", .kind = .lag },
+        .{ .field = "amount", .kind = .row_number },
+    };
+    const results = try computeMany(allocator, rows.items, &.{}, &order, &specs, .rows);
+    defer freeManyResults(allocator, results);
+    try std.testing.expectEqual(@as(usize, 3), results.len);
+    // nth_value(amount, 2): row 1's frame is too small (default None), rows 2-3 both see 20.
+    try std.testing.expectEqual(Value{ .none = {} }, results[0][0]);
+    try std.testing.expectEqual(@as(i64, 20), results[1][0].int);
+    try std.testing.expectEqual(@as(i64, 20), results[2][0].int);
+}
+
+test "computeMany mixes lag/lead with running aggregates and ranking under one shared window" {
+    const allocator = std.testing.allocator;
+    var rows = std.ArrayList(Row).init(allocator);
+    defer {
+        for (rows.items) |*r| r.deinit();
+        rows.deinit();
+    }
+    const amounts = [_]i64{ 10, 20, 30 };
+    for (amounts, 0..) |a, i| {
+        try rows.append(try makeRow(allocator, &.{
+            .{ .name = "seq", .value = .{ .int = @intCast(i) } },
+            .{ .name = "amount", .value = .{ .int = a } },
+        }));
+    }
+    const order = [_]querymod.OrderBy{.{ .field = "seq" }};
+    const specs = [_]WindowSpec{
+        .{ .field = "amount", .kind = .lag },
+        .{ .field = "amount", .kind = .lead },
+        .{ .field = "amount", .kind = .sum },
+        .{ .field = "", .kind = .row_number },
+    };
+    const many = try computeMany(allocator, rows.items, &.{}, &order, &specs, .rows);
+    defer freeManyResults(allocator, many);
+
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, many[0][0]));
+    try std.testing.expectEqual(@as(i64, 10), many[1][0].int); // lag
+    try std.testing.expectEqual(@as(i64, 20), many[0][1].int); // lead
+    try std.testing.expectEqual(rowmod.ValueTag.none, @as(rowmod.ValueTag, many[2][1]));
+    try std.testing.expectEqual(@as(i64, 60), many[2][2].int); // running sum, final row
+    try std.testing.expectEqual(@as(i64, 3), many[2][3].int); // row_number
+}