diff --git a/‎.changeset/20106-reclaim-space-full-freelist.md‎
Lines changed: 19 additions & 0 deletions b/‎.changeset/20106-reclaim-space-full-freelist.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎packages/drivers/driver-sql/src/sql-driver-sqlite-reclaim-space.test.ts‎
Lines changed: 126 additions & 0 deletions b/‎packages/drivers/driver-sql/src/sql-driver-sqlite-reclaim-space.test.ts‎
Lines changed: 126 additions & 0 deletions
diff --git a/‎packages/drivers/driver-sql/src/sql-driver.ts‎
Lines changed: 30 additions & 5 deletions b/‎packages/drivers/driver-sql/src/sql-driver.ts‎
Lines changed: 30 additions & 5 deletions
diff --git a/‎packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-reclaim-space.test.ts‎
Lines changed: 92 additions & 0 deletions b/‎packages/drivers/driver-sqlite-wasm/src/sqlite-wasm-reclaim-space.test.ts‎
Lines changed: 92 additions & 0 deletions
diff --git a/‎packages/drivers/driver-turso/README.md‎
Lines changed: 7 additions & 5 deletions b/‎packages/drivers/driver-turso/README.md‎
Lines changed: 7 additions & 5 deletions
diff --git a/‎packages/drivers/driver-turso/src/turso-driver.ts‎
Lines changed: 31 additions & 6 deletions b/‎packages/drivers/driver-turso/src/turso-driver.ts‎
Lines changed: 31 additions & 6 deletions
@@ -0,0 +1,19 @@
+---
+'@objectstack/driver-sql': patch
+'@objectstack/driver-turso': patch
+---
+
+fix(driver-sql, driver-turso): `reclaimSpace()` returns the whole SQLite freelist, not one page per call (#20106)
+
+Clause-②: no
+
+`reclaimSpace()` is what the lifecycle service calls after every sweep that deleted rows (ADR-0057 §3.4). On SQLite it runs `PRAGMA incremental_vacuum`, and that statement frees one page per step. Two clients stepped it once:
+
+- **`SqlDriver` on better-sqlite3, and `TursoDriver` in local mode.** knex's better-sqlite3 client runs a statement that declares no result columns with `Statement.run()`, which steps it once. A database with 300 free pages had 299 after the call, read from a second connection, and the file barely shrank. `incremental_vacuum(N)` freed one page too. The method now drives that binding through its own `exec()`, which steps the statement until SQLite reports done: 300 → 0, and the file shrinks by those pages.
+- **`TursoDriver` in remote mode.** The libSQL client's `execute()` stepped the statement once and left it unfinished. Over a libSQL `file:` client, the issuing connection read one page fewer, but a second connection read the freelist and the file size unchanged, and a row written after the call on the same connection never reached the file. The remote route now reads `PRAGMA freelist_count`, sends nothing more when it is `0`, and otherwise runs the vacuum through the client's `executeMultiple()`: 300 → 0 from a second connection, and the later write lands. A server that refuses either statement answers `DATABASE_ERROR` / 500, as before. What a hosted libSQL server does with either call is not measured.
+
+`SqliteWasmDriver` was already complete: its dialect steps every PRAGMA to the end (300 → 0 before and after this change).
+
+On a file-backed database in WAL mode (the default) the database file shrinks once a checkpoint runs, and during the call the freed pages pass through the `-wal` file, which keeps its size until the last connection closes.
+
+Nothing to migrate: `reclaimSpace()` keeps its signature, and a database whose `auto_vacuum` mode is not `INCREMENTAL` still reclaims nothing, as before.
@@ -0,0 +1,126 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// `reclaimSpace()` (ADR-0057 §3.4) returns the WHOLE freelist on SQLite, read
+// from a SECOND connection rather than from the one that issued the statement.
+//
+// SQLite's incremental-vacuum program frees one page per step. knex's
+// better-sqlite3 client runs a statement that declares no result columns with
+// `Statement.run()`, which steps it once, so this method used to free ONE page
+// per call: 300 → 299 from a second connection, and the lifecycle sweep that
+// calls it after every bulk delete left the file at its high-water mark.
+
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import knex, { type Knex } from 'knex';
+import { SqlDriver, type SqlDriverConfig } from './sql-driver.js';
+
+const PAGE_SIZE = 4096;
+const cleanup: Array<() => Promise<void> | void> = [];
+afterEach(async () => {
+  while (cleanup.length) await cleanup.pop()!();
+});
+
+function tempDb(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'os-reclaim-'));
+  cleanup.push(() => rmSync(dir, { recursive: true, force: true }));
+  return join(dir, 'app.db');
+}
+
+/** A connected driver on `filename`, and a `close()` the cleanup then skips. */
+async function openDriver(
+  filename: string,
+  cfg: Partial<SqlDriverConfig> = {},
+): Promise<{ driver: SqlDriver; close: () => Promise<void> }> {
+  const driver = new SqlDriver({ client: 'better-sqlite3', connection: { filename }, useNullAsDefault: true, ...cfg });
+  let open = true;
+  const close = async () => {
+    if (!open) return;
+    open = false;
+    await driver.disconnect();
+  };
+  cleanup.push(close);
+  await driver.connect();
+  return { driver, close };
+}
+
+/** Fill `rows` rows of ~4 KB each, then delete them all: roughly one freelist page per row. */
+async function freePages(driver: SqlDriver, rows: number): Promise<void> {
+  await driver.initObjects([{ name: 'bulk', fields: { body: { type: 'text' } } }]);
+  const body = 'x'.repeat(4000);
+  for (let i = 0; i < rows; i += 100) {
+    const batch = Array.from({ length: Math.min(100, rows - i) }, (_, j) => ({ id: `r${i + j}`, body }));
+    await driver.bulkCreate('bulk', batch);
+  }
+  await driver.deleteMany('bulk', { where: { id: { $ne: '' } } });
+}
+
+/** The freelist and page count as a SECOND, read-only connection reads them. */
+async function secondConnection(filename: string): Promise<{ freelist: number; pages: number }> {
+  const reader: Knex = knex({
+    client: 'better-sqlite3',
+    connection: { filename, options: { readonly: true } },
+    useNullAsDefault: true,
+  });
+  try {
+    const [free] = await reader.raw('PRAGMA freelist_count');
+    const [count] = await reader.raw('PRAGMA page_count');
+    return { freelist: Number(free.freelist_count), pages: Number(count.page_count) };
+  } finally {
+    await reader.destroy();
+  }
+}
+
+describe('SqlDriver.reclaimSpace() on better-sqlite3 returns the whole freelist', () => {
+  it('WAL (the file-backed default): every free page leaves the database, and the file shrinks once closed', async () => {
+    const file = tempDb();
+    const { driver, close } = await openDriver(file);
+    await freePages(driver, 300);
+    const before = await secondConnection(file);
+    expect(before.freelist).toBeGreaterThanOrEqual(250);
+
+    await driver.reclaimSpace();
+
+    const after = await secondConnection(file);
+    expect(after).toEqual({ freelist: 0, pages: before.pages - before.freelist });
+    await close();
+    expect(statSync(file).size).toBe(after.pages * PAGE_SIZE);
+  });
+
+  it('DELETE journal: the file shrinks while the driver is still open', async () => {
+    const file = tempDb();
+    const { driver } = await openDriver(file, { sqliteJournalMode: 'delete' });
+    await freePages(driver, 300);
+    const before = await secondConnection(file);
+    expect(before.freelist).toBeGreaterThanOrEqual(250);
+    expect(statSync(file).size).toBe(before.pages * PAGE_SIZE);
+
+    await driver.reclaimSpace();
+
+    const after = await secondConnection(file);
+    expect(after).toEqual({ freelist: 0, pages: before.pages - before.freelist });
+    expect(statSync(file).size).toBe(after.pages * PAGE_SIZE);
+  });
+
+  it('control: an empty freelist resolves, and nothing changes', async () => {
+    const file = tempDb();
+    const { driver } = await openDriver(file, { sqliteJournalMode: 'delete' });
+    await freePages(driver, 0);
+    const before = await secondConnection(file);
+    expect(before.freelist).toBe(0);
+
+    await expect(driver.reclaimSpace()).resolves.toBeUndefined();
+
+    expect(await secondConnection(file)).toEqual(before);
+  });
+
+  it('the pooled connection is handed back: the driver answers a query after the call', async () => {
+    const file = tempDb();
+    const { driver } = await openDriver(file);
+    await freePages(driver, 50);
+    await driver.reclaimSpace();
+    await driver.bulkCreate('bulk', [{ id: 'after', body: 'still writable' }]);
+    expect(await driver.count('bulk', {})).toBe(1);
+  });
+});
@@ -10905,14 +10905,39 @@ export class SqlDriver implements IDataDriver {
 
   /**
    * Reclaim free pages after bulk deletions (ADR-0057 §3.4). On SQLite this
-   * issues `PRAGMA incremental_vacuum`, returning freelist pages to the OS —
-   * it pairs with the `auto_vacuum=INCREMENTAL` default set in {@link connect}
-   * (files created before that default need one full `VACUUM` to adopt it).
-   * Postgres/MySQL manage space via their own vacuum/purge machinery, so this
-   * is a no-op there.
+   * runs `PRAGMA incremental_vacuum` TO COMPLETION, returning every freelist
+   * page — it pairs with the `auto_vacuum=INCREMENTAL` default set in
+   * {@link connect} (files created before that default need one full `VACUUM`
+   * to adopt it). Postgres/MySQL manage space via their own vacuum/purge
+   * machinery, so this is a no-op there.
+   *
+   * "To completion" is a property of how the statement is STEPPED, not of its
+   * text. SQLite's incremental-vacuum program frees one page per step and
+   * yields a column-less result row for it, so a caller that steps once frees
+   * one page. knex's better-sqlite3 client runs a statement that declares no
+   * result columns with `Statement.run()`, which steps it once: through
+   * `knex.raw` one call freed ONE page (freelist 300 → 299, read from a second
+   * connection). An explicit page count, `incremental_vacuum(N)`, freed one
+   * page too — the count is a ceiling, not what stops the loop. So that binding
+   * is driven through its own `exec()`, which steps every statement until
+   * SQLite reports done (300 → 0). sql.js needs nothing: `driver-sqlite-wasm`'s
+   * dialect already iterates every row a PRAGMA yields (300 → 0 through the
+   * `knex.raw` below). knex's node-sqlite3 client runs a raw statement with
+   * `Database.all()`, which reads every row too (read from knex's source; that
+   * binding is not installed in this repository).
    */
   async reclaimSpace(_options?: DriverOptions): Promise<void> {
     if (!this.isSqlite) return;
+    const client = this.knex.client;
+    if (client.driverName === 'better-sqlite3') {
+      const connection = await client.acquireConnection();
+      try {
+        connection.exec('PRAGMA incremental_vacuum');
+      } finally {
+        await client.releaseConnection(connection);
+      }
+      return;
+    }
     await this.knex.raw('PRAGMA incremental_vacuum');
   }
 
 
@@ -0,0 +1,92 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// `reclaimSpace()` (ADR-0057 §3.4) is inherited from `SqlDriver`, and on this
+// transport it returns the WHOLE freelist: the wasm dialect steps every PRAGMA
+// until SQLite reports done, so `PRAGMA incremental_vacuum` runs to its end
+// through `knex.raw`. `SqlDriver` drives better-sqlite3 through that binding's
+// own `exec()` instead, because knex's better-sqlite3 client stepped the
+// statement once and freed one page per call; this transport stays on the
+// `knex.raw` arm, and this file pins that it is complete there.
+//
+// Read from a second reader: the image this driver persists, opened by a fresh
+// sql.js database, never the live one that issued the statement.
+
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import initSqlJs from 'sql.js';
+
+import { SqliteWasmDriver } from '../src/index.js';
+
+const PAGE_SIZE = 4096;
+const dirs: string[] = [];
+const drivers: SqliteWasmDriver[] = [];
+
+afterEach(async () => {
+  await Promise.all(drivers.splice(0).map((d) => d.disconnect().catch(() => {})));
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+async function openDriver(): Promise<{ driver: SqliteWasmDriver; file: string }> {
+  const dir = mkdtempSync(join(tmpdir(), 'wasm-reclaim-'));
+  dirs.push(dir);
+  const file = join(dir, 'app.db');
+  const driver = new SqliteWasmDriver({ filename: file, persist: 'on-write' });
+  drivers.push(driver);
+  await driver.connect();
+  return { driver, file };
+}
+
+/** Fill `rows` rows of ~4 KB each, then delete them all: roughly one freelist page per row. */
+async function freePages(driver: SqliteWasmDriver, rows: number): Promise<void> {
+  await driver.initObjects([{ name: 'bulk', fields: { body: { type: 'text' } } }]);
+  const body = 'x'.repeat(4000);
+  for (let i = 0; i < rows; i += 100) {
+    const batch = Array.from({ length: Math.min(100, rows - i) }, (_, j) => ({ id: `r${i + j}`, body }));
+    await driver.bulkCreate('bulk', batch);
+  }
+  await driver.deleteMany('bulk', { where: { id: { $ne: '' } } });
+  await driver.flush();
+}
+
+/** The freelist and page count of the persisted image, read by a fresh sql.js database. */
+async function persistedImage(file: string): Promise<{ freelist: number; pages: number }> {
+  const SQL = await initSqlJs();
+  const db = new SQL.Database(readFileSync(file));
+  try {
+    const freelist = Number(db.exec('PRAGMA freelist_count')[0].values[0][0]);
+    const pages = Number(db.exec('PRAGMA page_count')[0].values[0][0]);
+    return { freelist, pages };
+  } finally {
+    db.close();
+  }
+}
+
+describe('SqliteWasmDriver.reclaimSpace() returns the whole freelist', () => {
+  it('every free page leaves the persisted image, and the file shrinks to the pages left', async () => {
+    const { driver, file } = await openDriver();
+    await freePages(driver, 300);
+    const before = await persistedImage(file);
+    expect(before.freelist).toBeGreaterThanOrEqual(250);
+
+    await driver.reclaimSpace();
+    await driver.flush();
+
+    const after = await persistedImage(file);
+    expect(after).toEqual({ freelist: 0, pages: before.pages - before.freelist });
+    expect(statSync(file).size).toBe(after.pages * PAGE_SIZE);
+  });
+
+  it('control: an empty freelist resolves, and the image is unchanged', async () => {
+    const { driver, file } = await openDriver();
+    await freePages(driver, 0);
+    const before = await persistedImage(file);
+    expect(before.freelist).toBe(0);
+
+    await expect(driver.reclaimSpace()).resolves.toBeUndefined();
+    await driver.flush();
+
+    expect(await persistedImage(file)).toEqual(before);
+  });
+});
@@ -166,11 +166,13 @@ Answered in remote mode, differently from local mode:
   presentation (a declared boolean reads back as `true` / `false`), and an
   unknown column refused with `INVALID_FIELD` / 400. A tenant-scoped call is
   refused (table above), because no remote read applies the tenant scope.
-- **`reclaimSpace()`** sends the statement local mode issues,
-  `PRAGMA incremental_vacuum`, to the remote database. It returns free pages
-  only on a database whose `auto_vacuum` mode is `INCREMENTAL`: local mode sets
-  that mode when it connects, and remote mode does not. A server that refuses
-  the statement answers `DATABASE_ERROR` / 500.
+- **`reclaimSpace()`** reads `PRAGMA freelist_count` from the remote database
+  and, when there are free pages, runs the statement local mode issues,
+  `PRAGMA incremental_vacuum`, to completion there (through the client's
+  `executeMultiple()`). It returns free pages only on a database whose
+  `auto_vacuum` mode is `INCREMENTAL`: local mode sets that mode when it
+  connects, and remote mode does not. A server that refuses either statement
+  answers `DATABASE_ERROR` / 500.
 - **`supportsRotation`** is `false`. The lifecycle service reads it, and for an
   object that declares `lifecycle.storage.strategy: 'rotation'` it then takes the
   path it has for a driver that cannot shard: an age-based reap bounded by the
 
@@ -3222,18 +3222,43 @@ export class TursoDriver extends SqlDriver {
 
   /**
    * Reclaim free pages — answered on the REMOTE face with the statement the
-   * local face issues, `PRAGMA incremental_vacuum`, sent to the remote database
-   * through the raw door's envelope (`DATABASE_ERROR` / 500 if the server
-   * refuses it). As on a local file, it returns pages only on a database whose
-   * `auto_vacuum` is `INCREMENTAL`; the remote face does not set that mode at
-   * connect, the local face does.
+   * local face issues, `PRAGMA incremental_vacuum`, run to completion on the
+   * remote database, in the raw door's envelope (`DATABASE_ERROR` / 500 if the
+   * server refuses it). As on a local file, it returns pages only on a database
+   * whose `auto_vacuum` is `INCREMENTAL`; the remote face does not set that
+   * mode at connect, the local face does.
+   *
+   * The statement goes through the client's `executeMultiple()`, not
+   * `execute()`. SQLite frees one page per step of this statement, and the
+   * libSQL client's `execute()` steps a statement that declares no result
+   * columns once and leaves it unfinished. Measured over a libSQL `file:`
+   * client: the issuing connection read one page fewer (300 → 299), a second
+   * connection read the freelist and the file size unchanged, and a row
+   * written after the call on the same connection never reached the file.
+   * `executeMultiple()` runs each statement to its end: a second connection
+   * reads 300 → 0, and the later write lands. What a hosted libSQL server does
+   * with either call is not measured here.
+   *
+   * The free-page count is read first, through the raw door, which connects
+   * the transport lazily as every remote door does. Nothing more is sent when
+   * the freelist is empty.
    */
   override async reclaimSpace(options?: DriverOptions): Promise<void> {
     this.assertRemoteTransactionUnsupported(options, 'reclaimSpace');
     if (this.isRemote) {
+      const transport = this.remoteTransport!;
+      const count = 'PRAGMA freelist_count';
+      let freePages: number;
+      try {
+        const rows = (await transport.execute(count)) as ArrayLike<ArrayLike<unknown>>;
+        freePages = Number(rows[0]?.[0]);
+      } catch (error) {
+        throw this.rawStatementFault(count, error);
+      }
+      if (freePages === 0) return;
       const statement = 'PRAGMA incremental_vacuum';
       try {
-        await this.remoteTransport!.execute(statement);
+        await transport.getClient()!.executeMultiple(statement);
       } catch (error) {
         throw this.rawStatementFault(statement, error);
       }