fix(driver-sql, driver-turso): reclaimSpace() returns the whole SQLite freelist, not one page per call (#20106)

[objectstack-fleet]

Fixes #20106
Clause-②: no

reclaimSpace() now returns the whole SQLite freelist on every face. Every reading below comes from a second connection. The file size is read beside it. Each run has an empty-freelist control. Measured head: 0adf65deb.

What was wrong

SQLite's incremental-vacuum program frees one page per sqlite3_step(), and it yields a result row with no columns for each page. A caller that steps it once frees one page. Two clients stepped it once:

• SqlDriver on better-sqlite3, and TursoDriver in local mode, which is the same code. knex's better-sqlite3 client runs a statement that declares no result columns with Statement.run(), and run() steps once. Statement.reader is false for this pragma.
• TursoDriver in remote mode. The libSQL client's execute() steps the statement once and leaves it unfinished. The page it freed never reached the file. The unfinished statement also held the connection's implicit transaction open, so a later write on that connection never reached the file either.

What changed

• packages/drivers/driver-sql/src/sql-driver.ts, SqlDriver.reclaimSpace: when the knex client is better-sqlite3, the pragma runs through that binding's own exec() on the pooled connection. exec() steps every statement until SQLite reports done. Every other SQLite client stays on knex.raw. sql.js steps every PRAGMA to the end in driver-sqlite-wasm's dialect (measured). knex's node-sqlite3 client uses Database.all() (read from knex's source; the binding is not installed here).
• packages/drivers/driver-turso/src/turso-driver.ts, the remote reclaimSpace route: it reads PRAGMA freelist_count through the raw door first. That read also connects the transport lazily, as every remote door does. When the count is 0 nothing more is sent. Otherwise the vacuum runs through the client's executeMultiple(). Both statements keep the raw door's envelope (DATABASE_ERROR / 500).
• packages/drivers/driver-turso/README.md: the sentence on the remote reclaimSpace() now says what the route sends.
• Tests in all three driver packages, and .changeset/20106-reclaim-space-full-freelist.md (patch for driver-sql and driver-turso).

Readings: freelist / page count from a second connection

The fixture fills about 300 pages and deletes them. The control is an empty freelist.

face	before	main (789b2ae54) after one call	this PR after one call
SqlDriver (better-sqlite3, WAL)	300 / 304	299 / 303	0 / 4
SqliteWasmDriver (sql.js image)	300 / 304	0 / 4, already complete	0 / 4
TursoDriver local (better-sqlite3, WAL)	300 / 304	299 / 303	0 / 4
TursoDriver remote (@libsql/client, file:)	300 / 304	300 / 304 (the issuing connection read 299)	0 / 4
control, every face	0 / 4	0 / 4	0 / 4

File size in bytes:

• Wasm image and remote file: database (rollback journal): 1,245,184 → 16,384 with this PR. On main the remote file stayed at 1,245,184, even after disconnect.
• The two WAL faces, after disconnect: main 1,241,088, this PR 16,384.

Raw clients, 300 free pages, read from a second connection:

• better-sqlite3. Statement.run('PRAGMA incremental_vacuum') → 299. incremental_vacuum(600) through run() → 299 too. db.pragma() and db.exec() → 0.
• @libsql/client file:.
  • execute() → 300. The issuing connection read 299, and the file was unchanged after close().
  • execute('PRAGMA incremental_vacuum(600)') → 300.
  • executeMultiple() → 0.
  • batch([...], 'write') → throws SQLITE_BUSY: cannot commit transaction - SQL statements in progress.
