A commit that waits for another commit's disk sync fails with TimeoutException after 500 ms: LockTimeout.Default is tuned for an unsynced WAL #303

What happens

LockTimeout.Default gives a writer 500 ms to take the commit lock and, in single-file mode, the file-wide write lock that every collection shares (StorageEngine.CreateCollectionWriteLock returns _dataWriteLock). An auto-committing InsertAsync holds that lock through its commit, so the second and third writer wait for the first writer's commit, and the commit waits for the disk.

Today the commit is "hand the WAL to the OS" (no sync, #260), which takes well under a millisecond, and the doc comment on LockTimeout.Default says so: "observed p99 well under 500 ms". The CI runs show the budget is already tight when the disk is shared: 4 of the last 80 runs of the test workflow failed with Timed out acquiring collection lock (Insert) or Timed out acquiring commit lock (GroupCommit) in tests with 3 to 8 in-process writers on an otherwise idle database (PR #302 makes those tests open with a longer timeout; it does not change the default).

With #280 (fix for #260) a commit syncs the WAL before it is acknowledged. The PR measured 4.5 ms mean / 7 ms p99 per commit on Apple Silicon; a consumer SSD under load or a network disk is in the tens of milliseconds, and a cloud VM disk can stall for hundreds. Three writers sharing the lock then wait 2 × sync each, and any stall longer than the budget surfaces as TimeoutException from InsertAsync, with the transaction rolled back. The application cannot tell this from a deadlock.

Why it matters

• The exception is thrown for a healthy database doing exactly what it is told. SQLite's busy_timeout (the comparison the doc comment draws) is 0 by default but every ORM and most applications set seconds; LiteDB's default is 1 minute.
• The fail-fast argument in the doc comment ("rather than leaving threads blocked for seconds, starving the thread-pool") applies to synchronous waits; the write paths wait with WaitAsync, which blocks no thread.
• A timeout that is shorter than a plausible disk stall turns durability (fix(wal): sync the WAL to disk before a commit is acknowledged #280) into availability failures, which is the trade-off fix(wal): sync the WAL to disk before a commit is acknowledged #280 was careful not to make silently.

Proposal

Pick one, or both:

1. Raise LockTimeout.Default.WriteTimeoutMs (and ReadTimeoutMs) to something no healthy disk reaches, e.g. 5 s like the WAL's own writeTimeoutMs default, and keep Immediate for callers who want SQLITE_BUSY semantics. Document that a TimeoutException means a stuck writer, not a slow one.
2. Keep 500 ms but exclude the wait for an in-flight commit's sync from the budget: the lock waiter's clock starts when the holder has finished writing to disk. That is more work for little gain over 1.

Either way the doc comment's "p99 well under 500 ms" needs to be re-measured with WalSyncMode.Full.

Connected

• WAL commits are never flushed to disk: a power loss drops acknowledged commits and can leave documents pointing at freed pages #260 / fix(wal): sync the WAL to disk before a commit is acknowledged #280: the fsync that makes the budget tight.
• Epic: reliability before features — durability, AOT, query correctness and oracle coverage #288 (reliability epic), P0 durability section.
• PR test: make the concurrency tests independent of the runner's load #302: the tests that hit this on CI now open with a 30 s timeout so that a timeout can only mean a deadlock.