diff --git a/README.md b/README.md
index 0ce8d45..3e11df4 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,55 @@ The Undici HTTP agent was introduced in 4.0.0, and it is the default HTTP transp
 The standard HTTP/HTTPS modules of Node.js are still supported for backwards compatibility.
 Use the <i>stdlib_http</i> option to switch to the standard HTTP/HTTPS modules.
 
+## Transport support matrix
+
+| Protocol | Transport | Notes |
+|---|---|---|
+| `http` / `https` | HTTP | ILP, request/response |
+| `tcp` / `tcps` | TCP | ILP, persistent |
+| `ws` / `wss` | WebSocket | **QWP** — columnar binary, store-and-forward |
+
+### QWP caveats
+
+These properties of the WebSocket (QWP) sender differ from what the HTTP/ILP
+senders do, and each one can surprise a user who assumes otherwise:
+
+- `flush()` resolves once rows are **published** to the send log, not when the
+  server acknowledges them. This differs from `http::`.
+- Delivery is **at-least-once**. A retried batch can duplicate rows; use a
+  `DEDUP` table if you need idempotence.
+- Symbol columns are serialized in **delta mode**: a connection dictionary is
+  shared with the buffer and persisted to `<sf_dir>/.symbol-dict` in disk mode,
+  so only newly-introduced symbols ride each frame. Recovery re-seeds it
+  positionally, keeping ids dense from 0 — so **don't** assume symbol ids are
+  stable across senders or restarts.
+- An acknowledgement means server-side **commit**, not object-store durability.
+  Set `request_durable_ack=on` if durability gates downstream work — the client
+  then requests durable ACKs and **fails fast at connect** if the server cannot
+  confirm them (`X-QWP-Durable-Ack: enabled`).
+- `sf_dir` alone is **not** power-loss durability. The default
+  `sf_durability=memory` never fsyncs, so bytes survive a *process* crash but
+  not a power loss. `sf_durability=periodic` (requires `sf_dir`) runs a
+  background barrier every `sf_sync_interval_millis` that fsyncs the active
+  segment and the ack watermark, making bytes survive an OS/power crash up to
+  that cadence.
+- `drain_orphans` (off by default) replays slots left by a crashed process: on
+  startup, the client scans `<sf_dir>/` for slot directories not held by a live
+  lock and hands each to a background drainer (bounded by
+  `max_background_drainers`) that opens its own WebSocket, re-registers the
+  recovered symbol dictionary, and replays unacked frames to the server before
+  releasing the slot. A terminal failure drops a `.failed` sentinel so the slot
+  is retried only after an operator clears it; a transient outage is retried
+  indefinitely. Requires `sf_dir`.
+- In disk mode, recovery cross-checks the scanned segment chain against
+  `sf-manifest.bin`, a crash-safe boundary record (magic `SFM1`) written on
+  each segment rotation using the same alternating-generation scheme as the ack
+  watermark, and quarantines the slot when the manifest's recorded chain head is
+  ahead of what is actually on disk (a vanished tail segment = real data loss).
+- `tls_roots` accepts PEM or PKCS#12.
+- `tls_roots` accepts PEM or PKCS#12. **JKS keystores are not supported** by
+  Node; convert them first.
+
 ## Configuration options
 
 Detailed description of the client's configuration options can be found in
diff --git a/benchmarks/README.md b/benchmarks/README.md
new file mode 100644
index 0000000..bd9d0c8
--- /dev/null
+++ b/benchmarks/README.md
@@ -0,0 +1,107 @@
+# QWP benchmarks
+
+Ad hoc. No CI job, no gate. Run them when you want a number.
+
+```bash
+# Point this at REAL storage, not tmpfs — see "Am I measuring disk?" below.
+export QWP_BENCH_DIR=/var/tmp/qwp-bench
+
+pnpm bench                       # encoder, buffer, sf  (no server needed)
+pnpm bench:e2e                   # needs QuestDB on :9000
+QDB_ADDR=host:9000 pnpm bench:e2e
+
+pnpm typecheck:bench             # tsc over src + benchmarks
+pnpm lint:bench                  # eslint over benchmarks/
+```
+
+**If `pnpm <script>` fails before running anything**, that is this repo's
+ignored-builds check, not your benchmark. Every earlier QWP handoff hit it. Call
+the binary directly instead — the scripts above are still the canonical
+definitions, and they work wherever the gate is satisfied:
+
+```bash
+./node_modules/.bin/vitest bench --run benchmarks/          # pnpm bench
+./node_modules/.bin/tsx benchmarks/e2e.ts                   # pnpm bench:e2e
+./node_modules/.bin/tsc -p tsconfig.bench.json --noEmit     # pnpm typecheck:bench
+```
+
+## Reading the output
+
+**`hz` is callbacks per second, not rows per second.** Each encoder callback
+covers 10,000 rows, so rows/s is `hz × 10_000`. This is the easiest way to
+write down a number that is wrong by four orders of magnitude.
+
+**The disk arm spikes every tenth iteration, and that is real.** `APPENDS × 4 KiB
+= 400 KiB` per iteration against `segmentBytes: 4 << 20`, so a segment roll fires
+on roughly every 10th body. A roll closes the active fd, creates the next `.sfa`,
+writes its header, and rewrites the whole 8 KiB `sf-manifest.bin` (`persistManifest`
+in `sf/engine.ts`, added by the C2 work in handoff 8 — *after* this plan was first
+drafted). At the default durability there is no `fsync` on that path, so the spike
+is syscalls and a file creation rather than a device round-trip. Read **p75 as
+steady-state append cost** and `max`/`p999` as roughly the cost of a roll: a
+bimodal distribution here is the benchmark working, not noise or GC.
+
+It also means **the memory arm is not the disk arm minus the disk.** Memory mode
+never reaches `persistFrame`, so it never rolls and never writes a manifest — the
+gap between the two arms is segment management *plus* writing, not writing alone.
+Don't quote the ratio as "the cost of durability".
+
+**`rme` is the relative margin of error.** Check it before believing a
+difference: a 5% gap between two arms each carrying ±3% rme is not a result.
+
+There is no p50 or p90 in `vitest bench` output. The e2e script computes its own
+percentiles, which is why it is a separate script.
+
+**sf-on is not always faster than sf-off.** `e2e.ts` runs the two flush
+contracts on one server, and the SF engagement is real (the slot dir gets a
+`.sfa` + `sf-manifest.bin`). On a same-host server the localhost round-trip can
+be *faster* than a disk-backed append, so sf-on can legitimately come out
+slower — check that SF is engaged (slot files appear) and the disk baseline is
+sane before reading anything into the sign of the gap. They answer different
+questions regardless: sf-on is "recoverable if I crash now"; sf-off is "the
+server has it". Do not quote one as the other.
+
+## Am I measuring disk?
+
+`os.tmpdir()` is `/tmp` on most Linux boxes, and `/tmp` is frequently **tmpfs —
+RAM**. If the SF benchmarks and the e2e sf-on arm run there, they measure memory
+while claiming to measure disk, and the `dd` baseline reports an *excellent*
+figure — so the guard confirms a false conclusion instead of catching it.
+
+```bash
+df -T "$QWP_BENCH_DIR"   # type must not be tmpfs
+```
+
+## Before you quote anything
+
+1. **Check the disk line.** `sf.bench.ts` prints a `dd` figure first. If it is
+   far below what the hardware should do, the SF numbers are meaningless —
+   fix the machine, do not average around it.
+2. **Check the spread.** `e2e.ts` runs every arm three times and prints a range.
+   If p99 varies by more than about 2× across repeats, the machine is too busy.
+3. **Do not mix the two e2e numbers.** With SF on, `flush()` returns once the
+   row is durable *locally*. With SF off it waits for the *server*. They answer
+   different questions and the SF-on number is not a faster version of the
+   SF-off one.
+
+## What the floors mean
+
+`encoder.bench.ts` compares against hand-written baselines that do the minimum
+byte movement — no null bitmap, no schema, no framing. The floor is not a
+target. The gap between floor and encoder is what the protocol costs.
+
+Both sides accumulate into a `sink` so neither can be optimised away. If the
+encoder still beats its floor, the comparison itself is wrong — not dead-code
+removal. (A flat LONG column lands *at* its floor by design: the encoder uses
+the same `writeBigInt64LE` primitive, so near-parity is the correct result.)
+
+## What this suite does not cover
+
+- **Gorilla's raw fallback.** Every workload has perfectly regular timestamps,
+  so delta-of-delta is always 0 and the compressed path always wins. The
+  fallback needs a delta-of-delta beyond signed int32 — about a 35-minute jump
+  at microsecond resolution. `validate.test.ts` asserts the behaviour; these
+  numbers say nothing about it.
+- **Reconnect, replay and drainers.** Dominated by network and disk timing
+  rather than client code, so a number there measures the environment.
+- **Concurrency.** Single sender, single connection throughout.
diff --git a/benchmarks/buffer.bench.ts b/benchmarks/buffer.bench.ts
new file mode 100644
index 0000000..c76cbd7
--- /dev/null
+++ b/benchmarks/buffer.bench.ts
@@ -0,0 +1,87 @@
+import { bench, describe } from "vitest";
+import { QwpBuffer } from "../src/qwp/buffer";
+import { SymbolDict } from "../src/qwp/protocol/symbolDict";
+import { WORKLOADS } from "./workloads";
+
+const N = 10_000;
+const CAP = 1 << 30; // large enough that nothing splits
+
+/** See Task 5's note — consumes results so nothing is optimised away. */
+let sink = 0;
+
+/**
+ * Handles every column family the workloads generate — see Task 5's note.
+ *
+ * Note `Number(v)`: `intColumn` takes a `number` while the workloads carry
+ * `bigint`, so this layer pays a per-value conversion the encoder benchmarks in
+ * Task 5 do not (they push the bigint straight into `values`). The two tasks are
+ * therefore not directly comparable — some of the gap is representation, not
+ * buffer overhead. All generated values are well under 2^53, so no precision is
+ * lost; raise N or change a generator and re-check that.
+ */
+function fill(b: QwpBuffer, rows: ReturnType<typeof WORKLOADS.trades.rows>): void {
+  for (const row of rows) {
+    b.table(row.table);
+    for (const [n, v] of row.symbols) b.symbol(n, v);
+    for (const [n, v] of row.longs) b.intColumn(n, Number(v));
+    for (const [n, v] of row.doubles) b.floatColumn(n, v);
+    for (const [n, v] of row.strings) b.stringColumn(n, v);
+    // QwpBuffer.at() is synchronous (src/qwp/buffer.ts:173) — do NOT await it.
+    b.at(row.ts, "us");
+  }
+}
+
+describe("QwpBuffer build + seal", () => {
+  for (const name of ["trades", "wide", "sparse"] as const) {
+    const rows = WORKLOADS[name].rows(N);
+    bench(`build+seal / ${name}`, () => {
+      const b = new QwpBuffer();
+      fill(b, rows);
+      // sealFrames returns Buffer[]; sum BYTES, not the array length --
+      // `.length` here would be the frame count (always 1 under CAP) and
+      // would leave the encoded contents unobserved.
+      for (const f of b.sealFrames(CAP)) sink += f.length;
+    });
+  }
+});
+
+describe("dictionary mode", () => {
+  const rows = WORKLOADS.highCardSymbol.rows(N);
+
+  bench("full-dict (no dict attached)", () => {
+    const b = new QwpBuffer();
+    fill(b, rows);
+    for (const f of b.sealFrames(CAP)) sink += f.length;
+  });
+
+  // Steady state needs BOTH halves: a populated dictionary and a confirmed
+  // baseline. confirmedMaxId lives on the buffer, starts at -1, and only moves
+  // via confirmDeltaPublished() from the transport's publish path -- so a
+  // fresh buffer with a primed dict still ships every symbol, because
+  // entriesFrom(-1 + 1) returns everything. Priming the dict alone measures
+  // nothing new.
+  const primed = new SymbolDict();
+  {
+    const warm = new QwpBuffer();
+    warm.attachDict(primed);
+    fill(warm, rows);
+    warm.sealFrames(CAP);
+  }
+
+  bench("delta-dict (primed + baseline confirmed)", () => {
+    const b = new QwpBuffer();
+    b.attachDict(primed);
+    b.setConfirmedMaxId(primed.size() - 1);
+    fill(b, rows);
+    for (const f of b.sealFrames(CAP)) sink += f.length;
+  });
+
+  bench("delta-dict (cold, first batch)", () => {
+    const b = new QwpBuffer();
+    b.attachDict(new SymbolDict());
+    fill(b, rows);
+    for (const f of b.sealFrames(CAP)) sink += f.length;
+  });
+});
+
+export const _sink = () => sink;
diff --git a/benchmarks/e2e.ts b/benchmarks/e2e.ts
new file mode 100644
index 0000000..86705df
--- /dev/null
+++ b/benchmarks/e2e.ts
@@ -0,0 +1,152 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { Sender } from "../src";
+import { WORKLOADS } from "./workloads";
+
+const ADDR = process.env.QDB_ADDR ?? "localhost:9000";
+const ROWS = Number(process.env.BENCH_ROWS ?? 5000);
+const WARMUP = 500;
+const REPEATS = 3;
+/** Wide enough that repeat N never overlaps repeat N-1's timestamp range. */
+const REPEAT_TS_STRIDE = 1_000_000_000n;
+
+/**
+ * Where the sf-on arm writes. Defaults to the OS temp dir, which on most Linux
+ * boxes is /tmp and is frequently tmpfs — i.e. RAM. The sf-on number is
+ * "durable locally", so measuring it against RAM makes it look dramatically
+ * better than any real deployment. Set QWP_BENCH_DIR to real storage.
+ */
+const SF_ROOT = process.env.QWP_BENCH_DIR ?? process.env.TMPDIR ?? "/tmp";
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return NaN;
+  const i = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+  return sorted[i];
+}
+
+/**
+ * Measures flush() per row.
+ *
+ * This is only a clean measurement BECAUSE we flush every row. Sender.at()
+ * awaits tryFlush(), which fires when pendingRowCount >= auto_flush_rows
+ * (1000) or the auto_flush_interval elapses -- and flush() resets both. Since
+ * we flush after every row, neither trigger is ever reached, so no flush
+ * happens outside the timed window. Batch rows before flushing and the samples
+ * become a bimodal mixture of real flushes and near-no-ops, with p50 dominated
+ * by the no-ops. If you change the flush cadence, disable auto-flush's row
+ * trigger first.
+ *
+ * `tsOffset` keeps each repeat APPENDING. Workload rows are deterministic, so
+ * without it every repeat would resend the same timestamp range into the same
+ * table — and after repeat 1 those rows are older than what is already
+ * committed, which puts QuestDB on its out-of-order commit path. Repeat 1 would
+ * measure append while repeats 2 and 3 measure O3, and the "spread across
+ * repeats" guard would read that as machine noise.
+ *
+ * The same hazard exists a second time, through the symbol dictionary, and the
+ * defence is easy to delete by accident. Each repeat builds a FRESH Sender, and
+ * the sf-on arm passes `sender_id=bench-${i}` — a different id per repeat, so a
+ * different slot directory and therefore a cold `.symbol-dict` every time.
+ * Collapse that to a fixed `sender_id` and repeat 1 pays full-dict encoding plus
+ * write-ahead symbol persistence while repeats 2 and 3 recover the dictionary
+ * and run in delta mode (spec 5.2, 8.1.6). Delta wiring is live end-to-end as of
+ * handoff 6, so this is a real difference now, not a latent one. Keep the id
+ * per-repeat; it is load-bearing for comparability, not just for slot locking.
+ */
+async function arm(config: string, table: string, tsOffset: bigint): Promise<number[]> {
+  const sender = await Sender.fromConfig(config);
+  const samples: number[] = [];
+  try {
+    await sender.connect();
+    // Warmup rows are DISJOINT from measured rows: re-sending the same
+    // timestamps would double-ingest them, which is harmless for latency but
+    // breaks any later row-count assertion added to this script.
+    const warm = WORKLOADS.trades.rows(WARMUP);
+    const rows = WORKLOADS.trades.rows(WARMUP + ROWS).slice(WARMUP);
+
+    for (const row of warm) {
+      sender.table(table).symbol("symbol", row.symbols[0][1]);
+      for (const [n, v] of row.doubles) sender.floatColumn(n, v);
+      await sender.at(row.ts + tsOffset, "us");
+    }
+    await sender.flush();
+
+    for (const row of rows) {
+      sender.table(table).symbol("symbol", row.symbols[0][1]);
+      for (const [n, v] of row.doubles) sender.floatColumn(n, v);
+      await sender.at(row.ts + tsOffset, "us");
+      const t0 = process.hrtime.bigint();
+      await sender.flush();
+      samples.push(Number(process.hrtime.bigint() - t0) / 1000); // microseconds
+    }
+  } finally {
+    // Without this, a throw mid-loop leaks the sender and the SF barrier
+    // timer keeps the process alive.
+    await sender.close();
+  }
+  samples.sort((a, b) => a - b);
+  return samples;
+}
+
+function report(label: string, runs: number[][]): void {
+  console.log(`\n${label}`);
+  for (const p of [50, 90, 99, 99.9]) {
+    const vals = runs.map((s) => percentile(s, p));
+    const lo = Math.min(...vals).toFixed(1);
+    const hi = Math.max(...vals).toFixed(1);
+    console.log(`  p${p}\t${lo} – ${hi} µs   (spread across ${runs.length} repeats)`);
+  }
+}
+
+async function main(): Promise<void> {
+  console.log(`QWP e2e latency — ${ADDR}, ${ROWS} rows, ${REPEATS} repeats per arm`);
+  console.log("One server instance across both arms; no restart between them.\n");
+
+  // SF off: flush() covers encode -> send -> server ACK.
+  // Each arm has its OWN table. Sharing one would let the second arm ingest
+  // into a table already holding the first arm's rows — an asymmetry the
+  // "one server, no restart" guard exists to remove, not introduce.
+  const sfOff: number[][] = [];
+  for (let i = 0; i < REPEATS; i++) {
+    sfOff.push(
+      await arm(`ws::addr=${ADDR};`, "bench_e2e_sfoff", BigInt(i) * REPEAT_TS_STRIDE),
+    );
+  }
+  report("flush() = full server round-trip (sf off)", sfOff);
+
+  // SF on: flush() returns once the row is durable locally. A DIFFERENT
+  // contract, not a faster version of the same one.
+  // A FRESH directory per run. Reusing a fixed path leaves slots behind, and
+  // the next run's open() would recover those segments and replay stale frames
+  // into the measurement — so run 2 would differ from run 1 for reasons that
+  // have nothing to do with the code.
+  const sfDir = mkdtempSync(join(SF_ROOT, "qwp-bench-e2e-"));
+  console.log(`sf-on arm writing to ${sfDir}`);
+  console.log(`  (check this is not tmpfs: df -T ${SF_ROOT})\n`);
+
+  const sfOn: number[][] = [];
+  try {
+    for (let i = 0; i < REPEATS; i++) {
+      sfOn.push(
+        await arm(
+          `ws::addr=${ADDR};sf_dir=${sfDir};sender_id=bench-${i};`,
+          "bench_e2e_sfon",
+          BigInt(i) * REPEAT_TS_STRIDE,
+        ),
+      );
+    }
+  } finally {
+    rmSync(sfDir, { recursive: true, force: true });
+  }
+  report("flush() = local durability only (sf on)", sfOn);
+
+  console.log(
+    "\nThese two numbers answer different questions. sf-on is 'recoverable if I\n" +
+      "crash now'; sf-off is 'the server has it'. Do not quote one as the other.",
+  );
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/benchmarks/encoder.bench.ts b/benchmarks/encoder.bench.ts
new file mode 100644
index 0000000..1c04e4c
--- /dev/null
+++ b/benchmarks/encoder.bench.ts
@@ -0,0 +1,114 @@
+import { bench, describe } from "vitest";
+import { QwpTableBuffer } from "../src/qwp/protocol/tableBuffer";
+import { encodeFrame } from "../src/qwp/protocol/frameEncoder";
+import { SymbolDict } from "../src/qwp/protocol/symbolDict";
+import {
+  TYPE_LONG,
+  TYPE_DOUBLE,
+  TYPE_SYMBOL,
+  TYPE_TIMESTAMP,
+  TYPE_VARCHAR,
+} from "../src/qwp/protocol/constants";
+import { WORKLOADS } from "./workloads";
+import { floorWriteLongs, floorWriteStrings, floorInternSymbols } from "./floors";
+
+const N = 10_000;
+
+/**
+ * Consumes every result so neither the encoder nor the floor can be optimised
+ * away. Built in rather than added reactively: a floor that gets eliminated
+ * while the encoder does not (or vice versa) produces a ratio that looks like
+ * a finding, and the whole point of the floor is that the ratio is trustworthy.
+ */
+let sink = 0;
+
+/**
+ * Every column family the workloads generate must be handled here. Dropping
+ * one silently shrinks the benchmark: omitting `strings` turns `wide` from the
+ * advertised 50 columns into 42 and stops exercising varchar entirely.
+ */
+function buildTable(name: string, rows: ReturnType<typeof WORKLOADS.trades.rows>): QwpTableBuffer {
+  const t = new QwpTableBuffer(name);
+  for (const row of rows) {
+    for (const [n, v] of row.symbols) t.getOrCreateColumn(n, TYPE_SYMBOL)?.values.push(v);
+    for (const [n, v] of row.longs) t.getOrCreateColumn(n, TYPE_LONG)?.values.push(v);
+    for (const [n, v] of row.doubles) t.getOrCreateColumn(n, TYPE_DOUBLE)?.values.push(v);
+    for (const [n, v] of row.strings) t.getOrCreateColumn(n, TYPE_VARCHAR)?.values.push(v);
+    t.getOrCreateColumn("timestamp", TYPE_TIMESTAMP)?.values.push(row.ts);
+    t.nextRow();
+  }
+  return t;
+}
+
+describe("frame encode", () => {
+  for (const name of ["trades", "wide", "sparse"] as const) {
+    const rows = WORKLOADS[name].rows(N);
+    // Use the workload's own table name, matching Tasks 4 and 6. Passing
+    // WORKLOADS[name].name instead ("trades" vs "bench_trades") would encode a
+    // different table-name length and make frame sizes differ between tasks
+    // measuring nominally the same workload.
+    const table = buildTable(rows[0].table, rows);
+    bench(`encodeFrame / ${name} / gorilla off`, () => {
+      sink += encodeFrame([table], { gorilla: false }).length;
+    });
+    bench(`encodeFrame / ${name} / gorilla on`, () => {
+      sink += encodeFrame([table], { gorilla: true }).length;
+    });
+  }
+});
+
+describe("floor comparison", () => {
+  const longs = WORKLOADS.sparse.rows(N).flatMap((r) => r.longs.map(([, v]) => v));
+
+  bench("FLOOR writeBigInt64LE loop", () => {
+    sink += floorWriteLongs(longs).length;
+  });
+
+  const t = new QwpTableBuffer("floor_cmp");
+  for (const v of longs) {
+    t.getOrCreateColumn("v", TYPE_LONG)?.values.push(v);
+    t.nextRow();
+  }
+  bench("encodeFrame single long column", () => {
+    sink += encodeFrame([t], { gorilla: false }).length;
+  });
+});
+
+describe("varchar floor comparison", () => {
+  // `wide` strings are "v0".."v99" — 2 to 3 bytes each. With a 4-byte offset
+  // per value, the offset array outweighs the payload, so this arm chiefly
+  // measures offset-table overhead rather than string copying. That is the
+  // interesting comparison for short symbols-as-text, but do not read it as a
+  // large-varchar number.
+  const strs = WORKLOADS.wide.rows(N).flatMap((r) => r.strings.map(([, v]) => v));
+
+  bench("FLOOR utf8 write loop", () => {
+    sink += floorWriteStrings(strs).length;
+  });
+
+  const tv = new QwpTableBuffer("floor_varchar");
+  for (const v of strs) {
+    tv.getOrCreateColumn("s", TYPE_VARCHAR)?.values.push(v);
+    tv.nextRow();
+  }
+  bench("encodeFrame single varchar column", () => {
+    sink += encodeFrame([tv], { gorilla: false }).length;
+  });
+});
+
+describe("symbol interning", () => {
+  const syms = WORKLOADS.highCardSymbol.rows(N).map((r) => r.symbols[0][1]);
+
+  bench("FLOOR naive Map intern", () => {
+    sink += floorInternSymbols(syms).length;
+  });
+
+  bench("SymbolDict.getOrAdd", () => {
+    const d = new SymbolDict();
+    for (const s of syms) d.getOrAdd(s);
+    sink += d.size();
+  });
+});
+
+// Keeps `sink` observable so the compiler cannot treat it as dead.
+export const _sink = () => sink;
diff --git a/benchmarks/floors.test.ts b/benchmarks/floors.test.ts
new file mode 100644
index 0000000..bb37ad6
--- /dev/null
+++ b/benchmarks/floors.test.ts
@@ -0,0 +1,18 @@
+import { describe, it, expect } from "vitest";
+import { floorWriteLongs, floorWriteStrings, floorInternSymbols } from "./floors";
+
+describe("floors", () => {
+  it("writes 8 bytes per long", () => {
+    const b = floorWriteLongs([1n, 2n, 3n]);
+    expect(b.length).toBe(24);
+    expect(b.readBigInt64LE(8)).toBe(2n);
+  });
+
+  it("writes utf8 back to back", () => {
+    expect(floorWriteStrings(["ab", "cd"]).toString("utf8")).toBe("abcd");
+  });
+
+  it("interns to dense ids", () => {
+    expect(floorInternSymbols(["a", "b", "a"])).toEqual([0, 1, 0]);
+  });
+});
diff --git a/benchmarks/floors.ts b/benchmarks/floors.ts
new file mode 100644
index 0000000..2f0ccf7
--- /dev/null
+++ b/benchmarks/floors.ts
@@ -0,0 +1,41 @@
+import { Buffer } from "node:buffer";
+
+/**
+ * Hand-written baselines. Each does the minimum byte movement the equivalent
+ * encoder path must also do -- no null bitmap, no schema, no framing. The gap
+ * between a floor and the real encoder is the protocol's cost.
+ */
+
+export function floorWriteLongs(values: bigint[]): Buffer {
+  const b = Buffer.allocUnsafe(values.length * 8);
+  let o = 0;
+  for (const v of values) {
+    b.writeBigInt64LE(v, o);
+    o += 8;
+  }
+  return b;
+}
+
+export function floorWriteStrings(values: string[]): Buffer {
+  let total = 0;
+  for (const s of values) total += Buffer.byteLength(s, "utf8");
+  const b = Buffer.allocUnsafe(total);
+  let o = 0;
+  for (const s of values) o += b.write(s, o, "utf8");
+  return b;
+}
+
+/** Naive per-row map lookup -- what the row API pays at the same cardinality. */
+export function floorInternSymbols(values: string[]): number[] {
+  const map = new Map<string, number>();
+  const out: number[] = [];
+  for (const s of values) {
+    let id = map.get(s);
+    if (id === undefined) {
+      id = map.size;
+      map.set(s, id);
+    }
+    out.push(id);
+  }
+  return out;
+}
diff --git a/benchmarks/sf.bench.ts b/benchmarks/sf.bench.ts
new file mode 100644
index 0000000..367d47c
--- /dev/null
+++ b/benchmarks/sf.bench.ts
@@ -0,0 +1,129 @@
+import { bench, describe, beforeAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Buffer } from "node:buffer";
+import { SfEngine } from "../src/qwp/sf/engine";
+import { buildSegment, scanSegment } from "../src/qwp/sf/segment";
+
+let dir: string;
+
+/**
+ * Where the SF benchmark writes. os.tmpdir() is /tmp on most Linux boxes and
+ * /tmp is frequently tmpfs -- i.e. RAM. Both the dd baseline and the SF
+ * benchmark would then measure memory while claiming to measure disk, and the
+ * baseline would report a *great* number, so the guard fails silently in the
+ * most reassuring possible direction. Point QWP_BENCH_DIR at real storage.
+ */
+function benchRoot(): string {
+  const override = process.env.QWP_BENCH_DIR;
+  if (override) return override;
+  const t = tmpdir();
+  if (t.startsWith("/dev/shm") || t.startsWith("/run")) {
+    console.log(
+      `\n[disk baseline] ${t} is almost certainly tmpfs (RAM). ` +
+        "SF numbers below are NOT disk numbers. Set QWP_BENCH_DIR to real storage.",
+    );
+  } else {
+    console.log(
+      `\n[disk baseline] using ${t} — if this is tmpfs, these are RAM numbers. ` +
+        "Check with: df -T " + t,
+    );
+  }
+  return t;
+}
+
+/** Prints a dd throughput figure so a degraded disk is visible, not silent. */
+function diskBaseline(path: string): void {
+  // spawnSync so stderr (where dd writes the "N bytes copied, M s, X MB/s"
+  // summary) is captured alongside stdout — the plan's execFileSync captured
+  // only stdout and printed an empty baseline, defeating its purpose.
+  const r = spawnSync(
+    "dd",
+    ["if=/dev/zero", `of=${join(path, "dd.tmp")}`, "bs=1M", "count=256", "oflag=direct"],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+  );
+  const out = [r.stdout.trim(), r.stderr.trim()].filter(Boolean).join(" ").trim();
+  if (out) console.log(`[disk baseline] ${out.split("\n").pop()}`);
+  else {
+    console.log(
+      "[disk baseline] unavailable (dd missing, or O_DIRECT unsupported — " +
+        "which itself suggests tmpfs). Treat SF numbers with caution.",
+    );
+  }
+  rmSync(join(path, "dd.tmp"), { force: true });
+}
+
+// Engines are opened ONCE, not per iteration — see the note on withEngine below.
+let memEngine: SfEngine;
+let diskEngine: SfEngine;
+
+beforeAll(async () => {
+  dir = mkdtempSync(join(benchRoot(), "qwp-bench-"));
+  diskBaseline(dir);
+  memEngine = new SfEngine({
+    segmentBytes: 4 << 20,
+    maxTotalBytes: 1 << 30,
+    senderId: "bench-mem",
+  });
+  await memEngine.open();
+  diskEngine = new SfEngine({
+    segmentBytes: 4 << 20,
+    maxTotalBytes: 1 << 30,
+    sfDir: dir,
+    senderId: "bench-disk",
+  });
+  await diskEngine.open();
+  return async () => {
+    await memEngine.close();
+    await diskEngine.close();
+    rmSync(dir, { recursive: true, force: true });
+  };
+});
+
+// A synthetic 4 KiB frame, NOT a real encoded frame. SF does not inspect
+// contents, so the shape does not matter — but the SIZE does: a real `trades`
+// frame at 10k rows is tens of KiB, and appends amortise syscall cost over
+// their size. Read the disk-mode number as "cost of a 4 KiB append", and scale
+// FRAME up if you want to model a realistic flush.
+const FRAME = Buffer.alloc(4096, 0x41);
+
+const APPENDS = 100;
+
+/**
+ * Engines are opened once in beforeAll, NOT per iteration.
+ *
+ * Creating one inside the bench body would put acquireSlot (an exclusive
+ * lockfile), recovery, a dict fd open and a setInterval start inside the timed
+ * window — setup that dwarfs 100 appends, so the benchmark would report
+ * engine-open cost under an "append" label.
+ *
+ * The cost of hoisting is that the ring accumulates across iterations, so each
+ * body acknowledges what it just published to keep trim running. acknowledge()
+ * is cheap and is on the real ACK path anyway, so its inclusion is honest
+ * rather than a distortion.
+ */
+async function appendBatch(e: SfEngine): Promise<void> {
+  for (let i = 0; i < APPENDS; i++) await e.append(FRAME);
+  e.acknowledge(e.publishedFsn);
+}
+
+describe("SfEngine.append", () => {
+  bench(`memory mode / ${APPENDS} appends`, async () => {
+    await appendBatch(memEngine);
+  });
+
+  bench(`disk mode / ${APPENDS} appends`, async () => {
+    await appendBatch(diskEngine);
+  });
+});
+
+describe("segment recovery", () => {
+  const frames = Array.from({ length: 1000 }, () => FRAME);
+  const seg = buildSegment(0, frames, 8 << 20);
+
+  bench("scanSegment / 1000 frames", () => {
+    scanSegment(seg);
+  });
+});
diff --git a/benchmarks/validate.test.ts b/benchmarks/validate.test.ts
new file mode 100644
index 0000000..e7d088e
--- /dev/null
+++ b/benchmarks/validate.test.ts
@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import { QwpBuffer } from "../src/qwp/buffer";
+import { SymbolDict } from "../src/qwp/protocol/symbolDict";
+import { QwpTableBuffer } from "../src/qwp/protocol/tableBuffer";
+import { encodeFrame } from "../src/qwp/protocol/frameEncoder";
+import { TYPE_LONG, TYPE_TIMESTAMP } from "../src/qwp/protocol/constants";
+import { WORKLOADS } from "./workloads";
+
+const CAP = 1 << 30;
+const BASE = 1_700_000_000_000_000n;
+
+/**
+ * `confirmedMaxId` lives on the BUFFER, starts at -1, and only advances via
+ * confirmDeltaPublished(), which the transport's publish path calls -- not
+ * sealFrames(). So a fresh QwpBuffer with a fully primed dictionary still
+ * ships every symbol, because entriesFrom(-1 + 1) returns everything. Priming
+ * the dict alone does nothing; the baseline has to be set too, which is what
+ * `confirmed` simulates.
+ */
+function build(
+  rows: ReturnType<typeof WORKLOADS.trades.rows>,
+  dict?: SymbolDict,
+  confirmed?: number,
+): Buffer[] {
+  const b = new QwpBuffer();
+  if (dict) b.attachDict(dict);
+  if (confirmed !== undefined) b.setConfirmedMaxId(confirmed);
+  for (const row of rows) {
+    b.table(row.table);
+    for (const [n, v] of row.symbols) b.symbol(n, v);
+    for (const [n, v] of row.longs) b.intColumn(n, Number(v));
+    for (const [n, v] of row.doubles) b.floatColumn(n, v);
+    for (const [n, v] of row.strings) b.stringColumn(n, v);
+    b.at(row.ts, "us");
+  }
+  return b.sealFrames(CAP);
+}
+
+describe("wire-format invariants", () => {
+  it("trades encodes to a plausible bytes/row", () => {
+    const rows = WORKLOADS.trades.rows(10_000);
+    const bytes = build(rows).reduce((a, f) => a + f.length, 0);
+    const perRow = bytes / rows.length;
+    // Measured ~17.1 bytes/row (gorilla on by default in QwpBuffer): 8 (price)
+    // + 8 (amount) + ~1 (symbol id) + ~0.1 (gorilla-compressed timestamp, since
+    // trades timestamps are perfectly regular, delta-of-delta = 0) + ~0 table
+    // header amortised over 10k rows. Well under ~4 means a value is being
+    // dropped (losing either double drops ~8 bytes/row); well over means
+    // framing overhead has regressed. Band tightened from the original 20-120
+    // guess around this measured figure.
+    expect(perRow).toBeGreaterThan(14);
+    expect(perRow).toBeLessThan(24);
+  });
+
+  it("null values are compacted, not written as placeholders", () => {
+    const rows = WORKLOADS.sparse.rows(2000);
+    const sparseBytes = build(rows).reduce((a, f) => a + f.length, 0);
+
+    // Same shape with every value present.
+    const dense = rows.map((r) => ({
+      ...r,
+      nulls: [],
+      longs: ["a", "b", "c", "d", "e", "f", "g", "h"].map(
+        (n) => [n, 1n] as [string, bigint],
+      ),
+    }));
+    const denseBytes = build(dense).reduce((a, f) => a + f.length, 0);
+
+    // ~30% nulls must produce a materially smaller payload (spec 6.2.1).
+    expect(sparseBytes).toBeLessThan(denseBytes * 0.9);
+  });
+
+  it("delta mode emits fewer bytes than full-dict on high cardinality", () => {
+    const rows = WORKLOADS.highCardSymbol.rows(5000);
+    const full = build(rows).reduce((a, f) => a + f.length, 0);
+
+    // Steady state: the dictionary is populated AND the server has confirmed
+    // those ids, so the frame carries varint ids and an empty delta section.
+    // Both halves are required -- see the note on build() above.
+    const dict = new SymbolDict();
+    build(rows, dict); // first pass registers every symbol in the dict
+    const second = build(rows, dict, dict.size() - 1).reduce((a, f) => a + f.length, 0);
+
+    expect(second).toBeLessThan(full);
+  });
+
+  it("a cold delta batch is NOT smaller — the baseline is what saves bytes", () => {
+    // Guards the mistake above: priming the dict without advancing the
+    // confirmed baseline still ships every symbol string, so this must land
+    // in the same range as full-dict rather than winning.
+    const rows = WORKLOADS.highCardSymbol.rows(5000);
+    const full = build(rows).reduce((a, f) => a + f.length, 0);
+
+    const dict = new SymbolDict();
+    build(rows, dict);
+    const coldAgain = build(rows, dict).reduce((a, f) => a + f.length, 0);
+
+    // Both ship every symbol string once — cold delta in the delta section,
+    // full-dict in a per-column inline dictionary — so they should land within
+    // a few percent. A 0.5 threshold would also pass if the baseline were
+    // partially advancing, which is the bug this guards.
+    expect(coldAgain).toBeGreaterThan(full * 0.9);
+  });
+
+  it("the gorilla flag does not leak into non-timestamp columns", () => {
+    const t = new QwpTableBuffer("g");
+    for (let i = 0; i < 5000; i++) {
+      t.getOrCreateColumn("v", TYPE_LONG)?.values.push(BigInt(i));
+      t.nextRow();
+    }
+    const off = encodeFrame([t], { gorilla: false }).length;
+    const on = encodeFrame([t], { gorilla: true }).length;
+    // LONG is not gorilla-encoded, so these must match EXACTLY. A difference
+    // means the flag is reaching a column type it should not touch.
+    expect(on).toBe(off);
+  });
+
+  it("gorilla actually shrinks a regularly spaced timestamp column", () => {
+    // The positive case. Without this, the suite asserts only that gorilla does
+    // nothing to LONG — it would pass with the encoder never compressing at all.
+    const t = new QwpTableBuffer("g_ts");
+    for (let i = 0; i < 5000; i++) {
+      t.getOrCreateColumn("ts", TYPE_TIMESTAMP)?.values.push(BASE + BigInt(i) * 1000n);
+      t.nextRow();
+    }
+    const off = encodeFrame([t], { gorilla: false }).length;
+    const on = encodeFrame([t], { gorilla: true }).length;
+    // Constant spacing means every delta-of-delta is 0 — one bit per row after
+    // the first two raw values, versus 8 bytes each uncompressed.
+    expect(on).toBeLessThan(off / 2);
+  });
+});
diff --git a/benchmarks/workloads.test.ts b/benchmarks/workloads.test.ts
new file mode 100644
index 0000000..d935373
--- /dev/null
+++ b/benchmarks/workloads.test.ts
@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { WORKLOADS } from "./workloads";
+
+describe("workloads", () => {
+  it("are deterministic across calls", () => {
+    const a = WORKLOADS.trades.rows(100);
+    const b = WORKLOADS.trades.rows(100);
+    expect(JSON.stringify(a, (_, v) => (typeof v === "bigint" ? v.toString() : v)))
+      .toBe(JSON.stringify(b, (_, v) => (typeof v === "bigint" ? v.toString() : v)));
+  });
+
+  it("trades has the advertised shape", () => {
+    const r = WORKLOADS.trades.rows(1)[0];
+    expect(r.symbols.length).toBe(1);
+    expect(r.doubles.length).toBe(2);
+  });
+
+  it("wide has 50 data columns across all four families", () => {
+    expect(WORKLOADS.wide.columns).toBe(50);
+    const r = WORKLOADS.wide.rows(1)[0];
+    // 1 + 20 + 20 + 9 = 50. The encoded table carries 51 including the
+    // designated timestamp, which is not counted here.
+    expect(r.symbols.length + r.longs.length + r.doubles.length + r.strings.length).toBe(50);
+  });
+
+  it("highCardSymbol produces many distinct symbols", () => {
+    const rows = WORKLOADS.highCardSymbol.rows(5000);
+    const distinct = new Set(rows.map((r) => r.symbols[0][1]));
+    expect(distinct.size).toBeGreaterThan(4000);
+  });
+
+  it("sparse marks roughly 30% of values null", () => {
+    const rows = WORKLOADS.sparse.rows(1000);
+    const nullCount = rows.reduce((a, r) => a + r.nulls.length, 0);
+    const total = rows.length * 8;
+    expect(nullCount / total).toBeGreaterThan(0.2);
+    expect(nullCount / total).toBeLessThan(0.4);
+  });
+});
diff --git a/benchmarks/workloads.ts b/benchmarks/workloads.ts
new file mode 100644
index 0000000..2ec3013
--- /dev/null
+++ b/benchmarks/workloads.ts
@@ -0,0 +1,136 @@
+export interface Row {
+  table: string;
+  symbols: [string, string][];
+  longs: [string, bigint][];
+  doubles: [string, number][];
+  strings: [string, string][];
+  /** Column names deliberately left unset for this row. */
+  nulls: string[];
+  ts: bigint;
+}
+
+export interface Workload {
+  name: string;
+  columns: number;
+  rows(count: number): Row[];
+}
+
+/**
+ * xorshift32 — deterministic and dependency-free.
+ *
+ * The first outputs from a small seed are near zero (seed 1 yields 0.00006,
+ * then 0.01575) because the state has not diffused. Left unwarmed, `sparse`
+ * would make row 0's leading columns deterministically null and `trades` would
+ * open with its minimum price. Discarding the first 16 rounds costs nothing at
+ * setup time and makes the early rows as representative as the rest.
+ */
+function rng(seed: number): () => number {
+  let x = seed || 0x9e3779b9;
+  const next = () => {
+    x ^= x << 13;
+    x ^= x >>> 17;
+    x ^= x << 5;
+    return (x >>> 0) / 0x100000000;
+  };
+  for (let i = 0; i < 16; i++) next();
+  return next;
+}
+
+const BASE_TS = 1_700_000_000_000_000n;
+
+function trades(count: number): Row[] {
+  const r = rng(1);
+  const syms = ["ETH-USD", "BTC-USD", "SOL-USD", "ADA-USD"];
+  const out: Row[] = [];
+  for (let i = 0; i < count; i++) {
+    out.push({
+      table: "bench_trades",
+      symbols: [["symbol", syms[i % syms.length]]],
+      longs: [],
+      doubles: [
+        ["price", 1000 + r() * 5000],
+        ["amount", r()],
+      ],
+      strings: [],
+      nulls: [],
+      ts: BASE_TS + BigInt(i) * 1000n,
+    });
+  }
+  return out;
+}
+
+function wide(count: number): Row[] {
+  const r = rng(2);
+  const out: Row[] = [];
+  for (let i = 0; i < count; i++) {
+    const longs: [string, bigint][] = [];
+    const doubles: [string, number][] = [];
+    const strings: [string, string][] = [];
+    for (let c = 0; c < 20; c++) longs.push([`l${c}`, BigInt(Math.floor(r() * 1e6))]);
+    for (let c = 0; c < 20; c++) doubles.push([`d${c}`, r() * 1000]);
+    for (let c = 0; c < 9; c++) strings.push([`s${c}`, `v${Math.floor(r() * 100)}`]);
+    out.push({
+      table: "bench_wide",
+      symbols: [["sym", `s${i % 16}`]],
+      longs,
+      doubles,
+      strings,
+      nulls: [],
+      ts: BASE_TS + BigInt(i) * 1000n,
+    });
+  }
+  return out;
+}
+
+function highCardSymbol(count: number): Row[] {
+  const out: Row[] = [];
+  for (let i = 0; i < count; i++) {
+    out.push({
+      table: "bench_highcard",
+      // Distinct per row up to 100k, then repeats.
+      symbols: [["sym", `sym-${i % 100_000}`]],
+      longs: [["v", BigInt(i)]],
+      doubles: [],
+      strings: [],
+      nulls: [],
+      ts: BASE_TS + BigInt(i) * 1000n,
+    });
+  }
+  return out;
+}
+
+function sparse(count: number): Row[] {
+  const r = rng(4);
+  const names = ["a", "b", "c", "d", "e", "f", "g", "h"];
+  const out: Row[] = [];
+  for (let i = 0; i < count; i++) {
+    const longs: [string, bigint][] = [];
+    const nulls: string[] = [];
+    for (const n of names) {
+      if (r() < 0.3) nulls.push(n);
+      else longs.push([n, BigInt(Math.floor(r() * 1e6))]);
+    }
+    out.push({
+      table: "bench_sparse",
+      symbols: [],
+      longs,
+      doubles: [],
+      strings: [],
+      nulls,
+      ts: BASE_TS + BigInt(i) * 1000n,
+    });
+  }
+  return out;
+}
+
+export type WorkloadName = "trades" | "wide" | "highCardSymbol" | "sparse";
+
+// Keyed on the literal union, not `string`: Tasks 6 and 7 index this as
+// WORKLOADS[name], and a `Record<string, Workload>` would type a misspelled
+// name as a valid Workload and fail only at runtime.
+export const WORKLOADS: Record<WorkloadName, Workload> = {
+  trades: { name: "trades", columns: 4, rows: trades },
+  wide: { name: "wide", columns: 50, rows: wide },
+  highCardSymbol: { name: "highCardSymbol", columns: 3, rows: highCardSymbol },
+  sparse: { name: "sparse", columns: 8, rows: sparse },
+};
diff --git a/examples/qwp-basic.ts b/examples/qwp-basic.ts
new file mode 100644
index 0000000..2cca5df
--- /dev/null
+++ b/examples/qwp-basic.ts
@@ -0,0 +1,20 @@
+import { Sender } from "@questdb/nodejs-client";
+
+async function main(): Promise<void> {
+  const sender = await Sender.fromConfig("ws::addr=localhost:9000;");
+  await sender.connect();
+  await sender
+    .table("trades")
+    .symbol("symbol", "ETH-USD")
+    .symbol("side", "sell")
+    .floatColumn("price", 2615.54)
+    .floatColumn("amount", 0.00044)
+    .at(Date.now(), "ms");
+  await sender.flush();
+  await sender.close();
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
diff --git a/package.json b/package.json
index 2290156..7e97e92 100644
--- a/package.json
+++ b/package.json
@@ -1,12 +1,16 @@
 {
   "name": "@questdb/nodejs-client",
-  "version": "4.2.0",
+  "version": "5.0.0",
   "description": "QuestDB Node.js Client",
   "scripts": {
     "test": "vitest",
     "build": "bunchee",
     "eslint": "eslint src/**",
     "typecheck": "tsc --noEmit",
+    "bench": "vitest bench --run",
+    "bench:e2e": "npx tsx benchmarks/e2e.ts",
+    "typecheck:bench": "tsc --noEmit -p tsconfig.bench.json",
+    "lint:bench": "eslint benchmarks/**",
     "format": "prettier --write '{src,test}/**/*.{ts,js,json}'",
     "docs": "typedoc --out docs src/index.ts",
     "preview:docs": "serve docs"
@@ -47,10 +51,11 @@
     "prettier": "^3.5.3",
     "serve": "^14.2.4",
     "testcontainers": "^10.25.0",
+    "tsx": "^4.23.9",
     "typedoc": "^0.28.9",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.32.0",
-    "vitest": "^3.1.3"
+    "vitest": "3.1.3"
   },
   "dependencies": {
     "undici": "^7.8.0"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d824b63..a2af302 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,16 +26,19 @@ importers:
         version: 6.5.1(typescript@5.7.2)
       eslint:
         specifier: ^9.26.0
-        version: 9.26.0
+        version: 9.26.0(supports-color@7.2.0)
       prettier:
         specifier: ^3.5.3
         version: 3.5.3
       serve:
         specifier: ^14.2.4
-        version: 14.2.4
+        version: 14.2.4(supports-color@7.2.0)
       testcontainers:
         specifier: ^10.25.0
-        version: 10.25.0
+        version: 10.25.0(supports-color@7.2.0)
+      tsx:
+        specifier: ^4.23.9
+        version: 4.23.9
       typedoc:
         specifier: ^0.28.9
         version: 0.28.9(typescript@5.7.2)
@@ -44,10 +47,10 @@ importers:
         version: 5.7.2
       typescript-eslint:
         specifier: ^8.32.0
-        version: 8.32.0(eslint@9.26.0)(typescript@5.7.2)
+        version: 8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
       vitest:
         specifier: ^3.1.3
-        version: 3.1.3(@types/node@22.15.17)
+        version: 3.1.3(@types/node@22.15.17)(supports-color@7.2.0)
 
 packages:
 
@@ -68,138 +71,294 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
+  '@esbuild/aix-ppc64@0.28.1':
+    resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
   '@esbuild/android-arm64@0.21.5':
     resolution: {integrity: sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [android]
 
+  '@esbuild/android-arm64@0.28.1':
+    resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
   '@esbuild/android-arm@0.21.5':
     resolution: {integrity: sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==}
     engines: {node: '>=12'}
     cpu: [arm]
     os: [android]
 
+  '@esbuild/android-arm@0.28.1':
+    resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
   '@esbuild/android-x64@0.21.5':
     resolution: {integrity: sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [android]
 
+  '@esbuild/android-x64@0.28.1':
+    resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
   '@esbuild/darwin-arm64@0.21.5':
     resolution: {integrity: sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [darwin]
 
+  '@esbuild/darwin-arm64@0.28.1':
+    resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@esbuild/darwin-x64@0.21.5':
     resolution: {integrity: sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [darwin]
 
+  '@esbuild/darwin-x64@0.28.1':
+    resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
   '@esbuild/freebsd-arm64@0.21.5':
     resolution: {integrity: sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [freebsd]
 
+  '@esbuild/freebsd-arm64@0.28.1':
+    resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
   '@esbuild/freebsd-x64@0.21.5':
     resolution: {integrity: sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [freebsd]
 
+  '@esbuild/freebsd-x64@0.28.1':
+    resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@esbuild/linux-arm64@0.21.5':
     resolution: {integrity: sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [linux]
 
+  '@esbuild/linux-arm64@0.28.1':
+    resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
   '@esbuild/linux-arm@0.21.5':
     resolution: {integrity: sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==}
     engines: {node: '>=12'}
     cpu: [arm]
     os: [linux]
 
+  '@esbuild/linux-arm@0.28.1':
+    resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
   '@esbuild/linux-ia32@0.21.5':
     resolution: {integrity: sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==}
     engines: {node: '>=12'}
     cpu: [ia32]
     os: [linux]
 
+  '@esbuild/linux-ia32@0.28.1':
+    resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
   '@esbuild/linux-loong64@0.21.5':
     resolution: {integrity: sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==}
     engines: {node: '>=12'}
     cpu: [loong64]
     os: [linux]
 
+  '@esbuild/linux-loong64@0.28.1':
+    resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
   '@esbuild/linux-mips64el@0.21.5':
     resolution: {integrity: sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==}
     engines: {node: '>=12'}
     cpu: [mips64el]
     os: [linux]
 
+  '@esbuild/linux-mips64el@0.28.1':
+    resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
   '@esbuild/linux-ppc64@0.21.5':
     resolution: {integrity: sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==}
     engines: {node: '>=12'}
     cpu: [ppc64]
     os: [linux]
 
+  '@esbuild/linux-ppc64@0.28.1':
+    resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
   '@esbuild/linux-riscv64@0.21.5':
     resolution: {integrity: sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==}
     engines: {node: '>=12'}
     cpu: [riscv64]
     os: [linux]
 
+  '@esbuild/linux-riscv64@0.28.1':
+    resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
   '@esbuild/linux-s390x@0.21.5':
     resolution: {integrity: sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==}
     engines: {node: '>=12'}
     cpu: [s390x]
     os: [linux]
 
+  '@esbuild/linux-s390x@0.28.1':
+    resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
   '@esbuild/linux-x64@0.21.5':
     resolution: {integrity: sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [linux]
 
+  '@esbuild/linux-x64@0.28.1':
+    resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
   '@esbuild/netbsd-x64@0.21.5':
     resolution: {integrity: sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [netbsd]
 
+  '@esbuild/netbsd-x64@0.28.1':
+    resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
   '@esbuild/openbsd-x64@0.21.5':
     resolution: {integrity: sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [openbsd]
 
+  '@esbuild/openbsd-x64@0.28.1':
+    resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
   '@esbuild/sunos-x64@0.21.5':
     resolution: {integrity: sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [sunos]
 
+  '@esbuild/sunos-x64@0.28.1':
+    resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
   '@esbuild/win32-arm64@0.21.5':
     resolution: {integrity: sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==}
     engines: {node: '>=12'}
     cpu: [arm64]
     os: [win32]
 
+  '@esbuild/win32-arm64@0.28.1':
+    resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
   '@esbuild/win32-ia32@0.21.5':
     resolution: {integrity: sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==}
     engines: {node: '>=12'}
     cpu: [ia32]
     os: [win32]
 
+  '@esbuild/win32-ia32@0.28.1':
+    resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
   '@esbuild/win32-x64@0.21.5':
     resolution: {integrity: sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==}
     engines: {node: '>=12'}
     cpu: [x64]
     os: [win32]
 
+  '@esbuild/win32-x64@0.28.1':
+    resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
   '@eslint-community/eslint-utils@4.4.1':
     resolution: {integrity: sha512-s3O3waFUrMV8P/XaF/+ZTp1X9XBZW1a4B97ZnjQF2KYWaFD2A8KyFBsrsfSjEmjn3RGWAIuvlneuZm3CUK3jbA==}
     engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
@@ -468,101 +627,121 @@ packages:
     resolution: {integrity: sha512-WXveUPKtfqtaNvpf0iOb0M6xC64GzUX/OowbqfiCSXTdi/jLlOmH0Ba94/OkiY2yTGTwteo4/dsHRfh5bDCZ+w==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm-gnueabihf@4.40.2':
     resolution: {integrity: sha512-de6TFZYIvJwRNjmW3+gaXiZ2DaWL5D5yGmSYzkdzjBDS3W+B9JQ48oZEsmMvemqjtAFzE16DIBLqd6IQQRuG9Q==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.28.0':
     resolution: {integrity: sha512-yLc3O2NtOQR67lI79zsSc7lk31xjwcaocvdD1twL64PK1yNaIqCeWI9L5B4MFPAVGEVjH5k1oWSGuYX1Wutxpg==}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-arm-musleabihf@4.40.2':
     resolution: {integrity: sha512-urjaEZubdIkacKc930hUDOfQPysezKla/O9qV+O89enqsqUmQm8Xj8O/vh0gHg4LYfv7Y7UsE3QjzLQzDYN1qg==}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.28.0':
     resolution: {integrity: sha512-+P9G9hjEpHucHRXqesY+3X9hD2wh0iNnJXX/QhS/J5vTdG6VhNYMxJ2rJkQOxRUd17u5mbMLHM7yWGZdAASfcg==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-gnu@4.40.2':
     resolution: {integrity: sha512-KlE8IC0HFOC33taNt1zR8qNlBYHj31qGT1UqWqtvR/+NuCVhfufAq9fxO8BMFC22Wu0rxOwGVWxtCMvZVLmhQg==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.28.0':
     resolution: {integrity: sha512-1xsm2rCKSTpKzi5/ypT5wfc+4bOGa/9yI/eaOLW0oMs7qpC542APWhl4A37AENGZ6St6GBMWhCCMM6tXgTIplw==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-arm64-musl@4.40.2':
     resolution: {integrity: sha512-j8CgxvfM0kbnhu4XgjnCWJQyyBOeBI1Zq91Z850aUddUmPeQvuAy6OiMdPS46gNFgy8gN1xkYyLgwLYZG3rBOg==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-loongarch64-gnu@4.40.2':
     resolution: {integrity: sha512-Ybc/1qUampKuRF4tQXc7G7QY9YRyeVSykfK36Y5Qc5dmrIxwFhrOzqaVTNoZygqZ1ZieSWTibfFhQ5qK8jpWxw==}
     cpu: [loong64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-powerpc64le-gnu@4.28.0':
     resolution: {integrity: sha512-zgWxMq8neVQeXL+ouSf6S7DoNeo6EPgi1eeqHXVKQxqPy1B2NvTbaOUWPn/7CfMKL7xvhV0/+fq/Z/J69g1WAQ==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-powerpc64le-gnu@4.40.2':
     resolution: {integrity: sha512-3FCIrnrt03CCsZqSYAOW/k9n625pjpuMzVfeI+ZBUSDT3MVIFDSPfSUgIl9FqUftxcUXInvFah79hE1c9abD+Q==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-gnu@4.28.0':
     resolution: {integrity: sha512-VEdVYacLniRxbRJLNtzwGt5vwS0ycYshofI7cWAfj7Vg5asqj+pt+Q6x4n+AONSZW/kVm+5nklde0qs2EUwU2g==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-gnu@4.40.2':
     resolution: {integrity: sha512-QNU7BFHEvHMp2ESSY3SozIkBPaPBDTsfVNGx3Xhv+TdvWXFGOSH2NJvhD1zKAT6AyuuErJgbdvaJhYVhVqrWTg==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.40.2':
     resolution: {integrity: sha512-5W6vNYkhgfh7URiXTO1E9a0cy4fSgfE4+Hl5agb/U1sa0kjOLMLC1wObxwKxecE17j0URxuTrYZZME4/VH57Hg==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.28.0':
     resolution: {integrity: sha512-LQlP5t2hcDJh8HV8RELD9/xlYtEzJkm/aWGsauvdO2ulfl3QYRjqrKW+mGAIWP5kdNCBheqqqYIGElSRCaXfpw==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-s390x-gnu@4.40.2':
     resolution: {integrity: sha512-B7LKIz+0+p348JoAL4X/YxGx9zOx3sR+o6Hj15Y3aaApNfAshK8+mWZEf759DXfRLeL2vg5LYJBB7DdcleYCoQ==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.28.0':
     resolution: {integrity: sha512-Nl4KIzteVEKE9BdAvYoTkW19pa7LR/RBrT6F1dJCV/3pbjwDcaOq+edkP0LXuJ9kflW/xOK414X78r+K84+msw==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.40.2':
     resolution: {integrity: sha512-lG7Xa+BmBNwpjmVUbmyKxdQJ3Q6whHjMjzQplOs5Z+Gj7mxPtWakGHqzMqNER68G67kmCX9qX57aRsW5V0VOng==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.28.0':
     resolution: {integrity: sha512-eKpJr4vBDOi4goT75MvW+0dXcNUqisK4jvibY9vDdlgLx+yekxSm55StsHbxUsRxSTt3JEQvlr3cGDkzcSP8bw==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-x64-musl@4.40.2':
     resolution: {integrity: sha512-tD46wKHd+KJvsmije4bUskNuvWKFcTOIM9tZ/RrmIvcXnbi0YK/cKS9FzFtAm7Oxi2EhV5N2OpfFB348vSQRXA==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-win32-arm64-msvc@4.28.0':
     resolution: {integrity: sha512-Vi+WR62xWGsE/Oj+mD0FNAPY2MEox3cfyG0zLpotZdehPFXwz6lypkGs5y38Jd/NVSbOD02aVad6q6QYF7i8Bg==}
@@ -632,24 +811,28 @@ packages:
     engines: {node: '>=10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@swc/core-linux-arm64-musl@1.11.24':
     resolution: {integrity: sha512-ypXLIdszRo0re7PNNaXN0+2lD454G8l9LPK/rbfRXnhLWDBPURxzKlLlU/YGd2zP98wPcVooMmegRSNOKfvErw==}
     engines: {node: '>=10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@swc/core-linux-x64-gnu@1.11.24':
     resolution: {integrity: sha512-IM7d+STVZD48zxcgo69L0yYptfhaaE9cMZ+9OoMxirNafhKKXwoZuufol1+alEFKc+Wbwp+aUPe/DeWC/Lh3dg==}
     engines: {node: '>=10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@swc/core-linux-x64-musl@1.11.24':
     resolution: {integrity: sha512-DZByJaMVzSfjQKKQn3cqSeqwy6lpMaQDQQ4HPlch9FWtDx/dLcpdIhxssqZXcR2rhaQVIaRQsCqwV6orSDGAGw==}
     engines: {node: '>=10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@swc/core-win32-arm64-msvc@1.11.24':
     resolution: {integrity: sha512-Q64Ytn23y9aVDKN5iryFi8mRgyHw3/kyjTjT4qFCa8AEb5sGUuSj//AUZ6c0J7hQKMHlg9do5Etvoe61V98/JQ==}
@@ -1231,6 +1414,11 @@ packages:
     engines: {node: '>=12'}
     hasBin: true
 
+  esbuild@0.28.1:
+    resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   escalade@3.2.0:
     resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
     engines: {node: '>=6'}
@@ -1442,6 +1630,7 @@ packages:
 
   glob@10.4.5:
     resolution: {integrity: sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
     hasBin: true
 
   globals@14.0.0:
@@ -2242,6 +2431,11 @@ packages:
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
+  tsx@4.23.9:
+    resolution: {integrity: sha512-6q8uTORRGauQVjqMQnKUucLFoeXZAfw6zKvG35GLbdKWbLdeOtZ3H4mhyA5mxuUd2o2cRTskhj59nLLQseUvUw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
   tweetnacl@0.14.5:
     resolution: {integrity: sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==}
 
@@ -2308,6 +2502,7 @@ packages:
 
   uuid@10.0.0:
     resolution: {integrity: sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   vary@1.1.2:
@@ -2462,88 +2657,166 @@ snapshots:
   '@esbuild/aix-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/aix-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm64@0.21.5':
     optional: true
 
+  '@esbuild/android-arm64@0.28.1':
+    optional: true
+
   '@esbuild/android-arm@0.21.5':
     optional: true
 
+  '@esbuild/android-arm@0.28.1':
+    optional: true
+
   '@esbuild/android-x64@0.21.5':
     optional: true
 
+  '@esbuild/android-x64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-arm64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-arm64@0.28.1':
+    optional: true
+
   '@esbuild/darwin-x64@0.21.5':
     optional: true
 
+  '@esbuild/darwin-x64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-arm64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/freebsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/freebsd-x64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm64@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm64@0.28.1':
+    optional: true
+
   '@esbuild/linux-arm@0.21.5':
     optional: true
 
+  '@esbuild/linux-arm@0.28.1':
+    optional: true
+
   '@esbuild/linux-ia32@0.21.5':
     optional: true
 
+  '@esbuild/linux-ia32@0.28.1':
+    optional: true
+
   '@esbuild/linux-loong64@0.21.5':
     optional: true
 
+  '@esbuild/linux-loong64@0.28.1':
+    optional: true
+
   '@esbuild/linux-mips64el@0.21.5':
     optional: true
 
+  '@esbuild/linux-mips64el@0.28.1':
+    optional: true
+
   '@esbuild/linux-ppc64@0.21.5':
     optional: true
 
+  '@esbuild/linux-ppc64@0.28.1':
+    optional: true
+
   '@esbuild/linux-riscv64@0.21.5':
     optional: true
 
+  '@esbuild/linux-riscv64@0.28.1':
+    optional: true
+
   '@esbuild/linux-s390x@0.21.5':
     optional: true
 
+  '@esbuild/linux-s390x@0.28.1':
+    optional: true
+
   '@esbuild/linux-x64@0.21.5':
     optional: true
 
+  '@esbuild/linux-x64@0.28.1':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/netbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/netbsd-x64@0.28.1':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    optional: true
+
   '@esbuild/openbsd-x64@0.21.5':
     optional: true
 
+  '@esbuild/openbsd-x64@0.28.1':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    optional: true
+
   '@esbuild/sunos-x64@0.21.5':
     optional: true
 
+  '@esbuild/sunos-x64@0.28.1':
+    optional: true
+
   '@esbuild/win32-arm64@0.21.5':
     optional: true
 
+  '@esbuild/win32-arm64@0.28.1':
+    optional: true
+
   '@esbuild/win32-ia32@0.21.5':
     optional: true
 
+  '@esbuild/win32-ia32@0.28.1':
+    optional: true
+
   '@esbuild/win32-x64@0.21.5':
     optional: true
 
-  '@eslint-community/eslint-utils@4.4.1(eslint@9.26.0)':
+  '@esbuild/win32-x64@0.28.1':
+    optional: true
+
+  '@eslint-community/eslint-utils@4.4.1(eslint@9.26.0(supports-color@7.2.0))':
     dependencies:
-      eslint: 9.26.0
+      eslint: 9.26.0(supports-color@7.2.0)
       eslint-visitor-keys: 3.4.3
 
-  '@eslint-community/eslint-utils@4.7.0(eslint@9.26.0)':
+  '@eslint-community/eslint-utils@4.7.0(eslint@9.26.0(supports-color@7.2.0))':
     dependencies:
-      eslint: 9.26.0
+      eslint: 9.26.0(supports-color@7.2.0)
       eslint-visitor-keys: 3.4.3
 
   '@eslint-community/regexpp@4.12.1': {}
 
-  '@eslint/config-array@0.20.0':
+  '@eslint/config-array@0.20.0(supports-color@7.2.0)':
     dependencies:
       '@eslint/object-schema': 2.1.6
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       minimatch: 3.1.2
     transitivePeerDependencies:
       - supports-color
@@ -2554,10 +2827,10 @@ snapshots:
     dependencies:
       '@types/json-schema': 7.0.15
 
-  '@eslint/eslintrc@3.3.1':
+  '@eslint/eslintrc@3.3.1(supports-color@7.2.0)':
     dependencies:
       ajv: 6.12.6
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       espree: 10.3.0
       globals: 14.0.0
       ignore: 5.3.2
@@ -2631,14 +2904,14 @@ snapshots:
 
   '@microsoft/tsdoc@0.15.1': {}
 
-  '@modelcontextprotocol/sdk@1.11.1':
+  '@modelcontextprotocol/sdk@1.11.1(supports-color@7.2.0)':
     dependencies:
       content-type: 1.0.5
       cors: 2.8.5
       cross-spawn: 7.0.6
       eventsource: 3.0.7
-      express: 5.1.0
-      express-rate-limit: 7.5.0(express@5.1.0)
+      express: 5.1.0(supports-color@7.2.0)
+      express-rate-limit: 7.5.0(express@5.1.0(supports-color@7.2.0))
       pkce-challenge: 5.0.0
       raw-body: 3.0.0
       zod: 3.24.4
@@ -2970,15 +3243,15 @@ snapshots:
 
   '@types/unist@3.0.3': {}
 
-  '@typescript-eslint/eslint-plugin@8.32.0(@typescript-eslint/parser@8.32.0(eslint@9.26.0)(typescript@5.7.2))(eslint@9.26.0)(typescript@5.7.2)':
+  '@typescript-eslint/eslint-plugin@8.32.0(@typescript-eslint/parser@8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2))(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)':
     dependencies:
       '@eslint-community/regexpp': 4.12.1
-      '@typescript-eslint/parser': 8.32.0(eslint@9.26.0)(typescript@5.7.2)
+      '@typescript-eslint/parser': 8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
       '@typescript-eslint/scope-manager': 8.32.0
-      '@typescript-eslint/type-utils': 8.32.0(eslint@9.26.0)(typescript@5.7.2)
-      '@typescript-eslint/utils': 8.32.0(eslint@9.26.0)(typescript@5.7.2)
+      '@typescript-eslint/type-utils': 8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
+      '@typescript-eslint/utils': 8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
       '@typescript-eslint/visitor-keys': 8.32.0
-      eslint: 9.26.0
+      eslint: 9.26.0(supports-color@7.2.0)
       graphemer: 1.4.0
       ignore: 5.3.2
       natural-compare: 1.4.0
@@ -2987,14 +3260,14 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/parser@8.32.0(eslint@9.26.0)(typescript@5.7.2)':
+  '@typescript-eslint/parser@8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)':
     dependencies:
       '@typescript-eslint/scope-manager': 8.32.0
       '@typescript-eslint/types': 8.32.0
-      '@typescript-eslint/typescript-estree': 8.32.0(typescript@5.7.2)
+      '@typescript-eslint/typescript-estree': 8.32.0(supports-color@7.2.0)(typescript@5.7.2)
       '@typescript-eslint/visitor-keys': 8.32.0
-      debug: 4.4.0
-      eslint: 9.26.0
+      debug: 4.4.0(supports-color@7.2.0)
+      eslint: 9.26.0(supports-color@7.2.0)
       typescript: 5.7.2
     transitivePeerDependencies:
       - supports-color
@@ -3004,12 +3277,12 @@ snapshots:
       '@typescript-eslint/types': 8.32.0
       '@typescript-eslint/visitor-keys': 8.32.0
 
-  '@typescript-eslint/type-utils@8.32.0(eslint@9.26.0)(typescript@5.7.2)':
+  '@typescript-eslint/type-utils@8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)':
     dependencies:
-      '@typescript-eslint/typescript-estree': 8.32.0(typescript@5.7.2)
-      '@typescript-eslint/utils': 8.32.0(eslint@9.26.0)(typescript@5.7.2)
-      debug: 4.4.0
-      eslint: 9.26.0
+      '@typescript-eslint/typescript-estree': 8.32.0(supports-color@7.2.0)(typescript@5.7.2)
+      '@typescript-eslint/utils': 8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
+      debug: 4.4.0(supports-color@7.2.0)
+      eslint: 9.26.0(supports-color@7.2.0)
       ts-api-utils: 2.1.0(typescript@5.7.2)
       typescript: 5.7.2
     transitivePeerDependencies:
@@ -3017,11 +3290,11 @@ snapshots:
 
   '@typescript-eslint/types@8.32.0': {}
 
-  '@typescript-eslint/typescript-estree@8.32.0(typescript@5.7.2)':
+  '@typescript-eslint/typescript-estree@8.32.0(supports-color@7.2.0)(typescript@5.7.2)':
     dependencies:
       '@typescript-eslint/types': 8.32.0
       '@typescript-eslint/visitor-keys': 8.32.0
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       fast-glob: 3.3.2
       is-glob: 4.0.3
       minimatch: 9.0.5
@@ -3031,13 +3304,13 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/utils@8.32.0(eslint@9.26.0)(typescript@5.7.2)':
+  '@typescript-eslint/utils@8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)':
     dependencies:
-      '@eslint-community/eslint-utils': 4.7.0(eslint@9.26.0)
+      '@eslint-community/eslint-utils': 4.7.0(eslint@9.26.0(supports-color@7.2.0))
       '@typescript-eslint/scope-manager': 8.32.0
       '@typescript-eslint/types': 8.32.0
-      '@typescript-eslint/typescript-estree': 8.32.0(typescript@5.7.2)
-      eslint: 9.26.0
+      '@typescript-eslint/typescript-estree': 8.32.0(supports-color@7.2.0)(typescript@5.7.2)
+      eslint: 9.26.0(supports-color@7.2.0)
       typescript: 5.7.2
     transitivePeerDependencies:
       - supports-color
@@ -3217,11 +3490,11 @@ snapshots:
       inherits: 2.0.4
       readable-stream: 3.6.2
 
-  body-parser@2.2.0:
+  body-parser@2.2.0(supports-color@7.2.0):
     dependencies:
       bytes: 3.1.2
       content-type: 1.0.5
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       http-errors: 2.0.0
       iconv-lite: 0.6.3
       on-finished: 2.4.1
@@ -3386,12 +3659,12 @@ snapshots:
     dependencies:
       mime-db: 1.53.0
 
-  compression@1.7.4:
+  compression@1.7.4(supports-color@7.2.0):
     dependencies:
       accepts: 1.3.8
       bytes: 3.0.0
       compressible: 2.0.18
-      debug: 2.6.9
+      debug: 2.6.9(supports-color@7.2.0)
       on-headers: 1.0.2
       safe-buffer: 5.1.2
       vary: 1.1.2
@@ -3438,17 +3711,23 @@ snapshots:
       shebang-command: 2.0.0
       which: 2.0.2
 
-  debug@2.6.9:
+  debug@2.6.9(supports-color@7.2.0):
     dependencies:
       ms: 2.0.0
+    optionalDependencies:
+      supports-color: 7.2.0
 
-  debug@4.3.7:
+  debug@4.3.7(supports-color@7.2.0):
     dependencies:
       ms: 2.1.3
+    optionalDependencies:
+      supports-color: 7.2.0
 
-  debug@4.4.0:
+  debug@4.4.0(supports-color@7.2.0):
     dependencies:
       ms: 2.1.3
+    optionalDependencies:
+      supports-color: 7.2.0
 
   deep-eql@5.0.2: {}
 
@@ -3464,21 +3743,21 @@ snapshots:
     dependencies:
       yaml: 2.6.1
 
-  docker-modem@5.0.6:
+  docker-modem@5.0.6(supports-color@7.2.0):
     dependencies:
-      debug: 4.3.7
+      debug: 4.3.7(supports-color@7.2.0)
       readable-stream: 3.6.2
       split-ca: 1.0.1
       ssh2: 1.16.0
     transitivePeerDependencies:
       - supports-color
 
-  dockerode@4.0.6:
+  dockerode@4.0.6(supports-color@7.2.0):
     dependencies:
       '@balena/dockerignore': 1.0.2
       '@grpc/grpc-js': 1.13.3
       '@grpc/proto-loader': 0.7.15
-      docker-modem: 5.0.6
+      docker-modem: 5.0.6(supports-color@7.2.0)
       protobufjs: 7.5.1
       tar-fs: 2.1.2
       uuid: 10.0.0
@@ -3545,6 +3824,35 @@ snapshots:
       '@esbuild/win32-ia32': 0.21.5
       '@esbuild/win32-x64': 0.21.5
 
+  esbuild@0.28.1:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.1
+      '@esbuild/android-arm': 0.28.1
+      '@esbuild/android-arm64': 0.28.1
+      '@esbuild/android-x64': 0.28.1
+      '@esbuild/darwin-arm64': 0.28.1
+      '@esbuild/darwin-x64': 0.28.1
+      '@esbuild/freebsd-arm64': 0.28.1
+      '@esbuild/freebsd-x64': 0.28.1
+      '@esbuild/linux-arm': 0.28.1
+      '@esbuild/linux-arm64': 0.28.1
+      '@esbuild/linux-ia32': 0.28.1
+      '@esbuild/linux-loong64': 0.28.1
+      '@esbuild/linux-mips64el': 0.28.1
+      '@esbuild/linux-ppc64': 0.28.1
+      '@esbuild/linux-riscv64': 0.28.1
+      '@esbuild/linux-s390x': 0.28.1
+      '@esbuild/linux-x64': 0.28.1
+      '@esbuild/netbsd-arm64': 0.28.1
+      '@esbuild/netbsd-x64': 0.28.1
+      '@esbuild/openbsd-arm64': 0.28.1
+      '@esbuild/openbsd-x64': 0.28.1
+      '@esbuild/openharmony-arm64': 0.28.1
+      '@esbuild/sunos-x64': 0.28.1
+      '@esbuild/win32-arm64': 0.28.1
+      '@esbuild/win32-ia32': 0.28.1
+      '@esbuild/win32-x64': 0.28.1
+
   escalade@3.2.0: {}
 
   escape-html@1.0.3: {}
@@ -3560,26 +3868,26 @@ snapshots:
 
   eslint-visitor-keys@4.2.0: {}
 
-  eslint@9.26.0:
+  eslint@9.26.0(supports-color@7.2.0):
     dependencies:
-      '@eslint-community/eslint-utils': 4.4.1(eslint@9.26.0)
+      '@eslint-community/eslint-utils': 4.4.1(eslint@9.26.0(supports-color@7.2.0))
       '@eslint-community/regexpp': 4.12.1
-      '@eslint/config-array': 0.20.0
+      '@eslint/config-array': 0.20.0(supports-color@7.2.0)
       '@eslint/config-helpers': 0.2.2
       '@eslint/core': 0.13.0
-      '@eslint/eslintrc': 3.3.1
+      '@eslint/eslintrc': 3.3.1(supports-color@7.2.0)
       '@eslint/js': 9.26.0
       '@eslint/plugin-kit': 0.2.8
       '@humanfs/node': 0.16.6
       '@humanwhocodes/module-importer': 1.0.1
       '@humanwhocodes/retry': 0.4.3
-      '@modelcontextprotocol/sdk': 1.11.1
+      '@modelcontextprotocol/sdk': 1.11.1(supports-color@7.2.0)
       '@types/estree': 1.0.6
       '@types/json-schema': 7.0.15
       ajv: 6.12.6
       chalk: 4.1.2
       cross-spawn: 7.0.6
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       escape-string-regexp: 4.0.0
       eslint-scope: 8.3.0
       eslint-visitor-keys: 4.2.0
@@ -3652,23 +3960,23 @@ snapshots:
 
   expect-type@1.2.1: {}
 
-  express-rate-limit@7.5.0(express@5.1.0):
+  express-rate-limit@7.5.0(express@5.1.0(supports-color@7.2.0)):
     dependencies:
-      express: 5.1.0
+      express: 5.1.0(supports-color@7.2.0)
 
-  express@5.1.0:
+  express@5.1.0(supports-color@7.2.0):
     dependencies:
       accepts: 2.0.0
-      body-parser: 2.2.0
+      body-parser: 2.2.0(supports-color@7.2.0)
       content-disposition: 1.0.0
       content-type: 1.0.5
       cookie: 0.7.2
       cookie-signature: 1.2.2
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       etag: 1.8.1
-      finalhandler: 2.1.0
+      finalhandler: 2.1.0(supports-color@7.2.0)
       fresh: 2.0.0
       http-errors: 2.0.0
       merge-descriptors: 2.0.0
@@ -3679,9 +3987,9 @@ snapshots:
       proxy-addr: 2.0.7
       qs: 6.14.0
       range-parser: 1.2.1
-      router: 2.2.0
-      send: 1.2.0
-      serve-static: 2.2.0
+      router: 2.2.0(supports-color@7.2.0)
+      send: 1.2.0(supports-color@7.2.0)
+      serve-static: 2.2.0(supports-color@7.2.0)
       statuses: 2.0.1
       type-is: 2.0.1
       vary: 1.1.2
@@ -3728,9 +4036,9 @@ snapshots:
     dependencies:
       to-regex-range: 5.0.1
 
-  finalhandler@2.1.0:
+  finalhandler@2.1.0(supports-color@7.2.0):
     dependencies:
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       on-finished: 2.4.1
@@ -4362,9 +4670,9 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.40.2
       fsevents: 2.3.3
 
-  router@2.2.0:
+  router@2.2.0(supports-color@7.2.0):
     dependencies:
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       depd: 2.0.0
       is-promise: 4.0.0
       parseurl: 1.3.3
@@ -4384,9 +4692,9 @@ snapshots:
 
   semver@7.6.3: {}
 
-  send@1.2.0:
+  send@1.2.0(supports-color@7.2.0):
     dependencies:
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       encodeurl: 2.0.0
       escape-html: 1.0.3
       etag: 1.8.1
@@ -4410,16 +4718,16 @@ snapshots:
       path-to-regexp: 3.3.0
       range-parser: 1.2.0
 
-  serve-static@2.2.0:
+  serve-static@2.2.0(supports-color@7.2.0):
     dependencies:
       encodeurl: 2.0.0
       escape-html: 1.0.3
       parseurl: 1.3.3
-      send: 1.2.0
+      send: 1.2.0(supports-color@7.2.0)
     transitivePeerDependencies:
       - supports-color
 
-  serve@14.2.4:
+  serve@14.2.4(supports-color@7.2.0):
     dependencies:
       '@zeit/schemas': 2.36.0
       ajv: 8.12.0
@@ -4428,7 +4736,7 @@ snapshots:
       chalk: 5.0.1
       chalk-template: 0.4.0
       clipboardy: 3.0.0
-      compression: 1.7.4
+      compression: 1.7.4(supports-color@7.2.0)
       is-port-reachable: 4.0.0
       serve-handler: 6.1.6
       update-check: 1.5.4
@@ -4589,16 +4897,16 @@ snapshots:
       fast-fifo: 1.3.2
       streamx: 2.21.0
 
-  testcontainers@10.25.0:
+  testcontainers@10.25.0(supports-color@7.2.0):
     dependencies:
       '@balena/dockerignore': 1.0.2
       '@types/dockerode': 3.3.38
       archiver: 7.0.1
       async-lock: 1.4.1
       byline: 5.0.0
-      debug: 4.3.7
+      debug: 4.3.7(supports-color@7.2.0)
       docker-compose: 0.24.8
-      dockerode: 4.0.6
+      dockerode: 4.0.6(supports-color@7.2.0)
       get-port: 7.1.0
       proper-lockfile: 4.1.2
       properties-reader: 2.3.0
@@ -4641,6 +4949,12 @@ snapshots:
 
   tslib@2.8.1: {}
 
+  tsx@4.23.9:
+    dependencies:
+      esbuild: 0.28.1
+    optionalDependencies:
+      fsevents: 2.3.3
+
   tweetnacl@0.14.5: {}
 
   type-check@0.4.0:
@@ -4664,12 +4978,12 @@ snapshots:
       typescript: 5.7.2
       yaml: 2.8.1
 
-  typescript-eslint@8.32.0(eslint@9.26.0)(typescript@5.7.2):
+  typescript-eslint@8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2):
     dependencies:
-      '@typescript-eslint/eslint-plugin': 8.32.0(@typescript-eslint/parser@8.32.0(eslint@9.26.0)(typescript@5.7.2))(eslint@9.26.0)(typescript@5.7.2)
-      '@typescript-eslint/parser': 8.32.0(eslint@9.26.0)(typescript@5.7.2)
-      '@typescript-eslint/utils': 8.32.0(eslint@9.26.0)(typescript@5.7.2)
-      eslint: 9.26.0
+      '@typescript-eslint/eslint-plugin': 8.32.0(@typescript-eslint/parser@8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2))(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
+      '@typescript-eslint/parser': 8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
+      '@typescript-eslint/utils': 8.32.0(eslint@9.26.0(supports-color@7.2.0))(supports-color@7.2.0)(typescript@5.7.2)
+      eslint: 9.26.0(supports-color@7.2.0)
       typescript: 5.7.2
     transitivePeerDependencies:
       - supports-color
@@ -4705,10 +5019,10 @@ snapshots:
 
   vary@1.1.2: {}
 
-  vite-node@3.1.3(@types/node@22.15.17):
+  vite-node@3.1.3(@types/node@22.15.17)(supports-color@7.2.0):
     dependencies:
       cac: 6.7.14
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       es-module-lexer: 1.7.0
       pathe: 2.0.3
       vite: 5.4.11(@types/node@22.15.17)
@@ -4732,7 +5046,7 @@ snapshots:
       '@types/node': 22.15.17
       fsevents: 2.3.3
 
-  vitest@3.1.3(@types/node@22.15.17):
+  vitest@3.1.3(@types/node@22.15.17)(supports-color@7.2.0):
     dependencies:
       '@vitest/expect': 3.1.3
       '@vitest/mocker': 3.1.3(vite@5.4.11(@types/node@22.15.17))
@@ -4742,7 +5056,7 @@ snapshots:
       '@vitest/spy': 3.1.3
       '@vitest/utils': 3.1.3
       chai: 5.2.0
-      debug: 4.4.0
+      debug: 4.4.0(supports-color@7.2.0)
       expect-type: 1.2.1
       magic-string: 0.30.17
       pathe: 2.0.3
@@ -4753,7 +5067,7 @@ snapshots:
       tinypool: 1.0.2
       tinyrainbow: 2.0.0
       vite: 5.4.11(@types/node@22.15.17)
-      vite-node: 3.1.3(@types/node@22.15.17)
+      vite-node: 3.1.3(@types/node@22.15.17)(supports-color@7.2.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 22.15.17
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 0000000..8dda36f
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,6 @@
+allowBuilds:
+  '@swc/core': set this to true or false
+  cpu-features: set this to true or false
+  esbuild: set this to true or false
+  protobufjs: set this to true or false
+  ssh2: set this to true or false
diff --git a/src/buffer/index.ts b/src/buffer/index.ts
index 0b61c94..14f6c28 100644
--- a/src/buffer/index.ts
+++ b/src/buffer/index.ts
@@ -7,11 +7,14 @@ import {
   PROTOCOL_VERSION_V2,
   PROTOCOL_VERSION_AUTO,
   PROTOCOL_VERSION_V3,
+  WS,
+  WSS,
 } from "../options";
 import { TimestampUnit } from "../utils";
 import { SenderBufferV1 } from "./bufferv1";
 import { SenderBufferV2 } from "./bufferv2";
 import { SenderBufferV3 } from "./bufferv3";
+import { QwpBuffer } from "../qwp/buffer";
 
 // Default initial buffer size in bytes (64 KB).
 const DEFAULT_BUFFER_SIZE = 65536; //  64 KB
@@ -27,6 +30,11 @@ const DEFAULT_MAX_BUFFER_SIZE = 104857600; // 100 MB
  * @throws Error if protocol version is not specified or is unsupported
  */
 function createBuffer(options: SenderOptions): SenderBuffer {
+  // QWP has no protocol_version; this MUST precede the version switch or a
+  // ws:// sender silently receives SenderBufferV1 and emits ILP text.
+  if (options.protocol === WS || options.protocol === WSS) {
+    return new QwpBuffer();
+  }
   switch (options.protocol_version) {
     case PROTOCOL_VERSION_V3:
       return new SenderBufferV3(options);
diff --git a/src/index.ts b/src/index.ts
index bc8e514..3981134 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -16,5 +16,7 @@ export { createTransport } from "./transport";
 export { TcpTransport } from "./transport/tcp";
 export { HttpTransport } from "./transport/http/stdlib";
 export { UndiciTransport } from "./transport/http/undici";
+export { QwpBuffer } from "./qwp/buffer";
+export { QwpTransport } from "./qwp/transport";
 export type { Logger } from "./logging";
 export { bigintToTwosComplementBytes } from "./utils";
diff --git a/src/options.ts b/src/options.ts
index f09cc6c..015c825 100644
--- a/src/options.ts
+++ b/src/options.ts
@@ -6,6 +6,7 @@ import * as https from "https";
 
 import { Logger } from "./logging";
 import { fetchJson, isBoolean, isInteger } from "./utils";
+import { parseAddrList, Endpoint } from "./qwp/endpoints";
 import { DEFAULT_REQUEST_TIMEOUT } from "./transport/http/base";
 
 const HTTP_PORT = 9000;
@@ -15,6 +16,8 @@ const HTTP = "http";
 const HTTPS = "https";
 const TCP = "tcp";
 const TCPS = "tcps";
+const WS = "ws";
+const WSS = "wss";
 
 const ON = "on";
 const OFF = "off";
@@ -150,6 +153,35 @@ class SenderOptions {
   addr?: string;
   host?: string; // derived from addr
   port?: number; // derived from addr
+  /** ws/wss only: the parsed multi-host list; host/port point at the first entry. */
+  endpoints?: Endpoint[];
+
+  // ws/wss only: reconnect budget + notification inbox capacities (spec 4.2, 9.1).
+  reconnect_initial_backoff_millis?: number;
+  reconnect_max_backoff_millis?: number;
+  reconnect_max_duration_millis?: number;
+  error_inbox_capacity?: number;
+  connection_listener_inbox_capacity?: number;
+  max_frame_rejections?: number;
+  poison_min_escalation_window_millis?: number;
+  /** spec 9.1: keepalive PING interval for the ws socket; < = 0 disables. */
+  durable_ack_keepalive_interval_millis?: number;
+  /** spec 9.1: connect + handshake timeout for a ws endpoint. */
+  auth_timeout_ms?: number;
+  /** spec 9.1 / 7.5: orphan-drainer catch-up cap-gap dwell window. */
+  catch_up_cap_gap_min_escalation_window_millis?: number;
+
+  // ws/wss store-and-forward (spec 8, 9).
+  sf_dir?: string;
+  sender_id?: string;
+  sf_durability?: string;
+  sf_sync_interval_millis?: number;
+  drain_orphans?: boolean;
+  sf_max_total_bytes?: number;
+  sf_segment_bytes?: number;
+  sf_append_deadline_millis?: number;
+  request_durable_ack?: boolean;
+  max_background_drainers?: number;
 
   // replaces `auth` and `jwk` options
   username?: string;
@@ -364,6 +396,8 @@ function parseConfigurationString(
   parseRequestTimeoutOptions(options);
   parseMaxNameLength(options);
   parseStdlibTransport(options);
+  parseQwpOptions(options);
+  parseSfOptions(options);
 }
 
 function parseSettings(
@@ -431,6 +465,26 @@ const ValidConfigKeys = [
   "tls_ca",
   "tls_roots",
   "tls_roots_password",
+  "reconnect_initial_backoff_millis",
+  "reconnect_max_backoff_millis",
+  "reconnect_max_duration_millis",
+  "error_inbox_capacity",
+  "connection_listener_inbox_capacity",
+  "max_frame_rejections",
+  "poison_min_escalation_window_millis",
+  "durable_ack_keepalive_interval_millis",
+  "auth_timeout_ms",
+  "catch_up_cap_gap_min_escalation_window_millis",
+  "sf_dir",
+  "sender_id",
+  "sf_durability",
+  "sf_sync_interval_millis",
+  "drain_orphans",
+  "sf_max_total_bytes",
+  "sf_segment_bytes",
+  "sf_append_deadline_millis",
+  "request_durable_ack",
+  "max_background_drainers",
 ];
 
 function validateConfigKey(key: string) {
@@ -467,16 +521,24 @@ function parseProtocol(options: SenderOptions, configString: string) {
     case HTTPS:
     case TCP:
     case TCPS:
+    case WS:
+    case WSS:
       break;
     default:
       throw new Error(
-        `Invalid protocol: '${options.protocol}', accepted protocols: 'http', 'https', 'tcp', 'tcps'`,
+        `Invalid protocol: '${options.protocol}', accepted protocols: 'http', 'https', 'tcp', 'tcps', 'ws', 'wss'`,
       );
   }
   return index + 2;
 }
 
 function parseProtocolVersion(options: SenderOptions) {
+  if (options.protocol === WS || options.protocol === WSS) {
+    if (options.protocol_version !== undefined && options.protocol_version !== null) {
+      throw new Error("protocol version is not supported for WebSocket protocol");
+    }
+    return; // stays undefined: createBuffer branches on protocol first
+  }
   const protocol_version = options.protocol_version ?? PROTOCOL_VERSION_AUTO;
   switch (protocol_version) {
     case PROTOCOL_VERSION_AUTO:
@@ -506,12 +568,24 @@ function parseAddress(options: SenderOptions) {
     throw new Error("Invalid configuration, 'addr' is required");
   }
 
+  // ws/wss addr is a comma-separated, IPv6-aware endpoint LIST (spec 1.2).
+  // host/port are kept pointing at the first entry so existing transport paths
+  // that read them continue to work.
+  if (options.protocol === WS || options.protocol === WSS) {
+    options.endpoints = parseAddrList(options.addr, HTTP_PORT);
+    options.host = options.endpoints[0].host;
+    options.port = options.endpoints[0].port;
+    return;
+  }
+
   const index = options.addr.indexOf(":");
   if (index < 0) {
     options.host = options.addr;
     switch (options.protocol) {
       case HTTP:
       case HTTPS:
+      case WS:
+      case WSS:
         options.port = HTTP_PORT;
         return;
       case TCP:
@@ -520,7 +594,7 @@ function parseAddress(options: SenderOptions) {
         return;
       default:
         throw new Error(
-          `Invalid protocol: '${options.protocol}', accepted protocols: 'http', 'https', 'tcp', 'tcps'`,
+          `Invalid protocol: '${options.protocol}', accepted protocols: 'http', 'https', 'tcp', 'tcps', 'ws', 'wss'`,
         );
     }
   }
@@ -578,6 +652,62 @@ function parseStdlibTransport(options: SenderOptions) {
   parseBoolean(options, "stdlib_http", "stdlib http");
 }
 
+function parseQwpOptions(options: SenderOptions) {
+  parseInteger(options, "reconnect_initial_backoff_millis", "reconnect initial backoff", 0);
+  parseInteger(options, "reconnect_max_backoff_millis", "reconnect max backoff", 0);
+  parseInteger(options, "reconnect_max_duration_millis", "reconnect max duration", 0);
+  parseInteger(options, "error_inbox_capacity", "error inbox capacity", 16);
+  parseInteger(options, "connection_listener_inbox_capacity", "connection listener inbox capacity", 16);
+  parseInteger(options, "max_frame_rejections", "max frame rejections", 1);
+  parseInteger(options, "poison_min_escalation_window_millis", "poison min escalation window", 0);
+  parseInteger(options, "auth_timeout_ms", "auth timeout", 1);
+  parseInteger(options, "durable_ack_keepalive_interval_millis", "durable ack keepalive interval", -1);
+}
+
+function parseSfOptions(options: SenderOptions) {
+  if (options.protocol !== WS && options.protocol !== WSS) return;
+  parseInteger(options, "sf_max_total_bytes", "sf max total bytes", 1);
+  parseInteger(options, "sf_segment_bytes", "sf segment bytes", 1);
+  parseInteger(options, "sf_append_deadline_millis", "sf append deadline", 1);
+  parseInteger(options, "sf_sync_interval_millis", "sf sync interval millis", 1);
+  parseInteger(options, "max_background_drainers", "max background drainers", 1);
+  parseInteger(options, "catch_up_cap_gap_min_escalation_window_millis", "catch-up cap-gap min escalation window", 0);
+  parseBoolean(options, "drain_orphans", "drain orphans");
+  parseBoolean(options, "request_durable_ack", "request durable ack");
+  if (options.sf_durability) {
+    // Enum values are case-insensitive (spec 9.1.1).
+    const d = options.sf_durability.toLowerCase();
+    switch (d) {
+      case "memory":
+      case "periodic":
+        options.sf_durability = d;
+        break;
+      case "flush":
+      case "append":
+        throw new Error(
+          `sf_durability=${options.sf_durability} is not yet supported (use sf_durability=memory or periodic)`,
+        );
+      default:
+        throw new Error(`Invalid sf_durability option: '${options.sf_durability}'`);
+    }
+  }
+  if (options.sf_dir && options.sf_dir.includes(";")) {
+    throw new Error("Invalid sf_dir option: ';' is not allowed");
+  }
+  if (!options.sf_dir && options.sf_durability === "periodic") {
+    // spec 9.2: periodic durability requires disk mode.
+    throw new Error("sf_durability=periodic requires sf_dir");
+  }
+  if (options.sf_sync_interval_millis !== undefined && options.sf_durability !== "periodic") {
+    // spec 9.2: the sync interval only makes sense against a periodic barrier.
+    throw new Error("sf_sync_interval_millis requires sf_durability=periodic");
+  }
+  if (options.drain_orphans && !options.sf_dir) {
+    // spec 9.2: orphan draining replays slot files, which requires disk mode.
+    throw new Error("drain_orphans requires sf_dir");
+  }
+}
+
 function parseBoolean(
   options: SenderOptions,
   property: string,
@@ -629,6 +759,8 @@ export {
   HTTPS,
   TCP,
   TCPS,
+  WS,
+  WSS,
   PROTOCOL_VERSION_AUTO,
   PROTOCOL_VERSION_V1,
   PROTOCOL_VERSION_V2,
diff --git a/src/qwp/ackTracker.ts b/src/qwp/ackTracker.ts
new file mode 100644
index 0000000..d85aa1a
--- /dev/null
+++ b/src/qwp/ackTracker.ts
@@ -0,0 +1,67 @@
+/**
+ * Bridges the connection-scoped wire sequence to the log-scoped FSN.
+ * Storing a raw seq as an FSN works until the first reconnect and then trims
+ * from near the start of the log, discarding unacked data (spec 6.6.1).
+ */
+export class AckTracker {
+  private fsnAtZero = 0;
+  private nextWireSeq = 0;
+  /** Number of wire frames at the head of this connection that are dictionary
+   *  catch-up frames rather than ring frames. The server assigns these the
+   *  lowest wire seqs, so a populated dictionary shifts every ring frame's seq
+   *  up by this count (spec 6.6.1, handoff B1b). */
+  private catchUpFrames = 0;
+  private ackedFsn = -1;
+
+  /** Call on every successful connect, with the FSN replay resumes at, and the
+   *  number of dictionary catch-up frames that will precede the ring frames. */
+  onConnected(replayStartFsn: number, catchUpFrames = 0): void {
+    this.fsnAtZero = replayStartFsn;
+    this.catchUpFrames = catchUpFrames;
+    this.nextWireSeq = catchUpFrames;
+  }
+
+  /** One ws-> ring frame OR catch-up frame sent on the current connection. */
+  onFrameSent(): void {
+    this.nextWireSeq++;
+  }
+
+  /** Returns the new cumulative acked FSN, or null when the ACK is not applicable. */
+  onAck(wireSeq: number): number | null {
+    const fsn = this.fsnForAck(wireSeq);
+    if (fsn === null) return null;
+    if (fsn > this.ackedFsn) this.ackedFsn = fsn;
+    return this.ackedFsn;
+  }
+
+  /**
+   * Maps an OK's wire sequence to the exact ring FSN it names, with the same
+   * catch-up exclusion and highest-sent clamp as {@link onAck}, but without
+   * advancing cumulative state. Durable-ACK mode needs the exact FSN so it can
+   * retain that frame until its table transactions are durable.
+   */
+  fsnForAck(wireSeq: number): number | null {
+    // An ACK for a catch-up frame (lowest seqs) must never trim a ring frame.
+    if (wireSeq < this.catchUpFrames) return null;
+    const ringIndex = wireSeq - this.catchUpFrames;
+    const highestRingIndex = this.nextWireSeq - 1 - this.catchUpFrames;
+    if (highestRingIndex < 0) return null; // ACK before any ring send
+    const capped = Math.max(0, Math.min(ringIndex, highestRingIndex));
+    return this.fsnAtZero + capped;
+  }
+
+  /**
+   * The FSN a given wire sequence refers to, for mapping a NACK's rejected
+   * frame back to the log (spec 7.4 poison strikes). Unlike onAck this does not
+   * clamp to the highest sent frame or advance ack state — a rejection names the
+   * exact bytes it rejected.
+   */
+  fsnFor(wireSeq: number): number | null {
+    if (wireSeq < this.catchUpFrames) return null;
+    return this.fsnAtZero + (wireSeq - this.catchUpFrames);
+  }
+
+  get acked(): number {
+    return this.ackedFsn;
+  }
+}
diff --git a/src/qwp/buffer.ts b/src/qwp/buffer.ts
new file mode 100644
index 0000000..f895123
--- /dev/null
+++ b/src/qwp/buffer.ts
@@ -0,0 +1,373 @@
+import { Buffer } from "node:buffer";
+import { SenderBuffer } from "../buffer";
+import { TimestampUnit } from "../utils";
+import { QwpTableBuffer } from "./protocol/tableBuffer";
+import { encodeFrame } from "./protocol/frameEncoder";
+import { SymbolDict } from "./protocol/symbolDict";
+import { flattenArray } from "./protocol/columnWriter";
+import {
+  TYPE_BOOLEAN,
+  TYPE_DOUBLE,
+  TYPE_DOUBLE_ARRAY,
+  TYPE_LONG,
+  TYPE_SYMBOL,
+  TYPE_TIMESTAMP,
+  TYPE_VARCHAR,
+  MAX_ROWS_PER_TABLE,
+} from "./protocol/constants";
+
+function toMicros(value: number | bigint, unit: TimestampUnit): bigint {
+  const v = typeof value === "bigint" ? value : BigInt(Math.trunc(value));
+  switch (unit) {
+    case "ns":
+      return v / 1000n;
+    case "ms":
+      return v * 1000n;
+    default:
+      return v;
+  }
+}
+
+function unsupported(what: string): never {
+  throw new Error(`${what} is not supported by the QWP buffer yet`);
+}
+
+export class QwpBuffer implements SenderBuffer {
+  private tables: QwpTableBuffer[] = [];
+  private byName = new Map<string, QwpTableBuffer>();
+  private current?: QwpTableBuffer;
+  private rows = 0;
+  private dict?: SymbolDict;
+  /** Highest id appended completely to the write-ahead side file. */
+  private persistedMaxId = -1;
+  /** Highest id confirmed as published to the store-and-forward ring. */
+  private confirmedMaxId = -1;
+  private gorilla = true;
+  private deferCommit = false;
+  private persist?: (entries: string[]) => void;
+  /**
+   * Baseline to advance `confirmedMaxId` to once THIS sealed batch's frame(s)
+   * have been queued onto the store-and-forward ring (spec 5.2). Populated by
+   * {@link sealFrames} from the write-ahead persist; -1 when delta mode is not
+   * active or the batch introduced no new symbols. See {@link confirmDeltaPublished}.
+   */
+  private deltaTarget = -1;
+
+  /**
+   * Attach a connection-scoped symbol dictionary (delta mode) plus an optional
+   * write-ahead persist callback, or undefined to stay in full-dict mode.
+   * `persist` is invoked with every batch of newly introduced symbols before
+   * the owning frame is published (spec 8.1.6); if it throws, the buffer
+   * degrades permanently to full-dict mode (spec 5.2).
+   */
+  attachDict(
+    d: SymbolDict | undefined,
+    persist?: (entries: string[]) => void,
+  ): void {
+    this.dict = d;
+    this.persist = persist;
+  }
+
+  /**
+   * One-way, permanent degradation. The side file can start failing appends
+   * while segments stay writable, because segments are pre-allocated and the
+   * dictionary is the one thing still growing. A fixed mode would turn that
+   * into total, permanent ingestion loss (spec 5.2).
+   */
+  private disableDeltaDict(): void {
+    this.dict = undefined;
+    this.persist = undefined;
+    this.persistedMaxId = -1;
+    this.confirmedMaxId = -1;
+  }
+
+  setConfirmedMaxId(id: number): void {
+    this.confirmedMaxId = id;
+    // Recovery calls this with the tail loaded from .symbol-dict. Reconnects
+    // may call it again with the same or a later already-persisted baseline.
+    if (id > this.persistedMaxId) this.persistedMaxId = id;
+  }
+
+  setDeferCommit(on: boolean): void {
+    this.deferCommit = on;
+  }
+
+  /**
+   * Report the delta baseline this sealed batch should advance to once its
+   * frames are queued onto the ring, or -1 when nothing advances (spec 5.2).
+   * Consumed by the transport's publish path.
+   */
+  get pendingDeltaTarget(): number {
+    return this.deltaTarget;
+  }
+
+  /**
+   * Advance the confirmed delta baseline because the sealed batch's frame(s)
+   * were successfully queued onto the ring. Only ever forward; a batch that
+   * introduced no new symbols leaves it untouched (spec 5.2).
+   */
+  confirmDeltaPublished(target = this.deltaTarget): void {
+    if (target > this.confirmedMaxId) this.confirmedMaxId = target;
+  }
+
+  reset(): SenderBuffer {
+    // Clears the staging tables only. The confirmed delta baseline and the
+    // write-ahead dictionary survive: they describe the connection-scoped
+    // dictionary, which is independent of any one buffered batch (spec 5.2).
+    this.tables = [];
+    this.byName = new Map();
+    this.current = undefined;
+    this.rows = 0;
+    return this;
+  }
+
+  table(table: string): SenderBuffer {
+    let t = this.byName.get(table);
+    if (!t) {
+      t = new QwpTableBuffer(table);
+      this.byName.set(table, t);
+      this.tables.push(t);
+    }
+    this.current = t;
+    return this;
+  }
+
+  private require(): QwpTableBuffer {
+    if (!this.current)
+      throw new Error("table name must be set before adding columns");
+    return this.current;
+  }
+
+  /**
+   * A setter that throws mid-row must roll every column back to the last row
+   * boundary, or columns desynchronise and every later frame is malformed while
+   * still looking structurally valid (spec 4.1.1).
+   */
+  private guard<R>(fn: () => R): R {
+    try {
+      return fn();
+    } catch (e) {
+      this.current?.rollbackRow();
+      throw e;
+    }
+  }
+
+  symbol(name: string, value: unknown): SenderBuffer {
+    return this.guard(() => {
+      const col = this.require().getOrCreateColumn(name, TYPE_SYMBOL);
+      if (col) {
+        const text = String(value);
+        // Keep the id AND the text. Delta mode encodes the id; a runtime
+        // fallback to full-dict mode needs the text back (spec 5.2).
+        col.values.push(
+          this.dict ? { id: this.dict.getOrAdd(text), text } : text,
+        );
+      }
+      return this;
+    });
+  }
+
+  intColumn(name: string, value: number): SenderBuffer {
+    return this.guard(() => {
+      if (!Number.isInteger(value))
+        throw new Error(`value must be an integer, received ${value}`);
+      const col = this.require().getOrCreateColumn(name, TYPE_LONG);
+      if (col) col.values.push(BigInt(value));
+      return this;
+    });
+  }
+
+  floatColumn(name: string, value: number): SenderBuffer {
+    return this.guard(() => {
+      const col = this.require().getOrCreateColumn(name, TYPE_DOUBLE);
+      if (col) col.values.push(value);
+      return this;
+    });
+  }
+
+  timestampColumn(
+    name: string,
+    value: number | bigint,
+    unit: TimestampUnit = "us",
+  ): SenderBuffer {
+    return this.guard(() => {
+      const col = this.require().getOrCreateColumn(name, TYPE_TIMESTAMP);
+      if (col) col.values.push(toMicros(value, unit));
+      return this;
+    });
+  }
+
+  at(timestamp: number | bigint, unit: TimestampUnit = "us"): void {
+    const t = this.require();
+    // Designated timestamp column: an empty schema name signals the designated
+    // timestamp (QwpSchema nameLen=0); the server names it "timestamp".
+    const col = t.getOrCreateColumn("", TYPE_TIMESTAMP);
+    if (col) col.values.push(toMicros(timestamp, unit));
+    t.nextRow();
+    this.rows++;
+    this.current = undefined;
+  }
+
+  atNow(): void {
+    const t = this.require();
+    t.nextRow();
+    this.rows++;
+    this.current = undefined;
+  }
+
+  /**
+   * Seals the buffered rows into one or more frames. A flush produces more
+   * than one frame only when the encoded batch exceeds maxBatchSize (spec 5.1);
+   * splitting itself lands in Task 9.
+   */
+  sealFrames(maxBatchSize: number): Buffer[] {
+    const dirty = this.tables.filter((t) => t.rowCount > 0);
+    if (dirty.length === 0) return [];
+    // Spec 6.4: a single table is capped at DEFAULT_MAX_ROWS_PER_TABLE. The
+    // server raises this default operationally, so a client-side refusal could
+    // reject a frame a correctly-configured server accepts — but a frame that
+    // crosses it is refused by every default server, and under store-and-forward
+    // a refused frame is already durable and would replay forever. Fail the
+    // batch here, before any byte is published, with a diagnostic that names the
+    // table and the knob that raises it.
+    for (const t of dirty) {
+      if (t.rowCount > MAX_ROWS_PER_TABLE) {
+        throw new Error(
+          `table '${t.name}' carries ${t.rowCount} rows, exceeding the server ` +
+            `DEFAULT_MAX_ROWS_PER_TABLE of ${MAX_ROWS_PER_TABLE} — flush more ` +
+            `often (lower auto_flush_rows, or call flush()/sealFrames() sooner)` +
+            ` so each batch stays under the limit`,
+        );
+      }
+    }
+    this.deltaTarget = -1;
+
+    // Write-ahead persist this batch's new symbols before encoding any frame.
+    // With the buffer already containing this batch's rows, a failure here
+    // degrades to full-dict mode; the persisted symbols are not yet on any
+    // wire, so nothing must be retained (spec 5.2, 8.1.6).
+    //
+    // Only the PERSIST cursor moves here; the delta baseline (confirmedMaxId)
+    // is deliberately NOT advanced. Per spec 5.2 it may move only after a
+    // frame carrying these symbols is queued onto the ring (a failed publish
+    // would otherwise advance the baseline past ids the server never saw and
+    // earn a DICTIONARY_GAP on the next frame). The transport calls
+    // confirmDeltaPublished() on that ring-append success.
+    const delta = this.dict !== undefined;
+    if (delta) {
+      // Persistence and publication have distinct cursors. If a side-file
+      // append succeeds but ring publication later fails, the next seal must
+      // not append the same positional symbols again; it still encodes them
+      // from confirmedMaxId so the server receives everything it lacks.
+      const fresh = this.dict!.entriesFrom(this.persistedMaxId + 1);
+      if (fresh.length > 0) {
+        try {
+          this.persist?.(fresh);
+          this.persistedMaxId = this.dict!.size() - 1;
+          this.deltaTarget = this.persistedMaxId;
+        } catch {
+          this.disableDeltaDict();
+        }
+      } else {
+        // Symbols can already be write-ahead persisted while still awaiting a
+        // successful ring publication from an earlier seal.
+        this.deltaTarget =
+          this.dict!.size() - 1 > this.confirmedMaxId
+            ? this.dict!.size() - 1
+            : -1;
+      }
+    }
+
+    const opts = {
+      gorilla: this.gorilla,
+      dict: this.dict,
+      confirmedMaxId: this.confirmedMaxId,
+    };
+    const combined = encodeFrame(dirty, {
+      ...opts,
+      deferCommit: this.deferCommit,
+    });
+    if (combined.length <= maxBatchSize) {
+      this.reset();
+      return [combined];
+    }
+
+    // Pre-flight EVERY split frame before publishing any: discovering an
+    // oversized frame mid-publish strands the already-sent prefix and a later
+    // commit delivers a partial batch (spec 5.1).
+    const parts: Buffer[] = [];
+    for (let i = 0; i < dirty.length; i++) {
+      const isLast = i === dirty.length - 1;
+      // Delta-split: the FIRST part carries the whole batch's delta; later
+      // parts reference only ids that first part registered, so their delta is
+      // empty. Encoding them against the pre-advance baseline would re-ship
+      // the same entries and re-register them positionally on the server,
+      // silently renumbering later ids. Pin later parts to the post-batch
+      // baseline (spec 5.2) — safe because they publish only after part 0.
+      const partBaseline =
+        delta && i > 0 ? this.dict!.size() - 1 : opts.confirmedMaxId;
+      const f = encodeFrame([dirty[i]], {
+        ...opts,
+        confirmedMaxId: partBaseline,
+        deferCommit: this.deferCommit ? true : !isLast,
+      });
+      if (f.length > maxBatchSize) {
+        throw new Error(
+          `batch cannot fit the server cap however it is split ` +
+            `[table=${dirty[i].name}, frameSize=${f.length}, cap=${maxBatchSize}]`,
+        );
+      }
+      parts.push(f);
+    }
+    this.reset();
+    return parts;
+  }
+
+  toBufferNew(): Buffer | null {
+    const frames = this.sealFrames(Number.MAX_SAFE_INTEGER);
+    if (frames.length === 0) return null;
+    if (frames.length > 1) {
+      throw new Error("QWP produced multiple frames; use sealFrames()");
+    }
+    return frames[0];
+  }
+
+  toBufferView(): Buffer {
+    throw new Error("toBufferView is not supported by the QWP buffer");
+  }
+
+  currentPosition(): number {
+    return this.rows;
+  }
+
+  // Column types arriving in a later plan — fail loudly rather than emit wrong bytes.
+  stringColumn(name: string, value: string): SenderBuffer {
+    return this.guard(() => {
+      if (typeof value !== "string")
+        throw new Error("stringColumn accepts only string values");
+      const col = this.require().getOrCreateColumn(name, TYPE_VARCHAR);
+      if (col) col.values.push(value);
+      return this;
+    });
+  }
+  booleanColumn(name: string, value: boolean): SenderBuffer {
+    return this.guard(() => {
+      const col = this.require().getOrCreateColumn(name, TYPE_BOOLEAN);
+      if (col) col.values.push(value);
+      return this;
+    });
+  }
+  arrayColumn(name: string, value: unknown[]): SenderBuffer {
+    return this.guard(() => {
+      const col = this.require().getOrCreateColumn(name, TYPE_DOUBLE_ARRAY);
+      if (col) col.values.push(flattenArray(value));
+      return this;
+    });
+  }
+  decimalColumnText(): SenderBuffer {
+    return unsupported("decimalColumnText");
+  }
+  decimalColumn(): SenderBuffer {
+    return unsupported("decimalColumn");
+  }
+}
diff --git a/src/qwp/dispatcher.ts b/src/qwp/dispatcher.ts
new file mode 100644
index 0000000..e91ccb7
--- /dev/null
+++ b/src/qwp/dispatcher.ts
@@ -0,0 +1,42 @@
+/**
+ * Bounded inbox that drops the OLDEST entry when full (spec 4.2). Watermarks
+ * are monotonic, so the newest entry is always the most informative and
+ * dropping the head compresses information rather than losing it.
+ * The handler is never invoked on the caller's stack.
+ */
+export class Dispatcher<T> {
+  private readonly queue: T[] = [];
+  private scheduled = false;
+  dropped = 0;
+
+  constructor(
+    private readonly capacity: number,
+    private readonly handler: (item: T) => void,
+  ) {
+    if (capacity < 1) throw new Error("capacity must be >= 1");
+  }
+
+  offer(item: T): void {
+    if (this.queue.length >= this.capacity) {
+      this.queue.shift();
+      this.dropped++;
+    }
+    this.queue.push(item);
+    if (!this.scheduled) {
+      this.scheduled = true;
+      setImmediate(() => this.drain());
+    }
+  }
+
+  private drain(): void {
+    this.scheduled = false;
+    while (this.queue.length > 0) {
+      const item = this.queue.shift()!;
+      try {
+        this.handler(item);
+      } catch {
+        /* a handler must never break the sender */
+      }
+    }
+  }
+}
diff --git a/src/qwp/durableAckTracker.ts b/src/qwp/durableAckTracker.ts
new file mode 100644
index 0000000..1f79450
--- /dev/null
+++ b/src/qwp/durableAckTracker.ts
@@ -0,0 +1,58 @@
+export interface TableTxn {
+  name: string;
+  seqTxn: bigint;
+}
+
+/**
+ * Correlates OK-level per-table transaction numbers with cumulative
+ * DURABLE_ACK table watermarks. Entries retire strictly in FSN order so a
+ * later durable batch can never trim through an earlier unresolved one.
+ */
+export class DurableAckTracker {
+  private readonly pending = new Map<number, TableTxn[]>();
+  private readonly watermarks = new Map<string, bigint>();
+  private acked = -1;
+
+  reset(ackedFsn: number): void {
+    this.pending.clear();
+    this.watermarks.clear();
+    this.acked = ackedFsn;
+  }
+
+  onOk(fsn: number, tables: TableTxn[]): number | null {
+    if (fsn <= this.acked) return null;
+    this.pending.set(
+      fsn,
+      tables.map((t) => ({ name: t.name, seqTxn: t.seqTxn })),
+    );
+    return this.drain();
+  }
+
+  onDurableAck(tables: TableTxn[]): number | null {
+    for (const { name, seqTxn } of tables) {
+      const current = this.watermarks.get(name);
+      if (current === undefined || seqTxn > current) {
+        this.watermarks.set(name, seqTxn);
+      }
+    }
+    return this.drain();
+  }
+
+  private drain(): number | null {
+    const before = this.acked;
+    for (;;) {
+      const next = this.pending.get(this.acked + 1);
+      if (!next || !this.covered(next)) break;
+      this.pending.delete(this.acked + 1);
+      this.acked++;
+    }
+    return this.acked > before ? this.acked : null;
+  }
+
+  private covered(tables: TableTxn[]): boolean {
+    return tables.every((t) => {
+      const watermark = this.watermarks.get(t.name);
+      return watermark !== undefined && watermark >= t.seqTxn;
+    });
+  }
+}
diff --git a/src/qwp/endpoints.ts b/src/qwp/endpoints.ts
new file mode 100644
index 0000000..c4d2108
--- /dev/null
+++ b/src/qwp/endpoints.ts
@@ -0,0 +1,57 @@
+export interface Endpoint {
+  host: string;
+  port: number;
+}
+
+export function parseAddrList(addr: string, defaultPort: number): Endpoint[] {
+  const out: Endpoint[] = [];
+  const seen = new Set<string>();
+  for (const raw of addr.split(",")) {
+    const entry = raw.trim();
+    if (!entry) continue;
+    let host: string;
+    let port: number;
+
+    if (entry[0] === "[") {
+      const close = entry.indexOf("]");
+      if (close < 0) throw new Error(`missing closing ']' in IPv6 addr entry: ${entry}`);
+      host = entry.slice(1, close);
+      if (close === entry.length - 1) {
+        port = defaultPort;
+      } else if (entry[close + 1] !== ":") {
+        throw new Error(`expected ':' after ']' in IPv6 addr entry: ${entry}`);
+      } else {
+        port = parsePort(entry.slice(close + 2), entry);
+      }
+    } else if (entry.indexOf(":") !== entry.lastIndexOf(":")) {
+      // Unbracketed multi-colon: bare IPv6, default port. A custom port needs brackets.
+      host = entry;
+      port = defaultPort;
+    } else {
+      const colon = entry.indexOf(":");
+      if (colon < 0) {
+        host = entry;
+        port = defaultPort;
+      } else {
+        host = entry.slice(0, colon).trim();
+        port = parsePort(entry.slice(colon + 1), entry);
+      }
+    }
+
+    if (!host) throw new Error(`empty host in addr entry: ${entry}`);
+    const key = `${port}/${host}`;
+    if (seen.has(key)) throw new Error(`duplicate addr entry: ${entry}`);
+    seen.add(key);
+    out.push({ host, port });
+  }
+  if (out.length === 0) throw new Error("addr is missing");
+  return out;
+}
+
+function parsePort(s: string, entry: string): number {
+  const p = Number.parseInt(s, 10);
+  if (!Number.isInteger(p) || p < 1 || p > 65535) {
+    throw new Error(`invalid port in addr entry: ${entry}`);
+  }
+  return p;
+}
diff --git a/src/qwp/errors.ts b/src/qwp/errors.ts
new file mode 100644
index 0000000..2f54163
--- /dev/null
+++ b/src/qwp/errors.ts
@@ -0,0 +1,69 @@
+import { STATUS } from "./protocol/response";
+
+export enum Category {
+  SCHEMA_MISMATCH = "SCHEMA_MISMATCH",
+  PARSE_ERROR = "PARSE_ERROR",
+  INTERNAL_ERROR = "INTERNAL_ERROR",
+  SECURITY_ERROR = "SECURITY_ERROR",
+  WRITE_ERROR = "WRITE_ERROR",
+  NOT_WRITABLE = "NOT_WRITABLE",
+  DICTIONARY_GAP = "DICTIONARY_GAP",
+  PROTOCOL_VIOLATION = "PROTOCOL_VIOLATION",
+  DATA_LOSS = "DATA_LOSS",
+  UNKNOWN = "UNKNOWN",
+}
+
+export enum Policy {
+  RETRIABLE = "RETRIABLE",
+  RETRIABLE_OTHER = "RETRIABLE_OTHER",
+  TERMINAL = "TERMINAL",
+  ABANDONED = "ABANDONED",
+}
+
+export class SenderError extends Error {
+  constructor(
+    readonly category: Category,
+    readonly policy: Policy,
+    message: string,
+    readonly serverStatus = -1,
+    readonly fromFsn = -1,
+    readonly toFsn = -1,
+    readonly quarantinedPath?: string,
+  ) {
+    super(message);
+    this.name = "SenderError";
+  }
+}
+
+export function classify(status: number): Category {
+  switch (status) {
+    case STATUS.SCHEMA_MISMATCH: return Category.SCHEMA_MISMATCH;
+    case STATUS.PARSE_ERROR: return Category.PARSE_ERROR;
+    case STATUS.INTERNAL_ERROR: return Category.INTERNAL_ERROR;
+    case STATUS.SECURITY_ERROR: return Category.SECURITY_ERROR;
+    case STATUS.WRITE_ERROR: return Category.WRITE_ERROR;
+    case STATUS.NOT_WRITABLE: return Category.NOT_WRITABLE;
+    case STATUS.DICTIONARY_GAP: return Category.DICTIONARY_GAP;
+    default: return Category.UNKNOWN;
+  }
+}
+
+/**
+ * There is no drop policy. UNKNOWN fails OPEN so a status byte from a newer
+ * server degrades to a retry rather than a dead sender (spec 7.3).
+ */
+export function defaultPolicyFor(c: Category): Policy {
+  switch (c) {
+    case Category.WRITE_ERROR:
+    case Category.INTERNAL_ERROR:
+    case Category.DICTIONARY_GAP:
+    case Category.UNKNOWN:
+      return Policy.RETRIABLE;
+    case Category.NOT_WRITABLE:
+      return Policy.RETRIABLE_OTHER;
+    case Category.DATA_LOSS:
+      return Policy.ABANDONED;
+    default:
+      return Policy.TERMINAL;
+  }
+}
diff --git a/src/qwp/hostTracker.ts b/src/qwp/hostTracker.ts
new file mode 100644
index 0000000..0d84a37
--- /dev/null
+++ b/src/qwp/hostTracker.ts
@@ -0,0 +1,67 @@
+export enum HostState {
+  HEALTHY = 0,
+  UNKNOWN = 1,
+  TRANSIENT_REJECT = 2,
+  TRANSPORT_ERROR = 3,
+  TOPOLOGY_REJECT = 4,
+}
+
+/**
+ * State-ranked, round-based endpoint selection. The ingest sender is
+ * zone-blind, so ranking is state-only (spec 1.2) — do not add zone tiers.
+ */
+export class HostTracker {
+  private readonly states: HostState[];
+  private attempted: boolean[];
+
+  constructor(private readonly hostCount: number) {
+    if (hostCount <= 0) throw new Error("hostCount must be > 0");
+    this.states = new Array(hostCount).fill(HostState.UNKNOWN);
+    this.attempted = new Array(hostCount).fill(false);
+  }
+
+  record(index: number, state: HostState): void {
+    this.states[index] = state;
+  }
+
+  private best(attempted: boolean[]): number | null {
+    let bestIdx: number | null = null;
+    for (let i = 0; i < this.hostCount; i++) {
+      if (attempted[i]) continue;
+      if (bestIdx === null || this.states[i] < this.states[bestIdx]) bestIdx = i;
+    }
+    return bestIdx;
+  }
+
+  pickNext(): number | null {
+    const i = this.best(this.attempted);
+    if (i === null) return null;
+    this.attempted[i] = true;
+    return i;
+  }
+
+  isRoundExhausted(): boolean {
+    return this.attempted.every(Boolean);
+  }
+
+  beginRound(): void {
+    this.attempted = new Array(this.hostCount).fill(false);
+  }
+
+  /**
+   * A walker-local cursor. Background drainers MUST use this: sharing the
+   * round lets a drainer steal endpoints from the foreground sweep, which
+   * presents as unexplained ALL_ENDPOINTS_UNREACHABLE (spec 1.2).
+   */
+  newCursor(): { pickNext(): number | null } {
+    const local = new Array(this.hostCount).fill(false);
+    return {
+      pickNext: () => {
+        const i = this.best(local);
+        if (i === null) return null;
+        local[i] = true;
+        return i;
+      },
+    };
+  }
+}
diff --git a/src/qwp/poison.ts b/src/qwp/poison.ts
new file mode 100644
index 0000000..f19c3ca
--- /dev/null
+++ b/src/qwp/poison.ts
@@ -0,0 +1,36 @@
+/**
+ * Escalation requires a strike count AND a wall-clock dwell (spec 7.4).
+ * A count alone false-positives a brief outage into a producer-fatal terminal,
+ * because with pacing four strikes can accrue in well under a second.
+ */
+export class PoisonDetector {
+  private suspectFsn = -1;
+  private strikes = 0;
+  private firstStrikeAt = 0;
+
+  constructor(
+    private readonly maxStrikes: number,
+    private readonly minWindowMillis: number,
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  /** Returns true when the frame should escalate to PROTOCOL_VIOLATION. */
+  strike(fsn: number): boolean {
+    if (fsn !== this.suspectFsn) {
+      this.suspectFsn = fsn;
+      this.strikes = 0;
+      this.firstStrikeAt = this.now();
+    }
+    this.strikes++;
+    const dwell = this.now() - this.firstStrikeAt;
+    return this.strikes >= this.maxStrikes && dwell >= this.minWindowMillis;
+  }
+
+  /** Only acceptance AT OR BEYOND the suspect clears it. */
+  accept(ackedFsn: number): void {
+    if (this.suspectFsn >= 0 && ackedFsn >= this.suspectFsn) {
+      this.suspectFsn = -1;
+      this.strikes = 0;
+    }
+  }
+}
diff --git a/src/qwp/protocol/bits.ts b/src/qwp/protocol/bits.ts
new file mode 100644
index 0000000..5863f7d
--- /dev/null
+++ b/src/qwp/protocol/bits.ts
@@ -0,0 +1,27 @@
+import { Buffer } from "node:buffer";
+
+/** LSB-first bit writer; trailing bits are zero-padded to a byte boundary. */
+export class BitWriter {
+  private readonly buf: Buffer;
+  private byteIndex = 0;
+  private bitIndex = 0;
+
+  constructor(capacity: number) {
+    this.buf = Buffer.alloc(capacity);
+  }
+
+  writeBits(value: number, count: number): void {
+    for (let i = 0; i < count; i++) {
+      if ((value >>> i) & 1) this.buf[this.byteIndex] |= 1 << this.bitIndex;
+      if (++this.bitIndex === 8) {
+        this.bitIndex = 0;
+        this.byteIndex++;
+      }
+    }
+  }
+
+  finish(): Buffer {
+    const len = this.byteIndex + (this.bitIndex > 0 ? 1 : 0);
+    return this.buf.subarray(0, len);
+  }
+}
diff --git a/src/qwp/protocol/columnWriter.ts b/src/qwp/protocol/columnWriter.ts
new file mode 100644
index 0000000..710b44b
--- /dev/null
+++ b/src/qwp/protocol/columnWriter.ts
@@ -0,0 +1,346 @@
+import { Buffer } from "node:buffer";
+import { writeVarint, varintSize } from "./varint";
+import { ColumnBuffer } from "./tableBuffer";
+import * as T from "./constants";
+import { gorillaSize, encodeGorilla } from "./gorilla";
+
+export interface EncodeOpts {
+  gorilla: boolean;
+  /** Present+true means global-symbol delta mode: per-column dict omitted. */
+  delta?: boolean;
+}
+
+/**
+ * A symbol value is either a plain string (full-dict mode from the start) or
+ * an object carrying both the global id and the text (delta mode, or a runtime
+ * fallback back to full-dict mode where the text is needed again).
+ */
+function symbolText(v: unknown): string {
+  return typeof v === "string" ? v : (v as { text: string }).text;
+}
+function symbolId(v: unknown): number {
+  return typeof v === "number" ? v : (v as { id: number }).id;
+}
+
+function nullCountOf(col: ColumnBuffer): number {
+  let n = 0;
+  for (const v of col.nulls) if (v) n++;
+  return n;
+}
+
+function fixedWidth(type: number): number | undefined {
+  switch (type) {
+    case T.TYPE_BYTE:
+      return 1;
+    case T.TYPE_SHORT:
+    case T.TYPE_CHAR:
+      return 2;
+    case T.TYPE_INT:
+    case T.TYPE_FLOAT:
+    case T.TYPE_IPV4:
+      return 4;
+    case T.TYPE_LONG:
+    case T.TYPE_DOUBLE:
+    case T.TYPE_DATE:
+      return 8;
+    case T.TYPE_UUID:
+      return 16;
+    case T.TYPE_LONG256:
+      return 32;
+    default:
+      return undefined;
+  }
+}
+
+export function flattenArray(a: unknown[]): { dims: number[]; data: number[] } {
+  const dims: number[] = [];
+  let level: unknown = a;
+  while (Array.isArray(level)) {
+    dims.push(level.length);
+    level = level[0];
+  }
+  const data: number[] = [];
+  const walk = (node: unknown, depth: number): void => {
+    if (depth === dims.length) {
+      data.push(node as number);
+      return;
+    }
+    if (!Array.isArray(node) || node.length !== dims[depth]) {
+      throw new Error("irregular array shape");
+    }
+    for (const child of node) walk(child, depth + 1);
+  };
+  walk(a, 0);
+  return { dims, data };
+}
+
+export function columnPayloadSize(
+  col: ColumnBuffer,
+  rowCount: number,
+  opts: EncodeOpts,
+): number {
+  let n = 1;
+  if (nullCountOf(col) > 0) n += Math.ceil(rowCount / 8);
+  const v = col.values.length;
+
+  if (col.type === T.TYPE_BOOLEAN) return n + Math.ceil(v / 8);
+
+  if (col.type === T.TYPE_TIMESTAMP || col.type === T.TYPE_TIMESTAMP_NANOS) {
+    if (!opts.gorilla) return n + v * 8;
+    const ts = col.values.map((x) => BigInt(x as bigint));
+    const size = ts.length > 2 ? gorillaSize(ts) : -1;
+    if (size > 0) return n + 1 + size;
+    return n + 1 + ts.length * 8;
+  }
+
+  const w = fixedWidth(col.type);
+  if (w !== undefined) return n + v * w;
+
+  if (col.type === T.TYPE_SYMBOL) {
+    if (opts.delta) {
+      let n2 = 0;
+      for (const v of col.values) n2 += varintSize(symbolId(v));
+      return n + n2;
+    }
+    const dict = [...new Set(col.values.map((v) => symbolText(v)) as string[])];
+    n += varintSize(dict.length);
+    for (const s of dict) {
+      const b = Buffer.byteLength(s, "utf8");
+      n += varintSize(b) + b;
+    }
+    for (const v of col.values) n += varintSize(dict.indexOf(symbolText(v)));
+    return n;
+  }
+
+  if (col.type === T.TYPE_VARCHAR || col.type === T.TYPE_BINARY) {
+    let data = 0;
+    for (const s of col.values) {
+      data +=
+        col.type === T.TYPE_VARCHAR
+          ? Buffer.byteLength(s as string, "utf8")
+          : (s as unknown as Buffer).length;
+    }
+    return n + (v + 1) * 4 + data;
+  }
+
+  if (col.type === T.TYPE_DOUBLE_ARRAY || col.type === T.TYPE_LONG_ARRAY) {
+    let total = 0;
+    for (const val of col.values) {
+      const a = val as unknown as { dims: number[]; data: number[] };
+      total += 1 + a.dims.length * 4 + a.data.length * 8;
+    }
+    return n + total;
+  }
+  if (col.type === T.TYPE_GEOHASH) {
+    const p = col.geohashPrecision ?? 1;
+    return n + varintSize(p) + v * Math.ceil(p / 8);
+  }
+  if (col.type === T.TYPE_DECIMAL64) return n + 1 + v * 8;
+  if (col.type === T.TYPE_DECIMAL128) return n + 1 + v * 16;
+  if (col.type === T.TYPE_DECIMAL256) return n + 1 + v * 32;
+
+  throw new Error(`unsupported QWP column type: 0x${col.type.toString(16)}`);
+}
+
+export function writeColumn(
+  buf: Buffer,
+  offset: number,
+  col: ColumnBuffer,
+  rowCount: number,
+  opts: EncodeOpts,
+): number {
+  let o = offset;
+  if (nullCountOf(col) > 0) {
+    buf[o++] = 1;
+    const bytes = Math.ceil(rowCount / 8);
+    buf.fill(0, o, o + bytes);
+    for (let i = 0; i < rowCount; i++) {
+      if (col.nulls[i]) buf[o + (i >>> 3)] |= 1 << (i & 7);
+    }
+    o += bytes;
+  } else {
+    buf[o++] = 0;
+  }
+
+  switch (col.type) {
+    case T.TYPE_BOOLEAN: {
+      const bytes = Math.ceil(col.values.length / 8);
+      buf.fill(0, o, o + bytes);
+      col.values.forEach((v, i) => {
+        if (v) buf[o + (i >>> 3)] |= 1 << (i & 7);
+      });
+      return o + bytes;
+    }
+    case T.TYPE_BYTE:
+      for (const v of col.values) buf.writeInt8(Number(v), o++);
+      return o;
+    case T.TYPE_SHORT:
+      for (const v of col.values) {
+        buf.writeInt16LE(Number(v), o);
+        o += 2;
+      }
+      return o;
+    case T.TYPE_CHAR:
+      for (const v of col.values) {
+        buf.writeUInt16LE((v as string).charCodeAt(0), o);
+        o += 2;
+      }
+      return o;
+    case T.TYPE_INT:
+      for (const v of col.values) {
+        buf.writeInt32LE(Number(v), o);
+        o += 4;
+      }
+      return o;
+    case T.TYPE_IPV4:
+      for (const v of col.values) {
+        buf.writeUInt32LE(Number(v) >>> 0, o);
+        o += 4;
+      }
+      return o;
+    case T.TYPE_FLOAT:
+      for (const v of col.values) {
+        buf.writeFloatLE(Number(v), o);
+        o += 4;
+      }
+      return o;
+    case T.TYPE_LONG:
+    case T.TYPE_DATE:
+      for (const v of col.values) {
+        buf.writeBigInt64LE(BigInt(v as number | bigint), o);
+        o += 8;
+      }
+      return o;
+    case T.TYPE_TIMESTAMP:
+    case T.TYPE_TIMESTAMP_NANOS: {
+      const ts = col.values.map((x) => BigInt(x as bigint));
+      if (!opts.gorilla) {
+        for (const v of ts) {
+          buf.writeBigInt64LE(v, o);
+          o += 8;
+        }
+        return o;
+      }
+      const size = ts.length > 2 ? gorillaSize(ts) : -1;
+      if (size > 0) {
+        buf.writeUInt8(T.ENCODING_GORILLA, o++);
+        encodeGorilla(ts).copy(buf, o);
+        return o + size;
+      }
+      buf.writeUInt8(T.ENCODING_UNCOMPRESSED, o++);
+      for (const v of ts) {
+        buf.writeBigInt64LE(v, o);
+        o += 8;
+      }
+      return o;
+    }
+    case T.TYPE_DOUBLE:
+      for (const v of col.values) {
+        buf.writeDoubleLE(Number(v), o);
+        o += 8;
+      }
+      return o;
+    case T.TYPE_UUID:
+      for (const v of col.values) {
+        (v as unknown as Buffer).copy(buf, o);
+        o += 16;
+      }
+      return o;
+    case T.TYPE_LONG256:
+      for (const v of col.values) {
+        (v as unknown as Buffer).copy(buf, o);
+        o += 32;
+      }
+      return o;
+    case T.TYPE_SYMBOL: {
+      if (opts.delta) {
+        for (const v of col.values) o = writeVarint(buf, o, symbolId(v));
+        return o;
+      }
+      const dict = [...new Set(col.values.map((v) => symbolText(v)) as string[])];
+      o = writeVarint(buf, o, dict.length);
+      for (const s of dict) {
+        const n = Buffer.byteLength(s, "utf8");
+        o = writeVarint(buf, o, n);
+        buf.write(s, o, "utf8");
+        o += n;
+      }
+      for (const v of col.values) o = writeVarint(buf, o, dict.indexOf(symbolText(v)));
+      return o;
+    }
+    case T.TYPE_VARCHAR:
+    case T.TYPE_BINARY: {
+      const parts: Buffer[] = col.values.map((s) =>
+        col.type === T.TYPE_VARCHAR
+          ? Buffer.from(s as string, "utf8")
+          : (s as unknown as Buffer),
+      );
+      let acc = 0;
+      buf.writeUInt32LE(0, o);
+      o += 4;
+      for (const p of parts) {
+        acc += p.length;
+        buf.writeUInt32LE(acc, o);
+        o += 4;
+      }
+      for (const p of parts) {
+        p.copy(buf, o);
+        o += p.length;
+      }
+      return o;
+    }
+    case T.TYPE_DOUBLE_ARRAY:
+    case T.TYPE_LONG_ARRAY: {
+      for (const val of col.values) {
+        const a = val as unknown as { dims: number[]; data: number[] };
+        buf.writeUInt8(a.dims.length, o++);
+        for (const d of a.dims) {
+          buf.writeUInt32LE(d, o);
+          o += 4;
+        }
+        for (const x of a.data) {
+          if (col.type === T.TYPE_DOUBLE_ARRAY) buf.writeDoubleLE(x, o);
+          else buf.writeBigInt64LE(BigInt(x), o);
+          o += 8;
+        }
+      }
+      return o;
+    }
+    case T.TYPE_GEOHASH: {
+      const p = col.geohashPrecision ?? 1;
+      o = writeVarint(buf, o, p);
+      const width = Math.ceil(p / 8);
+      for (const val of col.values) {
+        let bits = BigInt(val as bigint);
+        for (let i = 0; i < width; i++) {
+          buf.writeUInt8(Number(bits & 0xffn), o++);
+          bits >>= 8n;
+        }
+      }
+      return o;
+    }
+    case T.TYPE_DECIMAL64:
+    case T.TYPE_DECIMAL128:
+    case T.TYPE_DECIMAL256: {
+      buf.writeUInt8(col.decimalScale ?? 0, o++);
+      const width =
+        col.type === T.TYPE_DECIMAL64
+          ? 8
+          : col.type === T.TYPE_DECIMAL128
+            ? 16
+            : 32;
+      for (const val of col.values) {
+        let x = BigInt(val as bigint);
+        for (let i = 0; i < width; i++) {
+          buf.writeUInt8(Number(x & 0xffn), o++);
+          x >>= 8n;
+        }
+      }
+      return o;
+    }
+    default:
+      throw new Error(
+        `unsupported QWP column type: 0x${col.type.toString(16)}`,
+      );
+  }
+}
diff --git a/src/qwp/protocol/constants.ts b/src/qwp/protocol/constants.ts
new file mode 100644
index 0000000..433c7c1
--- /dev/null
+++ b/src/qwp/protocol/constants.ts
@@ -0,0 +1,49 @@
+import { Buffer } from "node:buffer";
+
+/** ASCII "QWP1"; reads as 0x31505751 when interpreted little-endian. */
+export const QWP_MAGIC = Buffer.from("QWP1", "ascii");
+export const QWP_VERSION = 1;
+export const HEADER_SIZE = 12;
+
+export const FLAG_DEFER_COMMIT = 0x01;
+export const FLAG_GORILLA = 0x04;
+export const FLAG_DELTA_SYMBOL_DICT = 0x08;
+
+// Column type codes (spec 6.3).
+export const TYPE_BOOLEAN = 0x01;
+export const TYPE_BYTE = 0x02;
+export const TYPE_SHORT = 0x03;
+export const TYPE_INT = 0x04;
+export const TYPE_LONG = 0x05;
+export const TYPE_FLOAT = 0x06;
+export const TYPE_DOUBLE = 0x07;
+export const TYPE_SYMBOL = 0x09;
+export const TYPE_TIMESTAMP = 0x0a;
+export const TYPE_DATE = 0x0b;
+export const TYPE_UUID = 0x0c;
+export const TYPE_LONG256 = 0x0d;
+export const TYPE_GEOHASH = 0x0e;
+export const TYPE_VARCHAR = 0x0f;
+export const TYPE_TIMESTAMP_NANOS = 0x10;
+export const TYPE_DOUBLE_ARRAY = 0x11;
+export const TYPE_LONG_ARRAY = 0x12;
+export const TYPE_DECIMAL64 = 0x13;
+export const TYPE_DECIMAL128 = 0x14;
+export const TYPE_DECIMAL256 = 0x15;
+export const TYPE_CHAR = 0x16;
+export const TYPE_BINARY = 0x17;
+export const TYPE_IPV4 = 0x18;
+
+export const ENCODING_UNCOMPRESSED = 0x00;
+export const ENCODING_GORILLA = 0x01;
+
+// Limits mirrored from the server (spec 6.4).
+export const MAX_COLUMNS_PER_TABLE = 2048;
+export const MAX_NAME_LENGTH = 127;
+export const MAX_ROWS_PER_TABLE = 1_000_000;
+export const MAX_SYMBOL_DICTIONARY_SIZE = 1_000_000;
+
+export const WRITE_PATH = "/write/v4";
+
+/** "Not advertised" is not "unbounded": cap dictionary catch-up when the cap is unknown (spec 7.5). */
+export const UNCAPPED_CATCHUP_PACKING_LIMIT = 64 * 1024;
diff --git a/src/qwp/protocol/frameEncoder.ts b/src/qwp/protocol/frameEncoder.ts
new file mode 100644
index 0000000..6f465d5
--- /dev/null
+++ b/src/qwp/protocol/frameEncoder.ts
@@ -0,0 +1,122 @@
+import { Buffer } from "node:buffer";
+import { writeVarint, varintSize } from "./varint";
+import { QwpTableBuffer } from "./tableBuffer";
+import { columnPayloadSize, writeColumn, EncodeOpts } from "./columnWriter";
+import { SymbolDict } from "./symbolDict";
+import {
+  HEADER_SIZE,
+  QWP_MAGIC,
+  QWP_VERSION,
+  FLAG_GORILLA,
+  FLAG_DELTA_SYMBOL_DICT,
+  FLAG_DEFER_COMMIT,
+} from "./constants";
+
+function utf8Size(s: string): number {
+  return Buffer.byteLength(s, "utf8");
+}
+
+/** varint length + utf8 bytes (spec 6.0 "string"). */
+function writeString(buf: Buffer, offset: number, s: string): number {
+  const n = utf8Size(s);
+  const o = writeVarint(buf, offset, n);
+  buf.write(s, o, "utf8");
+  return o + n;
+}
+
+function stringSize(s: string): number {
+  const n = utf8Size(s);
+  return varintSize(n) + n;
+}
+
+function tableSize(t: QwpTableBuffer, colOpts: EncodeOpts): number {
+  let n =
+    stringSize(t.name) +
+    varintSize(t.rowCount) +
+    varintSize(t.columns.length);
+  for (const c of t.columns) n += stringSize(c.name) + 1;
+  for (const c of t.columns) n += columnPayloadSize(c, t.rowCount, colOpts);
+  return n;
+}
+
+export interface FrameOpts {
+  gorilla: boolean;
+  /** Present means delta mode; absent means full-dict/inline mode. */
+  dict?: SymbolDict;
+  /** Highest symbol id the server has already confirmed. */
+  confirmedMaxId?: number;
+  deferCommit?: boolean;
+}
+
+/** Encodes one QWP v1 message (spec 6.1, 6.2). */
+export function encodeFrame(tables: QwpTableBuffer[], opts: FrameOpts): Buffer {
+  const delta = opts.dict !== undefined;
+  const deltaStart = delta ? (opts.confirmedMaxId ?? -1) + 1 : 0;
+  const entries = delta ? opts.dict!.entriesFrom(deltaStart) : [];
+
+  let flags = 0;
+  if (opts.gorilla) flags |= FLAG_GORILLA;
+  if (delta) flags |= FLAG_DELTA_SYMBOL_DICT;
+  if (opts.deferCommit) flags |= FLAG_DEFER_COMMIT;
+
+  let payloadLen = 0;
+  if (delta) {
+    payloadLen += varintSize(deltaStart) + varintSize(entries.length);
+    for (const s of entries) {
+      const n = utf8Size(s);
+      payloadLen += varintSize(n) + n;
+    }
+  }
+  const colOpts: EncodeOpts = { gorilla: opts.gorilla, delta };
+  payloadLen += tables.reduce((a, t) => a + tableSize(t, colOpts), 0);
+
+  const buf = Buffer.allocUnsafe(HEADER_SIZE + payloadLen);
+  QWP_MAGIC.copy(buf, 0);
+  buf.writeUInt8(QWP_VERSION, 4);
+  buf.writeUInt8(flags, 5);
+  buf.writeUInt16LE(tables.length, 6);
+  buf.writeUInt32LE(payloadLen, 8);
+
+  let o = HEADER_SIZE;
+  if (delta) {
+    o = writeVarint(buf, o, deltaStart);
+    o = writeVarint(buf, o, entries.length);
+    for (const s of entries) {
+      const n = utf8Size(s);
+      o = writeVarint(buf, o, n);
+      buf.write(s, o, "utf8");
+      o += n;
+    }
+  }
+  for (const t of tables) {
+    o = writeString(buf, o, t.name);
+    o = writeVarint(buf, o, t.rowCount);
+    o = writeVarint(buf, o, t.columns.length);
+    for (const c of t.columns) {
+      o = writeString(buf, o, c.name);
+      buf.writeUInt8(c.type, o++);
+    }
+    for (const c of t.columns) o = writeColumn(buf, o, c, t.rowCount, colOpts);
+  }
+  if (o !== buf.length) {
+    throw new Error(`frame size mismatch: wrote ${o}, sized ${buf.length}`);
+  }
+  return buf;
+}
+
+/**
+ * A commit carries no rows and MUST carry no symbols. The empty delta is built
+ * by construction from [baseline+1 .. baseline] — deriving the bound from batch
+ * state re-ships the whole dictionary in a frame no chunker covers (spec 5.1.1).
+ */
+export function encodeCommitFrame(
+  dict: SymbolDict | undefined,
+  baseline: number,
+): Buffer {
+  return encodeFrame([], {
+    gorilla: false,
+    dict,
+    confirmedMaxId: baseline,
+    deferCommit: false,
+  });
+}
diff --git a/src/qwp/protocol/gorilla.ts b/src/qwp/protocol/gorilla.ts
new file mode 100644
index 0000000..e69093d
--- /dev/null
+++ b/src/qwp/protocol/gorilla.ts
@@ -0,0 +1,70 @@
+import { Buffer } from "node:buffer";
+import { BitWriter } from "./bits";
+
+const INT32_MIN = -2147483648n;
+const INT32_MAX = 2147483647n;
+
+function bitsRequired(dod: bigint): number {
+  if (dod === 0n) return 1;
+  if (dod >= -64n && dod <= 63n) return 9;
+  if (dod >= -256n && dod <= 255n) return 12;
+  if (dod >= -2048n && dod <= 2047n) return 16;
+  return 36;
+}
+
+/** Encoded size in bytes, or -1 when a delta-of-delta leaves int32 range. */
+export function gorillaSize(ts: bigint[]): number {
+  if (ts.length === 0) return 0;
+  if (ts.length === 1) return 8;
+  if (ts.length === 2) return 16;
+  let prevTs = ts[1];
+  let prevDelta = ts[1] - ts[0];
+  let bits = 0;
+  for (let i = 2; i < ts.length; i++) {
+    const delta = ts[i] - prevTs;
+    const dod = delta - prevDelta;
+    if (dod < INT32_MIN || dod > INT32_MAX) return -1;
+    bits += bitsRequired(dod);
+    prevDelta = delta;
+    prevTs = ts[i];
+  }
+  return 16 + Math.ceil(bits / 8);
+}
+
+export function encodeGorilla(ts: bigint[]): Buffer {
+  const size = gorillaSize(ts);
+  if (size < 0) throw new Error("gorilla: delta-of-delta out of int32 range");
+  const out = Buffer.alloc(size);
+  out.writeBigInt64LE(ts[0], 0);
+  if (ts.length === 1) return out;
+  out.writeBigInt64LE(ts[1], 8);
+  if (ts.length === 2) return out;
+
+  const w = new BitWriter(size - 16);
+  let prevTs = ts[1];
+  let prevDelta = ts[1] - ts[0];
+  for (let i = 2; i < ts.length; i++) {
+    const delta = ts[i] - prevTs;
+    const dod = delta - prevDelta;
+    // Prefixes are BIT-REVERSED because packing is LSB-first (spec 6.3.2).
+    if (dod === 0n) {
+      w.writeBits(0b0, 1);
+    } else if (dod >= -64n && dod <= 63n) {
+      w.writeBits(0b01, 2); // logical '10'
+      w.writeBits(Number(dod & 0x7fn), 7);
+    } else if (dod >= -256n && dod <= 255n) {
+      w.writeBits(0b011, 3); // logical '110'
+      w.writeBits(Number(dod & 0x1ffn), 9);
+    } else if (dod >= -2048n && dod <= 2047n) {
+      w.writeBits(0b0111, 4); // logical '1110'
+      w.writeBits(Number(dod & 0xfffn), 12);
+    } else {
+      w.writeBits(0b1111, 4); // logical '1111'
+      w.writeBits(Number(dod & 0xffffffffn), 32);
+    }
+    prevDelta = delta;
+    prevTs = ts[i];
+  }
+  w.finish().copy(out, 16);
+  return out;
+}
diff --git a/src/qwp/protocol/response.ts b/src/qwp/protocol/response.ts
new file mode 100644
index 0000000..1bf68ad
--- /dev/null
+++ b/src/qwp/protocol/response.ts
@@ -0,0 +1,65 @@
+import { Buffer } from "node:buffer";
+
+export const STATUS = {
+  OK: 0x00,
+  DURABLE_ACK: 0x02,
+  SCHEMA_MISMATCH: 0x03,
+  PARSE_ERROR: 0x05,
+  INTERNAL_ERROR: 0x06,
+  SECURITY_ERROR: 0x08,
+  WRITE_ERROR: 0x09,
+  CANCELLED: 0x0a,
+  LIMIT_EXCEEDED: 0x0b,
+  NOT_WRITABLE: 0x0c,
+  DICTIONARY_GAP: 0x0d,
+} as const;
+
+export const MAX_ERROR_MESSAGE_LENGTH = 1024;
+
+export interface QwpResponse {
+  status: number;
+  sequence: number;
+  tables: { name: string; seqTxn: bigint }[];
+  errorMessage?: string;
+}
+
+export function decodeResponse(payload: Buffer): QwpResponse {
+  if (payload.length < 3) throw new Error("invalid QWP response: truncated");
+  const status = payload.readUInt8(0);
+
+  if (status === STATUS.DURABLE_ACK) {
+    const count = payload.readUInt16LE(1);
+    return { status, sequence: -1, tables: readTables(payload, 3, count) };
+  }
+
+  if (payload.length < 11) throw new Error("invalid QWP response: truncated");
+  const sequence = Number(payload.readBigUInt64LE(1));
+
+  if (status === STATUS.OK) {
+    const count = payload.readUInt16LE(9);
+    return { status, sequence, tables: readTables(payload, 11, count) };
+  }
+
+  const len = payload.readUInt16LE(9);
+  if (len > MAX_ERROR_MESSAGE_LENGTH) throw new Error("invalid QWP response: error message too long");
+  return {
+    status,
+    sequence,
+    tables: [],
+    errorMessage: payload.subarray(11, 11 + len).toString("utf8"),
+  };
+}
+
+function readTables(buf: Buffer, offset: number, count: number) {
+  const out: { name: string; seqTxn: bigint }[] = [];
+  let o = offset;
+  for (let i = 0; i < count; i++) {
+    const n = buf.readUInt16LE(o);
+    o += 2;
+    const name = buf.subarray(o, o + n).toString("utf8");
+    o += n;
+    out.push({ name, seqTxn: buf.readBigInt64LE(o) });
+    o += 8;
+  }
+  return out;
+}
diff --git a/src/qwp/protocol/symbolDict.ts b/src/qwp/protocol/symbolDict.ts
new file mode 100644
index 0000000..246c317
--- /dev/null
+++ b/src/qwp/protocol/symbolDict.ts
@@ -0,0 +1,53 @@
+import { MAX_SYMBOL_DICTIONARY_SIZE } from "./constants";
+
+/** Connection-scoped global symbol dictionary. Ids are dense from 0. */
+export class SymbolDict {
+  private readonly ids = new Map<string, number>();
+  private readonly list: string[] = [];
+
+  size(): number {
+    return this.list.length;
+  }
+
+  checkCap(next: number): void {
+    if (next >= MAX_SYMBOL_DICTIONARY_SIZE) {
+      throw new Error(
+        `symbol dictionary exceeds maximum size ${MAX_SYMBOL_DICTIONARY_SIZE}`,
+      );
+    }
+  }
+
+  getOrAdd(s: string): number {
+    const existing = this.ids.get(s);
+    if (existing !== undefined) return existing;
+    this.checkCap(this.list.length);
+    const id = this.list.length;
+    this.ids.set(s, id);
+    this.list.push(s);
+    return id;
+  }
+
+  /**
+   * Appends at the next id WITHOUT de-duplicating. The persisted dictionary,
+   * the wire delta and the catch-up mirror all key on POSITION, so collapsing
+   * two entries would leave this shorter than the persisted count and silently
+   * misattribute every later symbol (spec 8.1.6).
+   */
+  addRecovered(s: string): number {
+    const id = this.list.length;
+    this.list.push(s);
+    // Keep the highest id; both encode identically, and callers rely on the
+    // positional ordinal for catch-up mirroring.
+    this.ids.set(s, id);
+    return id;
+  }
+
+  entriesFrom(startId: number): string[] {
+    return this.list.slice(Math.max(0, startId));
+  }
+
+  reset(): void {
+    this.ids.clear();
+    this.list.length = 0;
+  }
+}
diff --git a/src/qwp/protocol/tableBuffer.ts b/src/qwp/protocol/tableBuffer.ts
new file mode 100644
index 0000000..148c3a3
--- /dev/null
+++ b/src/qwp/protocol/tableBuffer.ts
@@ -0,0 +1,137 @@
+import { Buffer } from "node:buffer";
+import { MAX_COLUMNS_PER_TABLE, MAX_NAME_LENGTH, TYPE_TIMESTAMP } from "./constants";
+
+export interface ColumnBuffer {
+  name: string;
+  type: number;
+  /** Non-null values only — the wire is compacted (spec 6.2.1). */
+  values: unknown[];
+  /** One entry per row; true means NULL. */
+  nulls: boolean[];
+  /** Rows accounted for so far, including nulls. */
+  size: number;
+  geohashPrecision?: number;
+  decimalScale?: number;
+}
+
+export class QwpTableBuffer {
+  readonly name: string;
+  private readonly cols: ColumnBuffer[] = [];
+  private readonly byName = new Map<string, ColumnBuffer>();
+  private rows = 0;
+
+  constructor(name: string) {
+    if (!name) throw new Error("table name cannot be empty");
+    if (Buffer.byteLength(name, "utf8") > MAX_NAME_LENGTH) {
+      throw new Error(`table name too long [maxLength=${MAX_NAME_LENGTH}]`);
+    }
+    this.name = name;
+  }
+
+  get rowCount(): number {
+    return this.rows;
+  }
+
+  get columns(): ColumnBuffer[] {
+    return this.cols;
+  }
+
+  /** Returns null when the column already holds a value for the in-progress row. */
+  getOrCreateColumn(name: string, type: number): ColumnBuffer | null {
+    // An empty name is reserved for the designated timestamp column (TYPE_TIMESTAMP):
+    // QwpSchema allows nameLen=0 to signal the designated timestamp, and the server
+    // names it "timestamp". A non-empty name of any other type must not be empty.
+    if (!name && type !== TYPE_TIMESTAMP) {
+      throw new Error("column name cannot be empty");
+    }
+    const existing = this.byName.get(name);
+    if (existing) {
+      if (existing.type !== type) {
+        throw new Error(
+          `Column type mismatch for column '${name}': columnType=${existing.type}, sentType=${type}`,
+        );
+      }
+      // Already has a value for this row -> first value wins, silently.
+      if (existing.size > this.rows) return null;
+      existing.nulls.push(false);
+      existing.size++;
+      return existing;
+    }
+    if (Buffer.byteLength(name, "utf8") > MAX_NAME_LENGTH) {
+      throw new Error(`column name too long [maxLength=${MAX_NAME_LENGTH}]`);
+    }
+    if (this.cols.length >= MAX_COLUMNS_PER_TABLE) {
+      throw new Error(
+        `column count exceeds maximum: ${this.cols.length + 1} (max ${MAX_COLUMNS_PER_TABLE})`,
+      );
+    }
+    // Back-fill this column as null for every row already closed.
+    const col: ColumnBuffer = {
+      name,
+      type,
+      values: [],
+      nulls: new Array(this.rows).fill(true),
+      size: this.rows,
+    };
+    col.nulls.push(false);
+    col.size++;
+    this.cols.push(col);
+    this.byName.set(name, col);
+    return col;
+  }
+
+  /** Closes the row, back-filling a null into every column that was not set. */
+  nextRow(): void {
+    this.rows++;
+    for (const c of this.cols) {
+      while (c.size < this.rows) {
+        c.nulls.push(true);
+        c.size++;
+      }
+    }
+  }
+
+  /** Precision is 1-60 and locked on the column's first value (spec 6.5.3). */
+  setGeoHashPrecision(col: ColumnBuffer, precision: number): void {
+    if (precision < 1 || precision > 60) {
+      throw new Error(`invalid GeoHash precision: ${precision} (must be 1-60)`);
+    }
+    if (col.geohashPrecision === undefined) {
+      col.geohashPrecision = precision;
+    } else if (col.geohashPrecision !== precision) {
+      throw new Error(
+        `GeoHash precision mismatch: column has ${col.geohashPrecision} bits, got ${precision}`,
+      );
+    }
+  }
+
+  /** Scale locks on the first value; later values rescale (spec 6.5.3). */
+  setDecimalScale(col: ColumnBuffer, scale: number): number {
+    if (col.decimalScale === undefined) col.decimalScale = scale;
+    return col.decimalScale;
+  }
+
+  /** Truncates every column back to the last completed row (spec 4.1.1). */
+  rollbackRow(): void {
+    for (const c of this.cols) {
+      while (c.size > this.rows) {
+        const wasNull = c.nulls.pop();
+        c.size--;
+        if (wasNull === false) c.values.pop();
+      }
+    }
+    // Drop columns created solely by the abandoned row.
+    for (let i = this.cols.length - 1; i >= 0; i--) {
+      if (this.cols[i].size === 0 && this.rows === 0) {
+        this.byName.delete(this.cols[i].name);
+        this.cols.splice(i, 1);
+      }
+    }
+  }
+
+  reset(): void {
+    this.cols.length = 0;
+    this.byName.clear();
+    this.rows = 0;
+  }
+}
diff --git a/src/qwp/protocol/varint.ts b/src/qwp/protocol/varint.ts
new file mode 100644
index 0000000..340c0d7
--- /dev/null
+++ b/src/qwp/protocol/varint.ts
@@ -0,0 +1,43 @@
+import { Buffer } from "node:buffer";
+
+/** Unsigned LEB128. 7 data bits per byte; high bit set means another byte follows. */
+export function writeVarint(buf: Buffer, offset: number, value: number): number {
+  if (value < 0 || !Number.isInteger(value)) {
+    throw new Error(`varint requires a non-negative integer, got ${value}`);
+  }
+  let v = value;
+  let o = offset;
+  while (v >= 0x80) {
+    buf[o++] = (v & 0x7f) | 0x80;
+    v = Math.floor(v / 128);
+  }
+  buf[o++] = v;
+  return o;
+}
+
+export function varintSize(value: number): number {
+  let v = value;
+  let n = 1;
+  while (v >= 0x80) {
+    v = Math.floor(v / 128);
+    n++;
+  }
+  return n;
+}
+
+export function readVarint(
+  buf: Buffer,
+  offset: number,
+): { value: number; offset: number } {
+  let value = 0;
+  let shift = 1;
+  let o = offset;
+  for (;;) {
+    if (o >= buf.length) throw new Error("incomplete varint");
+    const b = buf[o++];
+    value += (b & 0x7f) * shift;
+    if ((b & 0x80) === 0) break;
+    shift *= 128;
+  }
+  return { value, offset: o };
+}
diff --git a/src/qwp/sf/boundary.ts b/src/qwp/sf/boundary.ts
new file mode 100644
index 0000000..3973c2b
--- /dev/null
+++ b/src/qwp/sf/boundary.ts
@@ -0,0 +1,45 @@
+import { Buffer } from "node:buffer";
+import { crc32c } from "./crc32c";
+
+export const BOUNDARY_FILE_SIZE = 8192;
+const RECORD_SIZE = 64;
+const SLOT_STRIDE = 4096;
+const CRC_OFFSET = 60;
+export const AKW1_MAGIC = 0x31574b41; // 'AKW1' (LE: 41 4b 57 31)
+const MAGIC = AKW1_MAGIC;
+
+export interface Boundary {
+  generation: number;
+  value: bigint;
+}
+
+/** Alternates slots by generation parity; the CRC is written last. */
+export function writeBoundary(
+  buf: Buffer,
+  generation: number,
+  value: bigint,
+  magic: number = MAGIC,
+): void {
+  const slot = (generation % 2) * SLOT_STRIDE;
+  buf.fill(0, slot, slot + RECORD_SIZE);
+  buf.writeUInt32LE(magic, slot);
+  buf.writeUInt32LE(1, slot + 4);
+  buf.writeBigUInt64LE(BigInt(generation), slot + 8);
+  buf.writeBigInt64LE(value, slot + 16);
+  const crc = crc32c(buf.subarray(slot, slot + CRC_OFFSET));
+  buf.writeUInt32LE(crc, slot + CRC_OFFSET);
+}
+
+export function readBoundary(buf: Buffer, magic: number = MAGIC): Boundary | null {
+  let best: Boundary | null = null;
+  for (const slot of [0, SLOT_STRIDE]) {
+    if (slot + RECORD_SIZE > buf.length) continue;
+    if (buf.readUInt32LE(slot) !== magic) continue;
+    const stored = buf.readUInt32LE(slot + CRC_OFFSET);
+    if (crc32c(buf.subarray(slot, slot + CRC_OFFSET)) !== stored) continue;
+    const generation = Number(buf.readBigUInt64LE(slot + 8));
+    const value = buf.readBigInt64LE(slot + 16);
+    if (!best || generation > best.generation) best = { generation, value };
+  }
+  return best;
+}
diff --git a/src/qwp/sf/crc32c.ts b/src/qwp/sf/crc32c.ts
new file mode 100644
index 0000000..40947f2
--- /dev/null
+++ b/src/qwp/sf/crc32c.ts
@@ -0,0 +1,20 @@
+import { Buffer } from "node:buffer";
+
+// Castagnoli polynomial, reversed: 0x82F63B78. NOT the zlib/ISO-HDLC one.
+const TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0x82f63b78 ^ (c >>> 1) : c >>> 1;
+    t[i] = c;
+  }
+  return t;
+})();
+
+export function crc32c(buf: Buffer, seed = 0): number {
+  let c = ~seed;
+  for (let i = 0; i < buf.length; i++) {
+    c = TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  }
+  return (~c) >>> 0;
+}
diff --git a/src/qwp/sf/drainer.ts b/src/qwp/sf/drainer.ts
new file mode 100644
index 0000000..87f3aa4
--- /dev/null
+++ b/src/qwp/sf/drainer.ts
@@ -0,0 +1,453 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SenderOptions } from "../../options";
+import { QwpWebSocket, QwpWebSocketOptions } from "../ws/socket";
+import { QwpUpgradeError } from "../ws/handshake";
+import { decodeResponse, STATUS } from "../protocol/response";
+import { encodeFrame } from "../protocol/frameEncoder";
+import { UNCAPPED_CATCHUP_PACKING_LIMIT } from "../protocol/constants";
+import { AckTracker } from "../ackTracker";
+import { DurableAckTracker } from "../durableAckTracker";
+import { HostTracker, HostState } from "../hostTracker";
+import { Endpoint } from "../endpoints";
+import { SfEngine, EngineOptions } from "./engine";
+import {
+  acquireSlot,
+  releaseSlot,
+  acquireLogicalLock,
+  releaseLogicalLock,
+  isLiveLock,
+  SlotHandle,
+} from "./slotLock";
+import { scanOrphans, OrphanSlot } from "./orphanScanner";
+import {
+  SenderError,
+  Category,
+  Policy,
+  classify,
+  defaultPolicyFor,
+} from "../errors";
+
+const CLIENT_ID = "nodejs/1.0.0";
+const DEFAULT_BACKOFF = 100;
+const POLL_QUIESCE = 10;
+// Orphan-drainer cap-gap escalation (spec 7.5): a foreground sender retries a
+// too-large catch-up forever; only a drainer may latch terminal, after this many
+// consecutive cap gaps AND this dwell window. The dwell is defaulted in the
+// config parser (catch_up_cap_gap_min_escalation_window_millis, spec 9.1).
+const MAX_CATCHUP_CAP_GAP_ATTEMPTS = 16;
+const DEFAULT_CATCHUP_CAP_GAP_DWELL_MILLIS = 300_000;
+const FAILED_SENTINEL = ".failed";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function engineOptions(o: SenderOptions): EngineOptions {
+  return {
+    segmentBytes: o.sf_segment_bytes ?? 4 * 1024 * 1024,
+    // Drainers only ever run in disk mode (they adopt orphan slots), so the
+    // disk default applies here even when sf_max_total_bytes is unset (spec 9.1:
+    // 10 GiB disk vs 128 MiB memory).
+    maxTotalBytes: o.sf_max_total_bytes ?? 10 * 1024 * 1024 * 1024,
+    senderId: o.sender_id ?? "default",
+  };
+}
+
+/**
+ * A background orphan drainer (spec 8.4): adopts an orphan slot left by a
+ * crashed producer, opens its OWN WebSocket with a PRIVATE round cursor (never
+ * the shared round, spec 1.2), and replays the slot read-only until ackedFsn
+ * catches the startup snapshot of publishedFsn, then releases the slot. A
+ * terminal failure drops a `.failed` sentinel so future scans skip it until an
+ * operator clears it; a transient all-replica outage is retried indefinitely.
+ */
+export class OrphanDrainer {
+  private stopped = false;
+  private ws?: QwpWebSocket;
+  private acks = new AckTracker();
+  private durableAcks = new DurableAckTracker();
+  private acked = -1;
+  private fatalResponse?: Error;
+  /** Reject late responses/closes from a recycled connection. */
+  private connectionGeneration = 0;
+  private activeConnectionGeneration = 0;
+  private readonly running: Promise<void>;
+
+  constructor(
+    private readonly options: SenderOptions,
+    private readonly endpoints: Endpoint[],
+    private readonly tracker: HostTracker,
+    private readonly slot: OrphanSlot,
+    private readonly emit: (e: SenderError) => void,
+  ) {
+    this.running = this.run();
+  }
+
+  get finished(): Promise<void> {
+    return this.running;
+  }
+
+  stop(): void {
+    this.stopped = true;
+    const ws = this.ws;
+    this.activeConnectionGeneration = 0;
+    this.ws = undefined;
+    void ws?.close();
+  }
+
+  private onBinary(payload: Buffer, generation: number): void {
+    if (generation !== this.activeConnectionGeneration) return;
+    const r = decodeResponse(payload);
+    if (r.status === STATUS.OK) {
+      const f = this.acks.fsnForAck(r.sequence);
+      if (f === null) return;
+      this.acks.onAck(r.sequence);
+      if (this.options.request_durable_ack === true) {
+        const durable = this.durableAcks.onOk(f, r.tables);
+        if (durable !== null) this.acked = Math.max(this.acked, durable);
+      } else {
+        this.acked = Math.max(this.acked, f);
+      }
+      return;
+    }
+    if (r.status === STATUS.DURABLE_ACK) {
+      if (this.options.request_durable_ack === true) {
+        const durable = this.durableAcks.onDurableAck(r.tables);
+        if (durable !== null) this.acked = Math.max(this.acked, durable);
+      }
+      return;
+    }
+    const category = classify(r.status);
+    const policy = defaultPolicyFor(category);
+    if (policy === Policy.TERMINAL) {
+      this.fatalResponse = new Error(
+        `terminal orphan replay rejection (${category}): ${r.errorMessage ?? r.status}`,
+      );
+    }
+    // Any retryable NACK recycles the connection and replays from the unchanged
+    // read-only watermark. A terminal NACK is observed by replay() and causes
+    // the slot to receive its .failed sentinel instead of hanging forever.
+    this.recycleConnection(generation);
+  }
+
+  private onClose(generation: number): void {
+    if (generation !== this.activeConnectionGeneration) return;
+    this.activeConnectionGeneration = 0;
+    this.ws = undefined;
+  }
+
+  private recycleConnection(generation: number): void {
+    if (generation !== this.activeConnectionGeneration) return;
+    const ws = this.ws;
+    this.activeConnectionGeneration = 0;
+    this.ws = undefined;
+    void ws?.close();
+  }
+
+  private buildWsOptions(
+    ep: Endpoint,
+    generation: number,
+  ): QwpWebSocketOptions {
+    const auth =
+      this.options.username && this.options.password
+        ? "Basic " +
+          Buffer.from(
+            `${this.options.username}:${this.options.password}`,
+          ).toString("base64")
+        : this.options.token
+          ? `Bearer ${this.options.token}`
+          : undefined;
+    return {
+      host: ep.host,
+      port: ep.port,
+      tls: this.options.protocol === "wss",
+      clientId: CLIENT_ID,
+      authorization: auth,
+      rejectUnauthorized: this.options.tls_verify !== false,
+      requestDurableAck: this.options.request_durable_ack === true,
+      authTimeoutMs: this.options.auth_timeout_ms,
+      keepaliveMs: this.options.durable_ack_keepalive_interval_millis,
+      onBinary: (payload) => this.onBinary(payload, generation),
+      onClose: () => this.onClose(generation),
+    };
+  }
+
+  private async run(): Promise<void> {
+    const sfDir = this.options.sf_dir!;
+    try {
+      await acquireLogicalLock(sfDir, this.slot.senderId);
+    } catch {
+      // Another producer/drainer won adoption. Contention is not a replay
+      // failure and must not become an unhandled rejected promise.
+      return;
+    }
+    let held: SlotHandle | undefined;
+    try {
+      // Revalidate: a producer may have re-adopted the slot while we scanned.
+      if (
+        this.stopped ||
+        (await isLiveLock(join(this.slot.slotDir, ".lock")))
+      ) {
+        return;
+      }
+      try {
+        held = await acquireSlot(sfDir, this.slot.senderId);
+      } catch {
+        return; // a live holder appeared; not ours to drain
+      }
+      if (this.stopped) return;
+
+      let engine: SfEngine;
+      try {
+        engine = await SfEngine.openReadOnly(
+          engineOptions(this.options),
+          sfDir,
+          this.slot.senderId,
+        );
+      } catch (e) {
+        await this.dropFailed(
+          `orphan slot could not be recovered: ${(e as Error)?.message ?? e}`,
+        );
+        return;
+      }
+      try {
+        await this.replay(engine);
+        if (!this.stopped && this.acked >= engine.publishedFsn) {
+          await this.retireOrphan(sfDir);
+          // The owned lock moved with the retired directory and was deleted.
+          held = undefined;
+        }
+      } catch (e) {
+        await this.dropFailed((e as Error)?.message ?? String(e));
+      }
+    } finally {
+      await releaseLogicalLock(sfDir, this.slot.senderId);
+      if (held) await releaseSlot(held);
+    }
+  }
+
+  /**
+   * Make successful completion crash-safe: rename to an ignored hidden path
+   * before deletion. A crash after rename can leak bytes but cannot replay them.
+   */
+  private async retireOrphan(sfDir: string): Promise<void> {
+    const ws = this.ws;
+    this.activeConnectionGeneration = 0;
+    this.ws = undefined;
+    await ws?.close().catch(() => undefined);
+    const retired = join(
+      sfDir,
+      `.drained-${this.slot.senderId}-${randomUUID()}`,
+    );
+    await rename(this.slot.slotDir, retired);
+    // Rename is the correctness boundary; cleanup is best-effort because the
+    // hidden name is already outside scanner visibility.
+    await rm(retired, { recursive: true, force: true }).catch(() => undefined);
+  }
+
+  /** Terminal failure: drop the `.failed` sentinel and surface DATA_LOSS. */
+  private async dropFailed(detail: string): Promise<void> {
+    try {
+      await writeFile(
+        join(this.slot.slotDir, FAILED_SENTINEL),
+        `drain failed at ${new Date().toISOString()}\n`,
+      );
+    } catch {
+      /* best-effort sentinel */
+    }
+    this.emit(
+      new SenderError(
+        Category.DATA_LOSS,
+        Policy.ABANDONED,
+        `orphan slot '${this.slot.senderId}' failed to drain: ${detail}`,
+        -1,
+        -1,
+        -1,
+        this.slot.slotDir,
+      ),
+    );
+  }
+
+  /** Replay until ackedFsn catches the recovered publishedFsn, then release. */
+  private async replay(engine: SfEngine): Promise<void> {
+    const dict = engine.symbolDict;
+    const target = engine.publishedFsn;
+    this.acked = engine.ackedFsn;
+    this.acks = new AckTracker();
+    let cursor = this.tracker.newCursor();
+    let capGapAttempts = 0;
+    let capGapFirstAt = 0;
+    const capGapDwell =
+      this.options.catch_up_cap_gap_min_escalation_window_millis ??
+      DEFAULT_CATCHUP_CAP_GAP_DWELL_MILLIS;
+    const hasDict = dict.size() > 0;
+
+    for (;;) {
+      if (this.stopped) return;
+      if (this.fatalResponse) throw this.fatalResponse;
+      if (this.acked >= target) return;
+
+      if (!this.ws) {
+        const idx = cursor.pickNext();
+        if (idx === null) {
+          // Private round exhausted: transient. Back off and start a fresh round
+          // (a fresh walker-local attempted set, never the shared round).
+          cursor = this.tracker.newCursor();
+          await sleep(
+            this.options.reconnect_initial_backoff_millis ?? DEFAULT_BACKOFF,
+          );
+          continue;
+        }
+        const ep = this.endpoints[idx];
+        const generation = ++this.connectionGeneration;
+        let w: QwpWebSocket | undefined;
+        try {
+          w = await QwpWebSocket.connect(this.buildWsOptions(ep, generation));
+          if (this.options.request_durable_ack === true && !w.durableAck) {
+            await w.close();
+            this.tracker.record(idx, HostState.TRANSIENT_REJECT);
+            continue;
+          }
+          this.tracker.record(idx, HostState.HEALTHY);
+          // Establish response correlation before catch-up is sent; a local
+          // server can ACK in the same event-loop turn.
+          this.acks.onConnected(this.acked + 1, hasDict ? 1 : 0);
+          this.durableAcks.reset(this.acked);
+          this.activeConnectionGeneration = generation;
+          this.ws = w;
+          if (hasDict) {
+            // Connection-scoped dictionary is empty on a fresh server: re-register
+            // it from id 0 before any replay frame (spec 7.5).
+            const frame = encodeFrame([], {
+              gorilla: false,
+              dict,
+              confirmedMaxId: -1,
+            });
+            const cap = w.maxBatchSize ?? UNCAPPED_CATCHUP_PACKING_LIMIT;
+            if (frame.length > cap) {
+              this.recycleConnection(generation);
+              await w.close();
+              capGapAttempts++;
+              if (capGapFirstAt === 0) capGapFirstAt = Date.now();
+              if (
+                capGapAttempts >= MAX_CATCHUP_CAP_GAP_ATTEMPTS &&
+                Date.now() - capGapFirstAt >= capGapDwell
+              ) {
+                throw new Error(
+                  `drainer catch-up exceeds every server cap [size=${frame.length}]`,
+                );
+              }
+              continue; // try the next node / round
+            }
+            capGapAttempts = 0;
+            capGapFirstAt = 0;
+            await w.sendBinary(frame);
+          }
+          if (this.fatalResponse) throw this.fatalResponse;
+          if (this.activeConnectionGeneration !== generation || this.ws !== w) {
+            continue;
+          }
+        } catch (e) {
+          if (this.activeConnectionGeneration === generation) {
+            this.activeConnectionGeneration = 0;
+            this.ws = undefined;
+          }
+          await w?.close().catch(() => undefined);
+          if (e instanceof QwpUpgradeError) {
+            if (e.kind === "auth") {
+              throw new Error(`drainer authentication failed: ${e.message}`);
+            }
+            this.tracker.record(
+              idx,
+              e.kind === "role-reject"
+                ? HostState.TOPOLOGY_REJECT
+                : HostState.TRANSPORT_ERROR,
+            );
+          } else if (
+            e instanceof Error &&
+            e.message.startsWith("drainer catch-up exceeds")
+          ) {
+            throw e;
+          } else {
+            this.tracker.record(idx, HostState.TRANSPORT_ERROR);
+          }
+          continue;
+        }
+      }
+
+      // Send every unacked frame up to the startup snapshot.
+      const pending = engine.framesFrom(this.acked + 1);
+      for (const f of pending) {
+        if (this.stopped) return;
+        const ws = this.ws;
+        const generation = this.activeConnectionGeneration;
+        if (!ws || generation === 0) break;
+        // Count the wire attempt before awaiting write completion so an
+        // immediate local ACK is correlated against this connection.
+        this.acks.onFrameSent();
+        try {
+          await ws.sendBinary(f);
+        } catch {
+          // Transport failures are transient for orphan replay. Keep the slot
+          // and replay from the unchanged watermark on another connection.
+          if (generation === this.activeConnectionGeneration) {
+            this.activeConnectionGeneration = 0;
+            this.ws = undefined;
+          }
+          await ws.close().catch(() => undefined);
+          break;
+        }
+        if (generation !== this.activeConnectionGeneration) break;
+      }
+      // Quiesce: ACKs arrive via onBinary and advance `this.acked`; a drop
+      // clears `this.ws` so the loop reconnects and re-sends what's unacked.
+      while (!this.stopped && this.acked < target && this.ws) {
+        if (this.fatalResponse) throw this.fatalResponse;
+        await sleep(POLL_QUIESCE);
+      }
+    }
+  }
+}
+
+/**
+ * Scans for orphan slots and hands each to a drainer, bounded by
+ * `max_background_drainers` concurrent WebSockets. Returns handles so the
+ * transport can stop them on close().
+ */
+export async function startOrphanDrainers(
+  options: SenderOptions,
+  endpoints: Endpoint[],
+  tracker: HostTracker,
+  emit: (e: SenderError) => void,
+  onStart?: (d: OrphanDrainer) => void,
+  shouldStop?: () => boolean,
+): Promise<OrphanDrainer[]> {
+  const sfDir = options.sf_dir;
+  if (!sfDir) return [];
+  const max = options.max_background_drainers ?? 4; // spec 9.1
+  const orphans = await scanOrphans(sfDir);
+  const running = new Set<OrphanDrainer>();
+  const all: OrphanDrainer[] = [];
+  for (const slot of orphans) {
+    if (shouldStop?.()) break;
+    // Bound concurrency: wait until a slot frees before starting the next.
+    while (running.size >= max && !shouldStop?.()) {
+      await Promise.race(
+        [...running].map((d) => d.finished.catch(() => undefined)),
+      );
+    }
+    if (shouldStop?.()) break;
+    const drainer = new OrphanDrainer(options, endpoints, tracker, slot, emit);
+    running.add(drainer);
+    all.push(drainer);
+    onStart?.(drainer);
+    void drainer.finished.then(
+      () => running.delete(drainer),
+      () => running.delete(drainer),
+    );
+  }
+  return all;
+}
diff --git a/src/qwp/sf/engine.ts b/src/qwp/sf/engine.ts
new file mode 100644
index 0000000..b3038ed
--- /dev/null
+++ b/src/qwp/sf/engine.ts
@@ -0,0 +1,569 @@
+import { Buffer } from "node:buffer";
+import { open, readFile, readdir, rm } from "node:fs/promises";
+import {
+  closeSync,
+  fstatSync,
+  fsyncSync,
+  ftruncateSync,
+  openSync,
+  writeSync,
+} from "node:fs";
+import { join } from "node:path";
+import { SegmentRing } from "./ring";
+import { acquireSlot, releaseSlot, SlotHandle } from "./slotLock";
+import { appendFrame, scanSegment, SEGMENT_HEADER_SIZE } from "./segment";
+import { writeBoundary, readBoundary, BOUNDARY_FILE_SIZE } from "./boundary";
+import {
+  writeManifest,
+  readManifest,
+  MANIFEST_FILE_NAME,
+  MANIFEST_FILE_SIZE,
+} from "./manifest";
+import {
+  decodeDictFileState,
+  DICT_HEADER,
+  encodeChunk,
+} from "./symbolDictFile";
+import { SymbolDict } from "../protocol/symbolDict";
+import { quarantineSlot } from "./quarantine";
+import { SenderError, Category, Policy } from "../errors";
+
+export const SEGMENT_EXT = ".sfa";
+/** Segment flags bit 0: this file is governed by an sf-manifest.bin (spec 8.1.5). */
+export const MANIFEST_REQUIRED_FLAG = 1;
+const ACK_WATERMARK = ".ack-watermark";
+const SYMBOL_DICT = ".symbol-dict";
+const DEFAULT_SYNC_INTERVAL_MILLIS = 5000; // spec 9.1
+
+export interface EngineOptions {
+  segmentBytes: number;
+  maxTotalBytes: number;
+  sfDir?: string;
+  senderId: string;
+  /** spec 8.2: page-cache only (default) vs a periodic background barrier. */
+  durability?: "memory" | "periodic";
+  /** Target cadence for the periodic barrier (spec 9.1 default 5000). */
+  syncIntervalMillis?: number;
+}
+
+/**
+ * Ties the FSN ring and the crash-safe on-disk state (segments, ack watermark,
+ * symbol dictionary) together. With `sfDir` set the engine writes every
+ * published frame to a segment file; without it (memory mode) it is just the
+ * ring, and a process crash loses everything as usual (spec 8, 9.2).
+ */
+export class SfEngine {
+  private ring: SegmentRing;
+  private slot?: SlotHandle;
+  private fh?: Awaited<ReturnType<typeof open>>;
+  private fileNo = 0;
+  private activeOffset = 0;
+  private activeDataBytes = 0;
+  private closed = false;
+  private appendTail: Promise<void> = Promise.resolve();
+
+  // ack watermark state (spec 8.2). Written on a cadence, never per-ACK (C1),
+  // and fsynced only in periodic durability.
+  private wmBuf = Buffer.alloc(BOUNDARY_FILE_SIZE);
+  private wmGen = 0;
+  private lastWm = -1n;
+  private watermarkDirty = false;
+  private barrierTimer?: ReturnType<typeof setInterval>;
+  private barrierInFlight = false;
+
+  // sf-manifest.bin state (spec 8.2, 8.1.1): records the chain head so
+  // recovery can cross-check the scanned segment chain. Same alternating
+  // generation scheme as the ack watermark; written on rotation, never per frame.
+  private manBuf = Buffer.alloc(MANIFEST_FILE_SIZE);
+  private manifestGen = 0;
+
+  // symbol dictionary file (load-bearing for delta mode; spec 8.1.6)
+  private dict = new SymbolDict();
+  private dictFd?: number;
+  private dictValidBytes = 0;
+  private dictDirty = false;
+  /** True when the slot had no (or an empty) symbol-dict file on open. */
+  private dictFresh = false;
+
+  constructor(private readonly opts: EngineOptions) {
+    this.ring = new SegmentRing({
+      segmentBytes: opts.segmentBytes,
+      maxTotalBytes: opts.maxTotalBytes,
+    });
+  }
+
+  get isDisk(): boolean {
+    return this.opts.sfDir !== undefined;
+  }
+
+  get ackedFsn(): number {
+    return this.ring.ackedFsn;
+  }
+
+  get publishedFsn(): number {
+    return this.ring.publishedFsn;
+  }
+
+  /** The configured total-retention cap (observability/test hook). */
+  get maxTotalBytes(): number {
+    return this.opts.maxTotalBytes;
+  }
+
+  /** The recovered symbol dictionary, for catch-up re-registration (spec 7.5). */
+  get symbolDict(): SymbolDict {
+    return this.dict;
+  }
+
+  get durability(): "memory" | "periodic" {
+    return this.opts.durability ?? "memory";
+  }
+
+  async open(): Promise<void> {
+    if (!this.isDisk) return;
+    const { sfDir, senderId } = this.opts;
+    this.slot = await acquireSlot(sfDir, senderId);
+    // A slot that cannot be recovered is set aside (rename + .failed sentinel)
+    // and surfaced as DATA_LOSS/ABANDONED rather than failing the sender with
+    // an unlabelled error (spec 8.4). This covers both a corrupt segment chain
+    // and a corrupt, load-bearing symbol dictionary (spec 8.1.6).
+    try {
+      await this.recover(this.slot.slotDir);
+    } catch (e) {
+      await this.failQuarantined(sfDir, senderId, e);
+    }
+    this.dictFd = openSync(join(this.slot.slotDir, SYMBOL_DICT), "a");
+    // Remove a torn final chunk before appending. Otherwise every later valid
+    // chunk remains hidden behind the first invalid tail on every recovery.
+    if (!this.dictFresh && fstatSync(this.dictFd).size > this.dictValidBytes) {
+      ftruncateSync(this.dictFd, this.dictValidBytes);
+    }
+    // A fresh (or zero-length) slot has no file header yet: publish it fully.
+    if (this.dictFresh) {
+      this.writeSyncFully(DICT_HEADER);
+      this.dictValidBytes = DICT_HEADER.length;
+      this.dictDirty = true;
+    }
+
+    // Start the throttled durability barrier. In memory mode it coalesces the
+    // page-cache watermark write across ACKs (spec 8.2 consequence 1); in
+    // periodic mode it additionally fsyncs the active segment (spec 8.1.5
+    // syncPublished semantics).
+    const interval =
+      this.opts.syncIntervalMillis ?? DEFAULT_SYNC_INTERVAL_MILLIS;
+    if (interval > 0) {
+      this.barrierTimer = setInterval(() => void this.runBarrier(), interval);
+      this.barrierTimer.unref?.();
+    }
+  }
+
+  /**
+   * Read-only recovery for orphan drainers, which already hold the slot lock and
+   * must never write (spec 8.4). Populates the recovered ring and symbol
+   * dictionary without taking a lock, opening write descriptors, or starting the
+   * durability barrier. Throws on a slot that cannot be recovered.
+   */
+  static async openReadOnly(
+    opts: EngineOptions,
+    sfDir: string,
+    senderId: string,
+  ): Promise<SfEngine> {
+    const e = new SfEngine({
+      ...opts,
+      sfDir: undefined, // never let a read-only view think it can write
+      durability: "memory",
+      syncIntervalMillis: 0,
+    });
+    await e.recover(join(sfDir, senderId));
+    return e;
+  }
+
+  /**
+   * Shared recovery: reads the ack watermark, the contiguous segment chain into
+   * the ring, and the loaded symbol dictionary. Throws on a slot that cannot be
+   * recovered (corrupt chain, bad magic, broken dictionary); the caller decides
+   * whether to quarantine (owner) or drop a .failed sentinel (drainer).
+   */
+  private async recover(slotDir: string): Promise<void> {
+    // sf-manifest.bin -> chain-head cross-check (spec 8.1.1, 8.2). The manifest
+    // is written only after the new segment's header exists, so on a crash the
+    // manifest is never AHEAD of a segment that is already on disk. Equality or
+    // a manifest behind the scanned head (the rotation write-order race) is a
+    // benign, recoverable state; a manifest strictly ahead of the scanned head
+    // means a recorded tail segment vanished from disk = real data loss.
+    const manData = await readFile(join(slotDir, MANIFEST_FILE_NAME)).catch(
+      () => undefined,
+    );
+    let manifestHead: number | undefined;
+    if (manData && manData.length > 0) {
+      manData.copy(this.manBuf);
+      const m = readManifest(this.manBuf);
+      if (m) {
+        manifestHead = m.headBaseSeq;
+        this.manifestGen = m.generation + 1;
+      }
+    }
+
+    // ack watermark (discardable optimisation, guarded by monotonic clamp)
+    let recoveredWm: number | undefined;
+    try {
+      const wmData = await readFile(join(slotDir, ACK_WATERMARK)).catch(
+        () => undefined,
+      );
+      if (wmData && wmData.length > 0) {
+        wmData.copy(this.wmBuf);
+        const b = readBoundary(this.wmBuf);
+        if (b) recoveredWm = Number(b.value);
+      }
+    } catch {
+      /* fall back to the segment-derived seed (spec 8.2) */
+    }
+
+    // segments -> contiguous FSN chain
+    const entries = await readdir(slotDir).catch(() => []);
+    const segFiles = entries
+      .filter((e) => e.endsWith(SEGMENT_EXT))
+      .sort((a, b) => {
+        const ai = Number(a.slice(0, -SEGMENT_EXT.length));
+        const bi = Number(b.slice(0, -SEGMENT_EXT.length));
+        if (Number.isFinite(ai) && Number.isFinite(bi)) return ai - bi;
+        return a.localeCompare(b);
+      });
+    // Resume the file counter PAST any existing segment so continued appends
+    // open fresh files rather than truncating a recovered one that may still
+    // hold unacked frames (spec 8.1.5).
+    let maxIdx = -1;
+    for (const f of segFiles) {
+      const n = Number(f.slice(0, -SEGMENT_EXT.length));
+      if (Number.isFinite(n) && n > maxIdx) maxIdx = n;
+    }
+    this.fileNo = maxIdx + 1;
+    const chain: { baseSeq: number; frames: Buffer[] }[] = [];
+    let manifestRequired = false;
+    for (const f of segFiles) {
+      const data = await readFile(join(slotDir, f));
+      const sr = scanSegment(data);
+      chain.push({ baseSeq: sr.baseSeq, frames: sr.frames });
+      if (sr.frames.length > 0 && (sr.flags & MANIFEST_REQUIRED_FLAG) !== 0) {
+        manifestRequired = true;
+      }
+    }
+    if (manifestRequired && manifestHead === undefined) {
+      throw new Error("sf manifest missing or corrupt for governed segments");
+    }
+    // Cross-check the manifest head against the scanned chain (spec 8.1.1).
+    // A valid manifest is only ever written after a new segment header exists,
+    // so the manifest is never ahead of an existing file on a benign crash.
+    // A manifest ahead of the scanned head therefore means a recorded tail
+    // segment (or its entire chain) vanished from disk = real data loss.
+    if (manifestHead !== undefined) {
+      let head = -1;
+      for (const c of chain) if (c.baseSeq > head) head = c.baseSeq;
+      if (head < 0 || head < manifestHead) {
+        const detail =
+          chain.length === 0
+            ? "no segments found but the manifest records head " + manifestHead
+            : `manifest head ${manifestHead} ahead of scanned chain head ${head}`;
+        throw new Error("sf lost-tail detected: " + detail);
+      }
+    }
+    if (chain.length > 0) {
+      this.ring = SegmentRing.recovered(chain, {
+        segmentBytes: this.opts.segmentBytes,
+        maxTotalBytes: this.opts.maxTotalBytes,
+      });
+      if (recoveredWm !== undefined) this.ring.acknowledge(recoveredWm);
+    }
+
+    // symbol dictionary (load-bearing; positions preserved, never de-duped)
+    const dictData = await readFile(join(slotDir, SYMBOL_DICT)).catch(
+      () => undefined,
+    );
+    if (dictData && dictData.length > 0) {
+      const decoded = decodeDictFileState(dictData);
+      for (const e of decoded.entries) this.dict.addRecovered(e);
+      this.dictValidBytes = decoded.validBytes;
+    } else {
+      this.dictValidBytes = 0;
+    }
+    this.dictFresh = !dictData || dictData.length === 0;
+  }
+
+  /**
+   * Releases the slot lock, quarantines the corrupt slot, and throws a
+   * DATA_LOSS/ABANDONED SenderError carrying the quarantined path (spec 8.4).
+   */
+  private async failQuarantined(
+    sfDir: string,
+    senderId: string,
+    cause: unknown,
+  ): Promise<never> {
+    const slot = this.slot!;
+    this.slot = undefined;
+    await releaseSlot(slot);
+    let quarantinedPath: string | undefined;
+    try {
+      quarantinedPath = await quarantineSlot(sfDir, senderId, slot.slotDir);
+    } catch {
+      // The cap refused the rename; keep the original path as context.
+      quarantinedPath = slot.slotDir;
+    }
+    const detail = (cause as Error)?.message ?? String(cause);
+    throw new SenderError(
+      Category.DATA_LOSS,
+      Policy.ABANDONED,
+      `sf slot '${senderId}' could not be recovered and was quarantined: ${detail}`,
+      -1,
+      -1,
+      -1,
+      quarantinedPath,
+    );
+  }
+
+  private async writeFully(
+    fh: Awaited<ReturnType<typeof open>>,
+    data: Buffer,
+    position = 0,
+  ): Promise<void> {
+    let offset = 0;
+    while (offset < data.length) {
+      const { bytesWritten } = await fh.write(
+        data,
+        offset,
+        data.length - offset,
+        position + offset,
+      );
+      if (bytesWritten <= 0) throw new Error("file write made no progress");
+      offset += bytesWritten;
+    }
+  }
+
+  private writeSyncFully(data: Buffer): void {
+    if (this.dictFd === undefined)
+      throw new Error("symbol dictionary is not open");
+    let offset = 0;
+    while (offset < data.length) {
+      const written = writeSync(
+        this.dictFd,
+        data,
+        offset,
+        data.length - offset,
+        undefined,
+      );
+      if (written <= 0) throw new Error("file write made no progress");
+      offset += written;
+    }
+  }
+
+  private async openForUpdate(path: string) {
+    try {
+      return await open(path, "r+");
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+      return open(path, "w+");
+    }
+  }
+
+  /**
+   * Background / close-time durability barrier. Coalesces the ACK watermark
+   * write (C1) and, in periodic mode, fsyncs the dictionary before any segment
+   * that can reference it.
+   */
+  private async runBarrier(): Promise<void> {
+    // NOT gated on this.closed: close() relies on a final barrier after it has
+    // already cleared the timer and set closed, and runBarrier is protected from
+    // overlap by barrierInFlight (the timer is cleared before the final call).
+    if (!this.isDisk || !this.slot || this.barrierInFlight) return;
+    this.barrierInFlight = true;
+    try {
+      // Periodic covering order: the load-bearing symbol dictionary must reach
+      // disk before any segment that references its ids, then the watermark.
+      if (this.durability === "periodic" && this.dictDirty) {
+        fsyncSync(this.dictFd!);
+        this.dictDirty = false;
+      }
+      if (this.durability === "periodic" && this.fh) await this.fh.sync();
+      if (this.watermarkDirty) {
+        this.wmGen++;
+        writeBoundary(this.wmBuf, this.wmGen, this.lastWm);
+        const path = join(this.slot.slotDir, ACK_WATERMARK);
+        const fh = await this.openForUpdate(path);
+        try {
+          await this.writeFully(fh, this.wmBuf);
+          if (this.durability === "periodic") await fh.sync();
+        } finally {
+          await fh.close();
+        }
+        this.watermarkDirty = false;
+      }
+      // Note: Node exposes no directory fsync, so the slot-dir covering fsync
+      // of spec 8.2 has no portable Node analogue; the file fsyncs above are
+      // the load-bearing part.
+    } catch {
+      // Durability is best-effort on a failing filesystem; leave the dirty flag
+      // set so the next barrier retries.
+    } finally {
+      this.barrierInFlight = false;
+    }
+  }
+
+  /**
+   * Publishes a frame, returning its FSN or a negative sentinel. In disk mode
+   * the frame is written ahead to a segment file before returning.
+   */
+  append(frame: Buffer): Promise<number> {
+    if (this.closed)
+      return Promise.reject(new Error("store-and-forward engine is closed"));
+    const run = this.appendTail.then(() => this.appendOne(frame));
+    this.appendTail = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  private async appendOne(frame: Buffer): Promise<number> {
+    if (!this.isDisk || !this.slot) return this.ring.append(frame);
+    const fsn = this.ring.planAppend(frame);
+    if (fsn < 0) return fsn;
+    // Persistence is the publication boundary in disk mode. A failed write
+    // must not leave a replay-visible in-memory FSN behind.
+    await this.persistFrame(fsn, frame);
+    const committed = this.ring.append(frame);
+    if (committed !== fsn) {
+      throw new Error(
+        `store-and-forward append plan changed [planned=${fsn}, actual=${committed}]`,
+      );
+    }
+    return fsn;
+  }
+
+  private async openActiveFile(baseSeq: number): Promise<void> {
+    const path = join(this.slot!.slotDir, `${this.fileNo++}${SEGMENT_EXT}`);
+    const fh = await open(path, "w+");
+    let headerWritten = false;
+    try {
+      const header = Buffer.alloc(SEGMENT_HEADER_SIZE);
+      header.write("SF01", 0, "ascii");
+      header.writeUInt8(1, 4);
+      header.writeUInt8(MANIFEST_REQUIRED_FLAG, 5); // governed by sf-manifest.bin
+      header.writeBigUInt64LE(BigInt(baseSeq), 8);
+      await this.writeFully(fh, header);
+      headerWritten = true;
+      // Record the new chain head AFTER the complete segment header exists.
+      await this.persistManifest(baseSeq);
+      this.fh = fh;
+      this.activeOffset = SEGMENT_HEADER_SIZE;
+      this.activeDataBytes = 0;
+    } catch (e) {
+      await fh.close().catch(() => undefined);
+      // A complete empty header is recoverable and may be left behind if the
+      // manifest update failed. A partial header can only poison recovery.
+      if (!headerWritten)
+        await rm(path, { force: true }).catch(() => undefined);
+      throw e;
+    }
+  }
+
+  /** Writes the chain head into sf-manifest.bin, alternating records by generation. */
+  private async persistManifest(head: number): Promise<void> {
+    if (!this.isDisk || !this.slot) return;
+    this.manifestGen++;
+    writeManifest(this.manBuf, this.manifestGen, head);
+    const path = join(this.slot.slotDir, MANIFEST_FILE_NAME);
+    const fh = await this.openForUpdate(path);
+    try {
+      await this.writeFully(fh, this.manBuf);
+      if (this.durability === "periodic") await fh.sync();
+    } finally {
+      await fh.close();
+    }
+  }
+
+  private async persistFrame(fsn: number, frame: Buffer): Promise<void> {
+    if (!this.fh) await this.openActiveFile(fsn);
+    if (this.activeDataBytes + frame.length > this.opts.segmentBytes) {
+      await this.fh.close();
+      this.fh = undefined;
+      await this.openActiveFile(fsn);
+    }
+    // Frame = u32 crc32c(payloadLen ++ payload) | u32 payloadLen | payload (spec 8.1.5)
+    const tmp = Buffer.alloc(8 + frame.length);
+    const newOff = appendFrame(tmp, 0, frame);
+    const oldOffset = this.activeOffset;
+    const oldDataBytes = this.activeDataBytes;
+    try {
+      await this.writeFully(
+        this.fh!,
+        tmp.subarray(0, newOff),
+        this.activeOffset,
+      );
+      this.activeOffset += newOff;
+      this.activeDataBytes += frame.length;
+    } catch (e) {
+      // Keep a failed/short record out of subsequent scans and allow a retry at
+      // the same FSN to reuse the active segment safely.
+      await this.fh!.truncate(oldOffset).catch(() => undefined);
+      this.activeOffset = oldOffset;
+      this.activeDataBytes = oldDataBytes;
+      throw e;
+    }
+  }
+
+  acknowledge(fsn: number): void {
+    this.ring.acknowledge(fsn);
+    if (this.isDisk && this.slot && fsn >= 0 && BigInt(fsn) > this.lastWm) {
+      // Memory durability is a page-cache write coalesced onto the barrier
+      // cadence, never a per-ACK syscall (spec 8.2 consequence 1).
+      this.lastWm = BigInt(fsn);
+      this.watermarkDirty = true;
+    }
+  }
+
+  /**
+   * Write-ahead persist a batch of newly introduced symbols before the frame
+   * carrying them is published (spec 8.1.6). Synchronous because the buffer's
+   * persist hook is sync and must complete before the frame goes on the wire.
+   *
+   * Wired end-to-end by the Sender: `QwpTransport.attachSymbolBuffer` installs
+   * this as the buffer's persist hook, so delta mode is live in memory mode and
+   * (once `.symbol-dict` has opened) in disk mode. The engine writes the SYD1
+   * header on a fresh slot, then one chunk per frame; recovery re-reads it
+   * positionally (spec 8.1.6, handoff B1).
+   */
+  persistSymbols(entries: string[]): void {
+    if (!this.isDisk || entries.length === 0 || this.dictFd === undefined)
+      return;
+    const buf = encodeChunk(entries);
+    const start = fstatSync(this.dictFd).size;
+    try {
+      this.writeSyncFully(buf);
+      this.dictValidBytes = start + buf.length;
+      this.dictDirty = true;
+    } catch (e) {
+      // A failed loop may already have appended a prefix. Remove it now so a
+      // later valid positional chunk is not hidden behind an invalid tail.
+      ftruncateSync(this.dictFd, start);
+      throw e;
+    }
+  }
+
+  framesFrom(fsn: number): Buffer[] {
+    return this.ring.framesFrom(fsn);
+  }
+
+  /** Drops the bytes that survive the current ring so a fresh open re-scans. */
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.barrierTimer) {
+      clearInterval(this.barrierTimer);
+      this.barrierTimer = undefined;
+    }
+    await this.appendTail;
+    // Final barrier: persist any un-flushed ACK watermark before the files close.
+    await this.runBarrier();
+    if (this.fh) await this.fh.close();
+    if (this.dictFd !== undefined) closeSync(this.dictFd);
+    if (this.slot) await releaseSlot(this.slot);
+  }
+}
diff --git a/src/qwp/sf/manifest.ts b/src/qwp/sf/manifest.ts
new file mode 100644
index 0000000..07f8916
--- /dev/null
+++ b/src/qwp/sf/manifest.ts
@@ -0,0 +1,42 @@
+import { Buffer } from "node:buffer";
+import { writeBoundary, readBoundary, BOUNDARY_FILE_SIZE } from "./boundary";
+
+/**
+ * SfManifest (spec 8.2, 8.1.1) — the crash-safe boundary record that lets
+ * recovery cross-check the scanned segment chain head against a recorded head.
+ *
+ * Same alternating-generation scheme as `.ack-watermark`: an 8 KiB file holding
+ * two independently CRC-protected 64-byte records at offsets 0 and 4096. Writes
+ * alternate between the slots by generation parity; recovery keeps the valid
+ * record with the greatest generation, falling back to no manifest when neither
+ * validates or the file is absent.
+ *
+ * The recorded value is the chain head — the `baseSeq` of the newest (active)
+ * segment. Spec 8.1.1: "the chain head must match the manifest's recorded head".
+ */
+export const MANIFEST_FILE_NAME = "sf-manifest.bin";
+/** 'SFM1' as little-endian u32 (spec 8.2). */
+export const SFM1_MAGIC = 0x314d4653;
+
+export interface ManifestRecord {
+  generation: number;
+  /** Recorded chain head = baseSeq of the active segment. */
+  headBaseSeq: number;
+}
+
+/** Writes the manifest into an 8 KiB buffer, alternating slots by generation. */
+export function writeManifest(
+  buf: Buffer,
+  generation: number,
+  headBaseSeq: number,
+): void {
+  writeBoundary(buf, generation, BigInt(headBaseSeq), SFM1_MAGIC);
+}
+
+/** Reads the manifest; returns null when absent or neither record validates. */
+export function readManifest(buf: Buffer): ManifestRecord | null {
+  const b = readBoundary(buf, SFM1_MAGIC);
+  return b ? { generation: b.generation, headBaseSeq: Number(b.value) } : null;
+}
+
+export { BOUNDARY_FILE_SIZE as MANIFEST_FILE_SIZE };
diff --git a/src/qwp/sf/orphanScanner.ts b/src/qwp/sf/orphanScanner.ts
new file mode 100644
index 0000000..31389b6
--- /dev/null
+++ b/src/qwp/sf/orphanScanner.ts
@@ -0,0 +1,44 @@
+import { access, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { isLiveLock } from "./slotLock";
+
+export interface OrphanSlot {
+  senderId: string;
+  slotDir: string;
+}
+
+/**
+ * A quarantined slot is renamed to `<senderId>.quarantined.<n>`, so a generic
+ * trailing-infx test (any sender) catches every copy regardless of who owns it.
+ * These are skipped by the orphan scanner: a quarantined slot already carries a
+ * `.failed` sentinel and must be inspected by a human, never replayed (spec 8.4).
+ */
+const QUARANTINE_RE = /\.quarantined\.\d+$/;
+
+/**
+ * Scans `<sf_dir>/` for slot directories not held by a live lock (spec 8.4).
+ * A slot is skipped when its `.lock` is live (actively owned); it is an orphan
+ * when the lock is absent or stale (the holder crashed). Dotfiles (including
+ * the `.slot-locks` logical-lock area) and quarantined slots are ignored.
+ */
+export async function scanOrphans(sfDir: string): Promise<OrphanSlot[]> {
+  const entries = await readdir(sfDir, { withFileTypes: true }).catch(() => []);
+  const orphans: OrphanSlot[] = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const name = e.name;
+    if (name.startsWith(".")) continue; // dotfiles / .slot-locks
+    if (QUARANTINE_RE.test(name)) continue; // quarantined, human-in-the-loop
+    const slotDir = join(sfDir, name);
+    // A terminal drainer failure is an operator gate. Do not retry until the
+    // sentinel is explicitly removed.
+    const failed = await access(join(slotDir, ".failed")).then(
+      () => true,
+      () => false,
+    );
+    if (failed) continue;
+    const live = await isLiveLock(join(slotDir, ".lock"));
+    if (!live) orphans.push({ senderId: name, slotDir });
+  }
+  return orphans;
+}
diff --git a/src/qwp/sf/quarantine.ts b/src/qwp/sf/quarantine.ts
new file mode 100644
index 0000000..2708e7d
--- /dev/null
+++ b/src/qwp/sf/quarantine.ts
@@ -0,0 +1,50 @@
+import { readdir, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Two-step quarantine for a slot recovery could not open (spec 8.4):
+ * 1. rename the slot so a restarting sender does not re-adopt it as its own
+ *    working slot (acquireSlot only ever adopts exactly `<sf_dir>/<sender_id>`);
+ * 2. drop a `.failed` sentinel so an orphan drainer skips it too.
+ *
+ * The capacity cap (64 copies per sf_dir) refuses to set any more aside: each
+ * quarantined slot is an unreplayable slot a human must inspect, and letting
+ * them pile up turns a disk-space problem into a second incident.
+ */
+export const QUARANTINE_INFIX = ".quarantined.";
+const FAILED_SENTINEL = ".failed";
+export const MAX_QUARANTINED = 64;
+
+/**
+ * Sets a slot aside and returns the renamed path. Throws (without renaming)
+ * when the 64-copy cap for this slot is already reached.
+ */
+export async function quarantineSlot(
+  sfDir: string,
+  senderId: string,
+  slotDir: string,
+): Promise<string> {
+  const re = new RegExp(`^${escapeRegExp(senderId)}${QUARANTINE_INFIX}\\d+$`);
+  const existing = (await readdir(sfDir).catch(() => [])).filter((e) => re.test(e));
+  if (existing.length >= MAX_QUARANTINED) {
+    throw new Error(
+      `refusing to quarantine another copy of slot '${senderId}' ` +
+        `(${MAX_QUARANTINED} already set aside under ${sfDir}); operator must clear them`,
+    );
+  }
+  let idx = 0;
+  for (const e of existing) {
+    const n = Number(e.slice(e.lastIndexOf(QUARANTINE_INFIX) + QUARANTINE_INFIX.length));
+    if (n >= idx) idx = n + 1;
+  }
+  const destDir = join(sfDir, `${senderId}${QUARANTINE_INFIX}${idx}`);
+  await rename(slotDir, destDir);
+  // Sentinel AFTER the rename so a crash between the two leaves no orphan .failed.
+  await writeFile(join(destDir, FAILED_SENTINEL), `quarantined at ${new Date().toISOString()}\n`);
+  return destDir;
+}
+
+function escapeRegExp(s: string): string {
+  // sender_id is a config string; neutralise regex metacharacters.
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
diff --git a/src/qwp/sf/ring.ts b/src/qwp/sf/ring.ts
new file mode 100644
index 0000000..a4dfdf4
--- /dev/null
+++ b/src/qwp/sf/ring.ts
@@ -0,0 +1,123 @@
+import { Buffer } from "node:buffer";
+
+export const BACKPRESSURE_NO_SPARE = -1;
+export const PAYLOAD_TOO_LARGE = -2;
+
+interface Seg {
+  baseSeq: number;
+  frames: Buffer[];
+  bytes: number;
+}
+
+export interface RingOptions {
+  segmentBytes: number;
+  maxTotalBytes: number;
+}
+
+export class SegmentRing {
+  private segs: Seg[] = [];
+  private nextSeq = 0;
+  private acked = -1;
+
+  constructor(private readonly opts: RingOptions) {
+    this.segs.push({ baseSeq: 0, frames: [], bytes: 0 });
+  }
+
+  /** FSNs derive from the chain, so a recovered ring continues numbering. */
+  static recovered(
+    chain: { baseSeq: number; frames: Buffer[] }[],
+    opts: RingOptions,
+  ): SegmentRing {
+    const r = new SegmentRing(opts);
+    r.segs = chain.map((c) => ({
+      baseSeq: c.baseSeq,
+      frames: c.frames,
+      bytes: c.frames.reduce((a, f) => a + f.length, 0),
+    }));
+    r.segs.sort((a, b) => a.baseSeq - b.baseSeq);
+    for (let i = 1; i < r.segs.length; i++) {
+      const prev = r.segs[i - 1];
+      if (prev.baseSeq + prev.frames.length !== r.segs[i].baseSeq) {
+        throw new Error("segment chain is not contiguous");
+      }
+    }
+    for (const s of r.segs) {
+      if (s.baseSeq < 0)
+        throw new Error("segment with negative baseSeq must be quarantined");
+    }
+    const last = r.segs[r.segs.length - 1];
+    r.nextSeq = last.baseSeq + last.frames.length;
+    return r;
+  }
+
+  get publishedFsn(): number {
+    return this.nextSeq - 1;
+  }
+
+  get ackedFsn(): number {
+    return this.acked;
+  }
+
+  get totalBytes(): number {
+    return this.segs.reduce((a, s) => a + s.bytes, 0);
+  }
+
+  /**
+   * Returns the FSN append() would assign without mutating the ring, or a
+   * negative sentinel. Disk mode uses this to persist before publication.
+   */
+  planAppend(frame: Buffer): number {
+    if (frame.length > this.opts.segmentBytes) return PAYLOAD_TOO_LARGE;
+    const active = this.segs[this.segs.length - 1];
+    if (
+      active.bytes + frame.length > this.opts.segmentBytes &&
+      this.totalBytes + frame.length > this.livenessFloorAdjustedCap()
+    ) {
+      return BACKPRESSURE_NO_SPARE;
+    }
+    return this.nextSeq;
+  }
+
+  /** Returns the assigned FSN, or a negative sentinel. */
+  append(frame: Buffer): number {
+    const planned = this.planAppend(frame);
+    if (planned < 0) return planned;
+    const active = this.segs[this.segs.length - 1];
+    if (active.bytes + frame.length > this.opts.segmentBytes) {
+      this.segs.push({ baseSeq: this.nextSeq, frames: [], bytes: 0 });
+    }
+    const seg = this.segs[this.segs.length - 1];
+    seg.frames.push(frame);
+    seg.bytes += frame.length;
+    this.nextSeq++;
+    return planned;
+  }
+
+  /**
+   * Never refuse below the minimum working set. Segment bytes are reclaimable
+   * by ACK-driven trim, but side files are lifetime-monotonic, so refusing on
+   * the raw total can wedge the producer permanently (spec 8.1.3).
+   */
+  private livenessFloorAdjustedCap(): number {
+    return Math.max(this.opts.maxTotalBytes, 2 * this.opts.segmentBytes);
+  }
+
+  acknowledge(fsn: number): void {
+    if (fsn > this.acked) this.acked = fsn;
+    while (this.segs.length > 1) {
+      const head = this.segs[0];
+      if (head.baseSeq + head.frames.length - 1 > this.acked) break;
+      this.segs.shift();
+    }
+  }
+
+  framesFrom(fsn: number): Buffer[] {
+    const out: Buffer[] = [];
+    for (const s of this.segs) {
+      s.frames.forEach((f, i) => {
+        if (s.baseSeq + i >= fsn) out.push(f);
+      });
+    }
+    return out;
+  }
+}
diff --git a/src/qwp/sf/segment.ts b/src/qwp/sf/segment.ts
new file mode 100644
index 0000000..6daf3f2
--- /dev/null
+++ b/src/qwp/sf/segment.ts
@@ -0,0 +1,89 @@
+import { Buffer } from "node:buffer";
+import { crc32c } from "./crc32c";
+
+export const SEGMENT_MAGIC = Buffer.from("SF01", "ascii");
+export const SEGMENT_HEADER_SIZE = 24;
+export const FRAME_HEADER_SIZE = 8;
+
+export interface ScanResult {
+  baseSeq: number;
+  flags: number;
+  frames: Buffer[];
+  /** Bytes of non-zero residue after the last valid frame. 0 = clean fill. */
+  tornTailBytes: number;
+  /** Offset where the next append must start. */
+  appendOffset: number;
+}
+
+export function buildSegment(
+  baseSeq: number,
+  frames: Buffer[],
+  capacity: number,
+): Buffer {
+  const buf = Buffer.alloc(capacity);
+  SEGMENT_MAGIC.copy(buf, 0);
+  buf.writeUInt8(1, 4); // version
+  buf.writeUInt8(0, 5); // flags
+  buf.writeUInt16LE(0, 6); // reserved
+  buf.writeBigUInt64LE(BigInt(baseSeq), 8);
+  buf.writeBigUInt64LE(0n, 16); // createdMicros; stamped by the caller if needed
+  let o = SEGMENT_HEADER_SIZE;
+  for (const f of frames) o = appendFrame(buf, o, f);
+  return buf;
+}
+
+/** Returns the new offset, or -1 when the frame does not fit. */
+export function appendFrame(
+  buf: Buffer,
+  offset: number,
+  payload: Buffer,
+): number {
+  const need = FRAME_HEADER_SIZE + payload.length;
+  if (offset + need > buf.length) return -1;
+  // CRC covers (payloadLen, payload) together -- not the payload alone.
+  const lenAndPayload = Buffer.allocUnsafe(4 + payload.length);
+  lenAndPayload.writeUInt32LE(payload.length, 0);
+  payload.copy(lenAndPayload, 4);
+  buf.writeUInt32LE(crc32c(lenAndPayload), offset);
+  buf.writeUInt32LE(payload.length, offset + 4);
+  payload.copy(buf, offset + 8);
+  return offset + need;
+}
+
+export function scanSegment(buf: Buffer): ScanResult {
+  if (
+    buf.length < SEGMENT_HEADER_SIZE ||
+    !buf.subarray(0, 4).equals(SEGMENT_MAGIC)
+  ) {
+    throw new Error("segment: bad magic");
+  }
+  if (buf.readUInt8(4) !== 1) throw new Error("segment: unsupported version");
+  const flags = buf.readUInt8(5);
+  const baseSeq = Number(buf.readBigUInt64LE(8));
+
+  const frames: Buffer[] = [];
+  let o = SEGMENT_HEADER_SIZE;
+  for (;;) {
+    if (o + FRAME_HEADER_SIZE > buf.length) break;
+    const crc = buf.readUInt32LE(o);
+    const len = buf.readUInt32LE(o + 4);
+    if (len === 0 && crc === 0) break; // unwritten space
+    if (o + FRAME_HEADER_SIZE + len > buf.length) break; // declared length overruns
+    const lenAndPayload = buf.subarray(o + 4, o + FRAME_HEADER_SIZE + len);
+    if (crc32c(lenAndPayload) !== crc) break; // first bad CRC ends the chain
+    frames.push(
+      Buffer.from(
+        buf.subarray(o + FRAME_HEADER_SIZE, o + FRAME_HEADER_SIZE + len),
+      ),
+    );
+    o += FRAME_HEADER_SIZE + len;
+  }
+
+  // Non-zero residue means a write was attempted and failed. Do NOT zero it
+  // here: after a mid-file tear it can hold valid-CRC frames that are the only
+  // surviving copy of real payloads (spec 8.1.5).
+  let torn = 0;
+  for (let i = o; i < buf.length; i++) if (buf[i] !== 0) torn++;
+
+  return { baseSeq, flags, frames, tornTailBytes: torn, appendOffset: o };
+}
diff --git a/src/qwp/sf/slotLock.ts b/src/qwp/sf/slotLock.ts
new file mode 100644
index 0000000..2c28e27
--- /dev/null
+++ b/src/qwp/sf/slotLock.ts
@@ -0,0 +1,334 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  link,
+  mkdir,
+  open,
+  readFile,
+  rm,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface SlotHandle {
+  slotDir: string;
+  lockPath: string;
+  ownerToken: string;
+}
+
+function readBootId(): string {
+  try {
+    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+function processStatFields(pid: number): string[] | undefined {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // The process name is parenthesised and can contain spaces. Field 3 starts
+    // after its final ')'.
+    return stat
+      .slice(stat.lastIndexOf(")") + 2)
+      .trim()
+      .split(/\s+/);
+  } catch {
+    return undefined;
+  }
+}
+
+function processStartIdentity(pid: number): string {
+  return processStatFields(pid)?.[19] ?? "unknown"; // /proc field 22
+}
+
+const BOOT_ID = readBootId();
+const PROCESS_START_ID = processStartIdentity(process.pid);
+const logicalOwners = new Map<string, string>();
+
+function lockContents(ownerToken: string): string {
+  return `${process.pid}\n${BOOT_ID}\n${PROCESS_START_ID}\n${ownerToken}\n`;
+}
+
+function genuineBootId(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value);
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    // A killed but not-yet-reaped child still has a PID and answers signal 0,
+    // but cannot own or release the lock. /proc field 3 identifies zombies.
+    if (processStatFields(pid)?.[0] === "Z") return false;
+    return true;
+  } catch (e: unknown) {
+    // EPERM proves that a process exists but is owned by another user.
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** A holder is live unless we can positively prove its process identity is stale. */
+export function lockHolderLive(
+  pid: number,
+  boot: string,
+  startIdentity = "unknown",
+): boolean {
+  if (!isAlive(pid)) return false;
+  // Compare boot ids only when both are genuine. This keeps lockfiles written
+  // by older clients conservative rather than stealing from a live process.
+  if (genuineBootId(BOOT_ID) && genuineBootId(boot) && boot !== BOOT_ID) {
+    return false;
+  }
+  const currentStart = processStartIdentity(pid);
+  if (
+    startIdentity &&
+    startIdentity !== "unknown" &&
+    currentStart !== "unknown" &&
+    startIdentity !== currentStart
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function parseLock(data: string): {
+  pid: number;
+  boot: string;
+  startIdentity: string;
+  ownerToken: string;
+} {
+  const [pidStr, boot = "unknown", startIdentity = "unknown", ownerToken = ""] =
+    data.split("\n");
+  return {
+    pid: Number.parseInt(pidStr, 10),
+    boot,
+    startIdentity,
+    ownerToken,
+  };
+}
+
+export async function isLiveLock(lockPath: string): Promise<boolean> {
+  const data = await readFile(lockPath, "utf8").catch(() => undefined);
+  if (!data) return false;
+  const { pid, boot, startIdentity } = parseLock(data);
+  return Number.isFinite(pid) && lockHolderLive(pid, boot, startIdentity);
+}
+
+/**
+ * Publish complete metadata atomically. Linking a fully-written sibling temp
+ * file avoids the empty/partial record window of open("wx") followed by write.
+ */
+async function publishLock(
+  lockPath: string,
+  ownerToken: string,
+): Promise<void> {
+  const tempPath = `${lockPath}.${process.pid}.${ownerToken}.tmp`;
+  const fh = await open(tempPath, "wx");
+  try {
+    try {
+      await fh.writeFile(lockContents(ownerToken), "utf8");
+    } finally {
+      await fh.close();
+    }
+    await link(tempPath, lockPath); // atomic EEXIST if another holder won
+  } finally {
+    await unlink(tempPath).catch(() => undefined);
+  }
+}
+
+const TAKEOVER_OWNER = ".owner";
+const EMPTY_GUARD_GRACE_MS = 100;
+
+function lockInUse(path: string): NodeJS.ErrnoException {
+  const e = new Error(`lock in use [path=${path}]`) as NodeJS.ErrnoException;
+  e.code = "EEXIST";
+  return e;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Serialize every acquire/release pathname transition. The guard carries the
+ * same process identity as the slot lock, so a crash in takeover is recoverable
+ * instead of wedging the slot forever. Empty guards get a short grace period
+ * for the creator to publish their owner record.
+ */
+async function acquireTransition(
+  lockPath: string,
+): Promise<string | undefined> {
+  const guardPath = `${lockPath}.takeover`;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const token = randomUUID();
+    try {
+      await mkdir(guardPath);
+      await writeFile(join(guardPath, TAKEOVER_OWNER), lockContents(token), {
+        flag: "wx",
+      });
+      return token;
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") {
+        await rm(guardPath, { recursive: true, force: true }).catch(
+          () => undefined,
+        );
+        throw e;
+      }
+      const ownerPath = join(guardPath, TAKEOVER_OWNER);
+      const data = await readFile(ownerPath, "utf8").catch(() => undefined);
+      if (data) {
+        const owner = parseLock(data);
+        if (
+          Number.isFinite(owner.pid) &&
+          lockHolderLive(owner.pid, owner.boot, owner.startIdentity)
+        ) {
+          return undefined;
+        }
+      } else {
+        const info = await stat(guardPath).catch(() => undefined);
+        if (info && Date.now() - info.mtimeMs < EMPTY_GUARD_GRACE_MS) {
+          return undefined;
+        }
+      }
+      // Revalidate after a scheduling turn so a just-created live guard is not
+      // mistaken for the stale record observed above.
+      await sleep(10);
+      const current = await readFile(ownerPath, "utf8").catch(() => undefined);
+      if (current) {
+        const owner = parseLock(current);
+        if (
+          Number.isFinite(owner.pid) &&
+          lockHolderLive(owner.pid, owner.boot, owner.startIdentity)
+        ) {
+          return undefined;
+        }
+      }
+      await rm(guardPath, { recursive: true, force: true }).catch(
+        () => undefined,
+      );
+    }
+  }
+  return undefined;
+}
+
+async function releaseTransition(
+  lockPath: string,
+  ownerToken: string,
+): Promise<void> {
+  const guardPath = `${lockPath}.takeover`;
+  const data = await readFile(join(guardPath, TAKEOVER_OWNER), "utf8").catch(
+    () => undefined,
+  );
+  if (!data || parseLock(data).ownerToken !== ownerToken) return;
+  await rm(guardPath, { recursive: true, force: true }).catch(() => undefined);
+}
+
+async function acquireLock(lockPath: string): Promise<string> {
+  await mkdir(dirname(lockPath), { recursive: true });
+  const transition = await acquireTransition(lockPath);
+  if (!transition) throw lockInUse(lockPath);
+  try {
+    const ownerToken = randomUUID();
+    try {
+      await publishLock(lockPath, ownerToken);
+      return ownerToken;
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+      const data = await readFile(lockPath, "utf8").catch(() => undefined);
+      if (data) {
+        const owner = parseLock(data);
+        if (
+          Number.isFinite(owner.pid) &&
+          lockHolderLive(owner.pid, owner.boot, owner.startIdentity)
+        ) {
+          throw e;
+        }
+      }
+      await unlink(lockPath).catch((unlinkError: unknown) => {
+        if ((unlinkError as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw unlinkError;
+        }
+      });
+      await publishLock(lockPath, ownerToken);
+      return ownerToken;
+    }
+  } finally {
+    await releaseTransition(lockPath, transition);
+  }
+}
+
+async function releaseOwnedLock(
+  lockPath: string,
+  ownerToken: string,
+): Promise<void> {
+  // Acquisition and release both use the transition guard, making token check
+  // plus unlink atomic with respect to replacement publication.
+  for (let attempt = 0; attempt < 20; attempt++) {
+    const transition = await acquireTransition(lockPath);
+    if (!transition) {
+      await sleep(10);
+      continue;
+    }
+    try {
+      const data = await readFile(lockPath, "utf8").catch(() => undefined);
+      if (!data || parseLock(data).ownerToken !== ownerToken) return;
+      await unlink(lockPath).catch(() => undefined);
+      return;
+    } finally {
+      await releaseTransition(lockPath, transition);
+    }
+  }
+}
+
+const LOGICAL_LOCK_DIR = ".slot-locks";
+
+export async function acquireLogicalLock(
+  sfDir: string,
+  senderId: string,
+): Promise<void> {
+  const lockPath = join(sfDir, LOGICAL_LOCK_DIR, senderId);
+  try {
+    const ownerToken = await acquireLock(lockPath);
+    logicalOwners.set(lockPath, ownerToken);
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+    throw new Error(`logical lock in use [dir=${lockPath}]`);
+  }
+}
+
+export async function releaseLogicalLock(
+  sfDir: string,
+  senderId: string,
+): Promise<void> {
+  const lockPath = join(sfDir, LOGICAL_LOCK_DIR, senderId);
+  const ownerToken = logicalOwners.get(lockPath);
+  if (!ownerToken) return;
+  logicalOwners.delete(lockPath);
+  await releaseOwnedLock(lockPath, ownerToken);
+}
+
+export async function acquireSlot(
+  sfDir: string,
+  senderId: string,
+): Promise<SlotHandle> {
+  const slotDir = join(sfDir, senderId);
+  const lockPath = join(slotDir, ".lock");
+  try {
+    const ownerToken = await acquireLock(lockPath);
+    return { slotDir, lockPath, ownerToken };
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+    const data = await readFile(lockPath, "utf8").catch(() => "");
+    const { pid } = parseLock(data);
+    throw new Error(
+      `sf slot already in use [dir=${slotDir}, holderPid=${pid}]. ` +
+        `Set a distinct sender_id for each sender sharing sf_dir.`,
+    );
+  }
+}
+
+export async function releaseSlot(h: SlotHandle): Promise<void> {
+  await releaseOwnedLock(h.lockPath, h.ownerToken);
+}
diff --git a/src/qwp/sf/symbolDictFile.ts b/src/qwp/sf/symbolDictFile.ts
new file mode 100644
index 0000000..5631bbd
--- /dev/null
+++ b/src/qwp/sf/symbolDictFile.ts
@@ -0,0 +1,105 @@
+import { Buffer } from "node:buffer";
+import { crc32c } from "./crc32c";
+import { writeVarint, varintSize, readVarint } from "../protocol/varint";
+
+export const DICT_HEADER = (() => {
+  const b = Buffer.alloc(8);
+  b.write("SYD1", 0, "ascii");
+  b.writeUInt8(1, 4);
+  return b;
+})();
+
+/** One chunk = exactly the symbols one frame introduces (spec 8.1.6). */
+export function encodeChunk(entries: string[]): Buffer {
+  let entryBytes = 0;
+  for (const s of entries) {
+    const n = Buffer.byteLength(s, "utf8");
+    entryBytes += varintSize(n) + n;
+  }
+  const head = Buffer.alloc(
+    varintSize(entries.length) + varintSize(entryBytes),
+  );
+  let ho = writeVarint(head, 0, entries.length);
+  ho = writeVarint(head, ho, entryBytes);
+
+  const body = Buffer.alloc(entryBytes);
+  let bo = 0;
+  for (const s of entries) {
+    const n = Buffer.byteLength(s, "utf8");
+    bo = writeVarint(body, bo, n);
+    body.write(s, bo, "utf8");
+    bo += n;
+  }
+
+  // CRC covers BOTH header varints and the entry region.
+  const crcInput = Buffer.concat([head.subarray(0, ho), body]);
+  const tail = Buffer.alloc(4);
+  tail.writeUInt32LE(crc32c(crcInput), 0);
+  return Buffer.concat([head.subarray(0, ho), body, tail]);
+}
+
+export interface DecodedDictFile {
+  entries: string[];
+  /** Byte offset immediately after the last fully validated chunk. */
+  validBytes: number;
+}
+
+export function decodeDictFileState(file: Buffer): DecodedDictFile {
+  if (
+    file.length < DICT_HEADER.length ||
+    file.subarray(0, 4).toString("ascii") !== "SYD1"
+  ) {
+    throw new Error("symbol dict: bad magic");
+  }
+  const out: string[] = [];
+  let o = DICT_HEADER.length;
+  let validBytes = o;
+  while (o < file.length) {
+    const start = o;
+    let count: number;
+    let entryBytes: number;
+    try {
+      const r = readVarint(file, o);
+      count = r.value;
+      o = r.offset;
+      const r2 = readVarint(file, o);
+      entryBytes = r2.value;
+      o = r2.offset;
+    } catch {
+      break;
+    }
+    if (o + entryBytes + 4 > file.length) break;
+    const crcInput = file.subarray(start, o + entryBytes);
+    if (crc32c(crcInput) !== file.readUInt32LE(o + entryBytes)) {
+      // The complete declared chunk and CRC are present: this is detectable
+      // corruption, not a torn tail that is safe to truncate.
+      throw new Error("symbol dict: chunk CRC mismatch");
+    }
+
+    const chunkEntries: string[] = [];
+    let eo = o;
+    try {
+      for (let i = 0; i < count; i++) {
+        const rl = readVarint(file, eo);
+        eo = rl.offset;
+        if (eo + rl.value > o + entryBytes)
+          throw new Error("entry exceeds chunk");
+        chunkEntries.push(file.subarray(eo, eo + rl.value).toString("utf8"));
+        eo += rl.value;
+      }
+    } catch {
+      throw new Error("symbol dict: corrupt chunk entries");
+    }
+    if (eo !== o + entryBytes) {
+      throw new Error("symbol dict: corrupt chunk length");
+    }
+    out.push(...chunkEntries);
+    o += entryBytes + 4;
+    validBytes = o;
+  }
+  return { entries: out, validBytes };
+}
+
+export function decodeDictFile(file: Buffer): string[] {
+  return decodeDictFileState(file).entries;
+}
diff --git a/src/qwp/transport.ts b/src/qwp/transport.ts
new file mode 100644
index 0000000..8c3556a
--- /dev/null
+++ b/src/qwp/transport.ts
@@ -0,0 +1,705 @@
+import { Buffer } from "node:buffer";
+import { SenderTransport } from "../transport";
+import { SenderOptions } from "../options";
+import { QwpWebSocket, QwpWebSocketOptions } from "./ws/socket";
+import { QwpUpgradeError } from "./ws/handshake";
+import { decodeResponse, STATUS } from "./protocol/response";
+import { UNCAPPED_CATCHUP_PACKING_LIMIT } from "./protocol/constants";
+import { encodeFrame } from "./protocol/frameEncoder";
+import { SymbolDict } from "./protocol/symbolDict";
+import { AckTracker } from "./ackTracker";
+import { DurableAckTracker } from "./durableAckTracker";
+import {
+  SenderError,
+  classify,
+  defaultPolicyFor,
+  Policy,
+  Category,
+} from "./errors";
+import { HostTracker, HostState } from "./hostTracker";
+import { Endpoint, parseAddrList } from "./endpoints";
+import { Dispatcher } from "./dispatcher";
+import { PoisonDetector } from "./poison";
+import { SfEngine } from "./sf/engine";
+import { startOrphanDrainers, OrphanDrainer } from "./sf/drainer";
+import { QwpBuffer } from "./buffer";
+import { BACKPRESSURE_NO_SPARE, PAYLOAD_TOO_LARGE } from "./sf/ring";
+
+const QWP_DEFAULT_AUTO_FLUSH_ROWS = 1000; // spec 9.1
+// Memory-mode store-and-forward defaults (spec 9.1, 9.2). The ring lives on
+// the transport for every sender; disk mode swaps the engine in later.
+const MEMORY_SEGMENT_BYTES = 4 * 1024 * 1024;
+const MEMORY_MAX_TOTAL_BYTES = 128 * 1024 * 1024;
+/** spec 9.1: disk-mode retention is ~80x the memory-mode ring. */
+const DISK_MAX_TOTAL_BYTES = 10 * 1024 * 1024 * 1024;
+const SF_APPEND_DEADLINE_MILLIS = 30_000; // spec 4.4
+const DEFAULT_SENDER_ID = "default";
+const CLIENT_ID = "nodejs/1.0.0"; // protocol client version, not the package version (spec 6.5)
+
+export enum ConnectMode {
+  OFF = "OFF",
+  SYNC = "SYNC",
+}
+
+/** Terminal durable-ack capability gap; escapes the rotation loop (spec 6.5.1). */
+class DurableAckMismatchError extends Error {}
+
+export interface ConnectionEvent {
+  type: "connected" | "disconnected";
+  endpoint?: Endpoint;
+  reason?: string;
+}
+
+/**
+ * The default is DERIVED: setting any reconnect_* key implicitly upgrades
+ * construction from non-connecting to connecting-with-retry, because those
+ * knobs read as a general retry budget while the underlying path governs only
+ * reconnects from an established connection (spec 4.3).
+ */
+export function deriveConnectMode(o: SenderOptions): ConnectMode {
+  const anyReconnect =
+    o.reconnect_max_duration_millis !== undefined ||
+    o.reconnect_initial_backoff_millis !== undefined ||
+    o.reconnect_max_backoff_millis !== undefined;
+  return anyReconnect ? ConnectMode.SYNC : ConnectMode.OFF;
+}
+
+export class QwpTransport implements SenderTransport {
+  private readonly options: SenderOptions;
+  private ws?: QwpWebSocket;
+  private readonly acks = new AckTracker();
+  private readonly durableAcks = new DurableAckTracker();
+  private readonly errors: Dispatcher<SenderError>;
+  private readonly events: Dispatcher<ConnectionEvent>;
+  private errorConsumer?: (e: SenderError) => void;
+  private eventConsumer?: (e: ConnectionEvent) => void;
+  private endpoints: Endpoint[] = [];
+  private tracker!: HostTracker;
+  private current?: Endpoint;
+  private readonly dict = new SymbolDict();
+  private confirmedMaxId = -1;
+  private engine: SfEngine;
+  /** The producer's buffer, once the Sender has attached it (delta wiring). */
+  private buffer?: QwpBuffer;
+  /** Highest FSN sent on the current connection (wire replay start). */
+  private sentUpTo = -1;
+  private reconnecting = false;
+  private closed = false;
+  private terminalError?: SenderError;
+  /** Ignore late callbacks from a socket that has already been recycled. */
+  private connectionGeneration = 0;
+  private activeConnectionGeneration = 0;
+  /** Orphan drainers launched on startup (spec 8.4); stopped on close(). */
+  private drainStarted = false;
+  private drainers: OrphanDrainer[] = [];
+  private drainerStartPromise?: Promise<void>;
+  /** Poison-frame escalation (spec 7.4): strikes AND dwell, keyed on FSN. */
+  private readonly poison: PoisonDetector;
+  private poisoned = false;
+  /** In-flight public connect, so an explicit connect() reuses the constructor's
+   *  fire-and-forget one instead of double-opening the engine (spec 4.3). */
+  private connectPromise?: Promise<boolean>;
+  /** Includes post-upgrade catch-up/replay so only one loop mutates wire state. */
+  private connectLoopPromise?: Promise<boolean>;
+  /** Serialize whole publish batches so split frames and ACK correlation stay ordered. */
+  private publishTail: Promise<void> = Promise.resolve();
+  /** Reconnect replay and producer publication share one wire drain. */
+  private drainTail: Promise<void> = Promise.resolve();
+
+  constructor(options: SenderOptions) {
+    this.options = options;
+    this.engine = new SfEngine({
+      segmentBytes: options.sf_segment_bytes ?? MEMORY_SEGMENT_BYTES,
+      // spec 9.1: the total-retention default is mode-dependent — 128 MiB in
+      // memory mode, 10 GiB in disk mode (sf_dir present). Applying the memory
+      // figure to a disk user would cap retention ~80x early and shed unacked
+      // frames during exactly the outage store-and-forward exists to survive.
+      maxTotalBytes:
+        options.sf_max_total_bytes ??
+        (options.sf_dir ? DISK_MAX_TOTAL_BYTES : MEMORY_MAX_TOTAL_BYTES),
+      sfDir: options.sf_dir,
+      senderId: options.sender_id ?? DEFAULT_SENDER_ID,
+      durability: options.sf_durability === "periodic" ? "periodic" : "memory",
+      syncIntervalMillis: options.sf_sync_interval_millis,
+    });
+    this.errors = new Dispatcher(options.error_inbox_capacity ?? 256, (e) =>
+      this.errorConsumer?.(e),
+    );
+    // The connection-event inbox is a SEPARATE drop-oldest inbox at capacity
+    // 64 (spec 9.1): error and connection notifications must not share a fence.
+    this.events = new Dispatcher(
+      options.connection_listener_inbox_capacity ?? 64,
+      (e) => this.eventConsumer?.(e),
+    );
+    this.poison = new PoisonDetector(
+      options.max_frame_rejections ?? 4, // spec 9.1
+      options.poison_min_escalation_window_millis ?? 5_000, // spec 9.1
+    );
+  }
+
+  onError(h: (e: SenderError) => void): void {
+    this.errorConsumer = h;
+  }
+
+  onConnectionEvent(h: (e: ConnectionEvent) => void): void {
+    this.eventConsumer = h;
+  }
+
+  /**
+   * Attach the producer's buffer so delta symbol-dictionary mode can run
+   * end-to-end (spec 8.1.6). Shares the transport-owned connection dictionary
+   * with the buffer and installs the engine's write-ahead persist hook. Must be
+   * called once, before connect(), from the Sender construction path.
+   */
+  attachSymbolBuffer(b: QwpBuffer): void {
+    this.buffer = b;
+    b.attachDict(this.dict, (entries) => this.engine.persistSymbols(entries));
+  }
+
+  get ackedFsn(): number {
+    return this.engine.ackedFsn;
+  }
+
+  /** The store-and-forward engine's configured retention cap (test hook). */
+  get engineMaxTotalBytes(): number {
+    return this.engine.maxTotalBytes;
+  }
+
+  private emit(e: SenderError): void {
+    // Delivered async via the drop-oldest inbox; a handler must never break the
+    // sender (spec 4.2).
+    this.errors.offer(e);
+  }
+
+  private emitConnectionEvent(e: ConnectionEvent): void {
+    this.events.offer(e);
+  }
+
+  async connect(): Promise<boolean> {
+    if (this.terminalError) throw this.terminalError;
+    // Idempotent: the constructor may already have kicked off a fire-and-forget
+    // connect (derived SYNC mode). An explicit connect() must join that in-flight
+    // attempt rather than open the engine a second time (spec 4.3, 8.3 slot lock).
+    if (this.ws) return true;
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = this.doConnect().finally(() => {
+      this.connectPromise = undefined;
+    });
+    return this.connectPromise;
+  }
+
+  private async doConnect(): Promise<boolean> {
+    await this.engine.open();
+    // Recovery seeding (spec 8.1.6, 5.2): the engine's recovered dictionary is a
+    // DIFFERENT SymbolDict from the transport's connection-scoped one. Seed ours
+    // positionally via addRecovered (never getOrAdd, which de-dupes and would
+    // desync the persisted id scheme), and tell the buffer the recovered count is
+    // already confirmed. That way the first flush only persists/ships NEW
+    // symbols and does not re-write the recovered baseline to .symbol-dict. The
+    // recovered symbols themselves reach the fresh server via the catch-up frame
+    // in connectLoop (spec 7.5).
+    if (this.engine.isDisk) {
+      const recovered = this.engine.symbolDict;
+      const recoveredSize = recovered.size();
+      for (const s of recovered.entriesFrom(0)) this.dict.addRecovered(s);
+      if (recoveredSize > 0) this.buffer?.setConfirmedMaxId(recoveredSize - 1);
+    }
+    this.endpoints = parseAddrList(this.options.addr!, 9000);
+    this.tracker = new HostTracker(this.endpoints.length);
+    // Orphan scan + background drainers (spec 8.4): recover slots abandoned by
+    // a crashed producer. Runs once on startup, after our own slot is locked so
+    // it is never mistaken for an orphan. Drainers use private round cursors so
+    // they never steal from the foreground connect round (spec 1.2).
+    if (
+      !this.drainStarted &&
+      this.options.drain_orphans === true &&
+      this.engine.isDisk
+    ) {
+      this.drainStarted = true;
+      this.drainerStartPromise = startOrphanDrainers(
+        this.options,
+        this.endpoints,
+        this.tracker,
+        (e) => this.emit(e),
+        (d) => this.drainers.push(d), // register eagerly so close() can stop them
+        () => this.closed,
+      ).then(
+        () => undefined,
+        (e: unknown) => {
+          this.emit(
+            new SenderError(
+              Category.UNKNOWN,
+              Policy.RETRIABLE,
+              `orphan drainer startup failed: ${(e as Error)?.message ?? e}`,
+            ),
+          );
+        },
+      );
+    }
+    return this.runConnectLoop();
+  }
+
+  private runConnectLoop(): Promise<boolean> {
+    if (this.connectLoopPromise) return this.connectLoopPromise;
+    const running = this.connectLoop().finally(() => {
+      if (this.connectLoopPromise === running) {
+        this.connectLoopPromise = undefined;
+      }
+    });
+    this.connectLoopPromise = running;
+    return running;
+  }
+
+  get connectedEndpoint(): Endpoint | undefined {
+    return this.current;
+  }
+
+  private auth(): string | undefined {
+    return this.options.username && this.options.password
+      ? "Basic " +
+          Buffer.from(
+            `${this.options.username}:${this.options.password}`,
+          ).toString("base64")
+      : this.options.token
+        ? `Bearer ${this.options.token}`
+        : undefined;
+  }
+
+  private wsOptions(ep: Endpoint, generation: number): QwpWebSocketOptions {
+    return {
+      host: ep.host,
+      port: ep.port,
+      tls: this.options.protocol === "wss",
+      clientId: CLIENT_ID,
+      authorization: this.auth(),
+      rejectUnauthorized: this.options.tls_verify !== false,
+      requestDurableAck: this.options.request_durable_ack === true,
+      authTimeoutMs: this.options.auth_timeout_ms,
+      keepaliveMs: this.options.durable_ack_keepalive_interval_millis,
+      onBinary: (p) => this.onResponse(p, generation),
+      onClose: (info) => this.onDisconnected(info, generation),
+    };
+  }
+
+  private backoffMillis(): number {
+    return this.options.reconnect_initial_backoff_millis ?? 100;
+  }
+
+  private async connectLoop(): Promise<boolean> {
+    for (;;) {
+      if (this.closed) return false;
+      const idx = this.tracker.pickNext();
+      if (idx === null) {
+        this.tracker.beginRound();
+        // A fully-rejected round means no primary is reachable yet; retry
+        // indefinitely rather than giving up (spec 6.5.1).
+        await new Promise((r) => setTimeout(r, this.backoffMillis()));
+        continue;
+      }
+      const ep = this.endpoints[idx];
+      const generation = ++this.connectionGeneration;
+      let candidate: QwpWebSocket | undefined;
+      try {
+        candidate = await QwpWebSocket.connect(this.wsOptions(ep, generation));
+        // Durable-ack capability gap (spec 6.5.1): an opted-in client that did
+        // not get the X-QWP-Durable-Ack: enabled confirmation must fail fast.
+        if (
+          this.options.request_durable_ack === true &&
+          candidate.durableAck !== true
+        ) {
+          throw new DurableAckMismatchError(
+            `server did not confirm X-QWP-Durable-Ack while request_durable_ack=on [endpoint=${ep.host}:${ep.port}]`,
+          );
+        }
+        if (this.closed) {
+          await candidate.close().catch(() => undefined);
+          return false;
+        }
+        this.ws = candidate;
+        this.activeConnectionGeneration = generation;
+        this.tracker.record(idx, HostState.HEALTHY);
+        this.current = ep;
+        this.emitConnectionEvent({ type: "connected", endpoint: ep });
+        // Account for catch-up before sending it: an immediate server response
+        // must not be interpreted using the previous connection's sequence map.
+        const catchUpFrames = this.dict.size() === 0 ? 0 : 1;
+        this.acks.onConnected(this.engine.ackedFsn + 1, catchUpFrames);
+        this.durableAcks.reset(this.engine.ackedFsn);
+        await this.sendDictCatchUp();
+        // Replay frames published beyond the acked FSN (memory-mode retention).
+        this.sentUpTo = this.engine.ackedFsn;
+        await this.queueDrain();
+        return true;
+      } catch (e) {
+        if (this.activeConnectionGeneration === generation) {
+          this.activeConnectionGeneration = 0;
+          this.ws = undefined;
+          this.current = undefined;
+        }
+        await candidate?.close().catch(() => undefined);
+        if (e instanceof DurableAckMismatchError) throw e;
+        if (e instanceof QwpUpgradeError) {
+          if (e.kind === "auth") throw e; // terminal, never rotate
+          this.tracker.record(
+            idx,
+            e.kind === "role-reject"
+              ? HostState.TOPOLOGY_REJECT
+              : HostState.TRANSPORT_ERROR,
+          );
+        } else {
+          this.tracker.record(idx, HostState.TRANSPORT_ERROR);
+        }
+      }
+    }
+  }
+
+  /**
+   * The server's dictionary is connection-scoped and empty after a reconnect,
+   * so re-register from id 0 before any data frame or every delta frame earns
+   * DICTIONARY_GAP (spec 7.5). Returns the number of catch-up frames sent so
+   * the caller can account for the wire seqs they consume (spec 6.6.1).
+   */
+  private async sendDictCatchUp(): Promise<number> {
+    if (this.dict.size() === 0) return 0;
+    const cap = this.ws?.maxBatchSize ?? UNCAPPED_CATCHUP_PACKING_LIMIT;
+    const frame = encodeFrame([], {
+      gorilla: false,
+      dict: this.dict,
+      confirmedMaxId: -1,
+    });
+    if (frame.length > cap) {
+      throw new Error(
+        `dictionary catch-up exceeds the batch cap [size=${frame.length}, cap=${cap}]`,
+      );
+    }
+    await this.ws!.sendBinary(frame);
+    this.confirmedMaxId = this.dict.size() - 1;
+    // The fresh server now knows the whole dictionary, so no old id is delta-pending
+    // any more: re-pin the buffer baseline to the dictionary tail so only truly new
+    // symbols are persisted/shipped going forward (spec 5.2, 7.5).
+    this.buffer?.setConfirmedMaxId(this.confirmedMaxId);
+    return 1;
+  }
+
+  /** Test hook: register a symbol in the transport-owned dictionary. */
+  registerSymbolForTest(s: string): void {
+    this.dict.getOrAdd(s);
+  }
+
+  /** Test hook: tear down and re-establish the connection (dict catch-up path). */
+  async reconnectForTest(): Promise<void> {
+    this.closed = false;
+    await this.ws?.close();
+    this.ws = undefined;
+    this.tracker.beginRound();
+    await this.runConnectLoop();
+  }
+
+  async send(data: Buffer): Promise<boolean> {
+    if (this.terminalError) throw this.terminalError;
+    if (this.poisoned)
+      throw new Error("QWP transport is terminal (poisoned frame)");
+    if (!this.ws) throw new Error("QWP transport is not connected");
+    await this.ws.sendBinary(data);
+    return true;
+  }
+
+  /**
+   * Publishes frames into the store-and-forward ring, then drains what the
+   * current connection has not yet sent. flush() therefore resolves on
+   * publish, not on server ACK (spec 4.4).
+   */
+  sendFrames(frames: Buffer[]): Promise<boolean> {
+    if (this.terminalError) return Promise.reject(this.terminalError);
+    if (this.poisoned) {
+      return Promise.reject(
+        new Error("QWP transport is terminal (poisoned frame)"),
+      );
+    }
+    if (this.closed)
+      return Promise.reject(new Error("QWP transport is closed"));
+    // Capture this batch's dictionary target before another flush seals and
+    // overwrites the buffer's pending target.
+    const deltaTarget = this.buffer?.pendingDeltaTarget ?? -1;
+    const run = this.publishTail.then(() =>
+      this.publishFrames(frames, deltaTarget),
+    );
+    this.publishTail = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  private async publishFrames(
+    frames: Buffer[],
+    deltaTarget: number,
+  ): Promise<boolean> {
+    if (this.terminalError) throw this.terminalError;
+    if (this.poisoned)
+      throw new Error("QWP transport is terminal (poisoned frame)");
+    const deadline = Date.now() + SF_APPEND_DEADLINE_MILLIS;
+    for (const f of frames) {
+      for (;;) {
+        const fsn = await this.engine.append(f);
+        if (fsn === PAYLOAD_TOO_LARGE) {
+          throw new Error(
+            `frame does not fit a fresh segment [size=${f.length}]`,
+          );
+        }
+        if (fsn !== BACKPRESSURE_NO_SPARE) break;
+        if (Date.now() >= deadline) {
+          throw new Error(
+            "store-and-forward append deadline exceeded while waiting for space",
+          );
+        }
+        // Space frees only via ACK-driven trim on the I/O side; yield to it.
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      // The frame is queued onto the ring: this is the point where the delta
+      // baseline may advance (spec 5.2). Only reaches here on append success;
+      // a PAYLOAD_TOO_LARGE or backpressure deadline above throws before it, and
+      // the baseline stays put so ids never ship as a delta the server lacks.
+      // Replayed frames (drain) never call this, so a reconnect cannot double-
+      // advance it. It is idempotent and forward-only, so per-frame and
+      // per-(whole-)batch confirmation are equivalent.
+      this.buffer?.confirmDeltaPublished(deltaTarget);
+    }
+    await this.queueDrain();
+    return true;
+  }
+
+  private queueDrain(): Promise<void> {
+    const run = this.drainTail.then(() => this.drain());
+    this.drainTail = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+
+  /** Sends everything published beyond what the current connection has sent. */
+  private async drain(): Promise<void> {
+    const ws = this.ws;
+    const generation = this.activeConnectionGeneration;
+    if (!ws || generation === 0) return;
+    const pending = this.engine.framesFrom(this.sentUpTo + 1);
+    for (const f of pending) {
+      if (ws !== this.ws || generation !== this.activeConnectionGeneration) {
+        break;
+      }
+      // Register before awaiting the write: an immediate local response can
+      // arrive before the write callback resumes this coroutine.
+      this.acks.onFrameSent();
+      await ws.sendBinary(f);
+      if (generation !== this.activeConnectionGeneration) break;
+      this.sentUpTo++;
+    }
+  }
+
+  private onResponse(payload: Buffer, generation: number): void {
+    if (generation !== this.activeConnectionGeneration || this.terminalError)
+      return;
+    const r = decodeResponse(payload);
+    if (r.status === STATUS.OK) {
+      const exactFsn = this.acks.fsnForAck(r.sequence);
+      if (exactFsn !== null) {
+        this.acks.onAck(r.sequence);
+        // Only acceptance AT OR BEYOND the suspect frame clears a strike (spec
+        // 7.4) — re-OKs behind it must not launder the count.
+        this.poison.accept(exactFsn);
+        if (this.options.request_durable_ack === true) {
+          const durableFsn = this.durableAcks.onOk(exactFsn, r.tables);
+          if (durableFsn !== null) this.engine.acknowledge(durableFsn);
+        } else {
+          this.engine.acknowledge(exactFsn);
+        }
+      }
+      return;
+    }
+    if (r.status === STATUS.DURABLE_ACK) {
+      if (this.options.request_durable_ack === true) {
+        const durableFsn = this.durableAcks.onDurableAck(r.tables);
+        if (durableFsn !== null) this.engine.acknowledge(durableFsn);
+      }
+      return;
+    }
+
+    const category = classify(r.status);
+    const policy = defaultPolicyFor(category);
+    const fsn = this.acks.fsnForAck(r.sequence);
+    const err = new SenderError(
+      category,
+      policy,
+      r.errorMessage ??
+        `server rejected frame [status=0x${r.status.toString(16)}]`,
+      r.status,
+      fsn ?? this.engine.ackedFsn + 1,
+      fsn ?? this.engine.publishedFsn,
+    );
+
+    if (policy === Policy.TERMINAL) {
+      this.latchTerminal(err);
+      return;
+    }
+    // A RETRIABLE rejection is a verdict on the named bytes and counts toward
+    // poison escalation. RETRIABLE_OTHER is a node-state verdict and rotates
+    // without adding a strike.
+    if (
+      policy === Policy.RETRIABLE &&
+      fsn !== null &&
+      this.poison.strike(fsn)
+    ) {
+      this.poisonEscalated(
+        fsn,
+        r.errorMessage ?? `status=0x${r.status.toString(16)}`,
+      );
+      return;
+    }
+    this.emit(err);
+    this.recycleAfterNack(policy);
+  }
+
+  private latchTerminal(err: SenderError): void {
+    this.terminalError = err;
+    this.closed = true;
+    this.activeConnectionGeneration = 0;
+    this.emit(err);
+    const ws = this.ws;
+    this.ws = undefined;
+    this.current = undefined;
+    void ws?.close().catch(() => undefined);
+  }
+
+  private recycleAfterNack(policy: Policy): void {
+    const ws = this.ws;
+    const endpoint = this.current;
+    this.activeConnectionGeneration = 0;
+    this.ws = undefined;
+    this.current = undefined;
+    this.durableAcks.reset(this.engine.ackedFsn);
+    this.emitConnectionEvent({ type: "disconnected", endpoint });
+    if (policy === Policy.RETRIABLE) {
+      // Retry the healthy node first. RETRIABLE_OTHER deliberately preserves
+      // the current round cursor so connectLoop rotates to another endpoint.
+      this.tracker.beginRound();
+    } else if (endpoint) {
+      const idx = this.endpoints.findIndex(
+        (e) => e.host === endpoint.host && e.port === endpoint.port,
+      );
+      if (idx >= 0) this.tracker.record(idx, HostState.TRANSIENT_REJECT);
+    }
+    void (ws ? ws.close().catch(() => undefined) : Promise.resolve()).finally(
+      () => void this.reconnect(),
+    );
+  }
+
+  /**
+   * A frame was rejected too many times within the dwell window: PROTOCOL_VIOLATION
+   * is TERMINAL (spec 7.4). Stop replaying it — under store-and-forward a poisoned
+   * frame would otherwise replay forever — and surface the error, then tear down.
+   */
+  private poisonEscalated(fsn: number, detail: string): void {
+    this.poisoned = true;
+    this.latchTerminal(
+      new SenderError(
+        Category.PROTOCOL_VIOLATION,
+        Policy.TERMINAL,
+        `poisoned frame ${fsn} was rejected too many times within the poison escalation ` +
+          `window — terminal (${detail})`,
+        -1,
+        fsn,
+        fsn,
+      ),
+    );
+  }
+
+  private onDisconnected(
+    info: { orderly: boolean; framesSent: number },
+    generation: number,
+  ): void {
+    if (generation !== this.activeConnectionGeneration) return;
+    this.activeConnectionGeneration = 0;
+    this.emitConnectionEvent({ type: "disconnected", endpoint: this.current });
+    this.current = undefined;
+    this.ws = undefined;
+    this.durableAcks.reset(this.engine.ackedFsn);
+    // spec 7.4: a NON-orderly close AFTER at least one send counts a strike on
+    // the head-of-line unacked frame (the first frame the reconnect replays). An
+    // orderly close (NORMAL/GONE) or a connection that sent nothing never counts
+    // — otherwise a graceful failover would false-positive into a terminal.
+    if (!info.orderly && info.framesSent > 0 && !this.poisoned) {
+      // Poison follows the retained replay head, not the highest commit-level
+      // OK. In durable mode an accepted frame remains retained until its table
+      // watermark arrives; striking OK+1 can target an unpublished FSN and can
+      // never be cleared by replay acceptance.
+      const fsn = this.engine.ackedFsn + 1;
+      if (
+        fsn >= 0 &&
+        fsn <= this.engine.publishedFsn &&
+        this.poison.strike(fsn)
+      ) {
+        this.poisonEscalated(
+          fsn,
+          "connection dropped repeatedly while the head-of-line frame was unacked",
+        );
+        return; // terminal: do not reconnect into the same poison
+      }
+    }
+    // With store-and-forward retention in place a disconnect no longer loses
+    // in-flight frames: they are replayed from the ring on reconnect. Make the
+    // reconnect automatic instead of surfacing DATA_LOSS (spec 8.1.1).
+    void this.reconnect();
+  }
+
+  private async reconnect(): Promise<void> {
+    if (this.reconnecting || this.closed) return;
+    this.reconnecting = true;
+    try {
+      await this.runConnectLoop();
+    } catch (e) {
+      if (!this.closed) {
+        const auth = e instanceof QwpUpgradeError && e.kind === "auth";
+        this.latchTerminal(
+          new SenderError(
+            auth ? Category.SECURITY_ERROR : Category.PROTOCOL_VIOLATION,
+            Policy.TERMINAL,
+            `QWP reconnect failed terminally: ${(e as Error)?.message ?? e}`,
+          ),
+        );
+      }
+    } finally {
+      this.reconnecting = false;
+    }
+  }
+
+  /** Server-advertised cap, or a conservative default before the handshake. */
+  get maxBatchSize(): number {
+    return this.ws?.maxBatchSize ?? 16 * 1024 * 1024;
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    await this.publishTail;
+    await this.drainTail;
+    for (const d of this.drainers) d.stop();
+    // Startup may be waiting for a drainer slot. Stopping current workers wakes
+    // it; shouldStop prevents it from constructing any post-close workers.
+    await this.drainerStartPromise;
+    for (const d of this.drainers) d.stop();
+    await Promise.all(
+      this.drainers.map((d) => d.finished.catch(() => undefined)),
+    );
+    await this.ws?.close();
+    this.ws = undefined;
+    await this.engine.close();
+  }
+
+  getDefaultAutoFlushRows(): number {
+    return QWP_DEFAULT_AUTO_FLUSH_ROWS;
+  }
+
+  getDefaultAutoFlushInterval(): number {
+    return 100; // spec 9.1
+  }
+}
diff --git a/src/qwp/ws/frame.ts b/src/qwp/ws/frame.ts
new file mode 100644
index 0000000..abb077f
--- /dev/null
+++ b/src/qwp/ws/frame.ts
@@ -0,0 +1,110 @@
+import { Buffer } from "node:buffer";
+import { newMaskKey, applyMask } from "./mask";
+
+export const OPCODE = {
+  CONT: 0x0,
+  TEXT: 0x1,
+  BINARY: 0x2,
+  CLOSE: 0x8,
+  PING: 0x9,
+  PONG: 0xa,
+} as const;
+
+const MAX_CONTROL_PAYLOAD = 125;
+
+/** Client->server frames are always FIN=1 and always masked (spec 3.2.1). */
+export function encodeClientFrame(opcode: number, payload: Buffer): Buffer {
+  const len = payload.length;
+  let headerLen = 2;
+  if (len >= 65536) headerLen += 8;
+  else if (len >= 126) headerLen += 2;
+
+  const out = Buffer.allocUnsafe(headerLen + 4 + len);
+  out[0] = 0x80 | opcode;
+  if (len < 126) {
+    out[1] = 0x80 | len;
+  } else if (len < 65536) {
+    out[1] = 0x80 | 126;
+    out.writeUInt16BE(len, 2);
+  } else {
+    out[1] = 0x80 | 127;
+    out.writeBigUInt64BE(BigInt(len), 2);
+  }
+  const key = newMaskKey();
+  key.copy(out, headerLen);
+  payload.copy(out, headerLen + 4);
+  applyMask(out.subarray(headerLen + 4), key);
+  return out;
+}
+
+export class FrameParser {
+  private buf: Buffer = Buffer.alloc(0);
+  private fragOpcode = -1;
+  private frags: Buffer[] = [];
+
+  push(chunk: Buffer): void {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+  }
+
+  /** Returns the next complete message, or null when more bytes are needed. */
+  next(): { opcode: number; payload: Buffer } | null {
+    for (;;) {
+      if (this.buf.length < 2) return null;
+      const b0 = this.buf[0];
+      const b1 = this.buf[1];
+
+      if ((b0 & 0x70) !== 0) throw new Error("websocket: non-zero RSV bits");
+      if ((b1 & 0x80) !== 0) throw new Error("websocket: inbound frame must not be masked");
+
+      const fin = (b0 & 0x80) !== 0;
+      const opcode = b0 & 0x0f;
+      const isControl = (opcode & 0x08) !== 0;
+
+      let len = b1 & 0x7f;
+      let offset = 2;
+      if (len === 126) {
+        if (this.buf.length < 4) return null;
+        len = this.buf.readUInt16BE(2);
+        offset = 4;
+      } else if (len === 127) {
+        if (this.buf.length < 10) return null;
+        const big = this.buf.readBigUInt64BE(2);
+        if (big > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("websocket: frame too large");
+        len = Number(big);
+        offset = 10;
+      }
+
+      if (isControl) {
+        if (len > MAX_CONTROL_PAYLOAD) {
+          throw new Error(`websocket: control frame payload exceeds ${MAX_CONTROL_PAYLOAD}`);
+        }
+        if (!fin) throw new Error("websocket: control frame must not be fragmented");
+      }
+
+      if (this.buf.length < offset + len) return null;
+      const payload = Buffer.from(this.buf.subarray(offset, offset + len));
+      this.buf = this.buf.subarray(offset + len);
+
+      // Control frames are never fragmented and interleave freely.
+      if (isControl) return { opcode, payload };
+
+      if (opcode === OPCODE.CONT) {
+        if (this.fragOpcode === -1) throw new Error("websocket: continuation without start");
+        this.frags.push(payload);
+        if (!fin) continue;
+        const full = Buffer.concat(this.frags);
+        const op = this.fragOpcode;
+        this.frags = [];
+        this.fragOpcode = -1;
+        return { opcode: op, payload: full };
+      }
+
+      if (!fin) {
+        this.fragOpcode = opcode;
+        this.frags = [payload];
+        continue;
+      }
+      return { opcode, payload };
+    }
+  }
+}
diff --git a/src/qwp/ws/handshake.ts b/src/qwp/ws/handshake.ts
new file mode 100644
index 0000000..35efe19
--- /dev/null
+++ b/src/qwp/ws/handshake.ts
@@ -0,0 +1,107 @@
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes } from "node:crypto";
+import { WRITE_PATH } from "../protocol/constants";
+
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+export type UpgradeFailureKind = "role-reject" | "auth" | "other";
+
+export class QwpUpgradeError extends Error {
+  readonly status: number;
+  readonly kind: UpgradeFailureKind;
+  /** 421 role rejects retry indefinitely; auth failures never do (spec 6.5.1). */
+  readonly retriable: boolean;
+  readonly role?: string;
+
+  constructor(status: number, kind: UpgradeFailureKind, message: string, role?: string) {
+    super(message);
+    this.name = "QwpUpgradeError";
+    this.status = status;
+    this.kind = kind;
+    this.retriable = kind === "role-reject";
+    this.role = role;
+  }
+}
+
+export interface UpgradeResult {
+  accept: string;
+  qwpVersion?: number;
+  maxBatchSize?: number;
+  role?: string;
+  /** "enabled" when this connection is durable-ack capable (spec 6.5.1). */
+  durableAck?: string;
+  /** Bytes already received after the header terminator. */
+  leftover: Buffer;
+}
+
+export function computeAccept(key: string): string {
+  return createHash("sha1").update(key + WS_GUID, "ascii").digest("base64");
+}
+
+export function buildUpgradeRequest(opts: {
+  host: string;
+  port: number;
+  clientId: string;
+  authorization?: string;
+  requestDurableAck?: boolean;
+}): { request: Buffer; key: string } {
+  const key = randomBytes(16).toString("base64");
+  const lines = [
+    `GET ${WRITE_PATH} HTTP/1.1`,
+    `Host: ${opts.host}:${opts.port}`,
+    "Connection: Upgrade",
+    "Upgrade: websocket",
+    "Sec-WebSocket-Version: 13",
+    `Sec-WebSocket-Key: ${key}`,
+    "X-QWP-Max-Version: 1",
+    `X-QWP-Client-Id: ${opts.clientId}`,
+  ];
+  if (opts.authorization) lines.push(`Authorization: ${opts.authorization}`);
+  // Durable-ack opt-in. The server echoes X-QWP-Durable-Ack: enabled only when
+  // it can back this connection with its durable-ack registry (spec 6.5.1); an
+  // opted-in client treats a missing echo as a hard capability gap and fails
+  // fast rather than silently running without the durability it asked for.
+  if (opts.requestDurableAck) lines.push("X-QWP-Request-Durable-Ack: true");
+  return { request: Buffer.from(lines.join("\r\n") + "\r\n\r\n", "ascii"), key };
+}
+
+export function parseUpgradeResponse(raw: Buffer): UpgradeResult {
+  const end = raw.indexOf("\r\n\r\n");
+  if (end < 0) throw new Error("incomplete HTTP upgrade response");
+  const head = raw.subarray(0, end).toString("ascii");
+  const leftover = Buffer.from(raw.subarray(end + 4));
+
+  const [statusLine, ...headerLines] = head.split("\r\n");
+  const status = Number.parseInt(statusLine.split(" ")[1], 10);
+
+  const headers = new Map<string, string>();
+  for (const line of headerLines) {
+    const i = line.indexOf(":");
+    if (i > 0) headers.set(line.slice(0, i).trim().toLowerCase(), line.slice(i + 1).trim());
+  }
+
+  if (status !== 101) {
+    const role = headers.get("x-questdb-role");
+    if (status === 421 && role) {
+      throw new QwpUpgradeError(status, "role-reject", `node cannot accept writes [role=${role}]`, role);
+    }
+    if (status === 401 || status === 403) {
+      throw new QwpUpgradeError(status, "auth", `authentication failed [status=${status}]`);
+    }
+    throw new QwpUpgradeError(status, "other", `websocket upgrade failed [status=${status}]`);
+  }
+
+  const accept = headers.get("sec-websocket-accept");
+  if (!accept) throw new Error("upgrade response missing Sec-WebSocket-Accept");
+
+  const version = headers.get("x-qwp-version");
+  const cap = headers.get("x-qwp-max-batch-size");
+  return {
+    accept,
+    qwpVersion: version ? Number.parseInt(version, 10) : undefined,
+    maxBatchSize: cap ? Number.parseInt(cap, 10) : undefined,
+    role: headers.get("x-questdb-role"),
+    durableAck: headers.get("x-qwp-durable-ack"),
+    leftover,
+  };
+}
diff --git a/src/qwp/ws/mask.ts b/src/qwp/ws/mask.ts
new file mode 100644
index 0000000..c6cdd93
--- /dev/null
+++ b/src/qwp/ws/mask.ts
@@ -0,0 +1,13 @@
+import { Buffer } from "node:buffer";
+import { randomFillSync } from "node:crypto";
+
+/** RFC 6455 §10.3 requires a fresh, unpredictable key per frame. */
+export function newMaskKey(): Buffer {
+  return randomFillSync(Buffer.allocUnsafe(4));
+}
+
+export function applyMask(payload: Buffer, key: Buffer): void {
+  for (let i = 0; i < payload.length; i++) {
+    payload[i] ^= key[i & 3];
+  }
+}
diff --git a/src/qwp/ws/socket.ts b/src/qwp/ws/socket.ts
new file mode 100644
index 0000000..a7db3db
--- /dev/null
+++ b/src/qwp/ws/socket.ts
@@ -0,0 +1,240 @@
+import { Buffer } from "node:buffer";
+import { connect as netConnect, Socket } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+import { encodeClientFrame, FrameParser, OPCODE } from "./frame";
+import {
+  buildUpgradeRequest,
+  computeAccept,
+  parseUpgradeResponse,
+} from "./handshake";
+
+const DEFAULT_AUTH_TIMEOUT_MS = 15_000; // spec 9.1
+
+export interface QwpWebSocketOptions {
+  host: string;
+  port: number;
+  tls: boolean;
+  clientId: string;
+  authorization?: string;
+  rejectUnauthorized?: boolean;
+  ca?: Buffer | Buffer[];
+  requestDurableAck?: boolean;
+  /** spec 9.1: connect + handshake timeout (default 15000 ms). */
+  authTimeoutMs?: number;
+  /** spec 9.1: keepalive PING interval; < = 0 disables (default 200 ms). */
+  keepaliveMs?: number;
+  /** Inbound binary payloads (response frames) are handed here. */
+  onBinary?: (payload: Buffer) => void;
+  /**
+   * Fires once when the connection is dropped or closed externally.
+   * `orderly` is true for a remote NORMAL_CLOSURE/GOING_AWAY close handshake,
+   * false for an abrupt drop — which is what the poison detector keys on
+   * (spec 7.4). `framesSent` counts frames written on this connection.
+   */
+  onClose?: (info: { orderly: boolean; framesSent: number }) => void;
+}
+
+export class QwpWebSocket {
+  private readonly socket: Socket;
+  private readonly parser = new FrameParser();
+  private closed = false;
+  private readonly onBinary?: (payload: Buffer) => void;
+  private readonly onClose?: (info: {
+    orderly: boolean;
+    framesSent: number;
+  }) => void;
+  private framesSent = 0;
+  private closeNotified = false;
+  private readonly keepalive?: NodeJS.Timeout;
+  readonly maxBatchSize?: number;
+  /** True when the server confirmed durable-ack capability (spec 6.5.1). */
+  readonly durableAck: boolean;
+
+  private constructor(
+    socket: Socket,
+    maxBatchSize: number | undefined,
+    durableAck: boolean,
+    onBinary?: (payload: Buffer) => void,
+    onClose?: (info: { orderly: boolean; framesSent: number }) => void,
+    keepaliveMs?: number,
+  ) {
+    this.socket = socket;
+    this.maxBatchSize = maxBatchSize;
+    this.durableAck = durableAck;
+    this.onBinary = onBinary;
+    this.onClose = onClose;
+    // Neither WebSocket framing errors nor application response-decoder errors
+    // may escape an EventEmitter callback: an uncaught throw here terminates the
+    // host process. Convert both into one abrupt-close notification instead.
+    this.socket.on("data", (chunk: Buffer) => this.handleDataSafely(chunk));
+    this.socket.on("close", () => this.handleClosed());
+    this.socket.on("error", () => this.handleClosed());
+    // Keepalive PING (spec 9.1, durable_ack_keepalive_interval_millis).
+    // < = 0 disables; the default 200 keeps the server's durable-ack wait
+    // bounded by a liveness signal even when no data is flowing.
+    if (keepaliveMs && keepaliveMs > 0) {
+      this.keepalive = setInterval(() => {
+        if (!this.closed)
+          this.socket.write(encodeClientFrame(OPCODE.PING, Buffer.alloc(0)));
+      }, keepaliveMs);
+    }
+  }
+
+  static connect(opts: QwpWebSocketOptions): Promise<QwpWebSocket> {
+    return new Promise((resolve, reject) => {
+      const socket: Socket = opts.tls
+        ? tlsConnect({
+            host: opts.host,
+            port: opts.port,
+            rejectUnauthorized: opts.rejectUnauthorized !== false,
+            ca: opts.ca,
+          })
+        : netConnect({ host: opts.host, port: opts.port });
+
+      let settled = false;
+      const fail = (e: Error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(authTimer);
+        reject(e);
+      };
+      // spec 9.1: bound the connect + handshake by auth_timeout_ms (15 s). A
+      // black-holed endpoint would otherwise hang the sender forever.
+      const authTimer = setTimeout(() => {
+        socket.destroy();
+        fail(
+          new Error(`QWP connect timed out [host=${opts.host}:${opts.port}]`),
+        );
+      }, opts.authTimeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS);
+
+      const onError = (e: Error) => fail(e);
+      socket.once("error", onError);
+
+      socket.once(opts.tls ? "secureConnect" : "connect", () => {
+        const { request, key } = buildUpgradeRequest(opts);
+        socket.write(request);
+
+        let acc = Buffer.alloc(0);
+        const onHeaderData = (chunk: Buffer) => {
+          acc = Buffer.concat([acc, chunk]);
+          if (acc.indexOf("\r\n\r\n") < 0) return;
+          socket.off("data", onHeaderData);
+          socket.off("error", onError);
+          clearTimeout(authTimer);
+          try {
+            const res = parseUpgradeResponse(acc);
+            if (res.accept !== computeAccept(key)) {
+              throw new Error("websocket: Sec-WebSocket-Accept mismatch");
+            }
+            const ws = new QwpWebSocket(
+              socket,
+              res.maxBatchSize,
+              res.durableAck === "enabled",
+              opts.onBinary,
+              opts.onClose,
+              opts.keepaliveMs,
+            );
+            // Resolve before dispatching bytes coalesced with the HTTP 101.
+            // Consumers such as QwpTransport must activate their connection
+            // generation before any response/close callback can arrive.
+            settled = true;
+            resolve(ws);
+            if (res.leftover.length > 0) {
+              queueMicrotask(() => ws.handleDataSafely(res.leftover));
+            }
+          } catch (e) {
+            socket.destroy();
+            fail(e as Error);
+          }
+        };
+        socket.on("data", onHeaderData);
+      });
+    });
+  }
+
+  private handleDataSafely(chunk: Buffer): void {
+    if (this.closed) return;
+    try {
+      this.onData(chunk);
+    } catch {
+      this.failConnection();
+    }
+  }
+
+  private onData(chunk: Buffer): void {
+    this.parser.push(chunk);
+    for (let m = this.parser.next(); m; m = this.parser.next()) {
+      switch (m.opcode) {
+        case OPCODE.PING:
+          this.socket.write(encodeClientFrame(OPCODE.PONG, m.payload));
+          break;
+        case OPCODE.CLOSE: {
+          // RFC 6455 §5.5.1: echo the close before tearing down.
+          // The close payload's 2-byte code classifies orderliness: NORMAL
+          // (1000) and GOING_AWAY (1001) are orderly; anything else (or none)
+          // is not (spec 7.4 — only NON-orderly closes can count a strike).
+          if (!this.closed) {
+            this.closed = true;
+            if (this.keepalive) clearInterval(this.keepalive);
+            this.socket.write(encodeClientFrame(OPCODE.CLOSE, m.payload));
+            this.socket.end();
+          }
+          const code = m.payload.length >= 2 ? m.payload.readUInt16BE(0) : -1;
+          this.notifyClosed(code === 1000 || code === 1001);
+          return;
+        }
+        case OPCODE.BINARY:
+          this.onBinary?.(m.payload);
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  /** One write per frame, so a control frame can never interleave mid-frame. */
+  sendBinary(payload: Buffer): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.closed) return reject(new Error("websocket is closed"));
+      const frame = encodeClientFrame(OPCODE.BINARY, payload);
+      this.framesSent++;
+      this.socket.write(frame, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  private notifyClosed(orderly: boolean): void {
+    if (this.closeNotified) return;
+    this.closeNotified = true;
+    if (this.keepalive) clearInterval(this.keepalive);
+    this.onClose?.({ orderly, framesSent: this.framesSent });
+  }
+
+  private failConnection(): void {
+    if (!this.closed) {
+      this.closed = true;
+      this.socket.destroy();
+    }
+    this.notifyClosed(false);
+  }
+
+  private handleClosed(): void {
+    // Fires on external drop (server teardown / socket error). A remote CLOSE
+    // handshake notifies in onData; our own close() intentionally does not.
+    if (this.closed) return;
+    this.closed = true;
+    this.notifyClosed(false);
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.closed) {
+        if (this.keepalive) clearInterval(this.keepalive);
+        return resolve();
+      }
+      this.closed = true;
+      if (this.keepalive) clearInterval(this.keepalive);
+      this.socket.write(encodeClientFrame(OPCODE.CLOSE, Buffer.alloc(0)));
+      this.socket.end(() => resolve());
+    });
+  }
+}
diff --git a/src/sender.ts b/src/sender.ts
index 4a63a3b..3d79cb3 100644
--- a/src/sender.ts
+++ b/src/sender.ts
@@ -1,12 +1,12 @@
 // @ts-check
 import { log, Logger } from "./logging";
-import { SenderOptions, ExtraOptions } from "./options";
+import { SenderOptions, ExtraOptions, WS, WSS } from "./options";
 import { SenderTransport, createTransport } from "./transport";
 import { SenderBuffer, createBuffer } from "./buffer";
+import { deriveConnectMode, ConnectMode, QwpTransport } from "./qwp/transport";
+import { QwpBuffer } from "./qwp/buffer";
 import { isBoolean, isInteger, TimestampUnit } from "./utils";
 
-const DEFAULT_AUTO_FLUSH_INTERVAL = 1000; // 1 sec
-
 /**
  * The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection. <br>
  * The client supports multiple transport protocols.
@@ -94,6 +94,10 @@ class Sender {
   private lastFlushTime: number;
   private pendingRowCount: number;
 
+  /** QWP seals share one mutable dictionary baseline; flushes must seal in order. */
+  private qwpFlushActive = false;
+  private readonly qwpFlushQueue: Array<() => void> = [];
+
   private readonly log: Logger;
 
   /**
@@ -106,6 +110,16 @@ class Sender {
     this.transport = createTransport(options);
     this.buffer = createBuffer(options);
 
+    // Wire the producer buffer into the QWP transport so delta symbol-dictionary
+    // mode runs end-to-end: the transport shares its connection dictionary with
+    // the buffer and installs the engine's write-ahead persist hook, and recovery
+    // seeding (transport.doConnect) then re-pins the buffer baseline (spec 8.1.6).
+    if (options.protocol === WS || options.protocol === WSS) {
+      (this.transport as unknown as QwpTransport).attachSymbolBuffer(
+        this.buffer as unknown as QwpBuffer,
+      );
+    }
+
     this.log = typeof options.log === "function" ? options.log : log;
 
     this.autoFlush = isBoolean(options.auto_flush) ? options.auto_flush : true;
@@ -114,9 +128,24 @@ class Sender {
       : this.transport.getDefaultAutoFlushRows();
     this.autoFlushInterval = isInteger(options.auto_flush_interval, 0)
       ? options.auto_flush_interval
-      : DEFAULT_AUTO_FLUSH_INTERVAL;
+      : this.transport.getDefaultAutoFlushInterval();
 
     this.reset();
+
+    // Derived connect mode (spec 4.3): any reconnect_* key upgrades construction
+    // from non-connecting to connecting-with-retry. Fire-and-forget because
+    // construction is synchronous; an eventual fatal failure surfaces through
+    // the error dispatcher rather than as an unhandled rejection.
+    if (options.protocol === WS || options.protocol === WSS) {
+      if (deriveConnectMode(options) === ConnectMode.SYNC) {
+        this.connect().catch((e) =>
+          this.log(
+            "warn",
+            `initial QWP connect failed: ${(e as Error).message}`,
+          ),
+        );
+      }
+    }
   }
 
   /**
@@ -185,6 +214,27 @@ class Sender {
    * @return {Promise<boolean>} Resolves to true when there was data in the buffer to send, and it was sent successfully.
    */
   async flush(): Promise<boolean> {
+    // QWP can produce several frames per flush; ILP always produces one.
+    const buf = this.buffer as unknown as {
+      sealFrames?: (cap: number) => Buffer[];
+    };
+    const tx = this.transport as unknown as {
+      sendFrames?: (f: Buffer[]) => Promise<boolean>;
+      maxBatchSize?: number;
+    };
+    if (buf.sealFrames && tx.sendFrames) {
+      return this.enqueueQwpFlush(async () => {
+        const frames = buf.sealFrames!(
+          tx.maxBatchSize ?? Number.MAX_SAFE_INTEGER,
+        );
+        if (frames.length === 0) return false;
+        this.log("debug", `Flushing ${frames.length} QWP frame(s)`);
+        this.resetAutoFlush();
+        await tx.sendFrames!(frames);
+        return true;
+      });
+    }
+
     const dataToSend: Buffer = this.buffer.toBufferNew();
     if (!dataToSend) {
       return false; // Nothing to send
@@ -200,6 +250,28 @@ class Sender {
     return true;
   }
 
+  private enqueueQwpFlush(work: () => Promise<boolean>): Promise<boolean> {
+    if (!this.qwpFlushActive) {
+      this.qwpFlushActive = true;
+      return this.runQwpFlush(work);
+    }
+    return new Promise<boolean>((resolve, reject) => {
+      this.qwpFlushQueue.push(() => {
+        void this.runQwpFlush(work).then(resolve, reject);
+      });
+    });
+  }
+
+  private async runQwpFlush(work: () => Promise<boolean>): Promise<boolean> {
+    try {
+      return await work();
+    } finally {
+      const next = this.qwpFlushQueue.shift();
+      if (next) queueMicrotask(next);
+      else this.qwpFlushActive = false;
+    }
+  }
+
   /**
    * Closes the connection to the database. <br>
    * Data sitting in the Sender's buffer will be lost unless flush() is called before close().
@@ -212,6 +284,10 @@ class Sender {
         `Buffer contains data which has not been flushed before closing the sender, and it will be lost [position=${pos}]`,
       );
     }
+    if (this.qwpFlushActive) {
+      // Join every already-queued QWP flush before transport teardown.
+      await this.enqueueQwpFlush(async () => false);
+    }
     return this.transport.close();
   }
 
diff --git a/src/transport/http/base.ts b/src/transport/http/base.ts
index c772899..0717fbf 100644
--- a/src/transport/http/base.ts
+++ b/src/transport/http/base.ts
@@ -13,6 +13,9 @@ const HTTP_NO_CONTENT = 204;
 // Default number of rows that trigger auto-flush for HTTP transport.
 const DEFAULT_HTTP_AUTO_FLUSH_ROWS = 75000;
 
+// Historical auto-flush interval for the ILP transports (milliseconds).
+const DEFAULT_AUTO_FLUSH_INTERVAL = 1000;
+
 // Default minimum throughput for HTTP requests (100 KB/sec).
 const DEFAULT_REQUEST_MIN_THROUGHPUT = 102400;
 
@@ -122,6 +125,10 @@ abstract class HttpTransportBase implements SenderTransport {
     return DEFAULT_HTTP_AUTO_FLUSH_ROWS;
   }
 
+  getDefaultAutoFlushInterval(): number {
+    return DEFAULT_AUTO_FLUSH_INTERVAL;
+  }
+
   /**
    * Sends data to the QuestDB server via HTTP.
    * Must be implemented by concrete HTTP transport classes.
diff --git a/src/transport/index.ts b/src/transport/index.ts
index 3b0d65d..287074c 100644
--- a/src/transport/index.ts
+++ b/src/transport/index.ts
@@ -1,10 +1,11 @@
 // @ts-check
 import { Buffer } from "node:buffer";
 
-import { SenderOptions, HTTP, HTTPS, TCP, TCPS } from "../options";
+import { SenderOptions, HTTP, HTTPS, TCP, TCPS, WS, WSS } from "../options";
 import { UndiciTransport } from "./http/undici";
 import { TcpTransport } from "./tcp";
 import { HttpTransport } from "./http/stdlib";
+import { QwpTransport } from "../qwp/transport";
 
 /**
  * Interface for QuestDB transport implementations. <br>
@@ -37,6 +38,13 @@ interface SenderTransport {
    * @returns Default auto-flush row count
    */
   getDefaultAutoFlushRows(): number;
+
+  /**
+   * Gets the default auto-flush interval (ms) for this transport. QWP uses
+   * 100 ms (spec 9.1); the ILP transports inherit the historical 1000 ms.
+   * @returns Default auto-flush interval in milliseconds
+   */
+  getDefaultAutoFlushInterval(): number;
 }
 
 /**
@@ -62,6 +70,9 @@ function createTransport(options: SenderOptions): SenderTransport {
     case TCP:
     case TCPS:
       return new TcpTransport(options);
+    case WS:
+    case WSS:
+      return new QwpTransport(options);
     default:
       throw new Error(`Invalid protocol: '${options.protocol}'`);
   }
diff --git a/src/transport/tcp.ts b/src/transport/tcp.ts
index efc76fa..df9c651 100644
--- a/src/transport/tcp.ts
+++ b/src/transport/tcp.ts
@@ -211,6 +211,10 @@ class TcpTransport implements SenderTransport {
     return DEFAULT_TCP_AUTO_FLUSH_ROWS;
   }
 
+  getDefaultAutoFlushInterval(): number {
+    return 1000; // historical ILP default
+  }
+
   /**
    * @ignore
    * Handles the JWK token authentication challenge-response flow.
diff --git a/test/qwp/ackTracker.test.ts b/test/qwp/ackTracker.test.ts
new file mode 100644
index 0000000..57b1e7e
--- /dev/null
+++ b/test/qwp/ackTracker.test.ts
@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { AckTracker } from "../../src/qwp/ackTracker";
+
+describe("AckTracker", () => {
+  it("translates a connection-scoped seq into an FSN", () => {
+    const t = new AckTracker();
+    t.onConnected(100); // replay resumes at FSN 100
+    t.onFrameSent();
+    t.onFrameSent();
+    expect(t.onAck(1)).toBe(101);
+  });
+
+  it("does NOT reset the FSN when the wire seq restarts", () => {
+    const t = new AckTracker();
+    t.onConnected(0);
+    t.onFrameSent();
+    expect(t.onAck(0)).toBe(0);
+    // reconnect: wire seq restarts at 0, FSNs continue from 1
+    t.onConnected(1);
+    t.onFrameSent();
+    expect(t.onAck(0)).toBe(1);
+  });
+
+  it("clamps an ACK beyond what was sent", () => {
+    const t = new AckTracker();
+    t.onConnected(0);
+    t.onFrameSent(); // highest wire seq is 0
+    expect(t.onAck(99)).toBe(0);
+  });
+
+  it("ignores an ACK arriving before any send", () => {
+    const t = new AckTracker();
+    t.onConnected(0);
+    expect(t.onAck(0)).toBeNull();
+  });
+
+  it("never moves the acked watermark backwards", () => {
+    const t = new AckTracker();
+    t.onConnected(0);
+    t.onFrameSent();
+    t.onFrameSent();
+    expect(t.onAck(1)).toBe(1);
+    expect(t.onAck(0)).toBe(1);
+  });
+
+  it("does not let a catch-up ACK over-trim the first ring frame (handoff B1b)", () => {
+    // A reconnect with a populated dictionary emits one catch-up frame first,
+    // which the server assigns wire seq 0. onConnected(100, 1) says so.
+    const t = new AckTracker();
+    t.onConnected(100, 1); // 1 catch-up frame; ring replay resumes at FSN 100
+    // The catch-up frame is counted by onConnected's initial nextWireSeq=1.
+    t.onFrameSent(); // ring frame 0 sent -> nextWireSeq = 2
+
+    // The catch-up ACK (wire seq 0) must NOT trim ring frame 0.
+    expect(t.onAck(0)).toBeNull();
+    // The real ACK for ring frame 0 (wire seq 1) maps to FSN 100.
+    expect(t.onAck(1)).toBe(100);
+
+    t.onFrameSent(); // ring frame 1 sent -> nextWireSeq = 3
+    expect(t.onAck(2)).toBe(101); // ring frame 1 (FSN 101)
+  });
+
+  it("behaves identically with no catch-up frames", () => {
+    const t = new AckTracker();
+    t.onConnected(100, 0);
+    t.onFrameSent();
+    expect(t.onAck(0)).toBe(100);
+    t.onFrameSent();
+    expect(t.onAck(1)).toBe(101);
+  });
+});
diff --git a/test/qwp/buffer.test.ts b/test/qwp/buffer.test.ts
new file mode 100644
index 0000000..1d25d6a
--- /dev/null
+++ b/test/qwp/buffer.test.ts
@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { QwpBuffer } from "../../src/qwp/buffer";
+import { HEADER_SIZE, TYPE_LONG, TYPE_TIMESTAMP, MAX_ROWS_PER_TABLE } from "../../src/qwp/protocol/constants";
+
+describe("QwpBuffer", () => {
+  it("seals a frame containing the buffered rows", () => {
+    const b = new QwpBuffer();
+    b.table("trades").symbol("sym", "ETH").floatColumn("price", 1.5);
+    b.at(1000n, "us");
+    const f = b.toBufferNew()!;
+    expect(f.subarray(0, 4).toString("ascii")).toBe("QWP1");
+    expect(f.readUInt16LE(6)).toBe(1); // one table
+    expect(f.length).toBeGreaterThan(HEADER_SIZE);
+  });
+
+  it("returns null when nothing is buffered", () => {
+    expect(new QwpBuffer().toBufferNew()).toBeNull();
+  });
+
+  it("accumulates multiple tables into one frame", () => {
+    const b = new QwpBuffer();
+    b.table("a").intColumn("x", 1);
+    b.at(1n, "us");
+    b.table("b").intColumn("y", 2);
+    b.at(2n, "us");
+    expect(b.toBufferNew()!.readUInt16LE(6)).toBe(2);
+  });
+
+  it("throws for column types this plan does not encode", () => {
+    const b = new QwpBuffer();
+    b.table("t");
+    expect(() => b.decimalColumnText("d", "1.5")).toThrow(/not supported/i);
+  });
+
+  it("clears state after sealing", () => {
+    const b = new QwpBuffer();
+    b.table("t").intColumn("x", 1);
+    b.at(1n, "us");
+    b.toBufferNew();
+    expect(b.toBufferNew()).toBeNull();
+  });
+
+  it("writes the designated timestamp as an empty-name TIMESTAMP column", () => {
+    // QwpSchema allows nameLen=0 for the designated timestamp; the server names
+    // it "timestamp". A column literally named "timestamp" collides with the
+    // server's reserved designated column, so it must NOT be emitted.
+    const b = new QwpBuffer();
+    b.table("t").intColumn("x", 1);
+    b.at(1_700_000_000_000_000n, "us");
+    const f = b.toBufferNew()!;
+    let o = HEADER_SIZE;
+    o += f[o] + 1; // table name "t" (varint len + bytes)
+    o += 1; // rowCount
+    const cc = f[o++];
+    expect(cc).toBe(2);
+    const nx = f[o++];
+    o += nx;
+    expect(f[o++]).toBe(TYPE_LONG); // "x"
+    expect(f[o++]).toBe(0); // empty column name length -> designated timestamp
+    expect(f[o++]).toBe(TYPE_TIMESTAMP);
+  });
+
+  it("fails a table that exceeds the rows-per-table limit before any byte is sent (spec 6.4)", () => {
+    const b = new QwpBuffer();
+    const rows = MAX_ROWS_PER_TABLE + 1;
+    for (let i = 0; i < rows; i++) {
+      b.table("big").intColumn("v", i);
+      b.at(BigInt(i), "us");
+    }
+    expect(() => b.sealFrames(1 << 30)).toThrow(/rows/);
+  });
+});
diff --git a/test/qwp/capSplit.test.ts b/test/qwp/capSplit.test.ts
new file mode 100644
index 0000000..f4cb556
--- /dev/null
+++ b/test/qwp/capSplit.test.ts
@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+import { QwpBuffer } from "../../src/qwp/buffer";
+import { encodeCommitFrame } from "../../src/qwp/protocol/frameEncoder";
+import { SymbolDict } from "../../src/qwp/protocol/symbolDict";
+import { FLAG_DEFER_COMMIT } from "../../src/qwp/protocol/constants";
+
+describe("cap splitting", () => {
+  it("splits per table when the batch exceeds the cap", () => {
+    const b = new QwpBuffer();
+    for (const t of ["a", "b", "c"]) {
+      b.table(t).intColumn("x", 1);
+      b.at(1n, "us");
+    }
+    const frames = b.sealFrames(80); // small cap forces a split
+    expect(frames.length).toBe(3);
+    // All but the last defer the commit.
+    expect(frames[0].readUInt8(5) & FLAG_DEFER_COMMIT).toBe(FLAG_DEFER_COMMIT);
+    expect(frames[1].readUInt8(5) & FLAG_DEFER_COMMIT).toBe(FLAG_DEFER_COMMIT);
+    expect(frames[2].readUInt8(5) & FLAG_DEFER_COMMIT).toBe(0);
+  });
+
+  it("throws before publishing when one table cannot fit any split", () => {
+    const b = new QwpBuffer();
+    b.table("wide").stringColumn("s", "x".repeat(500));
+    b.at(1n, "us");
+    expect(() => b.sealFrames(50)).toThrow(/cannot fit/i);
+  });
+
+  it("builds a commit frame with no tables and an empty delta", () => {
+    const dict = new SymbolDict();
+    dict.getOrAdd("a");
+    const f = encodeCommitFrame(dict, 0);
+    expect(f.readUInt16LE(6)).toBe(0); // tableCount
+    expect(f.readUInt8(5) & FLAG_DEFER_COMMIT).toBe(0);
+  });
+});
diff --git a/test/qwp/columnWriter.complex.test.ts b/test/qwp/columnWriter.complex.test.ts
new file mode 100644
index 0000000..82e92a0
--- /dev/null
+++ b/test/qwp/columnWriter.complex.test.ts
@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { QwpTableBuffer } from "../../src/qwp/protocol/tableBuffer";
+import { TYPE_GEOHASH, TYPE_DOUBLE_ARRAY } from "../../src/qwp/protocol/constants";
+import { columnPayloadSize, writeColumn, flattenArray } from "../../src/qwp/protocol/columnWriter";
+
+describe("complex column rules", () => {
+  it("locks geohash precision on the first value", () => {
+    const t = new QwpTableBuffer("t");
+    const c = t.getOrCreateColumn("g", TYPE_GEOHASH)!;
+    t.setGeoHashPrecision(c, 20);
+    expect(() => t.setGeoHashPrecision(c, 25)).toThrow(/precision mismatch/i);
+  });
+
+  it("rejects an out-of-range geohash precision", () => {
+    const t = new QwpTableBuffer("t");
+    const c = t.getOrCreateColumn("g", TYPE_GEOHASH)!;
+    expect(() => t.setGeoHashPrecision(c, 61)).toThrow(/1-60/);
+  });
+
+  it("writes a double array as per-value shape then values", () => {
+    const col = {
+      name: "m", type: TYPE_DOUBLE_ARRAY,
+      values: [{ dims: [2], data: [1.5, 2.5] }],
+      nulls: [false], size: 1,
+    };
+    const opts = { gorilla: false };
+    const size = columnPayloadSize(col as any, 1, opts);
+    const b = Buffer.alloc(size);
+    expect(writeColumn(b, 0, col as any, 1, opts)).toBe(size);
+    expect(b[1]).toBe(1); // nDims
+    expect(b.readUInt32LE(2)).toBe(2); // dim length
+    expect(b.readDoubleLE(6)).toBeCloseTo(1.5);
+    expect(b.readDoubleLE(14)).toBeCloseTo(2.5);
+  });
+
+  it("rejects a jagged array", () => {
+    expect(() => flattenArray([[1, 2], [3]])).toThrow(/irregular array shape/i);
+  });
+});
diff --git a/test/qwp/columnWriter.test.ts b/test/qwp/columnWriter.test.ts
new file mode 100644
index 0000000..117ba47
--- /dev/null
+++ b/test/qwp/columnWriter.test.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { columnPayloadSize, writeColumn } from "../../src/qwp/protocol/columnWriter";
+import { TYPE_BOOLEAN, TYPE_INT, TYPE_FLOAT } from "../../src/qwp/protocol/constants";
+
+const opts = { gorilla: false };
+
+function encode(col: any, rowCount: number): Buffer {
+  const size = columnPayloadSize(col, rowCount, opts);
+  const b = Buffer.alloc(size);
+  const end = writeColumn(b, 0, col, rowCount, opts);
+  expect(end).toBe(size);
+  return b;
+}
+
+describe("column writers", () => {
+  it("bit-packs BOOLEAN LSB-first over non-null values", () => {
+    const col = { name: "b", type: TYPE_BOOLEAN, values: [true, false, true], nulls: [false, false, false], size: 3 };
+    const b = encode(col, 3);
+    expect(b[0]).toBe(0); // nullHeader
+    expect(b[1]).toBe(0b00000101); // bits 0 and 2
+    expect(b.length).toBe(2);
+  });
+
+  it("writes INT as 4 bytes LE", () => {
+    const col = { name: "i", type: TYPE_INT, values: [258], nulls: [false], size: 1 };
+    const b = encode(col, 1);
+    expect(b.readInt32LE(1)).toBe(258);
+  });
+
+  it("writes FLOAT as 4 bytes IEEE754", () => {
+    const col = { name: "f", type: TYPE_FLOAT, values: [1.5], nulls: [false], size: 1 };
+    const b = encode(col, 1);
+    expect(b.readFloatLE(1)).toBeCloseTo(1.5, 6);
+  });
+});
diff --git a/test/qwp/columnWriter.varchar.test.ts b/test/qwp/columnWriter.varchar.test.ts
new file mode 100644
index 0000000..344b0ef
--- /dev/null
+++ b/test/qwp/columnWriter.varchar.test.ts
@@ -0,0 +1,18 @@
+import { describe, it, expect } from "vitest";
+import { columnPayloadSize, writeColumn } from "../../src/qwp/protocol/columnWriter";
+import { TYPE_VARCHAR } from "../../src/qwp/protocol/constants";
+
+describe("VARCHAR", () => {
+  it("writes V+1 offsets then concatenated utf8", () => {
+    const col = { name: "s", type: TYPE_VARCHAR, values: ["ab", "cde"], nulls: [false, false], size: 2 };
+    const opts = { gorilla: false };
+    const size = columnPayloadSize(col as any, 2, opts);
+    const b = Buffer.alloc(size);
+    expect(writeColumn(b, 0, col as any, 2, opts)).toBe(size);
+    expect(b[0]).toBe(0); // nullHeader
+    expect(b.readUInt32LE(1)).toBe(0);
+    expect(b.readUInt32LE(5)).toBe(2);
+    expect(b.readUInt32LE(9)).toBe(5);
+    expect(b.subarray(13).toString("utf8")).toBe("abcde");
+  });
+});
diff --git a/test/qwp/constants.test.ts b/test/qwp/constants.test.ts
new file mode 100644
index 0000000..c7c2460
--- /dev/null
+++ b/test/qwp/constants.test.ts
@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import { QWP_MAGIC, HEADER_SIZE, QWP_VERSION, TYPE_LONG, TYPE_SYMBOL } from "../../src/qwp/protocol/constants";
+
+describe("QWP constants", () => {
+  it("magic reads as 0x31505751 little-endian", () => {
+    expect(QWP_MAGIC.toString("ascii")).toBe("QWP1");
+    expect(QWP_MAGIC.readUInt32LE(0)).toBe(0x31505751);
+  });
+
+  it("pins header size and version", () => {
+    expect(HEADER_SIZE).toBe(12);
+    expect(QWP_VERSION).toBe(1);
+  });
+
+  it("pins the type codes this plan uses", () => {
+    expect(TYPE_LONG).toBe(0x05);
+    expect(TYPE_SYMBOL).toBe(0x09);
+  });
+});
diff --git a/test/qwp/deltaDict.test.ts b/test/qwp/deltaDict.test.ts
new file mode 100644
index 0000000..b59d4f5
--- /dev/null
+++ b/test/qwp/deltaDict.test.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { encodeFrame } from "../../src/qwp/protocol/frameEncoder";
+import { QwpTableBuffer } from "../../src/qwp/protocol/tableBuffer";
+import { SymbolDict } from "../../src/qwp/protocol/symbolDict";
+import { TYPE_SYMBOL, FLAG_DELTA_SYMBOL_DICT } from "../../src/qwp/protocol/constants";
+import { readVarint } from "../../src/qwp/protocol/varint";
+
+describe("delta symbol dictionary", () => {
+  it("sets the flag and emits only newly-seen symbols", () => {
+    const dict = new SymbolDict();
+    dict.getOrAdd("already"); // id 0, already confirmed
+    const t = new QwpTableBuffer("t");
+    t.getOrCreateColumn("s", TYPE_SYMBOL)!.values.push(dict.getOrAdd("fresh")); // id 1
+    t.nextRow();
+
+    const f = encodeFrame([t], { gorilla: false, dict, confirmedMaxId: 0 });
+    expect(f.readUInt8(5) & FLAG_DELTA_SYMBOL_DICT).toBe(FLAG_DELTA_SYMBOL_DICT);
+
+    let o = 12;
+    const start = readVarint(f, o);
+    o = start.offset;
+    const count = readVarint(f, o);
+    expect(start.value).toBe(1); // confirmedMaxId + 1
+    expect(count.value).toBe(1); // only "fresh"
+  });
+
+  it("emits an empty delta when nothing new was registered", () => {
+    const dict = new SymbolDict();
+    dict.getOrAdd("a");
+    const t = new QwpTableBuffer("t");
+    t.getOrCreateColumn("s", TYPE_SYMBOL)!.values.push(0);
+    t.nextRow();
+    const f = encodeFrame([t], { gorilla: false, dict, confirmedMaxId: 0 });
+    let o = 12;
+    const start = readVarint(f, o);
+    const count = readVarint(f, start.offset);
+    expect(count.value).toBe(0);
+  });
+
+  it("encodes delta ids >= 128 without overrunning the frame", () => {
+    // ids >= 128 occupy two varint bytes; the size path must use the id, not
+    // the stored {id,text} object, or the frame ends up undersized (spec 6.0).
+    const dict = new SymbolDict();
+    // register 300 symbols so the frame's symbol id is comfortably > 127
+    for (let i = 0; i < 300; i++) dict.getOrAdd(`s${i}`);
+    const t = new QwpTableBuffer("t");
+    const col = t.getOrCreateColumn("s", TYPE_SYMBOL)!;
+    col.values.push({ id: dict.getOrAdd("big") /* ~300 */, text: "big" });
+    t.nextRow();
+    expect(() => encodeFrame([t], { gorilla: false, dict, confirmedMaxId: 0 })).not.toThrow();
+  });
+});
diff --git a/test/qwp/deltaPublish.test.ts b/test/qwp/deltaPublish.test.ts
new file mode 100644
index 0000000..8e51a12
--- /dev/null
+++ b/test/qwp/deltaPublish.test.ts
@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { QwpBuffer } from "../../src/qwp/buffer";
+import { SymbolDict } from "../../src/qwp/protocol/symbolDict";
+import { FLAG_DELTA_SYMBOL_DICT } from "../../src/qwp/protocol/constants";
+import { readVarint } from "../../src/qwp/protocol/varint";
+
+/** Reads the delta header (deltaStart, count) immediately after the 12-byte frame header. */
+function deltaHeader(f: Buffer): { start: number; count: number } {
+  const start = readVarint(f, 12);
+  const count = readVarint(f, start.offset);
+  return { start: start.value, count: count.value };
+}
+
+describe("delta publish ordering (spec 5.2)", () => {
+  it("seals write-ahead but advances the baseline only at publish time", () => {
+    const dict = new SymbolDict();
+    dict.getOrAdd("base"); // id 0, already confirmed
+    const persisted: string[][] = [];
+    const b = new QwpBuffer();
+    b.setConfirmedMaxId(0);
+    b.attachDict(dict, (es) => persisted.push(es));
+
+    b.table("t").symbol("s", "alpha"); // id 1
+    b.at(1n, "us");
+    const f1 = b.sealFrames(1 << 20);
+
+    // Write-ahead happened before encoding...
+    expect(persisted).toEqual([["alpha"]]);
+    // ...and the frame still carries alpha as a delta (baseline is still 0).
+    expect(f1[0].readUInt8(5) & FLAG_DELTA_SYMBOL_DICT).toBe(
+      FLAG_DELTA_SYMBOL_DICT,
+    );
+    expect(deltaHeader(f1[0])).toEqual({ start: 1, count: 1 });
+    // ...but the baseline itself must NOT have moved yet (spec 5.2).
+    expect(b.pendingDeltaTarget).toBe(1);
+
+    // Simulate a successful ring append (the transport's publish time).
+    b.confirmDeltaPublished();
+
+    // A second batch reuses the now-confirmed alpha and introduces only beta.
+    b.table("t").symbol("s", "beta"); // id 2
+    b.at(2n, "us");
+    const f2 = b.sealFrames(1 << 20);
+    // alpha must not be re-persisted (it was already confirmed).
+    expect(persisted).toEqual([["alpha"], ["beta"]]);
+    // The second frame's delta begins at id 2 and carries just beta.
+    expect(deltaHeader(f2[0])).toEqual({ start: 2, count: 1 });
+  });
+
+  it("does not persist positional symbols twice after publication fails", () => {
+    const dict = new SymbolDict();
+    const persisted: string[][] = [];
+    const b = new QwpBuffer();
+    b.attachDict(dict, (es) => persisted.push(es));
+
+    b.table("t").symbol("s", "alpha");
+    b.at(1n, "us");
+    b.sealFrames(1 << 20);
+    // Do not confirm publication: the ring append failed after write-ahead.
+
+    b.table("t").symbol("s", "beta");
+    b.at(2n, "us");
+    const retry = b.sealFrames(1 << 20);
+
+    // The side file remains positional [alpha, beta], while the retry frame
+    // still carries both entries because the server baseline never advanced.
+    expect(persisted).toEqual([["alpha"], ["beta"]]);
+    expect(deltaHeader(retry[0])).toEqual({ start: 0, count: 2 });
+  });
+
+  it("a failed persist never advances the baseline (one-way delta->full-dict)", () => {
+    const dict = new SymbolDict();
+    const b = new QwpBuffer();
+    let calls = 0;
+    b.attachDict(dict, () => {
+      calls++;
+      throw new Error("ENOSPC");
+    });
+    b.table("t").symbol("s", "a");
+    b.at(1n, "us");
+    b.sealFrames(1 << 20);
+    expect(calls).toBe(1);
+    // Degraded to full-dict: the delta baseline is not consulted (-1).
+    expect(b.pendingDeltaTarget).toBe(-1);
+  });
+
+  it("in delta mode only the first split part ships the new symbols", () => {
+    const dict = new SymbolDict();
+    const persisted: string[][] = [];
+    const b = new QwpBuffer();
+    b.attachDict(dict, (es) => persisted.push(es));
+    // Two tables each introducing a distinct symbol; a small cap forces a split.
+    b.table("a").symbol("s", "x1");
+    b.at(1n, "us");
+    b.table("b").symbol("s", "y1");
+    b.at(2n, "us");
+    const parts = b.sealFrames(50);
+    expect(parts.length).toBe(2);
+
+    // Part 0 carries the whole batch delta (both new symbols found id 2, id 3).
+    expect(deltaHeader(parts[0])).toEqual({ start: 0, count: 2 });
+    // Part 1 re-ships nothing: its ids were registered by part 0, so its delta
+    // is empty and pinned to the post-batch baseline (spec 5.2). deltaStart is
+    // baseline + 1, i.e. dict.size() when the baseline is the dict tail.
+    expect(deltaHeader(parts[1])).toEqual({ start: dict.size(), count: 0 });
+    expect(persisted.flat()).toEqual(["x1", "y1"]);
+  });
+});
diff --git a/test/qwp/dispatcher.test.ts b/test/qwp/dispatcher.test.ts
new file mode 100644
index 0000000..78bc835
--- /dev/null
+++ b/test/qwp/dispatcher.test.ts
@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { Dispatcher } from "../../src/qwp/dispatcher";
+import { SenderOptions } from "../../src/options";
+import { deriveConnectMode, ConnectMode } from "../../src/qwp/transport";
+
+describe("Dispatcher", () => {
+  it("drops the OLDEST entry when full and counts the drop", async () => {
+    const seen: number[] = [];
+    const d = new Dispatcher<number>(2, (v) => seen.push(v));
+    d.offer(1);
+    d.offer(2);
+    d.offer(3); // evicts 1
+    await new Promise((r) => setImmediate(r));
+    expect(seen).toEqual([2, 3]);
+    expect(d.dropped).toBe(1);
+  });
+
+  it("never invokes the handler synchronously", () => {
+    let called = false;
+    const d = new Dispatcher<number>(4, () => (called = true));
+    d.offer(1);
+    expect(called).toBe(false);
+  });
+
+  it("survives a throwing handler", async () => {
+    const d = new Dispatcher<number>(4, () => {
+      throw new Error("bad handler");
+    });
+    d.offer(1);
+    await new Promise((r) => setImmediate(r));
+    expect(d.dropped).toBe(0);
+  });
+});
+
+describe("connect mode derivation", () => {
+  it("is OFF when no reconnect_* key is set", () => {
+    expect(deriveConnectMode(new SenderOptions("ws::addr=h:9000;"))).toBe(ConnectMode.OFF);
+  });
+
+  it("is SYNC when any reconnect_* key is supplied", () => {
+    expect(
+      deriveConnectMode(new SenderOptions("ws::addr=h:9000;reconnect_max_backoff_millis=1000;")),
+    ).toBe(ConnectMode.SYNC);
+  });
+});
diff --git a/test/qwp/durableAckTracker.test.ts b/test/qwp/durableAckTracker.test.ts
new file mode 100644
index 0000000..dcbc5bd
--- /dev/null
+++ b/test/qwp/durableAckTracker.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { DurableAckTracker } from "../../src/qwp/durableAckTracker";
+
+describe("DurableAckTracker", () => {
+  it("retires OK frames only after every table transaction is durable", () => {
+    const t = new DurableAckTracker();
+    t.reset(-1);
+    expect(t.onOk(0, [{ name: "a", seqTxn: 4n }])).toBeNull();
+    expect(t.onDurableAck([{ name: "a", seqTxn: 3n }])).toBeNull();
+    expect(t.onDurableAck([{ name: "a", seqTxn: 4n }])).toBe(0);
+  });
+
+  it("never crosses an unresolved earlier FSN", () => {
+    const t = new DurableAckTracker();
+    t.reset(-1);
+    expect(t.onOk(1, [{ name: "b", seqTxn: 2n }])).toBeNull();
+    expect(t.onDurableAck([{ name: "b", seqTxn: 2n }])).toBeNull();
+    expect(t.onOk(0, [])).toBe(1);
+  });
+
+  it("uses durable watermarks that arrive before their OK", () => {
+    const t = new DurableAckTracker();
+    t.reset(4);
+    expect(t.onDurableAck([{ name: "t", seqTxn: 9n }])).toBeNull();
+    expect(t.onOk(5, [{ name: "t", seqTxn: 9n }])).toBe(5);
+  });
+});
diff --git a/test/qwp/endpoints.test.ts b/test/qwp/endpoints.test.ts
new file mode 100644
index 0000000..ae89508
--- /dev/null
+++ b/test/qwp/endpoints.test.ts
@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { parseAddrList } from "../../src/qwp/endpoints";
+
+describe("parseAddrList", () => {
+  it("parses host and host:port", () => {
+    expect(parseAddrList("a,b:1234", 9000)).toEqual([
+      { host: "a", port: 9000 },
+      { host: "b", port: 1234 },
+    ]);
+  });
+
+  it("parses bracketed IPv6 with and without a port", () => {
+    expect(parseAddrList("[::1]:9001,[fe80::1]", 9000)).toEqual([
+      { host: "::1", port: 9001 },
+      { host: "fe80::1", port: 9000 },
+    ]);
+  });
+
+  it("treats an unbracketed multi-colon entry as bare IPv6 on the default port", () => {
+    expect(parseAddrList("fe80::1", 9000)).toEqual([{ host: "fe80::1", port: 9000 }]);
+  });
+
+  it("rejects duplicates on (host, port) but allows the same host twice on different ports", () => {
+    expect(() => parseAddrList("a:1,a:1", 9000)).toThrow(/duplicate/i);
+    expect(parseAddrList("a:1,a:2", 9000).length).toBe(2);
+  });
+
+  it("rejects a missing bracket and an empty host", () => {
+    expect(() => parseAddrList("[::1:9000", 9000)).toThrow(/closing/i);
+    expect(() => parseAddrList(":9000", 9000)).toThrow(/empty host/i);
+  });
+});
diff --git a/test/qwp/errors.test.ts b/test/qwp/errors.test.ts
new file mode 100644
index 0000000..7ab8810
--- /dev/null
+++ b/test/qwp/errors.test.ts
@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { Category, Policy, classify, defaultPolicyFor } from "../../src/qwp/errors";
+import { STATUS } from "../../src/qwp/protocol/response";
+
+describe("error classification", () => {
+  it("maps wire statuses to categories", () => {
+    expect(classify(STATUS.SCHEMA_MISMATCH)).toBe(Category.SCHEMA_MISMATCH);
+    expect(classify(STATUS.DICTIONARY_GAP)).toBe(Category.DICTIONARY_GAP);
+    expect(classify(0x7f)).toBe(Category.UNKNOWN);
+  });
+
+  it("fails OPEN on an unknown status", () => {
+    expect(defaultPolicyFor(Category.UNKNOWN)).toBe(Policy.RETRIABLE);
+  });
+
+  it("treats deterministic rejections as terminal", () => {
+    for (const c of [Category.SCHEMA_MISMATCH, Category.PARSE_ERROR, Category.SECURITY_ERROR]) {
+      expect(defaultPolicyFor(c)).toBe(Policy.TERMINAL);
+    }
+  });
+
+  it("routes DICTIONARY_GAP to retriable, not terminal", () => {
+    expect(defaultPolicyFor(Category.DICTIONARY_GAP)).toBe(Policy.RETRIABLE);
+  });
+
+  it("maps NOT_WRITABLE to RETRIABLE_OTHER and DATA_LOSS to ABANDONED", () => {
+    expect(defaultPolicyFor(Category.NOT_WRITABLE)).toBe(Policy.RETRIABLE_OTHER);
+    expect(defaultPolicyFor(Category.DATA_LOSS)).toBe(Policy.ABANDONED);
+  });
+});
diff --git a/test/qwp/frameEncoder.test.ts b/test/qwp/frameEncoder.test.ts
new file mode 100644
index 0000000..8f39f38
--- /dev/null
+++ b/test/qwp/frameEncoder.test.ts
@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { encodeFrame } from "../../src/qwp/protocol/frameEncoder";
+import { QwpTableBuffer } from "../../src/qwp/protocol/tableBuffer";
+import { TYPE_LONG, HEADER_SIZE } from "../../src/qwp/protocol/constants";
+
+describe("encodeFrame", () => {
+  it("writes a valid 12-byte header", () => {
+    const t = new QwpTableBuffer("t");
+    t.getOrCreateColumn("a", TYPE_LONG)!.values.push(7);
+    t.nextRow();
+    const f = encodeFrame([t], { gorilla: false });
+    expect(f.subarray(0, 4).toString("ascii")).toBe("QWP1");
+    expect(f.readUInt8(4)).toBe(1); // version
+    expect(f.readUInt8(5)).toBe(0); // flags: none in this plan
+    expect(f.readUInt16LE(6)).toBe(1); // tableCount
+    expect(f.readUInt32LE(8)).toBe(f.length - HEADER_SIZE); // payloadLen excludes header
+  });
+
+  it("emits nullHeader 0 and compacted values when there are no nulls", () => {
+    const t = new QwpTableBuffer("t");
+    t.getOrCreateColumn("a", TYPE_LONG)!.values.push(1);
+    t.nextRow();
+    t.getOrCreateColumn("a", TYPE_LONG)!.values.push(2);
+    t.nextRow();
+    const f = encodeFrame([t], { gorilla: false });
+    // ...header, table name "t", rowCount 2, colCount 1, schema "a"+type, then column
+    // nullHeader is the byte immediately after the schema entry.
+    const idx = f.indexOf(TYPE_LONG, HEADER_SIZE);
+    expect(f.readUInt8(idx + 1)).toBe(0); // nullHeader = no nulls
+    expect(f.readBigInt64LE(idx + 2)).toBe(1n);
+    expect(f.readBigInt64LE(idx + 10)).toBe(2n);
+  });
+
+  it("emits nullHeader 1, an LSB-first bitmap, and only non-null values", () => {
+    const t = new QwpTableBuffer("t");
+    t.getOrCreateColumn("a", TYPE_LONG)!.values.push(1);
+    t.nextRow();
+    t.nextRow(); // row 1: "a" not set -> null
+    const f = encodeFrame([t], { gorilla: false });
+    const idx = f.indexOf(TYPE_LONG, HEADER_SIZE);
+    expect(f.readUInt8(idx + 1)).toBe(1); // bitmap present
+    expect(f.readUInt8(idx + 2)).toBe(0b00000010); // bit 1 set -> row 1 is NULL
+    expect(f.readBigInt64LE(idx + 3)).toBe(1n); // only ONE value, not two
+    expect(f.length).toBe(idx + 3 + 8);
+  });
+});
diff --git a/test/qwp/gorilla.test.ts b/test/qwp/gorilla.test.ts
new file mode 100644
index 0000000..106e161
--- /dev/null
+++ b/test/qwp/gorilla.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { BitWriter } from "../../src/qwp/protocol/bits";
+import { gorillaSize, encodeGorilla } from "../../src/qwp/protocol/gorilla";
+
+describe("BitWriter", () => {
+  it("packs LSB-first within each byte", () => {
+    const w = new BitWriter(4);
+    w.writeBits(0b1, 1);
+    w.writeBits(0b0, 1);
+    w.writeBits(0b1, 1);
+    const out = w.finish();
+    expect(out[0]).toBe(0b00000101);
+  });
+});
+
+describe("gorilla", () => {
+  it("returns -1 when a delta-of-delta leaves int32", () => {
+    const ts = [0n, 1n, BigInt(2 ** 40)];
+    expect(gorillaSize(ts)).toBe(-1);
+  });
+
+  it("sizes a constant-interval series as first two raw plus one bit per row", () => {
+    const ts = [1000n, 2000n, 3000n, 4000n];
+    // 8 + 8 + ceil(2 bits / 8) = 17
+    expect(gorillaSize(ts)).toBe(17);
+  });
+
+  it("emits the first two timestamps raw", () => {
+    const ts = [1000n, 2000n, 3000n];
+    const b = encodeGorilla(ts);
+    expect(b.readBigInt64LE(0)).toBe(1000n);
+    expect(b.readBigInt64LE(8)).toBe(2000n);
+  });
+});
+describe("gorilla round-trip (bit-reversal correctness)", () => {
+  // Minimal LSB-first bit reader mirroring the encoder.
+  function makeReader(enc: Buffer) {
+    let byteIdx = 16, bitIdx = 0;
+    const read = (n: number): number => {
+      let v = 0;
+      for (let i = 0; i < n; i++) {
+        v |= ((enc[byteIdx] >> bitIdx) & 1) << i;
+        if (++bitIdx === 8) { bitIdx = 0; byteIdx++; }
+      }
+      return v;
+    };
+    const signed = (v: number, bits: number) =>
+      (v & (1 << (bits - 1))) ? v - (1 << bits) : v;
+    return { read, signed };
+  }
+
+  function decode(enc: Buffer, count: number): bigint[] {
+    const out: bigint[] = [enc.readBigInt64LE(0), enc.readBigInt64LE(8)];
+    const { read, signed } = makeReader(enc);
+    let prevDelta = out[1] - out[0];
+    let prevTs = out[1];
+    for (let i = 2; i < count; i++) {
+      let dod: number;
+      if (read(1) === 0) dod = 0;
+      else if (read(1) === 0) dod = signed(read(7), 7);
+      else if (read(1) === 0) dod = signed(read(9), 9);
+      else if (read(1) === 0) dod = signed(read(12), 12);
+      else dod = (read(32) | 0);
+      const delta = prevDelta + BigInt(dod);
+      prevTs = prevTs + delta;
+      out.push(prevTs);
+      prevDelta = delta;
+    }
+    return out;
+  }
+
+  it("round-trips a constant-interval series", () => {
+    const ts = [1000n, 2000n, 3000n, 4000n, 5000n];
+    expect(decode(encodeGorilla(ts), ts.length)).toEqual(ts);
+  });
+
+  it("round-trips a series exercising the '10' bucket", () => {
+    // deltas: 100, 110, 120 -> dod 10, 10 (in [-64,63])
+    const ts = [1000n, 1100n, 1210n, 1330n];
+    expect(decode(encodeGorilla(ts), ts.length)).toEqual(ts);
+  });
+});
diff --git a/test/qwp/hostTracker.test.ts b/test/qwp/hostTracker.test.ts
new file mode 100644
index 0000000..4d52f8a
--- /dev/null
+++ b/test/qwp/hostTracker.test.ts
@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { HostTracker, HostState } from "../../src/qwp/hostTracker";
+
+describe("HostTracker", () => {
+  it("prefers a known-good host over an untried one", () => {
+    const t = new HostTracker(3);
+    t.record(2, HostState.HEALTHY);
+    expect(t.pickNext()).toBe(2);
+  });
+
+  it("ranks HEALTHY > UNKNOWN > TRANSIENT_REJECT > TRANSPORT_ERROR > TOPOLOGY_REJECT", () => {
+    const t = new HostTracker(4);
+    t.record(0, HostState.TOPOLOGY_REJECT);
+    t.record(1, HostState.TRANSPORT_ERROR);
+    t.record(2, HostState.TRANSIENT_REJECT);
+    // index 3 stays UNKNOWN
+    expect(t.pickNext()).toBe(3);
+    expect(t.pickNext()).toBe(2);
+    expect(t.pickNext()).toBe(1);
+    expect(t.pickNext()).toBe(0);
+  });
+
+  it("exhausts a round and restarts on beginRound", () => {
+    const t = new HostTracker(2);
+    t.pickNext();
+    t.pickNext();
+    expect(t.pickNext()).toBeNull();
+    expect(t.isRoundExhausted()).toBe(true);
+    t.beginRound();
+    expect(t.pickNext()).not.toBeNull();
+  });
+
+  it("a private cursor does not consume the shared round", () => {
+    const t = new HostTracker(2);
+    const c = t.newCursor();
+    c.pickNext();
+    c.pickNext();
+    expect(t.isRoundExhausted()).toBe(false);
+  });
+});
diff --git a/test/qwp/integration.test.ts b/test/qwp/integration.test.ts
new file mode 100644
index 0000000..e4a8c0e
--- /dev/null
+++ b/test/qwp/integration.test.ts
@@ -0,0 +1,199 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync } from "node:child_process";
+import { GenericContainer, StartedTestContainer } from "testcontainers";
+import { Sender } from "../../src";
+
+function dockerAvailable(): boolean {
+  try {
+    execFileSync("docker", ["info"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the ingest endpoint. Three modes:
+ *
+ * 1. `QWP_TEST_ADDR=host:port` (e.g. "localhost:9000") — connect to an
+ *    ALREADY-RUNNING QuestDB instead of starting one. Use this to verify against
+ *    a container you manage yourself, or any external server.
+ * 2. Otherwise start `questdb/questdb:nightly` via testcontainers.
+ * 3. If neither is possible (no `QWP_TEST_ADDR` and Docker unavailable), skip.
+ */
+function parseAddr(
+  addr: string | undefined,
+): { host: string; port: number } | null {
+  if (!addr) return null;
+  const idx = addr.lastIndexOf(":");
+  if (idx < 0) return { host: addr, port: 9000 };
+  return { host: addr.slice(0, idx), port: Number(addr.slice(idx + 1)) };
+}
+
+const external = parseAddr(process.env.QWP_TEST_ADDR);
+const useExternal = external !== null;
+const canRun = useExternal || dockerAvailable();
+
+let container: StartedTestContainer | undefined;
+let host = external?.host ?? "localhost";
+let httpPort = external?.port ?? 0;
+
+async function query(sql: string): Promise<any> {
+  const res = await fetch(
+    `http://${host}:${httpPort}/exec?query=${encodeURIComponent(sql)}`,
+  );
+  return res.json();
+}
+
+describe.skipIf(!canRun)("QWP ingest end-to-end", () => {
+  beforeAll(async () => {
+    if (useExternal) {
+      // Confirm the target is actually a reachable QuestDB before proceeding.
+      const probe = await query("SELECT 1").catch(() => null);
+      if (!probe || probe.error) {
+        throw new Error(
+          `QWP_TEST_ADDR=${process.env.QWP_TEST_ADDR} is not a reachable QuestDB HTTP endpoint`,
+        );
+      }
+      return;
+    }
+    // Matches the existing test/sender.integration.test.ts pattern: no wait
+    // strategy, readiness is established by the polling loop below.
+    container = await new GenericContainer("questdb/questdb:nightly")
+      .withExposedPorts(9000)
+      .start();
+    host = container.getHost();
+    httpPort = container.getMappedPort(9000);
+  }, 180_000);
+
+  afterAll(async () => {
+    await container?.stop();
+  });
+
+  it("ingests rows over ws:// and they land with correct values", async () => {
+    // Unique table per run, so re-verifying against a persistent server is idempotent.
+    const table = `qwp_e2e_${Date.now()}`;
+    // fromConfig is async. Do NOT pass auto_flush=off: spec 9.2 records that
+    // disabling auto-flush is rejected for WebSocket. The default triggers are
+    // harmless here because we flush explicitly and then poll.
+    const sender = await Sender.fromConfig(`ws::addr=${host}:${httpPort};`);
+    await sender.connect();
+
+    await sender
+      .table(table)
+      .symbol("sym", "ETH-USD")
+      .floatColumn("price", 2615.54)
+      .intColumn("qty", 7)
+      .at(1_700_000_000_000_000n, "us");
+
+    await sender.flush();
+    await sender.close();
+
+    // WAL apply is asynchronous — poll rather than sleeping a fixed interval.
+    let rows: any[] = [];
+    for (let i = 0; i < 60; i++) {
+      const r = await query(`select sym, price, qty, timestamp from ${table}`);
+      rows = r.dataset ?? [];
+      if (rows.length > 0) break;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+
+    expect(rows.length).toBe(1);
+    expect(rows[0][0]).toBe("ETH-USD");
+    expect(rows[0][1]).toBeCloseTo(2615.54, 5);
+    expect(rows[0][2]).toBe(7);
+    // The designated timestamp lands with OUR value, not receive time.
+    expect(rows[0][3]).toBe("2023-11-14T22:13:20.000000Z");
+  }, 180_000);
+
+  it("round-trips every supported column type", async () => {
+    const table = `qwp_types_${Date.now()}`;
+    const sender = await Sender.fromConfig(
+      `ws::addr=${host}:${httpPort};`,
+    );
+    await sender.connect();
+    await sender
+      .table(table)
+      .symbol("sym", "A")
+      .stringColumn("str", "hello")
+      .booleanColumn("flag", true)
+      .intColumn("i", 42)
+      .floatColumn("d", 1.25)
+      .timestampColumn("ts2", 1_700_000_000_000_000n, "us")
+      .at(1_700_000_000_000_000n, "us");
+    await sender.flush();
+    await sender.close();
+
+    let rows: any[] = [];
+    for (let i = 0; i < 60; i++) {
+      const r = await query(
+        `select sym, str, flag, i, d from ${table}`,
+      );
+      rows = r.dataset ?? [];
+      if (rows.length > 0) break;
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    expect(rows[0][0]).toBe("A");
+    expect(rows[0][1]).toBe("hello");
+    expect(rows[0][2]).toBe(true);
+    expect(rows[0][3]).toBe(42);
+    expect(rows[0][4]).toBeCloseTo(1.25, 5);
+  }, 180_000);
+
+  it("delta mode persists the symbol dictionary and recovers it across a restart", async () => {
+    // Disk mode + a growing dictionary exercises the full B1 wiring: recovery
+    // seeding -> reconnect catch-up -> delta frames -> write-ahead persist.
+    const { mkdtempSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = mkdtempSync(join(tmpdir(), "qwp-delta-"));
+    const table = `qwp_delta_${Date.now()}`;
+    try {
+      // Phase 1: distinct symbols across several flushes so delta mode is real.
+      const s1 = await Sender.fromConfig(
+        `ws::addr=${host}:${httpPort};sf_dir=${dir};`,
+      );
+      await s1.connect();
+      for (let i = 0; i < 5; i++) {
+        s1.table(table).symbol("sym", `sym_${i}`).intColumn("n", i);
+        await s1.at(1_700_000_000_000_000n + BigInt(i), "us");
+        await s1.flush();
+      }
+      // Let the server ACKs land and the close-time watermark barrier record
+      // them, so the reopened engine does not replay the already-delivered frames
+      // (at-least-once semantics make an un-acked close a duplicate, not a loss).
+      await new Promise((r) => setTimeout(r, 300));
+      await s1.close();
+
+      // Phase 2: a brand-new Sender configured with the same sf_dir must recover
+      // the dictionary (positionally) and keep ingesting in delta mode.
+      const s2 = await Sender.fromConfig(
+        `ws::addr=${host}:${httpPort};sf_dir=${dir};`,
+      );
+      await s2.connect();
+      for (let i = 5; i < 10; i++) {
+        s2.table(table).symbol("sym", `sym_${i}`).intColumn("n", i);
+        await s2.at(1_700_000_000_000_000n + BigInt(i), "us");
+        await s2.flush();
+      }
+      await s2.close();
+
+      let rows: (string | number)[][] = [];
+      for (let i = 0; i < 60; i++) {
+        const r = await query(
+          `select sym, n from ${table} order by n`,
+        );
+        rows = r.dataset ?? [];
+        if (rows.length >= 10) break;
+        await new Promise((r) => setTimeout(r, 500));
+      }
+      expect(rows.length).toBe(10);
+      for (let i = 0; i < 10; i++) {
+        expect(rows[i][0]).toBe(`sym_${i}`);
+        expect(rows[i][1]).toBe(i);
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }, 180_000);
+});
diff --git a/test/qwp/mockServer.ts b/test/qwp/mockServer.ts
new file mode 100644
index 0000000..1cbb1b5
--- /dev/null
+++ b/test/qwp/mockServer.ts
@@ -0,0 +1,233 @@
+import { AddressInfo } from "node:net";
+import { createServer, Server, Socket } from "node:net";
+import { createHash } from "node:crypto";
+import { applyMask } from "../../src/qwp/ws/mask";
+import { STATUS } from "../../src/qwp/protocol/response";
+
+export interface MockOptions {
+  /** Return a status per received frame; OK by default. */
+  statusFor?: (frameIndex: number) => number;
+  /** Build a complete response payload for a frame (overrides statusFor). */
+  responseFor?: (frameIndex: number, sequence: number) => Buffer;
+  /** Build multiple responses written in one chunk (overrides responseFor). */
+  responsesFor?: (frameIndex: number, sequence: number) => Buffer[];
+  /** Drop the connection before responding after N total frames. */
+  dropAfter?: number;
+  /** Drop after writing the selected response(s). */
+  dropAfterResponseFor?: (frameIndex: number) => boolean;
+  upgradeStatus?: number;
+  upgradeHeaders?: string;
+  /** Echo X-QWP-Durable-Ack: enabled on every 101. */
+  durableAck?: boolean;
+  /** Per-connection durable capability override. */
+  durableAckFor?: (connectionIndex: number) => boolean;
+}
+
+function tableEntries(tables: [string, bigint][]): Buffer {
+  const entries = tables.map(([name, txn]) => {
+    const n = Buffer.byteLength(name, "utf8");
+    const b = Buffer.alloc(2 + n + 8);
+    b.writeUInt16LE(n, 0);
+    b.write(name, 2, "utf8");
+    b.writeBigInt64LE(txn, 2 + n);
+    return b;
+  });
+  return Buffer.concat(entries);
+}
+
+export function okResponse(
+  seq: number,
+  tables: [string, bigint][] = [],
+): Buffer {
+  const head = Buffer.alloc(11);
+  head.writeUInt8(STATUS.OK, 0);
+  head.writeBigUInt64LE(BigInt(seq), 1);
+  head.writeUInt16LE(tables.length, 9);
+  return Buffer.concat([head, tableEntries(tables)]);
+}
+
+export function durableAckResponse(tables: [string, bigint][]): Buffer {
+  const head = Buffer.alloc(3);
+  head.writeUInt8(STATUS.DURABLE_ACK, 0);
+  head.writeUInt16LE(tables.length, 1);
+  return Buffer.concat([head, tableEntries(tables)]);
+}
+
+export function errorResponse(
+  status: number,
+  seq: number,
+  msg: string,
+): Buffer {
+  const b = Buffer.alloc(11 + msg.length);
+  b.writeUInt8(status, 0);
+  b.writeBigUInt64LE(BigInt(seq), 1);
+  b.writeUInt16LE(msg.length, 9);
+  b.write(msg, 11, "utf8");
+  return b;
+}
+
+/**
+ * Server → client frames are NEVER masked (RFC 6455 §5.1: only client frames
+ * are). The shared encodeClientFrame masks, so the mock emits frames directly.
+ */
+function encodeServerFrame(opcode: number, payload: Buffer): Buffer {
+  const len = payload.length;
+  let headerLen = 2;
+  if (len >= 65536) headerLen += 8;
+  else if (len >= 126) headerLen += 2;
+
+  const out = Buffer.allocUnsafe(headerLen + len);
+  out[0] = 0x80 | opcode;
+  if (len < 126) {
+    out[1] = len;
+  } else if (len < 65536) {
+    out[1] = 126;
+    out.writeUInt16BE(len, 2);
+  } else {
+    out[1] = 127;
+    out.writeBigUInt64BE(BigInt(len), 2);
+  }
+  payload.copy(out, headerLen);
+  return out;
+}
+
+/**
+ * Reads CLIENT frames, which ARE masked (the inverse of the library's
+ * FrameParser, which rejects masked inbound). Unmask on arrival (spec 3.2.1).
+ */
+class MaskedFrameReader {
+  private buf: Buffer = Buffer.alloc(0);
+
+  push(chunk: Buffer): void {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+  }
+
+  next(): { opcode: number; payload: Buffer } | null {
+    for (;;) {
+      if (this.buf.length < 2) return null;
+      const b0 = this.buf[0];
+      const b1 = this.buf[1];
+      const opcode = b0 & 0x0f;
+      let len = b1 & 0x7f;
+      let offset = 2;
+      if (len === 126) {
+        if (this.buf.length < 4) return null;
+        len = this.buf.readUInt16BE(2);
+        offset = 4;
+      } else if (len === 127) {
+        if (this.buf.length < 10) return null;
+        len = Number(this.buf.readBigUInt64BE(2));
+        offset = 10;
+      }
+      const masked = (b1 & 0x80) !== 0;
+      const payloadStart = offset + (masked ? 4 : 0);
+      if (this.buf.length < payloadStart + len) return null;
+
+      const payload = Buffer.from(
+        this.buf.subarray(payloadStart, payloadStart + len),
+      );
+      if (masked) applyMask(payload, this.buf.subarray(offset, offset + 4));
+      this.buf = this.buf.subarray(payloadStart + len);
+      return { opcode, payload };
+    }
+  }
+}
+
+export class MockQwpServer {
+  private server?: Server;
+  private readonly sockets = new Set<Socket>();
+  readonly frames: Buffer[] = [];
+
+  async start(opts: MockOptions = {}): Promise<number> {
+    return new Promise((resolve) => {
+      let connectionIndex = 0;
+      this.server = createServer((sock: Socket) => {
+        this.sockets.add(sock);
+        sock.on("close", () => this.sockets.delete(sock));
+        this.onConn(sock, opts, connectionIndex++);
+      });
+      this.server.listen(0, "127.0.0.1", () =>
+        resolve((this.server!.address() as AddressInfo).port),
+      );
+    });
+  }
+
+  sendResponse(payload: Buffer): void {
+    const frame = encodeServerFrame(0x2, payload);
+    for (const socket of this.sockets) socket.write(frame);
+  }
+
+  async stop(): Promise<void> {
+    // Destroy any lingering half-open sockets first, or server.close() waits
+    // for them and the callback never fires.
+    for (const s of this.sockets) s.destroy();
+    this.sockets.clear();
+    await new Promise<void>((r) => this.server?.close(() => r()));
+  }
+
+  private onConn(
+    sock: Socket,
+    opts: MockOptions,
+    connectionIndex: number,
+  ): void {
+    let handshaken = false;
+    let seq = 0;
+    const reader = new MaskedFrameReader();
+    sock.on("error", () => undefined);
+    sock.on("data", (chunk: Buffer) => {
+      if (!handshaken) {
+        const status = opts.upgradeStatus ?? 101;
+        if (status !== 101) {
+          sock.write(
+            `HTTP/1.1 ${status} X\r\n${opts.upgradeHeaders ?? ""}\r\n`,
+          );
+          sock.end();
+          return;
+        }
+        const key = /Sec-WebSocket-Key: (.+)\r\n/.exec(
+          chunk.toString("ascii"),
+        )![1];
+        const accept = createHash("sha1")
+          .update(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", "ascii")
+          .digest("base64");
+        sock.write(
+          "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" +
+            `Connection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n` +
+            "X-QWP-Version: 1\r\nX-QWP-Max-Batch-Size: 1048576\r\n" +
+            `${(opts.durableAckFor?.(connectionIndex) ?? opts.durableAck) ? "X-QWP-Durable-Ack: enabled\r\n" : ""}\r\n`,
+        );
+        handshaken = true;
+        return;
+      }
+      reader.push(chunk);
+      for (let m = reader.next(); m; m = reader.next()) {
+        if (m.opcode !== 0x2 /* BINARY */) continue;
+        const idx = this.frames.length;
+        this.frames.push(m.payload);
+        if (opts.dropAfter !== undefined && idx + 1 >= opts.dropAfter) {
+          sock.destroy();
+          return;
+        }
+        const currentSeq = seq++;
+        const status = opts.statusFor ? opts.statusFor(idx) : STATUS.OK;
+        const bodies = opts.responsesFor
+          ? opts.responsesFor(idx, currentSeq)
+          : [
+              opts.responseFor
+                ? opts.responseFor(idx, currentSeq)
+                : status === STATUS.OK
+                  ? okResponse(currentSeq)
+                  : errorResponse(status, currentSeq, "mock"),
+            ];
+        const responseFrames = Buffer.concat(
+          bodies.map((body) => encodeServerFrame(0x2, body)),
+        );
+        if (opts.dropAfterResponseFor?.(idx)) {
+          sock.write(responseFrames, () => sock.destroy());
+        } else {
+          sock.write(responseFrames);
+        }
+      }
+    });
+  }
+}
diff --git a/test/qwp/multiframe.test.ts b/test/qwp/multiframe.test.ts
new file mode 100644
index 0000000..3297a67
--- /dev/null
+++ b/test/qwp/multiframe.test.ts
@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import { QwpBuffer } from "../../src/qwp/buffer";
+
+describe("multi-frame sealing", () => {
+  it("returns a single frame when the batch fits", () => {
+    const b = new QwpBuffer();
+    b.table("t").intColumn("x", 1);
+    b.at(1n, "us");
+    const frames = b.sealFrames(1_000_000);
+    expect(frames.length).toBe(1);
+    expect(frames[0].subarray(0, 4).toString("ascii")).toBe("QWP1");
+  });
+
+  it("returns an empty array when nothing is buffered", () => {
+    expect(new QwpBuffer().sealFrames(1_000_000)).toEqual([]);
+  });
+
+  it("clears state after sealing", () => {
+    const b = new QwpBuffer();
+    b.table("t").intColumn("x", 1);
+    b.at(1n, "us");
+    b.sealFrames(1_000_000);
+    expect(b.sealFrames(1_000_000)).toEqual([]);
+  });
+});
diff --git a/test/qwp/options.test.ts b/test/qwp/options.test.ts
new file mode 100644
index 0000000..d3ce0a5
--- /dev/null
+++ b/test/qwp/options.test.ts
@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { SenderOptions } from "../../src/options";
+import { createBuffer } from "../../src/buffer";
+import { createTransport } from "../../src/transport";
+import { QwpBuffer } from "../../src/qwp/buffer";
+import { QwpTransport } from "../../src/qwp/transport";
+
+describe("ws:// wiring", () => {
+  it("accepts ws:: and defaults the port to 9000", () => {
+    const o = new SenderOptions("ws::addr=localhost;");
+    expect(o.protocol).toBe("ws");
+    expect(o.port).toBe(9000);
+  });
+
+  it("accepts wss:: ", () => {
+    expect(new SenderOptions("wss::addr=localhost;").protocol).toBe("wss");
+  });
+
+  it("gives a ws:: sender a QwpBuffer, never an ILP buffer", () => {
+    const o = new SenderOptions("ws::addr=localhost:9000;");
+    expect(createBuffer(o)).toBeInstanceOf(QwpBuffer);
+  });
+
+  it("gives a ws:: sender a QwpTransport", () => {
+    const o = new SenderOptions("ws::addr=localhost:9000;");
+    expect(createTransport(o)).toBeInstanceOf(QwpTransport);
+  });
+
+  it("rejects protocol_version for ws:: (spec 9.2)", () => {
+    expect(() => new SenderOptions("ws::addr=localhost:9000;protocol_version=2;")).toThrow(
+      /not supported for WebSocket/i,
+    );
+  });
+
+  it("still rejects a genuinely unknown protocol", () => {
+    expect(() => new SenderOptions("wsx::addr=localhost;")).toThrow(/invalid protocol/i);
+  });
+
+  it("accepts sf_durability=periodic and sf_sync_interval_millis together (spec 9.2)", () => {
+    const o = new SenderOptions(
+      "ws::addr=localhost:9000;sf_dir=/tmp/x;sf_durability=periodic;sf_sync_interval_millis=2000;",
+    );
+    expect(o.sf_durability).toBe("periodic");
+    expect(o.sf_sync_interval_millis).toBe(2000);
+  });
+
+  it("sf_sync_interval_millis requires sf_durability=periodic (spec 9.2)", () => {
+    expect(() =>
+      new SenderOptions("ws::addr=localhost:9000;sf_dir=/tmp/x;sf_sync_interval_millis=2000;"),
+    ).toThrow(/sf_sync_interval_millis requires sf_durability=periodic/i);
+  });
+
+  it("sf_durability=periodic requires sf_dir (spec 9.2)", () => {
+    expect(() =>
+      new SenderOptions("ws::addr=localhost:9000;sf_durability=periodic;"),
+    ).toThrow(/requires sf_dir/i);
+  });
+
+  it("drain_orphans requires sf_dir (spec 9.2)", () => {
+    expect(() => new SenderOptions("ws::addr=localhost:9000;drain_orphans=on;")).toThrow(
+      /requires sf_dir|not yet implemented/i,
+    );
+  });
+
+  it("accepts the three spec-9.1 keys that were previously rejected as unknown", () => {
+    const o = new SenderOptions(
+      "ws::addr=localhost:9000;durable_ack_keepalive_interval_millis=200;" +
+        "auth_timeout_ms=15000;catch_up_cap_gap_min_escalation_window_millis=300000;",
+    );
+    expect(o.durable_ack_keepalive_interval_millis).toBe(200);
+    expect(o.auth_timeout_ms).toBe(15000);
+    expect(o.catch_up_cap_gap_min_escalation_window_millis).toBe(300000);
+  });
+
+  it("durable_ack_keepalive_interval_millis=0 is a valid 'disabled' value (spec 9.1)", () => {
+    const o = new SenderOptions(
+      "ws::addr=localhost:9000;durable_ack_keepalive_interval_millis=0;",
+    );
+    expect(o.durable_ack_keepalive_interval_millis).toBe(0);
+  });
+});
diff --git a/test/qwp/poison.test.ts b/test/qwp/poison.test.ts
new file mode 100644
index 0000000..e874b45
--- /dev/null
+++ b/test/qwp/poison.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { PoisonDetector } from "../../src/qwp/poison";
+
+describe("PoisonDetector", () => {
+  it("does NOT escalate on strikes alone inside the dwell window", () => {
+    let now = 1000;
+    const d = new PoisonDetector(4, 5000, () => now);
+    for (let i = 0; i < 6; i++) {
+      now += 100;
+      expect(d.strike(7)).toBe(false);
+    }
+  });
+
+  it("escalates once both the count and the dwell are satisfied", () => {
+    let now = 1000;
+    const d = new PoisonDetector(4, 5000, () => now);
+    d.strike(7);
+    for (let i = 0; i < 3; i++) {
+      now += 2000;
+      d.strike(7);
+    }
+    now += 1;
+    expect(d.strike(7)).toBe(true);
+  });
+
+  it("resets only on acceptance at or beyond the suspect frame", () => {
+    let now = 1000;
+    const d = new PoisonDetector(4, 0, () => now);
+    d.strike(7);
+    d.accept(5); // behind the suspect: must NOT launder the count
+    d.strike(7);
+    d.strike(7);
+    expect(d.strike(7)).toBe(true);
+
+    const d2 = new PoisonDetector(4, 0, () => now);
+    d2.strike(7);
+    d2.accept(7); // at the suspect: clears
+    expect(d2.strike(7)).toBe(false);
+  });
+
+  it("a different frame resets the sequence", () => {
+    let now = 1000;
+    const d = new PoisonDetector(4, 0, () => now);
+    d.strike(7);
+    d.strike(7);
+    d.strike(8);
+    expect(d.strike(8)).toBe(false);
+  });
+});
diff --git a/test/qwp/response.test.ts b/test/qwp/response.test.ts
new file mode 100644
index 0000000..f43d4ac
--- /dev/null
+++ b/test/qwp/response.test.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { decodeResponse, STATUS } from "../../src/qwp/protocol/response";
+
+function ok(seq: number, tables: [string, bigint][]): Buffer {
+  const parts: Buffer[] = [];
+  const head = Buffer.alloc(11);
+  head.writeUInt8(STATUS.OK, 0);
+  head.writeBigUInt64LE(BigInt(seq), 1);
+  head.writeUInt16LE(tables.length, 9);
+  parts.push(head);
+  for (const [name, txn] of tables) {
+    const n = Buffer.byteLength(name, "utf8");
+    const e = Buffer.alloc(2 + n + 8);
+    e.writeUInt16LE(n, 0);
+    e.write(name, 2, "utf8");
+    e.writeBigInt64LE(txn, 2 + n);
+    parts.push(e);
+  }
+  return Buffer.concat(parts);
+}
+
+describe("decodeResponse", () => {
+  it("decodes an OK with per-table seqTxn", () => {
+    const r = decodeResponse(ok(7, [["trades", 42n]]));
+    expect(r.status).toBe(STATUS.OK);
+    expect(r.sequence).toBe(7);
+    expect(r.tables).toEqual([{ name: "trades", seqTxn: 42n }]);
+  });
+
+  it("decodes an error with its message", () => {
+    const msg = "boom";
+    const b = Buffer.alloc(11 + msg.length);
+    b.writeUInt8(STATUS.WRITE_ERROR, 0);
+    b.writeBigUInt64LE(3n, 1);
+    b.writeUInt16LE(msg.length, 9);
+    b.write(msg, 11, "utf8");
+    const r = decodeResponse(b);
+    expect(r.status).toBe(STATUS.WRITE_ERROR);
+    expect(r.errorMessage).toBe("boom");
+  });
+
+  it("decodes DURABLE_ACK, which carries no sequence", () => {
+    const b = Buffer.alloc(3);
+    b.writeUInt8(STATUS.DURABLE_ACK, 0);
+    b.writeUInt16LE(0, 1);
+    expect(decodeResponse(b).status).toBe(STATUS.DURABLE_ACK);
+  });
+
+  it("rejects a truncated payload", () => {
+    expect(() => decodeResponse(Buffer.alloc(2))).toThrow(/invalid|truncated/i);
+  });
+});
diff --git a/test/qwp/rollback.test.ts b/test/qwp/rollback.test.ts
new file mode 100644
index 0000000..ecc9140
--- /dev/null
+++ b/test/qwp/rollback.test.ts
@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { QwpBuffer } from "../../src/qwp/buffer";
+
+describe("row rollback", () => {
+  it("leaves all columns equal-length after a mid-row throw", () => {
+    const b = new QwpBuffer();
+    b.table("t").intColumn("a", 1);
+    expect(() => b.intColumn("bad", 1.5)).toThrow(); // not an integer
+    b.intColumn("a2", 2);
+    b.at(1n, "us");
+    const frame = b.sealFrames(1_000_000)[0];
+    // One row; the frame must encode without a size mismatch, which the
+    // encoder asserts internally.
+    expect(frame.readUInt16LE(6)).toBe(1);
+  });
+
+  it("produces bytes identical to a row that was never started", () => {
+    const a = new QwpBuffer();
+    a.table("t").intColumn("x", 1);
+    a.at(5n, "us");
+    const clean = a.sealFrames(1_000_000)[0];
+
+    const c = new QwpBuffer();
+    c.table("t");
+    expect(() => c.intColumn("x", 0.5)).toThrow();
+    c.table("t").intColumn("x", 1);
+    c.at(5n, "us");
+    expect(c.sealFrames(1_000_000)[0].equals(clean)).toBe(true);
+  });
+
+  it("truncates a partially-filled in-progress row on a mid-row throw", () => {
+    const expected = (() => {
+      const b = new QwpBuffer();
+      b.table("t").intColumn("a", 1);
+      b.at(5n, "us");
+      return b.sealFrames(1_000_000)[0];
+    })();
+
+    const b = new QwpBuffer();
+    b.table("t").intColumn("a", 1);
+    b.at(5n, "us");
+    // Start a new row, populate 'a', then throw mid-row before at().
+    b.table("t").intColumn("a", 2);
+    expect(() => b.intColumn("bad", 1.5)).toThrow();
+    // Without rollback, 'a' would carry two compacted values for one row.
+    expect(b.sealFrames(1_000_000)[0].equals(expected)).toBe(true);
+  });
+});
diff --git a/test/qwp/sender.concurrent.test.ts b/test/qwp/sender.concurrent.test.ts
new file mode 100644
index 0000000..894373c
--- /dev/null
+++ b/test/qwp/sender.concurrent.test.ts
@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { Sender } from "../../src";
+import { readVarint } from "../../src/qwp/protocol/varint";
+import { MockQwpServer } from "./mockServer";
+
+let mock: MockQwpServer | undefined;
+afterEach(async () => mock?.stop());
+
+function deltaHeader(frame: Buffer): { start: number; count: number } {
+  const start = readVarint(frame, 12);
+  const count = readVarint(frame, start.offset);
+  return { start: start.value, count: count.value };
+}
+
+describe("QWP Sender concurrent flush", () => {
+  it("seals and publishes dictionary deltas in flush order", async () => {
+    mock = new MockQwpServer();
+    const port = await mock.start();
+    const sender = await Sender.fromConfig(
+      `ws::addr=127.0.0.1:${port};auto_flush_interval=60000;`,
+    );
+    await sender.connect();
+
+    await sender.table("t").symbol("s", "alpha").at(1n, "us");
+    const first = sender.flush();
+    await sender.table("t").symbol("s", "beta").at(2n, "us");
+    const second = sender.flush();
+    const closing = sender.close();
+    await Promise.all([first, second, closing]);
+    const deadline = Date.now() + 1000;
+    while (mock.frames.length < 2 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 10));
+    }
+
+    expect(mock.frames).toHaveLength(2);
+    expect(deltaHeader(mock.frames[0])).toEqual({ start: 0, count: 1 });
+    expect(deltaHeader(mock.frames[1])).toEqual({ start: 1, count: 1 });
+  });
+});
diff --git a/test/qwp/sf/boundary.test.ts b/test/qwp/sf/boundary.test.ts
new file mode 100644
index 0000000..4b61022
--- /dev/null
+++ b/test/qwp/sf/boundary.test.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { writeBoundary, readBoundary, BOUNDARY_FILE_SIZE } from "../../../src/qwp/sf/boundary";
+
+describe("boundary record", () => {
+  it("alternates slots and picks the greatest valid generation", () => {
+    const buf = Buffer.alloc(BOUNDARY_FILE_SIZE);
+    writeBoundary(buf, 1, 100n);
+    writeBoundary(buf, 2, 200n);
+    expect(readBoundary(buf)).toEqual({ generation: 2, value: 200n });
+  });
+
+  it("writes the two records 4096 bytes apart", () => {
+    const buf = Buffer.alloc(BOUNDARY_FILE_SIZE);
+    writeBoundary(buf, 1, 100n);
+    writeBoundary(buf, 2, 200n);
+    expect(buf.readUInt32LE(0)).not.toBe(0);
+    expect(buf.readUInt32LE(4096)).not.toBe(0);
+  });
+
+  it("falls back to the older record when the newer one is torn", () => {
+    const buf = Buffer.alloc(BOUNDARY_FILE_SIZE);
+    writeBoundary(buf, 1, 100n);
+    writeBoundary(buf, 2, 200n);
+    // Corrupt whichever slot holds generation 2.
+    const slot = buf.readBigUInt64LE(8) === 2n ? 0 : 4096;
+    buf[slot + 20] ^= 0xff;
+    expect(readBoundary(buf)).toEqual({ generation: 1, value: 100n });
+  });
+
+  it("returns null when neither record validates", () => {
+    const buf = Buffer.alloc(BOUNDARY_FILE_SIZE);
+    expect(readBoundary(buf)).toBeNull();
+  });
+});
diff --git a/test/qwp/sf/crash.test.ts b/test/qwp/sf/crash.test.ts
new file mode 100644
index 0000000..9216a76
--- /dev/null
+++ b/test/qwp/sf/crash.test.ts
@@ -0,0 +1,162 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { spawn, ChildProcess } from "node:child_process";
+import { mkdtempSync, rmSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MockQwpServer } from "../mockServer";
+import { Sender } from "../../../src";
+import { readVarint } from "../../../src/qwp/protocol/varint";
+import { TYPE_LONG } from "../../../src/qwp/protocol/constants";
+
+let mocks: MockQwpServer[] = [];
+let children: ChildProcess[] = [];
+let dir: string | undefined;
+
+function killTree(child: ChildProcess): void {
+  if (child.pid === undefined) return;
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+afterEach(async () => {
+  for (const c of children) killTree(c);
+  children = [];
+  for (const m of mocks) await m.stop();
+  mocks = [];
+  if (dir) rmSync(dir, { recursive: true, force: true });
+  dir = undefined;
+});
+
+/** Spawns a tsx child, resolving once it prints FLUSHED. */
+async function spawnCrasher(addr: string, sfDir: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Spawn the executable directly. Killing an `npx tsx ...` wrapper can leave
+    // its real tsx child alive and still legitimately holding the slot lock.
+    const child = spawn(
+      process.execPath,
+      [
+        join(process.cwd(), "node_modules/tsx/dist/cli.mjs"),
+        "test/qwp/sf/crashChild.ts",
+        addr,
+        sfDir,
+      ],
+      { cwd: process.cwd(), detached: true },
+    );
+    children.push(child);
+    let buf = "";
+    child.stdout?.on("data", (d) => {
+      buf += String(d);
+      if (buf.includes("FLUSHED")) resolve();
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (!buf.includes("FLUSHED"))
+        reject(new Error(`crasher exited early (code=${code})`));
+    });
+  });
+}
+
+/**
+ * Decodes the QWP frames a mock received and returns every value found under a
+ * LONG column named "i". The crash child emits a single table with columns
+ * ["i", designated timestamp], so the "i" payload is read directly and the
+ * trailing (possibly Gorilla) timestamp payload is not parsed.
+ */
+function collectIntValues(frames: Buffer[]): number[] {
+  const out: number[] = [];
+  for (const f of frames) {
+    if (f.length < 12 || f.subarray(0, 4).toString("ascii") !== "QWP1")
+      continue;
+    const flags = f.readUInt8(5);
+    const tableCount = f.readUInt16LE(6);
+    let o = 12;
+    if (flags & 0x08) {
+      // delta symbol dict: [deltaStart, count, count x string]
+      const a = readVarint(f, o);
+      o = a.offset;
+      const b = readVarint(f, o);
+      o = b.offset;
+      for (let i = 0; i < b.value; i++) {
+        const r = readVarint(f, o);
+        o = r.offset + r.value;
+      }
+    }
+    for (let t = 0; t < tableCount; t++) {
+      const nm = readVarint(f, o);
+      o = nm.offset + nm.value;
+      const rc = readVarint(f, o);
+      o = rc.offset;
+      const cc = readVarint(f, o);
+      o = cc.offset;
+      const specs: { name: string; type: number }[] = [];
+      for (let c = 0; c < cc.value; c++) {
+        const cn = readVarint(f, o);
+        const name = f
+          .subarray(cn.offset, cn.offset + cn.value)
+          .toString("utf8");
+        o = cn.offset + cn.value;
+        const type = f.readUInt8(o++);
+        specs.push({ name, type });
+      }
+      for (const cs of specs) {
+        const storage = f.readUInt8(o++);
+        if (storage === 1) o += Math.ceil(rc.value / 8);
+        if (cs.name === "i" && cs.type === TYPE_LONG) {
+          for (let r = 0; r < rc.value; r++) {
+            out.push(Number(f.readBigInt64LE(o)));
+            o += 8;
+          }
+        } else {
+          break; // only need "i"; column order puts it first in this fixture
+        }
+      }
+    }
+  }
+  return out;
+}
+
+describe("crash recovery", () => {
+  it("leaves a slot on disk when the process is killed mid-flight", async () => {
+    const mock = new MockQwpServer();
+    mocks.push(mock);
+    const port = await mock.start({ statusFor: () => 0x09 }); // never OK, nothing trims
+    dir = mkdtempSync(join(tmpdir(), "qwp-sf-"));
+
+    await spawnCrasher(`127.0.0.1:${port}`, dir);
+    // Kill implicitly via afterEach? No -- kill now, then assert the slot files.
+    for (const c of children) killTree(c);
+    await new Promise((r) => setTimeout(r, 300));
+
+    const slot = join(dir, "default");
+    expect(readdirSync(slot).length).toBeGreaterThan(0);
+  }, 120_000);
+
+  it("recovers the orphan slot and replays with no row lost", async () => {
+    // At-least-once: every row present, duplicates allowed (spec 5.1).
+    const noAck = new MockQwpServer();
+    const ack = new MockQwpServer();
+    mocks.push(noAck, ack);
+    const childPort = await noAck.start({ statusFor: () => 0x09 });
+    const ackPort = await ack.start(); // ACKs -> trims the recovered replay
+    dir = mkdtempSync(join(tmpdir(), "qwp-sf-"));
+
+    // Produce unacked data on disk, then kill the producer (slot left orphaned).
+    await spawnCrasher(`127.0.0.1:${childPort}`, dir);
+    for (const c of children) killTree(c);
+    await new Promise((r) => setTimeout(r, 300));
+
+    // A fresh sender on the same sf_dir adopts the slot and replays unacked rows.
+    const sender = await Sender.fromConfig(
+      `ws::addr=127.0.0.1:${ackPort};sf_dir=${dir};`,
+    );
+    await sender.connect();
+    await new Promise((r) => setTimeout(r, 1000));
+
+    const values = collectIntValues(ack.frames);
+    for (let i = 0; i < 50; i++) expect(values).toContain(i);
+    await sender.close();
+  }, 120_000);
+});
diff --git a/test/qwp/sf/crashChild.ts b/test/qwp/sf/crashChild.ts
new file mode 100644
index 0000000..36efd92
--- /dev/null
+++ b/test/qwp/sf/crashChild.ts
@@ -0,0 +1,19 @@
+import { Sender } from "../../../src";
+
+async function main(): Promise<void> {
+  const [addr, sfDir] = process.argv.slice(2);
+  const sender = await Sender.fromConfig(`ws::addr=${addr};sf_dir=${sfDir};`);
+  await sender.connect();
+  for (let i = 0; i < 50; i++) {
+    await sender
+      .table("crash_t")
+      .intColumn("i", i)
+      .at(BigInt(1_700_000_000_000_000 + i), "us");
+  }
+  await sender.flush();
+  process.stdout.write("FLUSHED\n");
+  // Never exits cleanly; the parent kills us mid-flight.
+  await new Promise(() => undefined);
+}
+
+void main();
diff --git a/test/qwp/sf/crc32c.test.ts b/test/qwp/sf/crc32c.test.ts
new file mode 100644
index 0000000..c1dfd4f
--- /dev/null
+++ b/test/qwp/sf/crc32c.test.ts
@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { crc32c } from "../../../src/qwp/sf/crc32c";
+
+describe("crc32c (Castagnoli)", () => {
+  it("matches the published check value for '123456789'", () => {
+    expect(crc32c(Buffer.from("123456789", "ascii")) >>> 0).toBe(0xe3069283);
+  });
+
+  it("returns 0 for an empty buffer", () => {
+    expect(crc32c(Buffer.alloc(0)) >>> 0).toBe(0);
+  });
+
+  it("is order-sensitive", () => {
+    expect(crc32c(Buffer.from("ab"))).not.toBe(crc32c(Buffer.from("ba")));
+  });
+});
diff --git a/test/qwp/sf/dictFallback.test.ts b/test/qwp/sf/dictFallback.test.ts
new file mode 100644
index 0000000..1c7f544
--- /dev/null
+++ b/test/qwp/sf/dictFallback.test.ts
@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { QwpBuffer } from "../../../src/qwp/buffer";
+import { SymbolDict } from "../../../src/qwp/protocol/symbolDict";
+import { FLAG_DELTA_SYMBOL_DICT } from "../../../src/qwp/protocol/constants";
+
+describe("delta -> full-dict fallback", () => {
+  it("keeps ingesting after the side file becomes unwritable", () => {
+    const b = new QwpBuffer();
+    b.attachDict(new SymbolDict(), () => {
+      throw new Error("ENOSPC");
+    });
+    b.table("t").symbol("s", "a");
+    b.at(1n, "us");
+    const frames = b.sealFrames(1 << 20); // must NOT throw
+    expect(frames.length).toBe(1);
+    expect(frames[0].readUInt8(5) & FLAG_DELTA_SYMBOL_DICT).toBe(0);
+  });
+
+  it("the fallback is permanent", () => {
+    const b = new QwpBuffer();
+    let fail = true;
+    b.attachDict(new SymbolDict(), () => {
+      if (fail) throw new Error("ENOSPC");
+    });
+    b.table("t").symbol("s", "a");
+    b.at(1n, "us");
+    b.sealFrames(1 << 20);
+    fail = false; // side file recovers, but we must stay in full-dict mode
+    b.table("t").symbol("s", "b");
+    b.at(2n, "us");
+    expect(b.sealFrames(1 << 20)[0].readUInt8(5) & FLAG_DELTA_SYMBOL_DICT).toBe(0);
+  });
+});
diff --git a/test/qwp/sf/engine.test.ts b/test/qwp/sf/engine.test.ts
new file mode 100644
index 0000000..bd2a9a3
--- /dev/null
+++ b/test/qwp/sf/engine.test.ts
@@ -0,0 +1,406 @@
+import { describe, it, expect, afterEach } from "vitest";
+import {
+  appendFileSync,
+  mkdtempSync,
+  rmSync,
+  readFileSync,
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SfEngine } from "../../../src/qwp/sf/engine";
+import { readBoundary } from "../../../src/qwp/sf/boundary";
+import { readManifest, MANIFEST_FILE_NAME } from "../../../src/qwp/sf/manifest";
+import {
+  quarantineSlot,
+  MAX_QUARANTINED,
+  QUARANTINE_INFIX,
+} from "../../../src/qwp/sf/quarantine";
+import { SenderError, Category, Policy } from "../../../src/qwp/errors";
+
+const FRAME = Buffer.from([0xde, 0xad, 0xbe, 0xef]);
+
+let dirs: string[] = [];
+
+afterEach(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  dirs = [];
+});
+
+function tmpSfDir(): string {
+  const d = mkdtempSync(join(tmpdir(), "qwp-engine-"));
+  dirs.push(d);
+  return d;
+}
+
+/** Engine that never fires its background barrier during a test. */
+function engine(sfDir: string, durability: "memory" | "periodic" = "memory") {
+  return new SfEngine({
+    segmentBytes: 1024 * 1024,
+    maxTotalBytes: 16 * 1024 * 1024,
+    sfDir,
+    senderId: "default",
+    durability,
+    syncIntervalMillis: 60_000, // do not let the timer interfere
+  });
+}
+
+describe("SfEngine durability barrier (spec 8.2, handoff A3/C1)", () => {
+  it("does NOT write the ack watermark per ACK, only on the barrier/close", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    await e.append(FRAME); // fsn 0
+    await e.append(FRAME); // fsn 1
+    e.acknowledge(0);
+    e.acknowledge(1);
+
+    // C1: acknowledging twice must not have produced a watermark file yet.
+    const wmPath = join(dir, "default", ".ack-watermark");
+    expect(existsSync(wmPath)).toBe(false);
+
+    // The final barrier on close persists the highest clamped value.
+    await e.close();
+    expect(e.ackedFsn).toBe(1);
+
+    const data = readFileSync(wmPath);
+    const b = readBoundary(data);
+    expect(b).not.toBeNull();
+    expect(Number(b!.value)).toBe(1);
+  });
+
+  it("coalesces several ACKs into a single watermark on close", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    for (let i = 0; i < 50; i++) {
+      await e.append(FRAME);
+      e.acknowledge(i);
+    }
+    expect(existsSync(join(dir, "default", ".ack-watermark"))).toBe(false);
+    await e.close();
+    const b = readBoundary(
+      readFileSync(join(dir, "default", ".ack-watermark")),
+    );
+    expect(Number(b!.value)).toBe(49);
+  });
+
+  it("recovers the ack watermark as the seeded ackedFsn", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    await e.append(FRAME); // fsn 0
+    await e.append(FRAME); // fsn 1
+    await e.append(FRAME); // fsn 2
+    e.acknowledge(2);
+    await e.close();
+
+    const e2 = engine(dir);
+    await e2.open();
+    expect(e2.ackedFsn).toBe(2);
+    await e2.close();
+  });
+
+  it("periodic mode writes and survives a reopen (fsync path)", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir, "periodic");
+    await e.open();
+    await e.append(FRAME);
+    e.acknowledge(0);
+    await e.close();
+    const b = readBoundary(
+      readFileSync(join(dir, "default", ".ack-watermark")),
+    );
+    expect(Number(b!.value)).toBe(0);
+
+    const e2 = engine(dir, "periodic");
+    await e2.open();
+    expect(e2.ackedFsn).toBe(0);
+    await e2.close();
+  });
+
+  it("does not publish an FSN when disk persistence rejects", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    const internals = e as unknown as {
+      persistFrame: (fsn: number, frame: Buffer) => Promise<void>;
+    };
+    internals.persistFrame = async () => {
+      throw new Error("injected disk failure");
+    };
+
+    await expect(e.append(FRAME)).rejects.toThrow(/injected disk failure/);
+    expect(e.publishedFsn).toBe(-1);
+    expect(e.framesFrom(0)).toEqual([]);
+    await e.close();
+  });
+
+  it("does not write a watermark when nothing was acknowledged", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    await e.append(FRAME);
+    await e.close();
+    // No ACK -> no dirty watermark -> nothing written by the final barrier.
+    expect(existsSync(join(dir, "default", ".ack-watermark"))).toBe(false);
+  });
+});
+
+describe("SfEngine sf-manifest.bin (spec 8.2, handoff C2)", () => {
+  function manPath(dir: string) {
+    return join(dir, "default", MANIFEST_FILE_NAME);
+  }
+
+  it("records the active chain head on segment creation and re-opens consistently", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    await e.append(FRAME); // fsn 0 -> segment head 0
+    await e.close();
+
+    expect(existsSync(manPath(dir))).toBe(true);
+    const m = readManifest(readFileSync(manPath(dir)));
+    expect(m).not.toBeNull();
+    expect(m!.headBaseSeq).toBe(0);
+
+    // Re-open: the scanned chain head matches the manifest head, so it recovers.
+    const e2 = engine(dir);
+    await e2.open();
+    expect(e2.publishedFsn).toBe(0);
+    await e2.close();
+  });
+
+  it("advances the recorded head across a segment rotation", async () => {
+    const dir = tmpSfDir();
+    // Small segments force a rotation after a few frames.
+    const e = new SfEngine({
+      segmentBytes: 32,
+      maxTotalBytes: 16 * 1024 * 1024,
+      sfDir: dir,
+      senderId: "default",
+      syncIntervalMillis: 60_000,
+    });
+    await e.open();
+    const big = Buffer.alloc(20);
+    await e.append(big); // fsn 0 -> segment head 0
+    await e.append(big); // fsn 1 -> 20+20>32 -> rotation -> segment head 1
+    await e.close();
+
+    const m = readManifest(readFileSync(manPath(dir)));
+    expect(m!.headBaseSeq).toBe(1);
+
+    const e2 = new SfEngine({
+      segmentBytes: 32,
+      maxTotalBytes: 16 * 1024 * 1024,
+      sfDir: dir,
+      senderId: "default",
+      syncIntervalMillis: 60_000,
+    });
+    await e2.open();
+    expect(e2.framesFrom(1)).toHaveLength(1);
+    await e2.close();
+  });
+
+  it("recovers more than ten numerically named segments in FSN order", async () => {
+    const dir = tmpSfDir();
+    const options = {
+      segmentBytes: FRAME.length,
+      maxTotalBytes: 16 * 1024 * 1024,
+      sfDir: dir,
+      senderId: "default",
+      syncIntervalMillis: 60_000,
+    };
+    const e = new SfEngine(options);
+    await e.open();
+    for (let i = 0; i < 11; i++) await e.append(Buffer.from([i, 0, 0, 0]));
+    await e.close();
+    expect(existsSync(join(dir, "default", "10.sfa"))).toBe(true);
+
+    const recovered = new SfEngine(options);
+    await recovered.open();
+    expect(recovered.publishedFsn).toBe(10);
+    expect(recovered.framesFrom(0).map((f) => f[0])).toEqual([
+      0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
+    ]);
+    await recovered.close();
+  });
+
+  it("quarantines when the manifest head is ahead of the scanned chain (lost tail)", async () => {
+    const dir = tmpSfDir();
+    const slot = join(dir, "default");
+    mkdirSync(slot, { recursive: true });
+    const e = engine(dir);
+    await e.open();
+    await e.append(FRAME); // segment head 0
+    await e.close();
+    expect(existsSync(manPath(dir))).toBe(true);
+
+    // Simulate a lost tail: delete the only segment so the scanned head drops
+    // below the manifest's recorded head 0 -> real data loss -> quarantine.
+    rmSync(join(slot, "0.sfa"), { force: true });
+
+    const e2 = engine(dir);
+    const err = await e2.open().then(
+      () => null as SenderError | null,
+      (x) => x as SenderError,
+    );
+    expect(err).toBeInstanceOf(SenderError);
+    expect(err!.category).toBe(Category.DATA_LOSS);
+    expect(err!.quarantinedPath).toContain(QUARANTINE_INFIX);
+  });
+
+  it("quarantines governed frames when the manifest is corrupt", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    await e.append(FRAME);
+    await e.close();
+    writeFileSync(manPath(dir), Buffer.alloc(8192));
+
+    const e2 = engine(dir);
+    const err = await e2.open().then(
+      () => null as SenderError | null,
+      (x) => x as SenderError,
+    );
+    expect(err).toBeInstanceOf(SenderError);
+    expect(err!.category).toBe(Category.DATA_LOSS);
+    expect(err!.message).toMatch(/manifest missing or corrupt/i);
+  });
+
+  it("sets MANIFEST_REQUIRED_FLAG (bit 0) on segments it writes", async () => {
+    const dir = tmpSfDir();
+    const e = engine(dir);
+    await e.open();
+    await e.append(FRAME);
+    await e.close();
+    const seg = readFileSync(join(dir, "default", "0.sfa"));
+    expect(seg.readUInt8(5) & 1).toBe(1); // flags bit 0
+  });
+});
+
+describe("SfEngine quarantine (spec 8.4, handoff A2)", () => {
+  it("sets aside a slot with a bad-magic segment and surfaces DATA_LOSS + path", async () => {
+    const dir = tmpSfDir();
+    const slot = join(dir, "default");
+    mkdirSync(slot, { recursive: true });
+    // 24-byte header with wrong magic -> scanSegment throws.
+    const bad = Buffer.alloc(64, 0);
+    bad.write("NOPE", 0, "ascii");
+    writeFileSync(join(slot, "0.sfa"), bad);
+
+    const e = new SfEngine({
+      segmentBytes: 1024 * 1024,
+      maxTotalBytes: 16 * 1024 * 1024,
+      sfDir: dir,
+      senderId: "default",
+    });
+    const err = await e.open().then(
+      () => null as SenderError | null,
+      (x) => x as SenderError,
+    );
+    expect(err).toBeInstanceOf(SenderError);
+    expect(err!.category).toBe(Category.DATA_LOSS);
+    expect(err!.policy).toBe(Policy.ABANDONED);
+    expect(err!.quarantinedPath).toContain(QUARANTINE_INFIX);
+
+    // The working slot is gone (renamed) and the sentinel marks the copy.
+    expect(existsSync(slot)).toBe(false);
+    expect(existsSync(join(err!.quarantinedPath!, ".failed"))).toBe(true);
+  });
+
+  it("refuses to set aside more than 64 quarantined copies of one slot", async () => {
+    const dir = tmpSfDir();
+    mkdirSync(dir, { recursive: true });
+    const existing: string[] = [];
+    for (let i = 0; i < MAX_QUARANTINED; i++) {
+      const d = join(dir, `default${QUARANTINE_INFIX}${i}`);
+      mkdirSync(d, { recursive: true });
+      existing.push(d);
+    }
+    const victim = join(dir, "default");
+    mkdirSync(victim, { recursive: true });
+    await expect(quarantineSlot(dir, "default", victim)).rejects.toThrow(
+      /refusing to quarantine/i,
+    );
+  });
+});
+
+describe("SfEngine persisted symbol dictionary (spec 8.1.6, handoff B1)", () => {
+  it("repairs a torn final chunk before appending new symbols", async () => {
+    const dir = tmpSfDir();
+    const e1 = engine(dir);
+    await e1.open();
+    e1.persistSymbols(["alpha"]);
+    await e1.close();
+
+    const dictPath = join(dir, "default", ".symbol-dict");
+    appendFileSync(dictPath, Buffer.from([0x81])); // torn entry-count varint
+
+    const e2 = engine(dir);
+    await e2.open();
+    expect(e2.symbolDict.entriesFrom(0)).toEqual(["alpha"]);
+    e2.persistSymbols(["beta"]);
+    await e2.close();
+
+    const e3 = engine(dir);
+    await e3.open();
+    expect(e3.symbolDict.entriesFrom(0)).toEqual(["alpha", "beta"]);
+    await e3.close();
+  });
+
+  it("quarantines a complete dictionary chunk with a bad CRC", async () => {
+    const dir = tmpSfDir();
+    const e1 = engine(dir);
+    await e1.open();
+    e1.persistSymbols(["alpha"]);
+    await e1.close();
+
+    const dictPath = join(dir, "default", ".symbol-dict");
+    const raw = readFileSync(dictPath);
+    raw[raw.length - 1] ^= 0xff;
+    writeFileSync(dictPath, raw);
+
+    const e2 = engine(dir);
+    const err = await e2.open().then(
+      () => null as SenderError | null,
+      (x) => x as SenderError,
+    );
+    expect(err).toBeInstanceOf(SenderError);
+    expect(err!.category).toBe(Category.DATA_LOSS);
+    expect(err!.message).toMatch(/CRC mismatch/i);
+  });
+
+  it("writes a recoverable SYD1 file that re-opens positionally without de-duping", async () => {
+    const dir = tmpSfDir();
+    const e1 = engine(dir);
+    await e1.open();
+    e1.persistSymbols(["alpha", "beta"]);
+    e1.persistSymbols(["alpha", "gamma"]); // alpha collides but must NOT de-dupe
+    await e1.close();
+
+    const dictPath = join(dir, "default", ".symbol-dict");
+    const raw = readFileSync(dictPath);
+    expect(raw.subarray(0, 4).toString("ascii")).toBe("SYD1");
+
+    const e2 = engine(dir);
+    await e2.open();
+    // Recovered positionally: alpha,beta,alpha,gamma -> size 4, ids dense from 0.
+    expect(e2.symbolDict.size()).toBe(4);
+    expect(e2.symbolDict.entriesFrom(0)).toEqual([
+      "alpha",
+      "beta",
+      "alpha",
+      "gamma",
+    ]);
+    await e2.close();
+
+    // A second reopen sees the same on-disk state (idempotent).
+    const e3 = engine(dir);
+    await e3.open();
+    expect(e3.symbolDict.size()).toBe(4);
+    await e3.close();
+  });
+});
diff --git a/test/qwp/sf/manifest.test.ts b/test/qwp/sf/manifest.test.ts
new file mode 100644
index 0000000..ba585e1
--- /dev/null
+++ b/test/qwp/sf/manifest.test.ts
@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import {
+  writeManifest,
+  readManifest,
+  MANIFEST_FILE_SIZE,
+  SFM1_MAGIC,
+} from "../../../src/qwp/sf/manifest";
+
+describe("sf-manifest.bin boundary record (spec 8.2, alternatgen scheme)", () => {
+  it("writes an SFM1 record and reads it back", () => {
+    const buf = Buffer.alloc(MANIFEST_FILE_SIZE);
+    writeManifest(buf, 1, 42);
+    const m = readManifest(buf);
+    expect(m).toEqual({ generation: 1, headBaseSeq: 42 });
+  });
+
+  it("uses little-endian 'SFM1' magic like .ack-watermark does 'AKW1'", () => {
+    const buf = Buffer.alloc(MANIFEST_FILE_SIZE);
+    writeManifest(buf, 1, 7);
+    // gen 1 -> slot 4096; LE bytes there: 'S' 'F' 'M' '1'
+    expect(buf.subarray(4096, 4100).toString("ascii")).toBe("SFM1");
+    expect(SFM1_MAGIC).toBe(0x314d4653);
+  });
+
+  it("alternates slots by generation parity so a torn record falls back", () => {
+    const buf = Buffer.alloc(MANIFEST_FILE_SIZE);
+    // slot = (generation % 2) * 4096: gen 1 -> slot 4096, gen 2 -> slot 0.
+    writeManifest(buf, 1, 100); // slot 4096
+    writeManifest(buf, 2, 200); // slot 0
+    // Corrupt the newest (gen 2, slot 0) record's CRC.
+    buf.writeUInt32LE(0, 0 + 60);
+    const m = readManifest(buf);
+    // Falls back to the older valid (gen 1, slot 4096) record.
+    expect(m).toEqual({ generation: 1, headBaseSeq: 100 });
+  });
+
+  it("returns null when the file is absent/empty or neither record validates", () => {
+    expect(readManifest(Buffer.alloc(MANIFEST_FILE_SIZE))).toBeNull();
+    const buf = Buffer.alloc(MANIFEST_FILE_SIZE);
+    buf.write("NOPE", 0, "ascii");
+    expect(readManifest(buf)).toBeNull();
+  });
+});
diff --git a/test/qwp/sf/orphan.test.ts b/test/qwp/sf/orphan.test.ts
new file mode 100644
index 0000000..984ccab
--- /dev/null
+++ b/test/qwp/sf/orphan.test.ts
@@ -0,0 +1,269 @@
+import { describe, it, expect, afterEach } from "vitest";
+import {
+  mkdtempSync,
+  rmSync,
+  readdirSync,
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { errorResponse, MockQwpServer, okResponse } from "../mockServer";
+import { Sender } from "../../../src";
+import { scanOrphans } from "../../../src/qwp/sf/orphanScanner";
+import { acquireSlot, releaseSlot } from "../../../src/qwp/sf/slotLock";
+import { readVarint } from "../../../src/qwp/protocol/varint";
+import { TYPE_LONG } from "../../../src/qwp/protocol/constants";
+import { STATUS } from "../../../src/qwp/protocol/response";
+
+let mocks: MockQwpServer[] = [];
+let dir: string | undefined;
+
+afterEach(async () => {
+  for (const m of mocks) await m.stop();
+  mocks = [];
+  if (dir) rmSync(dir, { recursive: true, force: true });
+  dir = undefined;
+});
+
+function tmp(): string {
+  dir = mkdtempSync(join(tmpdir(), "qwp-orphan-"));
+  return dir;
+}
+
+async function waitFor(cond: () => boolean, ms = 8000): Promise<void> {
+  const start = Date.now();
+  while (!cond()) {
+    if (Date.now() - start > ms) throw new Error("condition not met in time");
+    await new Promise((r) => setTimeout(r, 25));
+  }
+}
+
+/** Decodes QWP frames and returns every value found under a LONG column "i". */
+function collectIntValues(frames: Buffer[]): number[] {
+  const out: number[] = [];
+  for (const f of frames) {
+    if (f.length < 12 || f.subarray(0, 4).toString("ascii") !== "QWP1")
+      continue;
+    const flags = f.readUInt8(5);
+    const tableCount = f.readUInt16LE(6);
+    let o = 12;
+    if (flags & 0x08) {
+      const a = readVarint(f, o);
+      o = a.offset;
+      const b = readVarint(f, o);
+      o = b.offset;
+      for (let i = 0; i < b.value; i++) {
+        const r = readVarint(f, o);
+        o = r.offset + r.value;
+      }
+    }
+    for (let t = 0; t < tableCount; t++) {
+      const nm = readVarint(f, o);
+      o = nm.offset + nm.value;
+      const rc = readVarint(f, o);
+      o = rc.offset;
+      const cc = readVarint(f, o);
+      o = cc.offset;
+      const specs: { name: string; type: number }[] = [];
+      for (let c = 0; c < cc.value; c++) {
+        const cn = readVarint(f, o);
+        const name = f
+          .subarray(cn.offset, cn.offset + cn.value)
+          .toString("utf8");
+        o = cn.offset + cn.value;
+        const type = f.readUInt8(o++);
+        specs.push({ name, type });
+      }
+      for (const cs of specs) {
+        const storage = f.readUInt8(o++);
+        if (storage === 1) o += Math.ceil(rc.value / 8);
+        if (cs.name === "i" && cs.type === TYPE_LONG) {
+          for (let r = 0; r < rc.value; r++) {
+            out.push(Number(f.readBigInt64LE(o)));
+            o += 8;
+          }
+        } else {
+          break;
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Produces 50 unacked rows into the given slot and returns without acking them. */
+async function orphanSlot(
+  sfDir: string,
+  serverPort: number,
+  senderId: string,
+): Promise<void> {
+  const noAck = new MockQwpServer();
+  mocks.push(noAck);
+  const port = await noAck.start({ statusFor: () => 0x09 }); // never OK: nothing trims
+  const producer = await Sender.fromConfig(
+    `ws::addr=127.0.0.1:${port};sf_dir=${sfDir};sender_id=${senderId};`,
+  );
+  await producer.connect();
+  for (let i = 0; i < 50; i++) {
+    await producer
+      .table("crash_t")
+      .intColumn("i", i)
+      .at(BigInt(1_700_000_000_000_000 + i), "us");
+  }
+  await producer.flush();
+  await producer.close(); // graceful close, but the no-ack server never trimmed
+  // ignore serverPort param kept for symmetry with crash helpers
+  void serverPort;
+}
+
+/** True when a frame is a bare symbol-dictionary catch-up (delta flag, 0 tables). */
+function isCatchUpFrame(f: Buffer): boolean {
+  if (f.length < 12 || f.subarray(0, 4).toString("ascii") !== "QWP1")
+    return false;
+  const flags = f.readUInt8(5);
+  const tableCount = f.readUInt16LE(6);
+  return (flags & 0x08) !== 0 && tableCount === 0;
+}
+
+describe("orphan scanner (spec 8.4)", () => {
+  it("finds slots with a stale/absent lock and skips live-held ones", async () => {
+    const d = tmp();
+    const slotA = join(d, "slotA");
+    mkdirSync(slotA, { recursive: true });
+    writeFileSync(join(slotA, ".lock"), "999999999\notherboot\n"); // dead pid, foreign boot
+    const failed = join(d, "failed");
+    mkdirSync(failed, { recursive: true });
+    writeFileSync(join(failed, ".failed"), "operator action required\n");
+    const liv = await acquireSlot(d, "live");
+    try {
+      // dotfiles, quarantined slots, and terminal .failed slots are ignored.
+      mkdirSync(join(d, ".slot-locks", "x"), { recursive: true });
+      mkdirSync(join(d, "def.quarantined.0"), { recursive: true });
+      const orphans = await scanOrphans(d).then((o) =>
+        o.map((x) => x.senderId).sort(),
+      );
+      expect(orphans).toEqual(["slotA"]);
+    } finally {
+      await releaseSlot(liv);
+    }
+  });
+});
+
+describe("orphan drainer (spec 8.4)", () => {
+  it("replays a foreign orphan slot to a fresh acking server", async () => {
+    const d = tmp();
+    // A producer with its own sender_id crashes, leaving unacked rows in its slot.
+    await orphanSlot(d, 0, "crashed");
+
+    // A fresh sender (distinct sender_id) with drain_orphans=on adopts the
+    // orphan and replays it to an ACKing server on its own WebSocket.
+    const ack = new MockQwpServer();
+    mocks.push(ack);
+    const ackPort = await ack.start();
+    const drainer = await Sender.fromConfig(
+      `ws::addr=127.0.0.1:${ackPort};sf_dir=${d};drain_orphans=on;sender_id=runner;`,
+    );
+    await drainer.connect();
+
+    await waitFor(() => collectIntValues(ack.frames).length >= 50);
+    const values = collectIntValues(ack.frames);
+    for (let i = 0; i < 50; i++) expect(values).toContain(i);
+    // Completion is renamed out of scanner visibility before deletion, so a
+    // future startup cannot replay the same orphan again.
+    await waitFor(() => !existsSync(join(d, "crashed")));
+    const later = await scanOrphans(d);
+    expect(later.some((s) => s.senderId === "crashed")).toBe(false);
+    await drainer.close();
+  }, 30_000);
+
+  it("ignores an OK queued behind a retryable NACK on a recycled connection", async () => {
+    const d = tmp();
+    await orphanSlot(d, 0, "crashed");
+
+    const ack = new MockQwpServer();
+    mocks.push(ack);
+    const ackPort = await ack.start({
+      responsesFor: (idx, seq) =>
+        idx === 0
+          ? [errorResponse(STATUS.WRITE_ERROR, seq, "retry"), okResponse(seq)]
+          : [okResponse(seq)],
+    });
+    const drainer = await Sender.fromConfig(
+      `ws::addr=127.0.0.1:${ackPort};sf_dir=${d};drain_orphans=on;sender_id=runner;`,
+    );
+    await drainer.connect();
+
+    // The stale OK shares one socket-data chunk with the NACK. It must not mark
+    // the rejected frame drained; a fresh connection has to replay it.
+    await waitFor(
+      () =>
+        ack.frames.filter((f) => collectIntValues([f]).length > 0).length >= 2,
+    );
+    expect(existsSync(join(d, "crashed", ".failed"))).toBe(false);
+    await drainer.close();
+  }, 30_000);
+
+  it("re-registers the recovered symbol dictionary before replaying a delta slot", async () => {
+    const d = tmp();
+    // Producer writes SYMBOL rows, so the slot carries a persisted .symbol-dict
+    // and its frames are delta-encoded. Leave it unacked (no-ack server).
+    const noAck = new MockQwpServer();
+    mocks.push(noAck);
+    const noAckPort = await noAck.start({ statusFor: () => 0x09 });
+    const producer = await Sender.fromConfig(
+      `ws::addr=127.0.0.1:${noAckPort};sf_dir=${d};sender_id=delta;`,
+    );
+    await producer.connect();
+    for (let i = 0; i < 20; i++) {
+      await producer
+        .table("sym_t")
+        .intColumn("i", i)
+        .symbol("s", `sym_${i}`)
+        .at(BigInt(1_700_000_000_000_000 + i), "us");
+    }
+    await producer.flush();
+    await producer.close();
+
+    const ack = new MockQwpServer();
+    mocks.push(ack);
+    const ackPort = await ack.start();
+    const drainer = await Sender.fromConfig(
+      `ws::addr=127.0.0.1:${ackPort};sf_dir=${d};drain_orphans=on;sender_id=runner;`,
+    );
+    await drainer.connect();
+
+    // A bare dictionary catch-up frame must precede the replayed data frames so
+    // the fresh server can decode their delta ids (spec 7.5).
+    await waitFor(() => collectIntValues(ack.frames).length >= 20);
+    const catchUps = ack.frames.filter(isCatchUpFrame);
+    expect(catchUps.length).toBeGreaterThanOrEqual(1);
+    const firstDataIdx = ack.frames.findIndex(
+      (f) => collectIntValues([f]).length > 0,
+    );
+    expect(ack.frames.indexOf(catchUps[0])).toBeLessThan(firstDataIdx);
+    const values = collectIntValues(ack.frames);
+    for (let i = 0; i < 20; i++) expect(values).toContain(i);
+    await drainer.close();
+  }, 30_000);
+
+  it("drops a .failed sentinel and emits DATA_LOSS on a terminal failure", async () => {
+    const d = tmp();
+    await orphanSlot(d, 0, "crashed");
+
+    const authFail = new MockQwpServer();
+    mocks.push(authFail);
+    const authPort = await authFail.start({ upgradeStatus: 401 });
+
+    const drainer = await Sender.fromConfig(
+      `ws::addr=127.0.0.1:${authPort};sf_dir=${d};drain_orphans=on;sender_id=runner;`,
+    );
+    // The sender's own connection also fails auth; the drainer still runs.
+    await drainer.connect().catch(() => undefined);
+
+    await waitFor(() => existsSync(join(d, "crashed", ".failed")));
+    expect(readdirSync(join(d, "crashed")).length).toBeGreaterThan(0);
+    await drainer.close().catch(() => undefined);
+  }, 30_000);
+});
diff --git a/test/qwp/sf/replay.test.ts b/test/qwp/sf/replay.test.ts
new file mode 100644
index 0000000..6119297
--- /dev/null
+++ b/test/qwp/sf/replay.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { MockQwpServer } from "../mockServer";
+import { QwpTransport } from "../../../src/qwp/transport";
+import { SenderOptions } from "../../../src/options";
+
+let mock: MockQwpServer | undefined;
+afterEach(async () => await mock?.stop());
+
+describe("replay", () => {
+  it("resends unacked frames after a reconnect", async () => {
+    mock = new MockQwpServer();
+    // Drop the connection after the first frame, never ACKing it.
+    const port = await mock.start({ dropAfter: 1 });
+    const t = new QwpTransport(new SenderOptions(`ws::addr=127.0.0.1:${port};`));
+    await t.connect();
+    await t.sendFrames([Buffer.from("QWP1frame-one")]);
+    await new Promise((r) => setTimeout(r, 400));
+    // The same payload must appear at least twice: original plus replay.
+    const matching = mock.frames.filter((f) => f.toString().includes("frame-one"));
+    expect(matching.length).toBeGreaterThanOrEqual(2);
+    await t.close();
+  });
+
+  it("does not replay frames the server already acked", async () => {
+    mock = new MockQwpServer();
+    const port = await mock.start();
+    const t = new QwpTransport(new SenderOptions(`ws::addr=127.0.0.1:${port};`));
+    await t.connect();
+    await t.sendFrames([Buffer.from("QWP1acked-frame")]);
+    await new Promise((r) => setTimeout(r, 150));
+    await t.reconnectForTest();
+    await new Promise((r) => setTimeout(r, 150));
+    const matching = mock.frames.filter((f) => f.toString().includes("acked-frame"));
+    expect(matching.length).toBe(1);
+    await t.close();
+  });
+});
diff --git a/test/qwp/sf/ring.test.ts b/test/qwp/sf/ring.test.ts
new file mode 100644
index 0000000..4bda9d3
--- /dev/null
+++ b/test/qwp/sf/ring.test.ts
@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { SegmentRing, PAYLOAD_TOO_LARGE } from "../../../src/qwp/sf/ring";
+
+describe("SegmentRing", () => {
+  it("assigns FSNs from 0 on a fresh ring", () => {
+    const r = new SegmentRing({ segmentBytes: 4096, maxTotalBytes: 1 << 20 });
+    expect(r.publishedFsn).toBe(-1);
+    expect(r.append(Buffer.from("a"))).toBe(0);
+    expect(r.append(Buffer.from("b"))).toBe(1);
+    expect(r.publishedFsn).toBe(1);
+  });
+
+  it("continues numbering when recovered from existing segments", () => {
+    const r = SegmentRing.recovered([{ baseSeq: 10, frames: [Buffer.from("x"), Buffer.from("y")] }], {
+      segmentBytes: 4096,
+      maxTotalBytes: 1 << 20,
+    });
+    expect(r.publishedFsn).toBe(11);
+    expect(r.append(Buffer.from("z"))).toBe(12);
+  });
+
+  it("returns PAYLOAD_TOO_LARGE for a frame that cannot fit a fresh segment", () => {
+    const r = new SegmentRing({ segmentBytes: 64, maxTotalBytes: 1 << 20 });
+    expect(r.append(Buffer.alloc(1000))).toBe(PAYLOAD_TOO_LARGE);
+  });
+
+  it("trims acked segments and frees space", () => {
+    const r = new SegmentRing({ segmentBytes: 64, maxTotalBytes: 256 });
+    const fsns = [0, 1, 2].map(() => r.append(Buffer.alloc(20)));
+    r.acknowledge(fsns[2]);
+    expect(r.ackedFsn).toBe(fsns[2]);
+    expect(r.totalBytes).toBeLessThan(256);
+  });
+
+  it("returns the frames to replay from ackedFsn + 1", () => {
+    const r = new SegmentRing({ segmentBytes: 4096, maxTotalBytes: 1 << 20 });
+    r.append(Buffer.from("a"));
+    r.append(Buffer.from("b"));
+    r.append(Buffer.from("c"));
+    r.acknowledge(0);
+    expect(r.framesFrom(r.ackedFsn + 1).map((f) => f.toString())).toEqual(["b", "c"]);
+  });
+});
diff --git a/test/qwp/sf/segment.test.ts b/test/qwp/sf/segment.test.ts
new file mode 100644
index 0000000..8608838
--- /dev/null
+++ b/test/qwp/sf/segment.test.ts
@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { buildSegment, scanSegment, SEGMENT_HEADER_SIZE } from "../../../src/qwp/sf/segment";
+
+function seg(baseSeq: number, frames: Buffer[]): Buffer {
+  return buildSegment(baseSeq, frames, 4096);
+}
+
+describe("segment", () => {
+  it("writes an SF01 header carrying baseSeq", () => {
+    const b = seg(42, [Buffer.from("aa")]);
+    expect(b.subarray(0, 4).toString("ascii")).toBe("SF01");
+    expect(b.readUInt8(4)).toBe(1);
+    expect(Number(b.readBigUInt64LE(8))).toBe(42);
+  });
+
+  it("scans back the frames it wrote", () => {
+    const r = scanSegment(seg(0, [Buffer.from("aa"), Buffer.from("bbb")]));
+    expect(r.frames.map((f) => f.toString())).toEqual(["aa", "bbb"]);
+    expect(r.tornTailBytes).toBe(0);
+  });
+
+  it("stops at a bad CRC and reports a torn tail", () => {
+    const b = seg(0, [Buffer.from("aa"), Buffer.from("bbb")]);
+    b[SEGMENT_HEADER_SIZE + 8 + 2 + 0] ^= 0xff; // corrupt the second frame's payload
+    const r = scanSegment(b);
+    expect(r.frames.length).toBe(1);
+    expect(r.tornTailBytes).toBeGreaterThan(0);
+  });
+
+  it("distinguishes a clean partial fill from a torn tail", () => {
+    const b = seg(0, [Buffer.from("aa")]);
+    // trailing bytes are already zero -> clean fill, not a tear
+    expect(scanSegment(b).tornTailBytes).toBe(0);
+  });
+
+  it("stops when a declared length overruns the file", () => {
+    const b = seg(0, [Buffer.from("aa")]);
+    b.writeUInt32LE(9_000_000, SEGMENT_HEADER_SIZE + 4);
+    expect(scanSegment(b).frames.length).toBe(0);
+  });
+});
diff --git a/test/qwp/sf/slotLock.test.ts b/test/qwp/sf/slotLock.test.ts
new file mode 100644
index 0000000..0f6ba6d
--- /dev/null
+++ b/test/qwp/sf/slotLock.test.ts
@@ -0,0 +1,89 @@
+import { describe, it, expect, afterEach } from "vitest";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  acquireSlot,
+  lockHolderLive,
+  releaseSlot,
+} from "../../../src/qwp/sf/slotLock";
+
+let dir: string | undefined;
+afterEach(() => {
+  if (dir) rmSync(dir, { recursive: true, force: true });
+  dir = undefined;
+});
+
+describe("slot lock", () => {
+  it("acquires an unheld slot", async () => {
+    dir = mkdtempSync(join(tmpdir(), "qwp-"));
+    const h = await acquireSlot(dir, "default");
+    expect(h).toBeTruthy();
+    await releaseSlot(h);
+  });
+
+  it("refuses a second holder and names sender_id in the error", async () => {
+    dir = mkdtempSync(join(tmpdir(), "qwp-"));
+    const h = await acquireSlot(dir, "default");
+    await expect(acquireSlot(dir, "default")).rejects.toThrow(/sender_id/);
+    await releaseSlot(h);
+  });
+
+  it("never steals a legacy lock from a live foreign process", async () => {
+    dir = mkdtempSync(join(tmpdir(), "qwp-"));
+    const slotDir = join(dir, "default");
+    mkdirSync(slotDir);
+    // Older clients wrote their own process-start timestamp as the second line.
+    // A different process therefore always sees a different value.
+    writeFileSync(join(slotDir, ".lock"), `${process.pid}\nforeign-start\n`);
+    expect(lockHolderLive(process.pid, "foreign-start")).toBe(true);
+    await expect(acquireSlot(dir, "default")).rejects.toThrow(/already in use/);
+  });
+
+  it("reclaims a lock from a dead pid", async () => {
+    dir = mkdtempSync(join(tmpdir(), "qwp-"));
+    const slotDir = join(dir, "default");
+    mkdirSync(slotDir);
+    writeFileSync(
+      join(slotDir, ".lock"),
+      "2147483647\nunknown\nunknown\nold\n",
+    );
+    const h = await acquireSlot(dir, "default");
+    expect(h).toBeTruthy();
+    await releaseSlot(h);
+  });
+
+  it("recovers an abandoned stale-takeover guard", async () => {
+    dir = mkdtempSync(join(tmpdir(), "qwp-"));
+    const slotDir = join(dir, "default");
+    mkdirSync(slotDir);
+    writeFileSync(
+      join(slotDir, ".lock"),
+      "2147483647\nunknown\nunknown\nold\n",
+    );
+    const takeover = join(slotDir, ".lock.takeover");
+    mkdirSync(takeover);
+    const old = new Date(Date.now() - 1000);
+    utimesSync(takeover, old, old);
+
+    const h = await acquireSlot(dir, "default");
+    expect(h).toBeTruthy();
+    await releaseSlot(h);
+  });
+
+  it("an old handle cannot release a replacement holder", async () => {
+    dir = mkdtempSync(join(tmpdir(), "qwp-"));
+    const old = await acquireSlot(dir, "default");
+    await releaseSlot(old);
+    const replacement = await acquireSlot(dir, "default");
+    await releaseSlot(old);
+    await expect(acquireSlot(dir, "default")).rejects.toThrow(/already in use/);
+    await releaseSlot(replacement);
+  });
+});
diff --git a/test/qwp/sf/symbolDictFile.test.ts b/test/qwp/sf/symbolDictFile.test.ts
new file mode 100644
index 0000000..4bd7217
--- /dev/null
+++ b/test/qwp/sf/symbolDictFile.test.ts
@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import {
+  encodeChunk,
+  decodeDictFile,
+  DICT_HEADER,
+} from "../../../src/qwp/sf/symbolDictFile";
+import { SymbolDict } from "../../../src/qwp/protocol/symbolDict";
+
+describe("persisted symbol dictionary", () => {
+  it("round-trips chunks in order", () => {
+    const file = Buffer.concat([
+      DICT_HEADER,
+      encodeChunk(["a", "b"]),
+      encodeChunk(["c"]),
+    ]);
+    expect(decodeDictFile(file)).toEqual(["a", "b", "c"]);
+  });
+
+  it("rejects a complete chunk with a bad CRC", () => {
+    const file = Buffer.concat([
+      DICT_HEADER,
+      encodeChunk(["a"]),
+      encodeChunk(["b"]),
+    ]);
+    file[file.length - 1] ^= 0xff;
+    expect(() => decodeDictFile(file)).toThrow(/CRC mismatch/i);
+  });
+
+  it("recovery preserves positional ids and does NOT de-duplicate", () => {
+    const file = Buffer.concat([DICT_HEADER, encodeChunk(["x", "x"])]);
+    const entries = decodeDictFile(file);
+    const dict = new SymbolDict();
+    for (const e of entries) dict.addRecovered(e);
+    expect(dict.size()).toBe(2); // collapsing would renumber every later symbol
+  });
+
+  it("rejects a bad magic", () => {
+    expect(() => decodeDictFile(Buffer.from("NOPE0000"))).toThrow(/magic/i);
+  });
+});
diff --git a/test/qwp/symbolDict.test.ts b/test/qwp/symbolDict.test.ts
new file mode 100644
index 0000000..bcc6b5e
--- /dev/null
+++ b/test/qwp/symbolDict.test.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { SymbolDict } from "../../src/qwp/protocol/symbolDict";
+import { MAX_SYMBOL_DICTIONARY_SIZE } from "../../src/qwp/protocol/constants";
+
+describe("SymbolDict", () => {
+  it("assigns dense ids from 0 and de-dupes on getOrAdd", () => {
+    const d = new SymbolDict();
+    expect(d.getOrAdd("a")).toBe(0);
+    expect(d.getOrAdd("b")).toBe(1);
+    expect(d.getOrAdd("a")).toBe(0);
+    expect(d.size()).toBe(2);
+  });
+
+  it("returns entries above a baseline", () => {
+    const d = new SymbolDict();
+    d.getOrAdd("a");
+    d.getOrAdd("b");
+    d.getOrAdd("c");
+    expect(d.entriesFrom(1)).toEqual(["b", "c"]);
+  });
+
+  it("addRecovered never de-duplicates", () => {
+    const d = new SymbolDict();
+    d.addRecovered("x");
+    d.addRecovered("x");
+    expect(d.size()).toBe(2); // positional ids must be preserved
+  });
+
+  it("enforces the dictionary cap at registration time", () => {
+    const d = new SymbolDict();
+    expect(MAX_SYMBOL_DICTIONARY_SIZE).toBe(1_000_000);
+    expect(() => d.checkCap(MAX_SYMBOL_DICTIONARY_SIZE)).toThrow(/dictionary/i);
+  });
+});
diff --git a/test/qwp/tableBuffer.test.ts b/test/qwp/tableBuffer.test.ts
new file mode 100644
index 0000000..1b9a789
--- /dev/null
+++ b/test/qwp/tableBuffer.test.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { QwpTableBuffer } from "../../src/qwp/protocol/tableBuffer";
+import { TYPE_LONG, TYPE_DOUBLE } from "../../src/qwp/protocol/constants";
+
+describe("QwpTableBuffer", () => {
+  it("back-fills nulls so all columns stay equal length", () => {
+    const t = new QwpTableBuffer("trades");
+    t.getOrCreateColumn("a", TYPE_LONG)!.values.push(1);
+    t.nextRow();
+    t.getOrCreateColumn("b", TYPE_DOUBLE)!.values.push(2.5);
+    t.nextRow();
+    expect(t.rowCount).toBe(2);
+    for (const c of t.columns) expect(c.size).toBe(2);
+    // "a" is null in row 1, "b" is null in row 0
+    expect(t.columns.find((c) => c.name === "a")!.nulls).toEqual([false, true]);
+    expect(t.columns.find((c) => c.name === "b")!.nulls).toEqual([true, false]);
+  });
+
+  it("locks a column's type on first sight", () => {
+    const t = new QwpTableBuffer("x");
+    t.getOrCreateColumn("c", TYPE_LONG);
+    expect(() => t.getOrCreateColumn("c", TYPE_DOUBLE)).toThrow(/type mismatch/i);
+  });
+
+  it("ignores a duplicate column within one row (first value wins)", () => {
+    const t = new QwpTableBuffer("x");
+    t.getOrCreateColumn("c", TYPE_LONG)!.values.push(1);
+    expect(t.getOrCreateColumn("c", TYPE_LONG)).toBeNull();
+  });
+
+  it("rejects an empty column name", () => {
+    const t = new QwpTableBuffer("x");
+    expect(() => t.getOrCreateColumn("", TYPE_LONG)).toThrow(/empty/i);
+  });
+});
diff --git a/test/qwp/transport.acks.test.ts b/test/qwp/transport.acks.test.ts
new file mode 100644
index 0000000..f2fffc3
--- /dev/null
+++ b/test/qwp/transport.acks.test.ts
@@ -0,0 +1,187 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { durableAckResponse, MockQwpServer, okResponse } from "./mockServer";
+import { QwpTransport } from "../../src/qwp/transport";
+import { SenderOptions } from "../../src/options";
+import { STATUS } from "../../src/qwp/protocol/response";
+import { Category, SenderError } from "../../src/qwp/errors";
+
+let mock: MockQwpServer | undefined;
+afterEach(async () => await mock?.stop());
+
+async function connected(opts = {}) {
+  mock = new MockQwpServer();
+  const port = await mock.start(opts);
+  const t = new QwpTransport(new SenderOptions(`ws::addr=127.0.0.1:${port};`));
+  await t.connect();
+  return t;
+}
+
+describe("QwpTransport ack handling", () => {
+  it("advances the acked FSN on OK", async () => {
+    const t = await connected();
+    await t.sendFrames([Buffer.from("QWP1----------")]);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(t.ackedFsn).toBe(0);
+    await t.close();
+  });
+
+  it("retains frames until durable table watermarks cover their OK", async () => {
+    mock = new MockQwpServer();
+    const port = await mock.start({
+      durableAck: true,
+      responseFor: (_idx, seq) => okResponse(seq, [["trades", 10n]]),
+    });
+    const t = new QwpTransport(
+      new SenderOptions(`ws::addr=127.0.0.1:${port};request_durable_ack=on;`),
+    );
+    await t.connect();
+    await t.sendFrames([Buffer.from("QWP1----------")]);
+    await new Promise((r) => setTimeout(r, 50));
+    expect(t.ackedFsn).toBe(-1);
+
+    mock.sendResponse(durableAckResponse([["trades", 9n]]));
+    await new Promise((r) => setTimeout(r, 25));
+    expect(t.ackedFsn).toBe(-1);
+    mock.sendResponse(durableAckResponse([["trades", 10n]]));
+    await new Promise((r) => setTimeout(r, 25));
+    expect(t.ackedFsn).toBe(0);
+    await t.close();
+  });
+
+  it("does not poison an unpublished FSN while waiting for durable ACK", async () => {
+    mock = new MockQwpServer();
+    const port = await mock.start({
+      durableAck: true,
+      responseFor: (_idx, seq) => okResponse(seq, [["trades", 10n]]),
+      // Twice accept at the OK level, then drop before durability. The third
+      // connection stays up so its durable watermark can retire the frame.
+      dropAfterResponseFor: (idx) => idx < 2,
+    });
+    const t = new QwpTransport(
+      new SenderOptions(
+        `ws::addr=127.0.0.1:${port};request_durable_ack=on;` +
+          `max_frame_rejections=2;poison_min_escalation_window_millis=0;`,
+      ),
+    );
+    const errors: SenderError[] = [];
+    t.onError((e) => errors.push(e));
+    await t.connect();
+    await t.sendFrames([Buffer.from("QWP1-durable--")]);
+
+    const replayDeadline = Date.now() + 3000;
+    while (mock.frames.length < 3 && Date.now() < replayDeadline) {
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(mock.frames.length).toBeGreaterThanOrEqual(3);
+    expect(errors.some((e) => e.category === Category.PROTOCOL_VIOLATION)).toBe(
+      false,
+    );
+    expect(t.ackedFsn).toBe(-1);
+
+    mock.sendResponse(durableAckResponse([["trades", 10n]]));
+    const ackDeadline = Date.now() + 1000;
+    while (t.ackedFsn < 0 && Date.now() < ackDeadline) {
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(t.ackedFsn).toBe(0);
+    await t.close();
+  });
+
+  it("latches a reconnect capability failure without an unhandled rejection", async () => {
+    mock = new MockQwpServer();
+    const port = await mock.start({
+      durableAckFor: (connection) => connection === 0,
+      dropAfter: 1,
+    });
+    const t = new QwpTransport(
+      new SenderOptions(`ws::addr=127.0.0.1:${port};request_durable_ack=on;`),
+    );
+    const errors: SenderError[] = [];
+    t.onError((e) => errors.push(e));
+    await t.connect();
+    await t.sendFrames([Buffer.from("QWP1-reconnect-")]).catch(() => undefined);
+
+    const deadline = Date.now() + 2000;
+    while (errors.length === 0 && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(errors[0].policy).toBe("TERMINAL");
+    await expect(t.sendFrames([Buffer.from("QWP1-after----")])).rejects.toBe(
+      errors[0],
+    );
+    await t.close();
+  });
+
+  it("latches a terminal NACK and never trims through it", async () => {
+    const errors: SenderError[] = [];
+    const t = await connected({
+      statusFor: (idx: number) => (idx === 0 ? STATUS.PARSE_ERROR : STATUS.OK),
+    });
+    t.onError((e) => errors.push(e));
+    await t
+      .sendFrames([
+        Buffer.from("QWP1-first----"),
+        Buffer.from("QWP1-second---"),
+      ])
+      .catch(() => undefined);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(errors[0].category).toBe(Category.PARSE_ERROR);
+    expect(t.ackedFsn).toBe(-1);
+    await expect(t.sendFrames([Buffer.from("QWP1-third----")])).rejects.toBe(
+      errors[0],
+    );
+    await t.close();
+  });
+
+  it("reconnects and replays a retriable NACK", async () => {
+    const payload = Buffer.from("QWP1-retry----");
+    const t = await connected({
+      statusFor: (idx: number) => (idx === 0 ? STATUS.WRITE_ERROR : STATUS.OK),
+    });
+    await t.sendFrames([payload]).catch(() => undefined);
+    await new Promise((r) => setTimeout(r, 300));
+    expect(
+      mock!.frames.filter((f) => f.equals(payload)).length,
+    ).toBeGreaterThanOrEqual(2);
+    expect(t.ackedFsn).toBe(0);
+    await t.close();
+  });
+
+  it("rotates/reconnects and replays a RETRIABLE_OTHER NACK", async () => {
+    const payload = Buffer.from("QWP1-other----");
+    const t = await connected({
+      statusFor: (idx: number) => (idx === 0 ? STATUS.NOT_WRITABLE : STATUS.OK),
+    });
+    await t.sendFrames([payload]).catch(() => undefined);
+    await new Promise((r) => setTimeout(r, 300));
+    expect(
+      mock!.frames.filter((f) => f.equals(payload)).length,
+    ).toBeGreaterThanOrEqual(2);
+    expect(t.ackedFsn).toBe(0);
+    await t.close();
+  });
+
+  it("reports a terminal category on a deterministic NACK", async () => {
+    const errors: SenderError[] = [];
+    const t = await connected({ statusFor: () => STATUS.PARSE_ERROR });
+    t.onError((e) => errors.push(e));
+    await t.sendFrames([Buffer.from("QWP1----------")]);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(errors[0].category).toBe(Category.PARSE_ERROR);
+    await t.close();
+  });
+
+  it("replays the frame instead of reporting loss when the connection drops", async () => {
+    const errors: SenderError[] = [];
+    const t = await connected({ dropAfter: 1 });
+    t.onError((e) => errors.push(e));
+    const payload = Buffer.from("QWP1----------");
+    await t.sendFrames([payload]);
+    await new Promise((r) => setTimeout(r, 300));
+    // Retention replaces in-flight-loss: no DATA_LOSS, and the frame is replayed.
+    expect(errors.some((e) => e.category === Category.DATA_LOSS)).toBe(false);
+    const matching = mock!.frames.filter((f) => f.equals(payload));
+    expect(matching.length).toBeGreaterThanOrEqual(2);
+    await t.close();
+  });
+});
diff --git a/test/qwp/transport.reconnect.test.ts b/test/qwp/transport.reconnect.test.ts
new file mode 100644
index 0000000..17b8aea
--- /dev/null
+++ b/test/qwp/transport.reconnect.test.ts
@@ -0,0 +1,57 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { MockQwpServer } from "./mockServer";
+import { QwpTransport } from "../../src/qwp/transport";
+import { SenderOptions } from "../../src/options";
+
+let mocks: MockQwpServer[] = [];
+afterEach(async () => {
+  for (const m of mocks) await m.stop();
+  mocks = [];
+});
+
+describe("reconnect and rotation", () => {
+  it("rotates to the second endpoint when the first refuses the upgrade with 421", async () => {
+    const bad = new MockQwpServer();
+    const good = new MockQwpServer();
+    mocks.push(bad, good);
+    const badPort = await bad.start({
+      upgradeStatus: 421,
+      upgradeHeaders: "X-QuestDB-Role: replica\r\n",
+    });
+    const goodPort = await good.start();
+
+    const t = new QwpTransport(
+      new SenderOptions(`ws::addr=127.0.0.1:${badPort},127.0.0.1:${goodPort};`),
+    );
+    await t.connect();
+    expect(t.connectedEndpoint!.port).toBe(goodPort);
+    await t.close();
+  });
+
+  it("fails terminally on 401 without rotating", async () => {
+    const a = new MockQwpServer();
+    mocks.push(a);
+    const port = await a.start({ upgradeStatus: 401 });
+    const t = new QwpTransport(new SenderOptions(`ws::addr=127.0.0.1:${port};`));
+    await expect(t.connect()).rejects.toThrow(/authentication/i);
+  });
+
+  it("sends a dictionary catch-up frame before data after reconnect", async () => {
+    const s = new MockQwpServer();
+    mocks.push(s);
+    const port = await s.start();
+    const t = new QwpTransport(new SenderOptions(`ws::addr=127.0.0.1:${port};`));
+    await t.connect();
+    t.registerSymbolForTest("alpha");
+    await t.reconnectForTest();
+    // The catch-up frame is written to the kernel asynchronously; it lands on
+    // the server a tick later, so poll rather than assert synchronously.
+    for (let i = 0; i < 50 && s.frames.length === 0; i++) {
+      await new Promise((r) => setTimeout(r, 10));
+    }
+    // First frame after reconnect must carry the dictionary from id 0.
+    const first = s.frames[0];
+    expect(first.subarray(0, 4).toString("ascii")).toBe("QWP1");
+    await t.close();
+  });
+});
diff --git a/test/qwp/transport.test.ts b/test/qwp/transport.test.ts
new file mode 100644
index 0000000..25c1730
--- /dev/null
+++ b/test/qwp/transport.test.ts
@@ -0,0 +1,169 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { QwpTransport } from "../../src/qwp/transport";
+import { QwpBuffer } from "../../src/qwp/buffer";
+import { FLAG_DELTA_SYMBOL_DICT } from "../../src/qwp/protocol/constants";
+import { readVarint } from "../../src/qwp/protocol/varint";
+import { SenderOptions } from "../../src/options";
+import { SenderError, Category, Policy } from "../../src/qwp/errors";
+import { STATUS } from "../../src/qwp/protocol/response";
+import { MockQwpServer } from "./mockServer";
+
+let mocks: MockQwpServer[] = [];
+afterEach(async () => {
+  for (const m of mocks) await m.stop();
+  mocks = [];
+});
+
+describe("QwpTransport", () => {
+  it("uses the QWP auto-flush row default, not the ILP one", () => {
+    const t = new QwpTransport(new SenderOptions("ws::addr=localhost:9000;"));
+    expect(t.getDefaultAutoFlushRows()).toBe(1000);
+  });
+
+  it("uses the QWP auto-flush INTERVAL default (100 ms), not the ILP 1000 ms (spec 9.1)", () => {
+    const t = new QwpTransport(new SenderOptions("ws::addr=localhost:9000;"));
+    expect(t.getDefaultAutoFlushInterval()).toBe(100);
+  });
+
+  it("applies the 128 MiB memory retention default without sf_dir and 10 GiB with it (spec 9.1)", () => {
+    const mem = new QwpTransport(new SenderOptions("ws::addr=localhost:9000;"));
+    expect(mem.engineMaxTotalBytes).toBe(128 * 1024 * 1024);
+    const disk = new QwpTransport(new SenderOptions("ws::addr=localhost:9000;sf_dir=/tmp/x;"));
+    expect(disk.engineMaxTotalBytes).toBe(10 * 1024 * 1024 * 1024);
+  });
+
+  it("an explicit sf_max_total_bytes overrides either mode default", () => {
+    const t = new QwpTransport(
+      new SenderOptions("ws::addr=localhost:9000;sf_dir=/tmp/x;sf_max_total_bytes=1048576;"),
+    );
+    expect(t.engineMaxTotalBytes).toBe(1024 * 1024);
+  });
+
+  it("refuses to send before connect", async () => {
+    const t = new QwpTransport(new SenderOptions("ws::addr=localhost:9000;"));
+    await expect(t.send(Buffer.from([1]))).rejects.toThrow(/not connected/i);
+  });
+
+  it("an explicit connect() joins an in-flight connect instead of double-opening the slot", async () => {
+    const s = new MockQwpServer();
+    mocks.push(s);
+    const port = await s.start();
+    const dir = mkdtempSync(join(tmpdir(), "qwp-cc-"));
+    try {
+      const t = new QwpTransport(
+        new SenderOptions(`ws::addr=127.0.0.1:${port};sf_dir=${dir};`),
+      );
+      // Two concurrent connects must share one engine open: a second open would
+      // trip the slot lock and reject (spec 4.3 / shortened C4).
+      const [a, b] = await Promise.all([t.connect(), t.connect()]);
+      expect(a).toBe(true);
+      expect(b).toBe(true);
+      await t.close();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("connect() after an established connection returns without reopening", async () => {
+    const s = new MockQwpServer();
+    mocks.push(s);
+    const port = await s.start();
+    const t = new QwpTransport(new SenderOptions(`ws::addr=127.0.0.1:${port};`));
+    expect(await t.connect()).toBe(true);
+    expect(await t.connect()).toBe(true);
+    await t.close();
+  });
+
+  it("request_durable_ack=on fails fast on a server that cannot confirm it (spec 6.5.1)", async () => {
+    const s = new MockQwpServer();
+    mocks.push(s);
+    const port = await s.start(); // no X-QWP-Durable-Ack: enabled echo
+    const t = new QwpTransport(
+      new SenderOptions(`ws::addr=127.0.0.1:${port};request_durable_ack=on;`),
+    );
+    await expect(t.connect()).rejects.toThrow(/durable.*ack/i);
+  });
+
+  it("request_durable_ack=on connects when the server confirms durable acks", async () => {
+    const s = new MockQwpServer();
+    mocks.push(s);
+    const port = await s.start({ durableAck: true });
+    const t = new QwpTransport(
+      new SenderOptions(`ws::addr=127.0.0.1:${port};request_durable_ack=on;`),
+    );
+    expect(await t.connect()).toBe(true);
+    await t.close();
+  });
+
+  it("delta mode wires buffer->transport and advances the baseline on publish (spec 5.2, 8.1.6)", async () => {
+    const s = new MockQwpServer();
+    mocks.push(s);
+    const port = await s.start();
+    const t = new QwpTransport(new SenderOptions(`ws::addr=127.0.0.1:${port};`));
+    const b = new QwpBuffer();
+    t.attachSymbolBuffer(b);
+    await t.connect();
+
+    // First batch introduces alpha; the emitted frame must carry a delta flag.
+    b.table("t").symbol("s", "alpha").intColumn("x", 1);
+    b.at(1n, "us");
+    await t.sendFrames(b.sealFrames(1 << 20));
+    await new Promise((r) => setTimeout(r, 100));
+    expect(s.frames[0].readUInt8(5) & FLAG_DELTA_SYMBOL_DICT).toBe(FLAG_DELTA_SYMBOL_DICT);
+
+    // Second batch reuses confirmed alpha and introduces only beta, so its
+    // delta must begin at id 1 (baseline 0) and carry exactly one entry.
+    b.table("t").symbol("s", "beta").intColumn("x", 2);
+    b.at(2n, "us");
+    await t.sendFrames(b.sealFrames(1 << 20));
+    await new Promise((r) => setTimeout(r, 100));
+    const start = readVarint(s.frames[1], 12);
+    const count = readVarint(s.frames[1], start.offset);
+    expect(start.value).toBe(1);
+    expect(count.value).toBe(1);
+    await t.close();
+  });
+
+  it("escalates a repeatedly rejected frame to a terminal PROTOCOL_VIOLATION (spec 7.4)", async () => {
+    const s = new MockQwpServer();
+    mocks.push(s);
+    // Drop the connection after every frame so the unacked frame is re-sent on
+    // each reconnect; each non-orderly close after a send counts a strike, and
+    // with a 0 dwell window the strike threshold latches terminal.
+    const port = await s.start({ dropAfter: 1 });
+    const t = new QwpTransport(
+      new SenderOptions(
+        `ws::addr=127.0.0.1:${port};max_frame_rejections=3;poison_min_escalation_window_millis=0;`,
+      ),
+    );
+    const errors: SenderError[] = [];
+    t.onError((e) => errors.push(e));
+    await t.connect();
+
+    const b = new QwpBuffer();
+    t.attachSymbolBuffer(b);
+    b.table("t").symbol("s", "a").intColumn("x", 1);
+    b.at(1n, "us");
+    await t.sendFrames(b.sealFrames(1 << 20));
+
+    // Give the reconnect/replay cycles time to accrue strikes (3) and latch.
+    const deadline = Date.now() + 3000;
+    while (Date.now() < deadline) {
+      const escalated = errors.find((e) => e.category === Category.PROTOCOL_VIOLATION);
+      if (escalated) {
+        expect(escalated.policy).toBe(Policy.TERMINAL);
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(
+      errors.some((e) => e.category === Category.PROTOCOL_VIOLATION && e.policy === Policy.TERMINAL),
+    ).toBe(true);
+    // The transport is now terminal: further sends must throw, not reconnect.
+    await expect(t.send(Buffer.alloc(8))).rejects.toThrow(/poisoned/i);
+    await t.close();
+  });
+});
diff --git a/test/qwp/varint.test.ts b/test/qwp/varint.test.ts
new file mode 100644
index 0000000..a40afbf
--- /dev/null
+++ b/test/qwp/varint.test.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { writeVarint, varintSize, readVarint } from "../../src/qwp/protocol/varint";
+
+describe("varint (unsigned LEB128)", () => {
+  it("encodes single-byte values", () => {
+    const b = Buffer.alloc(4);
+    expect(writeVarint(b, 0, 0)).toBe(1);
+    expect(b[0]).toBe(0x00);
+    expect(writeVarint(b, 0, 127)).toBe(1);
+    expect(b[0]).toBe(0x7f);
+  });
+
+  it("encodes multi-byte values with the continuation bit", () => {
+    const b = Buffer.alloc(4);
+    const end = writeVarint(b, 0, 128);
+    expect(end).toBe(2);
+    expect(b[0]).toBe(0x80);
+    expect(b[1]).toBe(0x01);
+  });
+
+  it("round-trips a range of values", () => {
+    for (const v of [0, 1, 127, 128, 300, 16383, 16384, 1_000_000]) {
+      const b = Buffer.alloc(10);
+      const end = writeVarint(b, 0, v);
+      expect(end).toBe(varintSize(v));
+      expect(readVarint(b, 0)).toEqual({ value: v, offset: end });
+    }
+  });
+});
diff --git a/test/qwp/ws.frame.test.ts b/test/qwp/ws.frame.test.ts
new file mode 100644
index 0000000..5cccd1e
--- /dev/null
+++ b/test/qwp/ws.frame.test.ts
@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest";
+import { encodeClientFrame, FrameParser, OPCODE } from "../../src/qwp/ws/frame";
+
+/** Server->client frames are never masked (RFC 6455). */
+function serverFrame(opcode: number, payload: Buffer, fin = true): Buffer {
+  const head: number[] = [(fin ? 0x80 : 0) | opcode];
+  if (payload.length < 126) head.push(payload.length);
+  else if (payload.length < 65536) head.push(126, payload.length >>> 8, payload.length & 0xff);
+  else throw new Error("test helper: use a small payload");
+  return Buffer.concat([Buffer.from(head), payload]);
+}
+
+describe("ws frame codec", () => {
+  it("encodes a masked client binary frame", () => {
+    const f = encodeClientFrame(OPCODE.BINARY, Buffer.from([1, 2, 3]));
+    expect(f[0]).toBe(0x82); // FIN + binary
+    expect(f[1] & 0x80).toBe(0x80); // mask bit set
+    expect(f[1] & 0x7f).toBe(3);
+    expect(f.length).toBe(2 + 4 + 3);
+  });
+
+  it("uses the 64-bit length form above 65535", () => {
+    const f = encodeClientFrame(OPCODE.BINARY, Buffer.alloc(70000));
+    expect(f[1] & 0x7f).toBe(127);
+    expect(Number(f.readBigUInt64BE(2))).toBe(70000);
+  });
+
+  it("parses a frame split across chunks", () => {
+    const whole = serverFrame(OPCODE.BINARY, Buffer.from("abcd"));
+    const p = new FrameParser();
+    p.push(whole.subarray(0, 3));
+    expect(p.next()).toBeNull();
+    p.push(whole.subarray(3));
+    expect(p.next()!.payload.toString()).toBe("abcd");
+  });
+
+  it("defragments continuation frames", () => {
+    const p = new FrameParser();
+    p.push(serverFrame(OPCODE.BINARY, Buffer.from("ab"), false));
+    expect(p.next()).toBeNull();
+    p.push(serverFrame(OPCODE.CONT, Buffer.from("cd"), true));
+    const msg = p.next()!;
+    expect(msg.opcode).toBe(OPCODE.BINARY);
+    expect(msg.payload.toString()).toBe("abcd");
+  });
+
+  it("rejects a masked inbound frame", () => {
+    const f = serverFrame(OPCODE.BINARY, Buffer.from("x"));
+    f[1] |= 0x80; // claim masked
+    const p = new FrameParser();
+    p.push(f);
+    expect(() => p.next()).toThrow(/masked/i);
+  });
+
+  it("rejects non-zero RSV bits", () => {
+    const f = serverFrame(OPCODE.BINARY, Buffer.from("x"));
+    f[0] |= 0x40;
+    const p = new FrameParser();
+    p.push(f);
+    expect(() => p.next()).toThrow(/rsv/i);
+  });
+
+  it("rejects an oversized control frame", () => {
+    const f = serverFrame(OPCODE.PING, Buffer.alloc(126));
+    const p = new FrameParser();
+    p.push(f);
+    expect(() => p.next()).toThrow(/control frame/i);
+  });
+});
diff --git a/test/qwp/ws.handshake.test.ts b/test/qwp/ws.handshake.test.ts
new file mode 100644
index 0000000..d6c1ba2
--- /dev/null
+++ b/test/qwp/ws.handshake.test.ts
@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildUpgradeRequest,
+  computeAccept,
+  parseUpgradeResponse,
+  QwpUpgradeError,
+} from "../../src/qwp/ws/handshake";
+
+describe("qwp handshake", () => {
+  it("computes Sec-WebSocket-Accept per RFC 6455", () => {
+    // The canonical example from RFC 6455 §1.3.
+    expect(computeAccept("dGhlIHNhbXBsZSBub25jZQ==")).toBe("s3pPLMBiTxaQ9kYGzzhZRbK+xOo=");
+  });
+
+  it("builds an upgrade request with the QWP headers", () => {
+    const { request } = buildUpgradeRequest({ host: "h", port: 9000, clientId: "nodejs/1.0.0" });
+    const s = request.toString("ascii");
+    expect(s).toMatch(/^GET \/write\/v4 HTTP\/1\.1\r\n/);
+    expect(s).toMatch(/\r\nUpgrade: websocket\r\n/);
+    expect(s).toMatch(/\r\nSec-WebSocket-Version: 13\r\n/);
+    expect(s).toMatch(/\r\nX-QWP-Max-Version: 1\r\n/);
+    expect(s).toMatch(/\r\nX-QWP-Client-Id: nodejs\/1\.0\.0\r\n/);
+    expect(s.endsWith("\r\n\r\n")).toBe(true);
+  });
+
+  it("requests durable acks via X-QWP-Request-Durable-Ack when opted in (spec 6.5.1)", () => {
+    const off = buildUpgradeRequest({ host: "h", port: 9000, clientId: "c" }).request
+      .toString("ascii");
+    expect(off).not.toMatch(/X-QWP-Request-Durable-Ack/);
+    const on = buildUpgradeRequest({
+      host: "h",
+      port: 9000,
+      clientId: "c",
+      requestDurableAck: true,
+    }).request.toString("ascii");
+    expect(on).toMatch(/\r\nX-QWP-Request-Durable-Ack: true\r\n/);
+  });
+
+  it("reads the X-QWP-Durable-Ack confirmation from the 101", () => {
+    const raw = Buffer.from(
+      "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" +
+        "Connection: Upgrade\r\nSec-WebSocket-Accept: abc\r\n" +
+        "X-QWP-Version: 1\r\nX-QWP-Durable-Ack: enabled\r\n\r\n",
+      "ascii",
+    );
+    expect(parseUpgradeResponse(raw).durableAck).toBe("enabled");
+    const rawOff = Buffer.from(
+      "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" +
+        "Connection: Upgrade\r\nSec-WebSocket-Accept: abc\r\n\r\n",
+      "ascii",
+    );
+    expect(parseUpgradeResponse(rawOff).durableAck).toBeUndefined();
+  });
+
+  it("classifies 421 with a role header as a retriable role reject", () => {
+    const raw = Buffer.from(
+      "HTTP/1.1 421 Misdirected Request\r\nX-QuestDB-Role: replica\r\n\r\n",
+      "ascii",
+    );
+    try {
+      parseUpgradeResponse(raw);
+      throw new Error("expected throw");
+    } catch (e) {
+      expect(e).toBeInstanceOf(QwpUpgradeError);
+      expect((e as QwpUpgradeError).kind).toBe("role-reject");
+      expect((e as QwpUpgradeError).retriable).toBe(true);
+    }
+  });
+
+  it("classifies 401 as a terminal auth failure", () => {
+    const raw = Buffer.from("HTTP/1.1 401 Unauthorized\r\n\r\n", "ascii");
+    try {
+      parseUpgradeResponse(raw);
+      throw new Error("expected throw");
+    } catch (e) {
+      expect((e as QwpUpgradeError).kind).toBe("auth");
+      expect((e as QwpUpgradeError).retriable).toBe(false);
+    }
+  });
+
+  it("leaves 404 unclassified", () => {
+    const raw = Buffer.from("HTTP/1.1 404 Not Found\r\n\r\n", "ascii");
+    try {
+      parseUpgradeResponse(raw);
+      throw new Error("expected throw");
+    } catch (e) {
+      expect((e as QwpUpgradeError).kind).toBe("other");
+    }
+  });
+
+  it("returns negotiated headers on 101", () => {
+    const raw = Buffer.from(
+      "HTTP/1.1 101 Switching Protocols\r\n" +
+        "Upgrade: websocket\r\nConnection: Upgrade\r\n" +
+        "Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=\r\n" +
+        "X-QWP-Version: 1\r\nX-QWP-Max-Batch-Size: 1048576\r\n\r\n",
+      "ascii",
+    );
+    const r = parseUpgradeResponse(raw);
+    expect(r.accept).toBe("s3pPLMBiTxaQ9kYGzzhZRbK+xOo=");
+    expect(r.qwpVersion).toBe(1);
+    expect(r.maxBatchSize).toBe(1048576);
+  });
+});
diff --git a/test/qwp/ws.mask.test.ts b/test/qwp/ws.mask.test.ts
new file mode 100644
index 0000000..db639b0
--- /dev/null
+++ b/test/qwp/ws.mask.test.ts
@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { newMaskKey, applyMask } from "../../src/qwp/ws/mask";
+
+describe("ws masking", () => {
+  it("produces a fresh 4-byte key per call", () => {
+    const a = newMaskKey();
+    const b = newMaskKey();
+    expect(a.length).toBe(4);
+    // Not a strong randomness test; catches a constant/seeded-once key.
+    const keys = new Set([a.toString("hex"), b.toString("hex")]);
+    for (let i = 0; i < 20; i++) keys.add(newMaskKey().toString("hex"));
+    expect(keys.size).toBeGreaterThan(1);
+  });
+
+  it("is its own inverse", () => {
+    const key = Buffer.from([1, 2, 3, 4]);
+    const original = Buffer.from("hello websocket", "utf8");
+    const payload = Buffer.from(original);
+    applyMask(payload, key);
+    expect(payload.equals(original)).toBe(false);
+    applyMask(payload, key);
+    expect(payload.equals(original)).toBe(true);
+  });
+});
diff --git a/test/qwp/ws.socket.test.ts b/test/qwp/ws.socket.test.ts
new file mode 100644
index 0000000..5ba586a
--- /dev/null
+++ b/test/qwp/ws.socket.test.ts
@@ -0,0 +1,208 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { AddressInfo } from "node:net";
+import { createServer, Server, Socket } from "node:net";
+import { createHash } from "node:crypto";
+import { QwpWebSocket } from "../../src/qwp/ws/socket";
+import { encodeClientFrame, OPCODE } from "../../src/qwp/ws/frame";
+
+let server: Server | undefined;
+afterEach(() => server?.close());
+
+/**
+ * Decodes client->server frames, which RFC 6455 requires to be MASKED.
+ * (The client-side FrameParser deliberately rejects masked frames, so it can't
+ * be reused here — a real server must unmask client frames.)
+ */
+function maskedFrameDecoder() {
+  let buf = Buffer.alloc(0);
+  return function decode(chunk: Buffer): { opcode: number; payload: Buffer }[] {
+    buf = Buffer.concat([buf, chunk]);
+    const out: { opcode: number; payload: Buffer }[] = [];
+    for (;;) {
+      if (buf.length < 2) break;
+      const b0 = buf[0];
+      const b1 = buf[1];
+      const opcode = b0 & 0x0f;
+      let len = b1 & 0x7f;
+      let off = 2;
+      if (len === 126) {
+        if (buf.length < 4) break;
+        len = buf.readUInt16BE(2);
+        off = 4;
+      } else if (len === 127) {
+        if (buf.length < 10) break;
+        len = Number(buf.readBigUInt64BE(2));
+        off = 10;
+      }
+      const masked = (b1 & 0x80) !== 0;
+      const keyLen = masked ? 4 : 0;
+      if (buf.length < off + keyLen + len) break;
+      const key = buf.subarray(off, off + keyLen);
+      const payload = Buffer.from(
+        buf.subarray(off + keyLen, off + keyLen + len),
+      );
+      for (let i = 0; i < payload.length; i++) payload[i] ^= key[i & 3];
+      buf = buf.subarray(off + keyLen + len);
+      out.push({ opcode, payload });
+    }
+    return out;
+  };
+}
+
+function serverBinaryFrame(payload: Buffer): Buffer {
+  if (payload.length >= 126) throw new Error("test payload is too large");
+  return Buffer.concat([Buffer.from([0x82, payload.length]), payload]);
+}
+
+/** Minimal QWP-ish websocket server: completes the upgrade, echoes nothing. */
+function startServer(
+  onBinary: (b: Buffer) => void,
+  afterHandshake?: (socket: Socket) => void,
+  handshakeSuffix?: Buffer,
+): Promise<number> {
+  return new Promise((resolve) => {
+    server = createServer((sock) => {
+      let handshaken = false;
+      const decode = maskedFrameDecoder();
+      sock.on("data", (chunk) => {
+        if (!handshaken) {
+          const text = chunk.toString("ascii");
+          const key = /Sec-WebSocket-Key: (.+)\r\n/.exec(text)![1];
+          const accept = createHash("sha1")
+            .update(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", "ascii")
+            .digest("base64");
+          const response = Buffer.from(
+            "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" +
+              `Connection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n` +
+              "X-QWP-Version: 1\r\nX-QWP-Max-Batch-Size: 1048576\r\n\r\n",
+            "ascii",
+          );
+          sock.write(
+            handshakeSuffix
+              ? Buffer.concat([response, handshakeSuffix])
+              : response,
+          );
+          handshaken = true;
+          if (afterHandshake) setTimeout(() => afterHandshake(sock), 10);
+          return;
+        }
+        for (const m of decode(chunk)) {
+          if (m.opcode === OPCODE.BINARY) onBinary(m.payload);
+          if (m.opcode === OPCODE.PING)
+            sock.write(encodeClientFrame(OPCODE.PONG, m.payload));
+        }
+      });
+    });
+    server.listen(0, "127.0.0.1", () =>
+      resolve((server!.address() as AddressInfo).port),
+    );
+  });
+}
+
+describe("QwpWebSocket", () => {
+  it("connects, negotiates, and sends a binary frame", async () => {
+    const received: Buffer[] = [];
+    const port = await startServer((b) => received.push(b));
+    const ws = await QwpWebSocket.connect({
+      host: "127.0.0.1",
+      port,
+      tls: false,
+      clientId: "nodejs/1.0.0",
+    });
+    expect(ws.maxBatchSize).toBe(1048576);
+    await ws.sendBinary(Buffer.from("payload"));
+    await new Promise((r) => setTimeout(r, 50));
+    expect(received.length).toBe(1);
+    expect(received[0].toString()).toBe("payload");
+    await ws.close();
+  });
+
+  it("dispatches coalesced handshake leftovers only after connect resolves", async () => {
+    const payload = Buffer.from("early-response");
+    let connectResolved = false;
+    let callbackAfterResolve = false;
+    const port = await startServer(
+      () => undefined,
+      undefined,
+      serverBinaryFrame(payload),
+    );
+    const ws = await QwpWebSocket.connect({
+      host: "127.0.0.1",
+      port,
+      tls: false,
+      clientId: "x",
+      onBinary: (received) => {
+        callbackAfterResolve = connectResolved && received.equals(payload);
+      },
+    });
+    connectResolved = true;
+    await new Promise((r) => setImmediate(r));
+    expect(callbackAfterResolve).toBe(true);
+    await ws.close();
+  });
+
+  it("turns malformed inbound framing into one abrupt close", async () => {
+    const closes: { orderly: boolean; framesSent: number }[] = [];
+    const port = await startServer(
+      () => undefined,
+      (sock) => sock.write(Buffer.from([0x82, 0x80])), // masked server frame
+    );
+    const ws = await QwpWebSocket.connect({
+      host: "127.0.0.1",
+      port,
+      tls: false,
+      clientId: "x",
+      onClose: (info) => closes.push(info),
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(closes).toEqual([{ orderly: false, framesSent: 0 }]);
+    await ws.close();
+  });
+
+  it("contains an exception thrown by the binary response callback", async () => {
+    const closes: { orderly: boolean; framesSent: number }[] = [];
+    const payload = Buffer.from("bad-qwp-response");
+    const frame = serverBinaryFrame(payload);
+    const port = await startServer(
+      () => undefined,
+      (sock) => sock.write(frame),
+    );
+    const ws = await QwpWebSocket.connect({
+      host: "127.0.0.1",
+      port,
+      tls: false,
+      clientId: "x",
+      onBinary: () => {
+        throw new Error("decoder rejected payload");
+      },
+      onClose: (info) => closes.push(info),
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    expect(closes).toEqual([{ orderly: false, framesSent: 0 }]);
+    await ws.close();
+  });
+
+  it("rejects a bad Sec-WebSocket-Accept", async () => {
+    server = createServer((sock) => {
+      sock.on("data", () =>
+        sock.write(
+          "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" +
+            "Connection: Upgrade\r\nSec-WebSocket-Accept: wrong\r\n\r\n",
+        ),
+      );
+    });
+    const port: number = await new Promise((r) =>
+      server!.listen(0, "127.0.0.1", () =>
+        r((server!.address() as AddressInfo).port),
+      ),
+    );
+    await expect(
+      QwpWebSocket.connect({
+        host: "127.0.0.1",
+        port,
+        tls: false,
+        clientId: "x",
+      }),
+    ).rejects.toThrow(/accept/i);
+  });
+});
diff --git a/tsconfig.bench.json b/tsconfig.bench.json
new file mode 100644
index 0000000..afb2747
--- /dev/null
+++ b/tsconfig.bench.json
@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    // Importing `vitest` pulls in vite's importGlob types that reference DOM
+    // globals (WebWorker etc.), which the es-only base lib does not define.
+    // Those are declaration-file errors in a vendored .d.ts, so skipLibCheck
+    // suppresses them without widening src's lib (which would break undici's
+    // extended RequestInit in src/utils.ts). Benchmark source itself is still
+    // fully type-checked. The base config sets no `strict`; do not raise it
+    // here — that is a repo-wide decision (see plan Task 3).
+    "skipLibCheck": true
+  },
+  "include": ["src", "benchmarks"]
+}
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..1a414e5
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    // Keep `pnpm test` fast: unit tests and the benchmark validation
+    // assertions, but never the benchmarks themselves.
+    include: ["test/**/*.test.ts", "benchmarks/**/*.test.ts"],
+    // `benchmark` nests UNDER `test` — a top-level key is silently ignored
+    // and `vitest bench` then picks up its default globs instead.
+    benchmark: {
+      include: ["benchmarks/**/*.bench.ts"],
+    },
+  },
+});