• sql.js. A prepare-and-step loop (the wasm dialect's branch) → 0. One step → 299.

Remote face, write after reclaimSpace(): a create() made after the call is read back by the issuing connection. On main a second connection counted 0 rows, and after disconnect it still counted 0: the row was lost. With this PR it counts 1, and 1 after disconnect.

Cost at 25,660 free pages through knex on better-sqlite3 (shared box, so read the ratio):

• exec(): 245 ms.
• N single-page raw() calls in one transaction: 1,352 ms.
• N autocommitted raw() calls: 1,606 ms.
• One raw() call (main): 1.3 ms, for one page.

The dispatch's mechanism hypotheses

• H1: confirmed on 789b2ae54: if (!this.isSqlite) return; await this.knex.raw('PRAGMA incremental_vacuum');.
• H2: the first half is confirmed: one execution steps once and frees one page. The second half is falsified. An explicit page count does not help, because incremental_vacuum(600) freed one page through both better-sqlite3 run() and libSQL execute(). The count is a ceiling, not what ends the loop. The statement has to run to completion.
• H3: partly falsified. SqliteWasmDriver and local TursoDriver do inherit SqlDriver.reclaimSpace. But the defect lived in the client binding, not in the method's text, and the wasm face was already complete on main (its dialect steps every PRAGMA to the end). For this method there are three independent implementations:
  • better-sqlite3 through knex: two faces, both broken, fixed at the SqlDriver seam;
  • the sql.js dialect: one face, already correct, now pinned;
  • the libSQL remote route: one face, broken, fixed in turso-driver.ts.
• H4: confirmed, and worse than a reading. Through libSQL execute(), a second connection saw nothing land: not the freelist, not the file size, and not a later write on the same connection.

Does os db clean reach this method?

No. packages/cli/src/commands/db/clean.ts never calls reclaimSpace(). It runs driver.execute('PRAGMA auto_vacuum = INCREMENTAL'), then driver.execute('VACUUM'), then disconnects. A full VACUUM finishes in one step. Measured through SqlDriver.execute on a legacy file (auto_vacuum 0) with 300 free pages:

• freelist 300 → 0;
• auto_vacuum 0 → 2;
• file 1,236,992 → 12,288 bytes.

It is not edited here.

The remote face: measured and not measured

Measured over a libSQL file: client only (@libsql/client 0.17.4, libsql 0.5.29), plus a scripted client for the call order and the refusal envelope.

Not measured, because there is no live server: what a hosted libSQL / Turso server does. That covers whether it accepts PRAGMA freelist_count and PRAGMA incremental_vacuum, and how it steps execute() against executeMultiple() (a hrana sequence request). The route adds one read round trip when there are free pages. When the freelist is empty it sends no write.

Tests

• driver-sql/src/sql-driver-sqlite-reclaim-space.test.ts (new), 4 cases:
  • WAL: freelist 0 and page count equal to before minus free, read from a second connection; file size equal to pages times page size after close;
  • DELETE journal: the same, and the file shrinks while the driver is open;
  • the empty-freelist control;
  • the pooled connection is handed back.
• driver-sqlite-wasm/src/sqlite-wasm-reclaim-space.test.ts (new), 2 cases: the persisted image, read by a fresh sql.js database, plus the control.
• driver-turso/src/turso-remote-inherited-members.test.ts: the old pin read the freelist from the issuing client and asserted toBeLessThan(before), which a one-page, connection-local drop passed. It now reads a second client and asserts equality. Added:
  • the control on both faces;
  • the remote file shrinking while open;
  • a write after the call landing;
  • the call order (count first, nothing more on 0, vacuum through executeMultiple);
  • the DATABASE_ERROR / 500 envelope when either statement is refused.

Full suites at 0adf65deb:

• driver-sql: 195 files passed, 11 skipped; 3,224 tests passed, 178 skipped.
• driver-turso: 73 files; 1,927 tests passed, 16 skipped.
• driver-sqlite-wasm: 36 files; 658 tests passed.
• typecheck is green for all three. Each package's tsconfig includes its tests; the typecheck read the turso test file and caught an Array.prototype.at before it landed.

Ablations (committed state first; every leg went through scripts/ablation-replace.mjs, and the restore was proven blob-equal to HEAD):

• A: better-sqlite3 routed back to knex.raw. The driver-sql test goes red on WAL and DELETE ({ freelist: 299, pages: 303 } against { freelist: 0, pages: 4 }); the control and the pool case stay green. With driver-sql rebuilt and the marker proven in dist/ by ablation-dist-preflight, the turso local face goes red ({ freelist: 39, pages: 47 }) and the wasm test stays green (2/2). That is the H3 reading. The restore was rebuilt, and --absent proved dist/ and the tree clean.
• B: the knex.raw arm made a no-op, dist/ rebuilt, marker proven. The wasm test goes red ({ freelist: 300, pages: 304 }) and its control stays green. The restore was rebuilt and --absent passed.
• C: the remote route sent back through execute(). 5 turso cases go red: second-connection freelist 40 against 0, the file size case, the write after the call (0 against 1), the call order, and the vacuum refusal. The other 77 stay green.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 0adf65deb derives 63 commands. All 63 were run, and every exit code was recorded before any pipe: all 63 exited 0.

On the first run at 155234b97:

• check:query-options-erasure was red: the test surface grew 236 → 237 from an as any on a query bag in the new tests. The bags are now typed, and it holds at 236.
• check:dual-build-cjs-loads, check:lean-entry-closure and check:type-check-debt refused with PREREQUISITE NOT MET (exit 3). They passed after turbo run build over ./packages/* and ./packages/*/*.

--ran: 63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN.

check:driver-conformance: before, at 789b2ae54, 50 covered cells and 0 in the DEBT ledger (0 exempt). After, at 0adf65deb, the same: 50 covered, 0 DEBT.

pnpm lint is CI's run. The narrowed run here: eslint --no-inline-config --format json over the 5 changed TypeScript files reports 5 files, 0 errors and 0 warnings, with no file reported as ignored. eslint.config.mjs sets no parserOptions.project and registers no typed rule, so a diff cannot move the verdict of an untouched file.

Acceptance notes

• The -wal sidecar (a finding, reported for the seat to file; not fixed here). On a file-backed database in WAL mode, the default, a to-completion vacuum passes the freed pages through the -wal file. At 25,754 free pages through SqlDriver:

  • the second connection reads freelist 0 and page count 4;
  • the database file goes 105,631,744 → 16,384;
  • -wal goes 4,577,352 → 91,855,432 and keeps that size until the last connection closes.

  Measured options on raw better-sqlite3, 25,600 rows freed, one run on a shared box (database file + -wal, while open):

  option	database file	-wal	time
  exec() alone (this PR)	12,288	90,112,672	267 ms
  + wal_checkpoint(TRUNCATE)	12,288	0	309 ms
  chunked incremental_vacuum(1000) + wal_checkpoint(PASSIVE)	12,288	210,152	71 ms

  A TRUNCATE checkpoint can wait on another process's readers for up to the busy timeout. PASSIVE never waits.

• File surface. packages/drivers/driver-turso/README.md is outside the claim's listed surface. It documents the exact route this PR changes, and its old sentence ("sends the statement local mode issues") would have become false.

• Legacy files. A file whose auto_vacuum is still NONE reclaims nothing through reclaimSpace() (measured: 300 → 300), as the method's comment already says. The lifecycle report still lists that datasource as reclaimed. os db clean is the documented remedy.

• driver-turso remote: a federated object's external.remoteName is ignored — remote find queries a table named after the object and throws a bare LibsqlError (no code, no status), while the local face reads the mapped table #20107 (the remote read arms) and RLS enforcement: the write check (packages/formula matches-filter) admits a cross-class field-to-field comparison that driver-sql's read refuses — one classification, one answer per policy (the engine half of #20347) #20355 (crossFieldComparisonClass) had not landed when main was last merged, at 50e273fd7.

• Seat-added, not filed (zero pull; no producer calls it): on the Turso REMOTE face over a libSQL file: client (a supplied client, or mode: 'remote' with a file: url), the raw door driver.execute('PRAGMA incremental_vacuum') keeps the old hazard. libSQL execute() leaves the statement unfinished, so a row created afterwards on that connection is lost: the dev measured the issuer reading 1, a second connection 0, and 0 after disconnect. The same behaviour sits upstream in @libsql/client's file: implementation (os-dev-report 5868445205). Separately, the WAL sidecar reading above is filed as driver-sql: after reclaimSpace() on a WAL-mode SQLite file the -wal sidecar grows to about the space just freed (91.9 MB for a 105 MB freelist) and stays there until the last connection closes #20426.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/driver-sql, @objectstack/driver-turso, touching 3 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/drivers/driver-turso/README.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

8 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via SqlDriver (symbol, a top-level class), TursoDriver (symbol, a top-level class), reclaimSpace (symbol, a method of class SqlDriver; a method of class TursoDriver))
• content/docs/data-modeling/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/permissions/tenant-audit-census.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via SqlDriver (symbol, a top-level class), TursoDriver (symbol, a top-level class))
• content/docs/protocol/kernel/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/lifecycle.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/objectql/query-syntax.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/objectql/types.mdx (via SqlDriver (symbol, a top-level class))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/releases/v17/17-5.mdx (via SqlDriver (symbol, a top-level class), TursoDriver (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/drivers/driver-turso/README.md) — pages documenting those are invisible to this run
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 13 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 0283cb924a5e29f22fdf0db60bcaedeab3ead3f3 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 39fcf4ed91bdd2a8621ced2f5250e39f26887a7c — the merge of head 0adf65debb127f52660624df7ac9af06b752c1e0 into base 0283cb924a5e29f22fdf0db60bcaedeab3ead3f3, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 39fcf4ed91bdd2a8621ced2f5250e39f26887a7c && git checkout 39fcf4ed91bdd2a8621ced2f5250e39f26887a7c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0283cb924a5e29f22fdf0db60bcaedeab3ead3f3 0adf65debb127f52660624df7ac9af06b752c1e0 && git checkout -B drift-repro 0283cb924a5e29f22fdf0db60bcaedeab3ead3f3 && git merge --no-ff 0adf65debb127f52660624df7ac9af06b752c1e0

node scripts/docs-audit/affected-docs.mjs --json 0283cb924a5e29f22fdf0db60bcaedeab3ead3f3

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 0283cb924a5e29f22fdf0db60bcaedeab3ead3f3 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0adf65debb127f52660624df7ac9af06b752c1e0
Local-runs: none

① Derived judgments

Inputs read: card #20106 (body and all 5 comments, 5827314394 through 5868473417), PR #20425 (body, 7-file list) and git diff origin/main...origin/claude/issue-20106-reclaim-space-full-freelist at 0adf65deb (merge base 50e273fd7; +410 / −35 over 7 files, equal to the API file list), plus the vendored bindings the diff's own comments cite (knex 3.3.0, @libsql/client 0.17.4, the wasm dialect on main). Contract: IDataDriver.reclaimSpace (packages/spec/src/contracts/data-driver.ts 451–457: reclaim free space after bulk deletions, ADR-0057 §3.4; optional, best-effort after every sweep that deleted rows) and ADR-0057 §3.4 (the Reaper issues PRAGMA incremental_vacuum after a sweep). Neither is edited.

1. SqlDriver.reclaimSpace, the better-sqlite3 arm — RIGHT. knex's Client_BetterSQLite3._query (vendored, lines 51–57) runs a statement whose reader is false through Statement.run(): one step, one freed page. Database.exec() steps to done. The arm keys on client.driverName === 'better-sqlite3' (the dialect's declared driverName, line 98), takes client.acquireConnection() and hands it back in finally. The knex.raw arm stays for every other SQLite spelling isSqlite admits (sqlite3, sqlite, better-sqlite3): knex's node-sqlite3 client dispatches a raw statement to all (vendored line 149; that binding is not a dependency of driver-sql, so the PR rightly calls it read, not measured), and the wasm dialect (driverName: 'wasm-sqlite') runs every PRAGMA through while (stmt.step()) — complete on main, so the wasm face needs and gets no source change; SqliteWasmDriver overrides isSqlite to true, so the method reaches that arm. Faces delivered: SqlDriver on better-sqlite3; TursoDriver local, whose knex config is client: 'better-sqlite3' (turso-driver.ts 1569 / 1576 / 1584) and so takes the same arm; SqliteWasmDriver, pinned unchanged.

