# Current-head compaction proof

PR: [#20877](https://github.com/pingdotgg/t3code/pull/20877)
Head: [c36020967f](https://github.com/pingdotgg/t3code/commit/c36020967fad380d8eeb2a6e580ca11f37dd8107)
Base merged: [771fd93fc5](https://github.com/pingdotgg/t3code/commit/771fd93fc591de5fe1bfd66cf1b4faa39eb8547c)
Machine: headless Linux, Node 24, isolated task worktree state.
Date: 2026-10-19 UTC.

Publication note: the contributor concurrently merged newer main. The maintainer integrated that update and main through [08b1cbebf2](https://github.com/pingdotgg/t3code/commit/08b1cbebf2e8439a8481b58ec316fa09f23208c4), resulting in [2cc6fd9e69](https://github.com/pingdotgg/t3code/commit/2cc6fd9e69d1da7f4f3c50e386e0441d37c84ae2). All seven compaction PR files are byte-for-byte identical to the measured head; changes between these heads come only from main. The integrated head passes 149 tests across the five affected persistence/runtime/WebSocket suites. Measurements below were captured at the measured head, before this later merge.

## Real app background maintenance

Started the actual server and Vite web app through the worktree dev runner. Paired a T3 Browser panel tab, loaded the actual chat client with its startup project/thread, and kept the app connected. No provider turn was started and no production data was used.

Stopped the task-owned server before preparing fixtures. Seeded 100,000 synthetic legacy command receipts plus their completed-import marker into the migrated isolated database. These receipts are a maintenance workload, not a simulation of business commands or event-history replay. The actual scheduled DatabaseStorage loop began after its normal one-minute startup delay; no production source, schedule, clock, or pacing behavior was patched.

A separate read-only connection sampled only the synthetic receipt count every 500 ms. The observed removal window was 17:26:22.085–17:26:46.110 UTC. The app's server logged successful completion at 17:26:45.645: deletedEventCount=0, deletedReceiptCount=100000. The synthetic receipt count reached zero.

From the paired real browser, sampled the authenticated /api/orchestration/shell endpoint through the normal Vite proxy, using the current orchestration protocol header. Each request consumed its full body, with 200 ms between samples.

| Scope | Requests | Successful | Median | p95 | Maximum |
|---|---:|---:|---:|---:|---:|
| Full run, before/during/after | 450 | 450 HTTP 200 | 11.5 ms | 16.2 ms | 34.6 ms |
| Observed receipt-removal window | 113 | 113 HTTP 200 | 11.0 ms | 14.0 ms | 18.3 ms |

After receipt compaction completed, a separate authenticated WebSocket to /ws?orchestrationProtocol=2 sent 80 Effect RPC Ping frames: 80 Pong replies, median 1.8 ms, p95 2.8 ms, maximum 4.9 ms. This WebSocket measurement was AFTER compaction, not during it; it is a connection sanity check only.

## Actual offline doctor

Copied the stopped isolated database before the background run. Set auto_vacuum=NONE on this copy so the real doctor --fix command would choose repair. No service installed against another base directory was stopped; the CLI's existing base-directory guard remained in effect.

Actual CLI output:

    Database: 18.3 MiB, 0 KiB reclaimable.
    Reclaiming database space. This can take several minutes...
    Done: 18.3 MiB -> 760 KiB, 0 superseded events removed.

Whole CLI wall time was 7.184 seconds, including startup/migrations/verification/VACUUM. Read-only inspection confirmed zero synthetic receipts remain and auto_vacuum=2 (incremental).

Then opened the copied database in another SQLite connection and ran the actual doctor command again. It exited 1 with DatabaseInUseError, instructing the user to stop the server/desktop app, and the underlying database-is-locked error. This confirms the offline exclusive-lock refusal path. The earlier stopped-copy run had already succeeded.

## Focused before/after evidence and limits

The tests-only takeover revision reproduced an offline duty-cycle sleep of 270 ms where none should occur (48 pass, 1 failure). The implementation revision passes all 49 affected cases, plus three existing DatabaseStorage cases and two existing replay/caller cases: 54 executed tests. Reader-routing and pacing mutations were separately shown to fail assertions. The real worker test checks bounds/event/receipt discovery off the main SQLite connection, writer deletes, and exact deletion counts; the background integration test checks retained data, cursor state, foreground commits during a rest, and initial scan bounds.

The live workload above covers receipt deletion and full-app HTTP responsiveness on this Linux machine. It does not benchmark large JSON event payloads, a busy/slow disk, reader-worker fallback, a blocking writer DELETE/checkpoint, or arbitrary foreground WebSocket RPCs during compaction. It does not establish a complete fix for [#20203](https://github.com/pingdotgg/t3code/issues/20203). Routing/pacing reduces discovery blocking and average duty; it cannot preempt one synchronous writer statement. No macOS, Windows, Electron, iOS, Android, or relay/tunnel performance run was performed. Event retention and replay were proved by focused integration tests, not direct projection fixtures.