fix(driver-sql): reclaimSpace() returns the freed bytes from the SQLite -wal sidecar too, never waiting on another connection (#20426)

[objectstack-fleet]

Fixes #20426
Clause-②: no

reclaimSpace() on better-sqlite3 now returns the freed bytes from the -wal sidecar as well as the freelist, and it never waits on another connection. Every size below is the database file plus its -wal file, read from the file system while the driver is still open. Every freelist and page count is read from a second connection. Measured head: effb34a8a (the branch after merging origin/main at b28550818, which carries PR #20427).

What was wrong

With PR #20425, one Database.exec('PRAGMA incremental_vacuum') returns the whole freelist in one transaction. In WAL mode, the file-backed default, that transaction's dirty pages outgrow the page cache, so SQLite spills them into the WAL before the commit truncates them away. Nothing afterwards truncates the WAL, so the sidecar keeps its high-water size until the last connection closes.

What changed

• packages/drivers/driver-sql/src/sql-driver.ts: the better-sqlite3 arm of SqlDriver.reclaimSpace calls a module-local reclaimBetterSqlite3(connection). It is module-local, like formatDuplicateGroups, because SqlDriver's .d.ts carries its non-public members and this helper is no entry point. The published types are unchanged; the .d.ts gains one doc-comment sentence on reclaimSpace. The helper:
  1. reads PRAGMA freelist_count, and sends nothing more when it is 0;
  2. runs PRAGMA incremental_vacuum(N) in chunks, N being a quarter of this connection's page cache (1,000 pages at better-sqlite3's default cache_size = -16000 and 4 KiB pages), with a PASSIVE checkpoint after each chunk;
  3. stops when the freelist is empty or a chunk frees nothing (an auto_vacuum = NONE file never shrinks its freelist);
  4. ends with one PRAGMA wal_checkpoint(TRUNCATE) under a busy timeout of 0, and puts the connection's own busy timeout back in a finally.
     Every statement goes through the binding's exec() / pragma(), which step to completion. The loop is synchronous, so nothing else runs on the connection between chunks. Every other SQLite client stays on knex.raw, as before.
• Tests in driver-sql and driver-turso (below), and .changeset/20426-reclaim-space-wal-sidecar.md (@objectstack/driver-sql: patch).
• .changeset/20106-reclaim-space-full-freelist.md: one paragraph removed. It said the freed pages pass through the -wal file, "which keeps its size until the last connection closes". This PR makes that false, and that note is still pending release. This keeps check-empty-changeset red on purpose — see "The one red gate" below.

The dispatch's hypotheses

• H1 — confirmed on origin/main 8cdbe0c6e, through SqlDriver (25,754 free pages):

  step	database file	-wal	freelist / pages
  after the delete	103,149,568	4,255,992	25,754 / 25,789
  after reclaimSpace() (351 ms)	16,384	94,430,432	0 / 4
  after one more write	16,384	94,430,432	0 / 4
  after disconnect()	16,384	0	0 / 4

  The DELETE-journal control on the same tree: 105,631,744 → 16,384 while open, with no -wal file.

• H2 — re-measured on this tree, and the picked variant is a fourth one. Each variant ran on SqlDriver's own pooled connection after the real fill-and-delete path (25,754 free pages, chunk 1,000). The rows show database file + -wal after the call, driver open. This is one run per cell on a shared box, so read the ratios, not the absolute times.

  variant	no reader	reader in this process (read transaction open)	reader in another process (open for 1.5 s)
  exec alone (PR fix(driver-sql, driver-turso): reclaimSpace() returns the whole SQLite freelist, not one page per call (#20106) #20425)	16,384 + 94,430,432 · 315 ms	103,149,568 + 94,430,432 · 715 ms	103,149,568 + 94,430,432 · 273 ms
  + wal_checkpoint(TRUNCATE)	16,384 + 0 · 476 ms	103,149,568 + 94,430,432, busy · 5,333 ms	16,384 + 0 · 1,526 ms (waited out the reader)
  chunked + PASSIVE	16,384 + 4,255,992 · 157 ms	103,149,568 + 4,255,992 · 47 ms	103,149,568 + 4,255,992 · 62 ms
  chunked + PASSIVE + TRUNCATE at busy timeout 0 (this PR)	16,384 + 0 · 276 ms, 108 ms on a rerun	103,149,568 + 4,255,992, busy · 48 ms	103,149,568 + 4,255,992, busy · 61 ms

  • The driver-sql: reclaimSpace() frees ONE freelist page per call, not the freelist — PRAGMA incremental_vacuum measured 300 → 299 pages on SQLite, so the lifecycle sweep never returns bulk-deleted space (ADR-0057 §3.4) #20106 reading of about 210 KB for chunked + PASSIVE does not hold through SqlDriver. PASSIVE never shrinks the sidecar: it stays at whatever high-water size the sweep's own deletes left (4,255,992 here). Only a TRUNCATE checkpoint returns it.
  • A waiting TRUNCATE checkpoint blocks the whole process on this synchronous binding, for up to the connection's busy timeout (5,000 ms; knex's better-sqlite3 client passes no timeout, so it is always better-sqlite3's default). The lifecycle sweep runs in the server process, so the triage's never-wait direction holds.
  • So this PR takes the triage's chunked, never-waiting variant, plus one TRUNCATE checkpoint that cannot wait. It is the only row that both returns the space with no reader and never waits with one.
  • With a reader present, no variant can shrink the database file. The chunked rows keep the pair at its size before the call (107,405,560). The one-statement rows grow it to 197,580,000.

  The chunk size, and why. A chunk that outgrows the page cache spills its pages into the WAL, just as one statement does. Frames left in the WAL by the call, with a reader pinning every frame so none is reused:

  chunk (pages)	100	250	500	1,000	2,000	4,000	8,000	one statement
  default cache (-16000)	1,437	1,121	1,003	928	883	3,779	14,216	22,920
  2 MB cache (-2000)		1,121	4,554	15,491

  • The spill starts where the chunk reaches the page cache: between 2,000 and 4,000 pages at the default (PRAGMA cache_spill reads 3,871), and between 250 and 500 at -2000.
  • Below that point, larger chunks mean fewer commits and fewer frames.
  • A fixed 1,000 would spill on a connection with a smaller cache or larger pages. So N is derived from the connection's own cache_size and page_size, and the quarter leaves room for the per-page overhead and the b-tree pages each chunk rewrites. At the default that is 1,000 pages (4 MB).

• H3 — confirmed. resolveSqliteJournalMode() answers wal for a file-backed database unless configured otherwise, and the probe's second connection reads journal_mode = wal. The DELETE-journal control is unchanged by the fix. Before and after, the file shrinks while the driver is open and no -wal file exists: 105,631,744 → 16,384, 216 ms before and 127 ms after.

• H4 — confirmed. The local TursoDriver face uses knex's better-sqlite3 client, so it takes this arm through super.reclaimSpace(). Its suite reached the method, but it read only the freelist and the page count. It now has a WAL-size case. The remote route is untouched.

• H5 — nothing new is thrown, so the sweep logs nothing new. Both checkpoints report "busy" as a result row, not as an error. So a busy checkpoint degrades to "vacuumed, not checkpointed": the call resolves, the pages are off the freelist, and LifecycleService.sweep() lists the datasource as reclaimed, as before.

  • Their bytes leave the files at a later checkpoint: the next reclaim with free pages, SQLite's auto-checkpoint at 1,000 frames, or the last connection closing. The reader case of the new test measures the next reclaim.
  • What can still throw is unchanged. Another connection holding the write lock (BEGIN IMMEDIATE) makes the vacuum statement itself wait out the busy timeout and throw SQLITE_BUSY. Measured: main 5,021 ms and this PR 5,014 ms, both freelist unchanged, busy timeout 5,000 afterwards.
  • In that case the sweep logs its existing warning (space reclaim on datasource 'X' failed (database is locked)) and does not list the datasource.
  • The busy-timeout swap comes after the loop, so a throw inside the loop never reaches it.

The fix through SqlDriver

Same 25,754-page fixture:

condition	database file + -wal after the call	call	busy timeout after
WAL, no reader (was 103,149,568 + 4,255,992)	16,384 + 0	101 ms, 109 ms	5,000
DELETE journal	16,384, no -wal	127 ms	5,000
WAL, reader in this process	103,149,568 + 4,255,992 (unchanged; freelist 0)	47 ms	5,000
WAL, reader in another process	103,149,568 + 4,255,992 (unchanged; freelist 0)	66 ms	5,000

Tests

driver-sql/src/sql-driver-sqlite-reclaim-space.test.ts, 7 cases (4 before). Each size is the database file plus the -wal file, read while the driver is open. Each freelist and page count is read from a second connection.

• WAL: freelist 0, and { file: pages × 4096, wal: 0 } while open and again after close.
• WAL with a reader holding a read transaction. The reopened file has no WAL, the cache is set to about 100 pages, and 600 pages are free. The case asserts:
  • the call resolves in under half the busy timeout;
  • the busy timeout reads 5,000 afterwards;
  • freelist 0;
  • WAL growth under a quarter of the freed bytes. Measured: 0.08 for this PR, and 0.87 for both one statement and a fixed 1,000-page chunk.
  • Once the reader commits, the next reclaim returns everything: { file: pages × 4096, wal: 0 }.
• The auto_vacuum = NONE control:
  • the call resolves, so the loop stopped;
  • freelist and pages are unchanged;
  • the database file equals pages × 4096;
  • file + -wal is no larger than before.
• DELETE journal: freelist 0, and { file: pages × 4096, wal: 0 } while open.
• The empty-freelist control, for both journal modes: nothing changes, the sizes included.
• Unchanged: the pooled connection is handed back.

driver-turso/src/turso-remote-inherited-members.test.ts: new case "local face: in WAL mode the freed bytes leave the -wal sidecar too, while the driver is still open".

Suites on the merged head effb34a8a, all through scripts/pm/os-verify-lock.sh, each exit code recorded:

• pnpm --filter @objectstack/driver-sql test: exit 0, 195 files passed and 11 skipped; 3,179 tests passed and 178 skipped. The count before the merge was 3,227; the merge brought in PR fix(security)!: the RLS write check refuses a field-to-field comparison the read refuses — one comparison class, one answer per policy (#20355) #20427, which removed tests of its own.
• pnpm --filter @objectstack/driver-turso test: exit 0, 74 files; 1,982 passed and 16 skipped.
• typecheck for driver-sql and driver-turso: exit 0 each. tsc --listFilesOnly shows both changed test files are in each package's program.

Ablations

Every leg ran on the committed state through scripts/ablation-replace.mjs. In each, the anchor went from 1 hit to 0, and the restore was proven blob-equal to HEAD with an empty git diff HEAD. The driver-sql suite imports ./sql-driver.js (source), so those legs needed no build.

leg	mutation	result
A	final TRUNCATE checkpoint removed	3 red: WAL {16,384 + 1,334,912} vs {16,384 + 0}; the reader case's follow-up {16,384 + 296,672}; the NONE control's pair grew 1,318,384 → 2,555,376. 4 green.
B	one statement instead of chunks	1 red: the reader case, WAL growth 2,142,400 vs a bound of 618,496. 6 green.
C	fixed 1,000-page chunk instead of the derived one	1 red: the reader case, 2,142,400 vs 618,496. 6 green.
D	busy timeout not zeroed for the TRUNCATE	1 red: the reader case, elapsed 5,034.99 ms vs under 2,500. 6 green.
E	busy timeout not restored	1 red: the reader case, busy timeout 0 vs 5,000. 6 green.
F	the no-progress stop removed	the NONE control hung in the synchronous loop and was killed after 60 s (SIGKILL).
A, dist	leg A built into driver-sql's dist/, which driver-turso resolves	ablation-dist-preflight found the marker in 2 built files. driver-turso: 1 red (local face {32,768 + 280,192} vs {32,768 + 0}), 82 green. After the restore and a rebuild, --absent found the marker in none of the 6 built files, and the tree was clean.

In the first B–E runs, the red reader case also timed out its cleanup hook: the failed assertion left the reader's transaction open. The fixed case rolls the transaction back first. A rerun of leg B went red in 91 ms with no hook timeout.

Gates

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at effb34a8a derived 63 commands. All 63 ran, and every exit code was recorded before any pipe. 62 exited 0; check-empty-changeset --base origin/main exited 1 (next section).
• --ran: 63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN.
• The --ran pass printed a STALE TREE warning: origin/main moved 6 commits after the merge, and scripts/cross-package-test-inputs.mjs changed in that range. Of those 6 commits, only PR fix(driver-turso)!: new TursoDriver refuses syncUrl under a forced remote mode, and sync with no syncUrl (#20200) #20447 touches a driver: it changes the driver-turso constructor, and none of this PR's files. CI reads the merge ref.
• check:driver-conformance: 50 covered, 0 DEBT, 0 exempt, both before (8cdbe0c6e) and after (effb34a8a).
• pnpm lint is CI's run. The narrowed run: eslint --no-inline-config --format json over the 3 changed .ts files reports 3 files, 0 errors and 0 warnings. ESLint.isPathIgnored answers false for each, so all three are in pnpm lint's population. eslint.config.mjs sets no parserOptions.project and no typed rule, so this diff cannot move the verdict of an untouched file.

The one red gate: check-empty-changeset (a deliberate correction, for confirmation)

This PR edits .changeset/20106-reclaim-space-full-freelist.md, which exists on the merge base. The gate refuses that by name, and its own text sets out two classes. This is the deliberate correction class, not a collision.

• The removed paragraph says the -wal file "keeps its size until the last connection closes". After this PR it is truncated at the end of the call unless another connection is reading.
• That note has not been released, so restoring it from the base would publish the false sentence.
• The gate's prescription for this class is to leave it red and get the correction confirmed on the PR. skip-changeset is not applied and must not be: this PR publishes a patch.

For the seat: please confirm, or choose the other route. The other route is to restore the 20106 file from the merge base. The gate then goes green, but the release would carry that sentence beside this PR's own changeset, which describes the new behaviour.

Acceptance notes

• The file surface is widened by one file. The claim names .changeset/20426-*.md, and this PR also edits .changeset/20106-reclaim-space-full-freelist.md (one paragraph removed). It is the same defect, a mechanical removal, a card that has already landed, and the same changeset gate family.
• Behind a long reader, the bytes wait. When a reader holds a snapshot during the call, the database file keeps its size until a later checkpoint. LifecycleService.sweep() still lists the datasource as reclaimed. The next sweep that deletes rows returns it, and SQLite's auto-checkpoint or the last close returns it sooner. No producer is left worse off than on main, where the same reader left 197,580,000 bytes instead of 107,405,560.
• Partial progress is possible. Chunks commit one by one. Another process can take the write lock between two chunks, and then the next chunk waits up to the busy timeout and may throw with the earlier chunks already committed. This was not measured. A one-statement vacuum waited and threw the same way, all or nothing.
• Blocking is shorter, not gone. The call still blocks the event loop while it runs: 101 to 276 ms at 25,754 pages on this shared box, against 315 to 351 ms for PR fix(driver-sql, driver-turso): reclaimSpace() returns the whole SQLite freelist, not one page per call (#20106) #20425's single statement.
• The remote TursoDriver route, SqliteWasmDriver, LifecycleService and packages/spec are untouched.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql, touching 8 documentable anchor(s).

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

• content/docs/api/data-api.mdx (via page_size (literal, a string literal in reclaimBetterSqlite3))
• content/docs/data-modeling/drivers.mdx (via SqlDriver (symbol, a top-level class), reclaimSpace (symbol, a method of class SqlDriver))
• content/docs/data-modeling/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/deployment/cli.mdx (via busy_timeout (literal, a string literal in reclaimBetterSqlite3))
• 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))
• 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))

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

• 2 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 11 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 bea6d2ea3b355265e78da1a1fa131842c1e15fca → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 985984b9d1cf386b7c1c523cb1533d163cbfb81a — the merge of head effb34a8a32591d1360386c007eed7611e3222e7 into base bea6d2ea3b355265e78da1a1fa131842c1e15fca, 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 985984b9d1cf386b7c1c523cb1533d163cbfb81a && git checkout 985984b9d1cf386b7c1c523cb1533d163cbfb81a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin bea6d2ea3b355265e78da1a1fa131842c1e15fca effb34a8a32591d1360386c007eed7611e3222e7 && git checkout -B drift-repro bea6d2ea3b355265e78da1a1fa131842c1e15fca && git merge --no-ff effb34a8a32591d1360386c007eed7611e3222e7

node scripts/docs-audit/affected-docs.mjs --json bea6d2ea3b355265e78da1a1fa131842c1e15fca

⚠️ 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 bea6d2ea3b355265e78da1a1fa131842c1e15fca → 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: effb34a8a32591d1360386c007eed7611e3222e7
Local-runs: none

Inputs, and nothing else: card #20426 (body and all four comments: triage 5868711622, claim 5871282236, os-dev-report 5873136055, seat answer 5873177721); PR #20463 (body, file list of 5 files at +203 / −10, and the net diff against the merge base b285508188, the head being a merge of origin/main); the check-runs on the head, read at the start and again as the last step. Read-only throughout: git fetch plus git show / git diff / git grep on the shared checkout, REST GETs, and the installed sources of better-sqlite3 13.0.3 (SQLite 3.53.4) and knex 3.3.0 under node_modules. No checkout, build, test, gate re-run or probe.

① Derived judgments

Contract: IDataDriver.reclaimSpace (packages/spec/src/contracts/data-driver.ts: "Reclaim free space after bulk deletions (ADR-0057 §3.4) … the LifecycleService calls it best-effort after every sweep that deleted rows") and ADR-0057 §3.4. The signature (reclaimSpace(_options?: DriverOptions), a Promise of void) and the contract text are untouched; packages/spec, LifecycleService, the remote TursoDriver route and SqliteWasmDriver are not in the diff.

1. The chosen variant — RIGHT. reclaimBetterSqlite3 in sql-driver.ts is module-local and unexported (so is its BetterSqlite3Connection interface): no .d.ts member. It reads freelist_count and returns on 0; sizes the chunk as a quarter of the connection's page cache (cache_size negative → KiB × 1024 / page_size, positive → pages, floored at 1), which is 1,000 pages at better-sqlite3's compiled SQLITE_DEFAULT_CACHE_SIZE=-16000 (verified in deps/defines.gypi of the 13.0.3 build driver-sql resolves) and 4 KiB pages; per chunk PRAGMA incremental_vacuum(N) then wal_checkpoint(PASSIVE); then one wal_checkpoint(TRUNCATE) under busy_timeout = 0, the read-back value restored in finally. Every statement goes through exec() / pragma(), which step to completion. The seat's answer 5873177721 accepts this fourth variant and the module-local shape. The H2 table is the dev's one-run measurement, not re-measured here; what the tests pin are its ratios (WAL growth under a quarter of the freed bytes at a 100-page cache, elapsed under half the busy timeout, wal: 0 with no reader).

2. Never waits on a reader; cannot loop forever — RIGHT. In WAL mode a reader never blocks the vacuum's write transaction; a PASSIVE checkpoint never invokes the busy handler; the TRUNCATE checkpoint runs with the busy handler cleared, and SQLite reports a blocked checkpoint as the result row busy = 1, not as an error (OP_Checkpoint in the bundled sqlite3.c: if( rc!=SQLITE_BUSY ) goto abort_due_to_error; … aRes[0] = 1). Termination: free is a non-negative integer; every iteration either breaks (left === 0, or left at or above free for no progress) or strictly lowers free, so the loop runs at most free times. An auto_vacuum=NONE file frees nothing on its first chunk and exits on left at or above free; the NONE control test pins that the call resolves with the freelist unchanged, and ablation F (stop removed, the control hung for 60 s) is the dev's evidence that the guard is load-bearing.

3. busy_timeout restored on every path — RIGHT. The read-back and the zeroing come after the loop, so a throw from a chunk (a held write lock → SQLITE_BUSY after the connection's own timeout) never reaches the swap and leaves the timeout untouched; a throw inside the TRUNCATE runs the finally. knex's better-sqlite3 dialect passes no timeout (its acquireRawConnection sets only nativeBinding and readonly), so the value restored is the binding's default 5,000 ms (lib/database.js), which the reader case reads back after the call; ablation E is the dev's red for the restore.

4. A busy checkpoint, a held write lock, and what the sweep logs — RIGHT, as the PR body's H5 states. Reader present: the chunks commit, the freelist reaches 0, the PASSIVE checkpoints move only the frames the reader is past, the TRUNCATE answers busy as a row, the call resolves; LifecycleService.sweep() pushes the datasource to report.reclaimed and its one aggregate line counts it, exactly as on main; the sidecar's bytes leave at a later checkpoint (the next reclaim with free pages, SQLite's 1,000-frame auto-checkpoint, or the last close). Held write lock: the vacuum statement waits out the busy timeout and throws SQLITE_BUSY, as the single statement did on main (5,021 vs 5,014 ms measured); the sweep's existing warn ([lifecycle] space reclaim on datasource 'X' failed (…)) fires and the datasource is not listed. Nothing new is thrown and nothing new is logged.

5. The pooled connection is handed back — RIGHT. The acquireConnection / try … finally releaseConnection frame around the call is unchanged, and it releases on the throw paths above too. knex's sqlite pool default is { min: 1, max: 1 }, so the reader case's PRAGMA cache_size = -400 through driver.execute lands on the same connection the reclaim later uses. The pool-handback case still pins a write and a count after the call.

6. The early return on an empty freelist — RIGHT, with its consequence named: a call on an empty freelist sends nothing (the same shape as driver-sql: reclaimSpace() frees ONE freelist page per call, not the freelist — PRAGMA incremental_vacuum measured 300 → 299 pages on SQLite, so the lifecycle sweep never returns bulk-deleted space (ADR-0057 §3.4) #20106's remote route, and the sweep only calls after deletes), so a WAL that an earlier reader-blocked call left behind is not truncated by such a call; that is why the reader case frees 10 pages before its follow-up reclaim, and the empty-freelist controls (both journal modes) pin "nothing changes, sizes included".

7. Tests — RIGHT. driver-sql: 7 cases (4 before), every size the database file PLUS the -wal and every count from a second connection, as triage 5868711622 asked; the reader case now rolls its snapshot back before destroy (22ce9ad), so a red assertion cannot hang the cleanup hook. driver-turso: one local-face WAL-size case; the local face is SqlDriver on knex + better-sqlite3 (turso-driver.ts header; @objectstack/driver-sql at workspace:*), so it takes the same arm. In rollback-journal mode both checkpoints are no-ops and the DELETE case pins the result as before.

8. Wording, not a defect: the changeset heading and the PR title say "never waits on another connection". That is TRUE of the checkpoint, this card's subject, and of a WAL-mode reader; read alone it is overbroad, because against a held write lock (any journal mode), or a reader in rollback-journal mode, the vacuum statement still waits out the busy timeout, as on main. The note's third paragraph ("holds a read transaction") and the PR body's H5 carry the exact scope. No action for this verdict; tightening the heading would move the head.

The DELIBERATE CORRECTION — .changeset/20106-reclaim-space-full-freelist.md, pending on the merge base, one paragraph removed. The removed paragraph, "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", is FALSE once this change lands: the call's own PASSIVE and TRUNCATE checkpoints shrink the database file during the call and return the sidecar to 0 bytes before the call resolves (pinned as { file: pages × 4096, wal: 0 } while the driver is open, on both faces); only a reader's snapshot defers that, and then to a later checkpoint, not to the last close. Every remaining sentence of that note is still TRUE: the heading (whole freelist, not one page per call); Clause-②: no; the ADR-0057 §3.4 producer sentence; "it runs PRAGMA incremental_vacuum, and that statement frees one page per step" (SQLite's property, and the chunked form is the same PRAGMA); the better-sqlite3 bullet ("drives that binding through its own exec() … 300 → 0, and the file shrinks by those pages": still exec(), still 300 → 0, and the file now shrinks while open as well); the remote-route bullet and its hosted-server caveat (untouched by this PR); the SqliteWasmDriver sentence (untouched); "Nothing to migrate: reclaimSpace() keeps its signature, and a database whose auto_vacuum mode is not INCREMENTAL still reclaims nothing, as before" (the NONE control pins it). Confirmed in writing here: keep the removal; ⛔ no skip-changeset (this PR publishes a patch, and the label would exempt the whole job that names this class).

② Semver level

.changeset/20426-reclaim-space-wal-sidecar.md: @objectstack/driver-sql: patch, Clause-②: no — RIGHT. The diff changes no public surface: the method keeps its signature, the helper and its interface are unexported, and the only .d.ts movement is one doc-comment sentence on reclaimSpace. No new exported symbol, key or value, so patch is what the workflow's level rule requires. driver-turso changes only a test, so it owes no changeset (and it shares the fixed group in any case). Clause-②: no is right: the fix brings behaviour to what the contract already declares and moves no contract text; the PR body, the changeset and claim 5871282236 agree on the line.

Changeset sentences (20426): heading — TRUE of the checkpoint and of a reader, overbroad against a held write lock (①.8). Paragraph 1 (the WAL default; the whole freelist returned but the bytes left in the sidecar; the 25,754-page readings; the sweep listing the datasource as reclaimed) — TRUE: card #20426 and H1, and 103,149,568 + 4,255,992 = 107,405,560 checks. Paragraph 2 (chunks of a quarter of the page cache, 1,000 at the default; a PASSIVE checkpoint per chunk; one TRUNCATE at busy timeout 0 that never waits on another connection; 107,405,560 → 16,384 while open) — TRUE against the code; the size is the dev's, and the WAL case pins wal: 0 while open. Paragraph 3 (a reader: the call returns without waiting, 47 to 66 ms; a waiting TRUNCATE blocked the process for the 5-second timeout; the pages are off the freelist and the bytes leave at a later checkpoint; the pair no longer grows, 107,405,560 against 197,580,000 for one statement) — TRUE against the code; 103,149,568 + 94,430,432 = 197,580,000 checks, and the reader case pins elapsed under 2,500 ms and WAL growth under a quarter of the freed bytes. Paragraph 4 (rollback-journal mode as before; remote route and SqliteWasmDriver unchanged; signature kept) — TRUE by the file list and the DELETE case.

PR-body sentences. "What was wrong" — TRUE. "What changed": the four helper steps, exec() / pragma() stepping to completion, every other client on knex.raw, the .d.ts gaining one sentence, the 20106 paragraph removed and the gate red on purpose — TRUE against the diff. H1 — TRUE (the card's premise, re-measured through SqlDriver by the dev). H2: the table and the chunk-size sweep are the dev's one-run measurements, consistent with the code and with the ratios the tests pin, not re-measured (read-only brief); its four conclusions — PASSIVE never shrinks the sidecar, a waiting TRUNCATE blocks this synchronous binding, the pick is the only row that both returns the space and never waits, no variant shrinks the file under a reader — TRUE by SQLite's checkpoint semantics; the derived chunk (not a fixed 1,000) is what ablation C pins. H3 (resolveSqliteJournalMode() answers wal unless configured; the DELETE control unchanged) — TRUE, verified in sql-driver.ts. H4 (the local Turso face takes this arm; the remote route untouched) — TRUE. H5 — TRUE (①.4). "The fix through SqlDriver" table — the dev's readings, consistent with the WAL, DELETE and reader cases. "Tests": 7 cases (4 before) — TRUE, counted; each bullet names an assertion that exists. Suite counts, typecheck, the 63-command gate run with one red, conformance 50 / 0 / 0, the narrowed lint — the dev's runs, not re-run; the required CI contexts are the gate verdicts (③). Ablations A to F and A-dist — the dev's, each naming the assertion that went red and the blob-equal restore; consistent with the tests. "The one red gate" — TRUE: Check Changeset is not a required context (the main rulesets require TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance (live PG + MySQL), Lint & Repo Gates and Governed Surface Queue Guard), its only failure annotation is the foreign-changeset refusal naming the 20106 file, and lint.yml runs only the self-test halves. Acceptance notes — TRUE, answered in ③.

③ Boundary flags

Dev deviations (report 5873136055): the file surface widened by .changeset/20106-* — admitted by the seat's answer 5873177721; the file's only change is the one paragraph, judged above. The module-local helper — accepted (5873177721), judged right (①.1). The fourth variant — accepted (5873177721), judged right (①.1, ①.2). Attribution trailers — not a contract matter; recorded.

open_questions 1 (keep the correction, or restore the paragraph) — answered A by the seat (5873177721); this record is the written confirmation. B is refused: two notes in one release would contradict each other.

Acceptance-note carriers:

• A reader holding a snapshot keeps the file's size until a later checkpoint, and the sweep still lists the datasource as reclaimed — ANSWERED, not escalated. The contract and ADR-0057 §3.4 make reclaim best-effort; report.reclaimed means the driver reclaimed space after this sweep, and the freelist is 0; the OS bytes follow at the next checkpoint; and the pair no longer grows under a reader (107,405,560 held, against 197,580,000 on main). No wrong answer at a public door; the carrier stays as an Acceptance note, no card.
• Chunks commit one by one under a competing writer — ANSWERED, not escalated. Committed chunks are real reclaim; the throw is the same SQLITE_BUSY after the same timeout as main's single statement; it leaves busy_timeout untouched, the pooled connection is released, the sweep logs its existing warning, and the next sweep re-derives the set from the same deletes. Unmeasured, as the dev says; no producer is worse off.
• Blocking shorter, not gone — ANSWERED: the binding is synchronous by design and the sweep already ran the single statement synchronously (315 to 351 ms); no new class.
• Not measured, carried as stated: a hosted libSQL server (driver-sql: reclaimSpace() frees ONE freelist page per call, not the freelist — PRAGMA incremental_vacuum measured 300 → 299 pages on SQLite, so the lifecycle sweep never returns bulk-deleted space (ADR-0057 §3.4) #20106's note, untouched here) and the write-lock partial-progress case.
• Check Changeset red — by design (①); ⛔ skip-changeset is not applied and must not be.

Check-runs on effb34a8a, final read 2026-09-28T15:37:33Z (33 runs; the first read at the start of this review had 31, with 14 in progress): 25 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke — path- or opt-in-skipped), 1 failure, 4 in progress. Required contexts: TypeScript Type Check success (and its four Type Check · lanes); Build Core success; Dogfood Regression Gate success (rollup and 3 / 3 shards); Temporal Conformance (live PG + MySQL) success; Governed Surface Queue Guard success; Test Core — shards 2, 3 and 4 success, shards 1, 5 and 6 IN PROGRESS; Lint & Repo Gates IN PROGRESS. The one failure is Check Changeset, the expected red: its failure annotation is the foreign-changeset refusal on .changeset/20106-reclaim-space-full-freelist.md, the DELIBERATE CORRECTION class confirmed in ①, and it is not a required context. An in-progress run is recorded as in progress, not as passed: this verdict is the contract's, and a red among the four still running is a gate verdict this record does not override.

Implemented-by: claude/issue-20426-reclaim-space-wal-checkpoint
Reviewed-by: session_01N8TPEsoJxPsdSdNKGnNGEN

VERDICT: PASS