2. TursoDriver.reclaimSpace, the remote route — RIGHT. Order: transport.execute('PRAGMA freelist_count') (RemoteTransport.execute calls ensureConnected(), the lazy connect every remote door uses, and returns result.rows; a libSQL Row is index-addressable, so rows[0]?.[0] reads the scalar) → return on 0 → transport.getClient()!.executeMultiple('PRAGMA incremental_vacuum'), non-null once ensureConnected resolved. Both statements sit in rawStatementFault → DATABASE_ERROR / 500, pinned per refusal with a scripted client. Mechanism verified in the vendored @libsql/client file: implementation: executeStmt calls sqlStmt.raw(true), which throws for a column-less statement, so it falls to sqlStmt.run(args) (one step); executeMultiple is db.exec(sql). assertRemoteTransactionUnsupported and the local fall-through to super are unchanged. Edge, noted not flagged: a mis-shaped or empty count answer yields NaN, which is not === 0, so the vacuum still runs — the safe direction. Option A's named cost stands: a server refusing only the read now refuses the route at the read; LifecycleService.sweep() wraps reclaimSpace() in try/catch and logs a warning (lifecycle-service.ts 710–717), the same degradation a vacuum refusal had on main.

3. The remote face over a hosted server — NOT MEASURED, and nowhere stated as measured. The PR body's readings table labels its remote row @libsql/client, file:; the body's "measured and not measured" section, the changeset and the route's docstring each say what a hosted libSQL server does with either call is not measured. The lead sentence "on every face" is a design claim that the same body bounds two sections later; no reading is attributed to a hosted server.

4. The README bullet (packages/drivers/driver-turso/README.md, the one reclaimSpace() bullet; 5 lines out, 7 in, nothing else in the file) — TRUE against the code: the route reads PRAGMA freelist_count; when there are free pages it runs PRAGMA incremental_vacuum through executeMultiple(); free pages come only under auto_vacuum=INCREMENTAL (local connect sets it, sql-driver.ts 6857; the remote face does not — the unchanged half of the bullet); either refusal answers DATABASE_ERROR / 500. "To completion there" is what executeMultiple exists for and what the file: reading shows; the sentence claims no reading of a hosted server, so it states nothing as measured that was not.

5. The accept-set the tests pin — RIGHT, and the tightening the card asked for. Every reading comes from a SECOND connection (a read-only better-sqlite3 knex; a fresh sql.js database over the persisted image; a fresh libSQL client), with { freelist: 0, pages: before minus free } equality replacing the old issuing-client toBeLessThan; an empty-freelist control on every face; file size checked (DELETE journal while open, WAL after close, remote file: while open); the pooled connection handed back; the remote post-call write reaching a second connection; the call order and both refusal envelopes. No production behaviour is loosened anywhere.

6. os db clean (triage note 3) — answered correctly and not edited: packages/cli/src/commands/db/clean.ts 101–102 runs PRAGMA auto_vacuum = INCREMENTAL then VACUUM through driver.execute; packages/cli contains no call to reclaimSpace.

7. Public surface: both reclaimSpace signatures unchanged; the spec contract untouched; the remote face sends one extra read when pages are free and nothing when the freelist is empty; a supplied client must carry executeMultiple, which the @libsql/client Client type already declares. No accept-set is widened; "reclaimed" in the lifecycle report stays best-effort, as the contract says.

② Semver level

.changeset/20106-reclaim-space-full-freelist.md: @objectstack/driver-sql: patch, @objectstack/driver-turso: patch. Matches what the diff publishes: the two packages with source changes ship a behaviour fix under an unchanged signature and an unchanged contract; driver-sqlite-wasm changes only a test file and publishes nothing (Check Changeset: success). Clause-②: no — right: the change brings the method to what IDataDriver.reclaimSpace and ADR-0057 §3.4 already declare, and nothing in packages/spec or the ADR moves.

③ Boundary flags

• Deviation, README outside the claimed surface: answered — the seat's amended claim 5868473417 adds the one bullet, and the diff touches only that bullet. Closed.
• Deviation, issue_patch order conflict (the dev wrote the PR body once): answered — the seat, not the dev, added the "Seat-added, not filed" paragraph to the PR's Acceptance notes (the raw-door hazard and the driver-sql: after reclaimSpace() on a WAL-mode SQLite file the -wal sidecar grows to about the space just freed (91.9 MB for a 105 MB freelist) and stays there until the last connection closes #20426 pointer). Closed.
• Deviation, attribution trailers: reported, not a contract item — all 7 commits carry Claude-Session: plus a model-free Co-authored-by: Claude line, uniformly. No flag.
• open_questions, A against B: the seat ruled A in 5868473417; the head implements A (the pre-read through the raw door, executeMultiple on getClient(), no edit to remote-transport.ts). Closed.
• out_of_scope 1, the -wal sidecar holding the freed bytes until the last close: filed as driver-sql: after reclaimSpace() on a WAL-mode SQLite file the -wal sidecar grows to about the space just freed (91.9 MB for a 105 MB freelist) and stays there until the last connection closes #20426 (open, 2026-09-28T10:56Z, reach: LifecycleService). Closed here.
• out_of_scope 2, the raw door driver.execute('PRAGMA incremental_vacuum') over a remote file: client keeping the unfinished-statement hazard: in the PR's Acceptance notes with carrier none; not this route, no producer. Closed.
• out_of_scope 3, a legacy auto_vacuum=NONE file reclaiming nothing yet reading as reclaimed: documented in the method comment, the PR and ADR-0057 §3.4 (db:clean is the remedy). Closed.
• Regions: driver-turso remote: a federated object's external.remoteName is ignored — remote find queries a table named after the object and throws a bare LibsqlError (no code, no status), while the local face reads the mapped table #20107 and RLS enforcement: the write check (packages/formula matches-filter) admits a cross-class field-to-field comparison that driver-sql's read refuses — one classification, one answer per policy (the engine half of #20347) #20355 sit in other regions of the same two files; the later lander merges main (claim text). Not a gate here.
• Escalated: nothing.

Check-runs on 0adf65deb, final read 2026-09-28T11:05:20Z: 40 runs, 39 completed — 34 success, 5 skipped (Auto Label and Check PR Size on the 10:57 re-run, Console Pin Gate, Build Docs, Packed-tarball smoke opt-in), 0 failure. Green: Build Core; Test Core 1/6, 2/6, 3/6, 4/6, 5/6; Type Check source gates, workspace, consumer gates, debt ledger and TypeScript Type Check; Lint & Repo Gates; Temporal Conformance (live PG + MySQL); Dogfood Verify CLI and Dogfood Regression Gate 1/3, 2/3, 3/3; Check Changeset; Governed Surface Queue Guard; Flag docs affected by code changes; Check Documentation Links; the card/branch/single-writer/part-of guards (both runs). Test Core (6/6), the last run, completed success at 2026-09-28T11:07:33Z (read from the poll armed on the same endpoint): 40 runs, 40 completed, 35 success, 5 skipped, 0 failure. Every gate family on the head is green.

Implemented-by: claude/issue-20106-reclaim-space-full-freelist
Reviewed-by: session_01N8TPEsoJxPsdSdNKGnNGEN

VERDICT: PASS