`WriteAhead#advanceTxId` crashes with `TypeError: Cannot read properties of null (reading 'id')` when `#readTx()` returns null — unlike `#readAllTx()`, it has no guard

[darshanp40]

Summary

WriteAhead.js#advanceTxId() can crash with TypeError: Cannot read properties of null (reading 'id') when the local WAL-file read fallback (#readTx()) returns null. The identical call is correctly guarded in #readAllTx() but not in #advanceTxId(). The crash happens inside jUnlock → rejoin(), gets caught by OPFSWriteAheadVFS's blanket per-method catch, and is reported to the application as SQLITE_IOERR_UNLOCK — which SQLite renders as the generic, undiagnostic string "disk I/O error".

Confirmed present in 2.0.3 (currently pinned) and still present, unchanged, in the latest published 2.0.4.

The bug

// #readAllTx() — correctly guarded
*#readAllTx() {
  while (true) {
    const tx = this.#readTx();
    if (!tx) break;         // null is treated as "nothing more yet"
    yield tx;
  }
}

// #advanceTxId() — same call, no guard
#advanceTxId(options = {}) {
  let didAdvance = false;
  while (this.#mapIdToPendingTx.size) {
    const nextTxId = this.#txId + 1;
    let tx;
    if (this.#mapIdToPendingTx.has(nextTxId)) {
      tx = this.#mapIdToPendingTx.get(nextTxId);
      this.#mapIdToPendingTx.delete(tx.id);
      this.#skipTx(tx);
    } else {
      tx = this.#readTx();   // can return null (see #readTx's own @returns {Transaction?})
    }
    this.#activateTx(tx);    // <-- crashes here if tx is null
    didAdvance = true;
  }
  ...

#activateTx:

#activateTx(tx) {
  this.#mapIdToTx.set(tx.id, tx);   // TypeError: Cannot read properties of null (reading 'id')
  ...

How we believe this triggers

#advanceTxId is entered from #handleMessage's 'tx' branch (a peer connection broadcast a transaction) and from rejoin(). The while (this.#mapIdToPendingTx.size) guard only confirms some pending transaction exists — not that the specific next txId this connection needs is available. When it isn't in #mapIdToPendingTx, the code falls back to reading straight from the WAL file via #readTx().

#readFrame()'s own comments note two of its null-return paths are "not necessarily an error, could be from a restart without truncation" — specifically a salt/generation mismatch against #activeHeader. That's exactly what happens when another connection has called #swapActiveFile() (rotated the active WAL file) and this connection hasn't yet caught up via #followFileChange: it receives a broadcast for a transaction after the swap, tries to read the transaction at the swap boundary with its stale salt, #readFrame sees the mismatch and returns null, and #advanceTxId doesn't handle that — #readAllTx would have.

Observed impact

Once this fires, the connection's state isn't repaired (the pending-tx gap is never resolved), so every subsequent rejoin() (i.e. every transaction end) hits the identical crash. In one captured production session this repeated 46 times in the visible log plus 16,014 more collapsed by the browser console — i.e. it never recovers for the rest of the session, and each occurrence surfaces to the application as an opaque "disk I/O error" with no distinguishing detail (SQLITE_IOERR_UNLOCK, code 2058).

Suggested fix

Mirror #readAllTx()'s handling in #advanceTxId():

} else {
  tx = this.#readTx();
  if (!tx) break;   // or: wait/retry, if a peer catch-up mechanism exists
}
this.#activateTx(tx);

Happy to open a PR if that's the preferred direction — wanted to raise it for input first since I'm not certain whether break (stop advancing, try again later) or an active wait/retry against the salt mismatch is the intended recovery here.

Environment

• @journeyapps/wa-sqlite 2.0.3 (also confirmed present in 2.0.4)
• OPFSWriteAheadVFS, enableMultiTabs: true, WAL mode
• Chrome on macOS, multi-tab usage

[rhashimoto]

Thanks for the bug report and detailed investigation!

It seems like you have some ability to reproduce the problem, since you were able to see it on different versions. Are you able to catch it in the debugger when #readTx() returns null? If you can, I am interested in the values of this.#txId and the keys in this.#mapIdToPendingTx when this happens. I don't think I agree with your failure scenario and I have an alternative guess. I'll explain when I have more time later today.

[rhashimoto]

#advanceTxId is entered from #handleMessage's 'tx' branch (a peer connection broadcast a transaction) and from rejoin(). The while (this.#mapIdToPendingTx.size) guard only confirms some pending transaction exists — not that the specific next txId this connection needs is available. When it isn't in #mapIdToPendingTx, the code falls back to reading straight from the WAL file via #readTx().

This is a correct understanding of the code. It doesn't list all the ways that #advanceTxId() can be called, but that may not be relevant here.

#readFrame()'s own comments note two of its null-return paths are "not necessarily an error, could be from a restart without truncation" — specifically a salt/generation mismatch against #activeHeader. That's exactly what happens when another connection has called #swapActiveFile() (rotated the active WAL file) and this connection hasn't yet caught up via #followFileChange: it receives a broadcast for a transaction after the swap, tries to read the transaction at the swap boundary with its stale salt, #readFrame sees the mismatch and returns null, and #advanceTxId doesn't handle that — #readAllTx would have.

I don't think this should happen. #readTx() should never return null when called within #advanceTxId(). As noted, when within that loop there is a pending transaction received by broadcast but it is not the next one in sequence. If there is any transaction that the connection has not yet incorporated - and #mapIdToPending is telling us that there is - #readTx() should succeed. So the problem isn't that a null return isn't handled properly; the problem is what makes it happen at all.

One might think that there could be a race condition where another connection has written a transaction to the new WAL file and this connection can't read it yet. Technically, OPFS does not guarantee this, but POSIX does:

Writes can be serialized with respect to other reads and writes. If a read() of file data can be proven (by any means) to occur after a write() of the data, it must reflect that write(), even if the calls are made by different processes.

I expect OPFS to have POSIX behavior when Chrome runs on a POSIX platform, unless you're using some non-POSIX filesystem for your Chrome data.

So the problem is:

1. Someone (e.g. another connection) corrupted the WAL, or
2. A bug in #readTx() is failing to read a valid transaction, or
3. #advanceTxId() is incorrect that another transaction can be read.

My current suspicion is (3). I'm wondering if #mapIdToPendingTx contains a transaction that is not new but instead is old, which would fool #advanceTxId() into making that #readTx(). That could be confirmed by my debugging request in my previous message. If we can't do that for any reason - including that the debugger upsets the timing needed to expose the bug - then I could try a quick hack to detect and patch #mapIdToPendingTx to see if that helps while I look for an underlying cause.

[darshanp40]

Thanks for digging into this so quickly, and for the correction on the OPFS/POSIX write-ordering point — that's a fair pushback, we hadn't reasoned about it from that angle and it does rule out the race we originally proposed as an explanation.

To be upfront: we don't currently have a live debugger session reproducing this on demand — everything we've traced so far comes from post-hoc production log captures (browser console + a separate SharedWorker console capture from two different affected users), not an interactive repro we can attach to and inspect state in real time. We also don't currently log this.#txId or #mapIdToPendingTx's keys anywhere, so we can't answer your question from what we already have.

That said, we do see this fairly regularly across our user base (not a one-off), so we're likely better positioned to gather the exact evidence you're asking for from real occurrences than to force a one-off local repro. If it's useful, we'd like to add temporary targeted diagnostic logging — dumping this.#txId and [...this.#mapIdToPendingTx.keys()] (plus whatever else would help distinguish your three hypotheses) at the exact point #readTx() returns null inside #advanceTxId() — ship it behind a flag to a slice of our users, and report back what we capture from a genuine occurrence. Let us know what specifically would be most diagnostic to log and we'll get it out.

We're also happy to test whatever hack/patch you put together against our conditions, given we can reproduce the general multi-tab/multi-connection environment this shows up in reasonably often, even without being able to trigger the exact null on demand yet.

Given your point (3), we'll hold off on treating if (!tx) break as anything more than a stopgap against the crash — we don't want to ship something that just hides a deeper state bug in #mapIdToPendingTx.

One more piece of context that seems directly relevant to your POSIX-write-ordering point: we're using OPFSWriteAheadVFS with enableMultiTabs: true and additionalReaders: 2. Tracing your SDK's actual worker topology (not assuming — checked WASQLiteOpenFactory.ts/vfs.ts), here's how connections get created for us:

vfsRequiresDedicatedWorkers(OPFSWriteAheadVFS) === true
  → each openDatabaseWorker() call spins up its own DEDICATED Worker
    (not a shared one — useShared = !needsDedicated && enableMultiTabs = false)

per tab, on PowerSyncDatabase construction:
  writerWorker  = openDatabaseWorker(readonly=false)   // 1 dedicated Worker
  readerWorkers = [openDatabaseWorker(readonly=true) × additionalReaders]  // N more dedicated Workers

  each of these (1 + N) dedicated Workers independently:
    opens the SAME OPFS files: <dbFilename>.db, <dbFilename>-wa0, <dbFilename>-wa1
    calls fileHandle.createSyncAccessHandle({ mode: 'readwrite-unsafe' })  // OPFSWriteAheadVFS.js:923-925
      — this is what allows concurrent handles on the same WAL file at all
    constructs its own WriteAhead instance:
      acquires "<dbFilename>#ckpt" Web Lock briefly to read/init WAL headers
      subscribes BroadcastChannel("<dbFilename>#wa") for peer tx/checkpoint messages
      holds its own #waHandles open for the connection's lifetime

→ with 2 tabs open, additionalReaders=2, that's 2 × (1+2) = 6 separate dedicated
  Worker processes, each with its own WriteAhead instance, all independently
  reading/writing the SAME two physical WAL files, coordinating ONLY via the
  Web Lock + BroadcastChannel protocol inside WriteAhead.js — not via OS/browser
  handle exclusivity, since readwrite-unsafe explicitly opts out of that.

Separately, ONE SharedWorker (per origin) runs the SYNC engine
(SharedWebStreamingSyncImplementation) — this does NOT open OPFS itself. It
acquires a "streaming-sync-sync-<dbFilename>" Web Lock to elect which tab's
WRITER connection currently lends it a port, and issues sync-driven
reads/writes through THAT tab's writer dedicated-Worker (which is one of the
6 in the example above). That writer's resulting commit() is what gets
broadcast to the other 5.

Given that, the specific question your POSIX argument raises for us: does Chrome's OPFS readwrite-unsafe mode actually guarantee POSIX write-then-read ordering across separate FileSystemSyncAccessHandle instances on the same file (not just within one handle)? That mode's whole premise is opting out of the browser's normal single-handle exclusivity, so we're not certain the ordering guarantee you're citing (which we'd assume holds for a single handle, or for the OS file layer generally) necessarily extends to concurrent readwrite-unsafe handles the same way — that seems like it could be a fourth possibility alongside your three, if Chrome's implementation of that mode doesn't give full cross-handle visibility guarantees. We don't have evidence either way, just flagging it since it's specific to the locking mode this VFS uses.

[rhashimoto]

Thanks for all the info; that's very helpful!

We're also happy to test whatever hack/patch you put together against our conditions, given we can reproduce the general multi-tab/multi-connection environment this shows up in reasonably often, even without being able to trigger the exact null on demand yet.

I'll try to write a mitigation for cause (3).

Given your point (3), we'll hold off on treating if (!tx) break as anything more than a stopgap against the crash — we don't want to ship something that just hides a deeper state bug in #mapIdToPendingTx.

My concern about ignoring the null return as a workaround is that if we are dealing with cause (2), then instead of crashing it might let multiple connections write with inconsistent views of the database. The specific case I'm thinking about is when #advanceTxId() is called from isolateToWrite(). If #readTx() returns null then it is failing to read a transaction that another transaction has written, and if it then proceeds to write there are two connections that think they wrote the transaction at that point. Note that if the problem has cause (1) then the database is already corrupt and things can't really get any worse than they already are, and if the problem has cause (3) then we aren't in this scenario.

Given that, the specific question your POSIX argument raises for us: does Chrome's OPFS readwrite-unsafe mode actually guarantee POSIX write-then-read ordering across separate FileSystemSyncAccessHandle instances on the same file (not just within one handle)?

The OPFS spec for FileSystemSyncAccessHandle does not guarantee it. However, I think that the intended implementation is with platform file descriptors, and the behavior was left unspecified to allow whatever behavior the platform has.

I asked GitHub Copilot to examine the Chromium implementation, and it said:

Yes, writes to one FileSystemSyncAccessHandle are immediately visible to reads on another handle for the same file. This is achieved through:

Explicit offset-based I/O (no hidden file position state)
Direct filesystem operations bypassing renderer buffering
OS-level file consistency guarantees

The only exception would be if the underlying filesystem being used is not POSIX-compliant or doesn't provide proper concurrent access semantics.

That's not a guarantee either, but it is something.

An incognito context apparently does add a layer of IPC to use the file descriptor. GitHub Copilot didn't think that changed the behavior at issue, but it might be worth checking if that correlates with the failures, or if users are putting Chrome's data in a weird place that might not be POSIX-compliant, like network storage or FUSE.

[rhashimoto]

I'll try to write a mitigation for cause (3).

The patch is on a branch here:

wa-sqlite/src/examples/WriteAhead.js

Lines 549 to 559 in 6e6da12

	// This is a mitigation against a possible bug in the WAL implementation.
	// There should never be any pending transactions with
	// `tx.txId <= this.#txId`, but
	// https://github.com/rhashimoto/wa-sqlite/issues/345
	// could be explained if this somehow happened.
	for (const key of this.#mapIdToPendingTx.keys()) {
	if (key <= this.#txId) {
	console.warn(`removing invalid pending transaction ${key} <= ${this.#txId}`);
	this.#mapIdToPendingTx.delete(key);
	}
	}

If it's useful, we'd like to add temporary targeted diagnostic logging — dumping this.#txId and [...this.#mapIdToPendingTx.keys()] (plus whatever else would help distinguish your three hypotheses) at the exact point #readTx() returns null inside #advanceTxId() — ship it behind a flag to a slice of our users, and report back what we capture from a genuine occurrence.

I think that data would tell us definitively if it is or is not (3), plus it might uncover something strange that isn't even on our radar.

If it's (1) or (2) (or a failure mode I haven't accounted for) it will likely be hard to distinguish between them without access to WAL files, which is probably much more difficult for you to get.

[darshanp40]

Thanks again for the guidance here. We have patched this mitigation into our testing environment now, following the stale pending transaction cleanup approach rather than the earlier null-read break.

We also added diagnostics around the stale pending transaction cleanup and the remaining null #readTx() path in our PowerSync OPFSWriteAheadVFS setup, and routed those logs through our app logger/Sentry pipeline. We'll monitor the testing environment for these logs and report back with anything useful if the condition reproduces again.

[darshanp40]

We now have a production occurrence after deploying the stale-pending-transaction mitigation and targeted diagnostics.

The captured state was consistent across 262 diagnostic events over approximately 13 minutes:

{
  "txId": 4703,
  "nextTxId": 4704,
  "pendingCleanupCount": 0,
  "removedPendingTransactionCount": 0,
  "pendingKeys": [4705, 4706, 4707, "..."],
  "activeOffset": 32,
  "activeHeader": {
    "nextTxId": 4704,
    "salt1": 4225561170,
    "salt2": 3208497155
  },
  "options": {
    "autoCheckpoint": true
  }
}

At the first occurrence, the pending keys were 4705 through 4733. They continued accumulating while transaction 4704 remained missing. At the final captured occurrence, there were 197 later pending transaction IDs.

There were no stale pending transaction IDs at or below this.#txId. Both cleanup counters remained zero for every captured occurrence. Therefore, the mitigation had nothing to remove, and #readTx() still returned null.

Mitigation confirmation

The patched cleanup emits the following diagnostic when it actually removes one or more invalid pending transactions:

wa-sqlite: removed invalid pending transactions in #advanceTxId

That cleanup event was not present in either captured log. Because it is emitted at debug level and production logging may filter debug records, we are not relying on its absence alone. The stronger confirmation comes from the error-level null-read diagnostics: all 262 occurrences contained both of the following counters, and both remained zero throughout the incident:

{
  "pendingCleanupCount": 0,
  "removedPendingTransactionCount": 0
}

These counters are cumulative per WriteAhead instance. Every captured null-read record reported zero, confirming that the emitting instance had not found or removed an invalid pending transaction before that failure. This is why the mitigation did not change the outcome for this production occurrence.

The active WAL header and local state both agreed that the next transaction should be 4704:

• this.#txId === 4703
• Expected next transaction: 4704
• activeHeader.nextTxId === 4704
• Pending transactions start at 4705
• #readTx() returns null while trying to obtain 4704

The subsequent failure sequence was:

1. #readTx() returned null inside #advanceTxId().
2. The existing failure path attempted to activate the null transaction.
3. This raised TypeError: Cannot read properties of null (reading 'id').
4. SQLite surfaced disk I/O error.
5. PowerSync upload retries repeatedly failed with the same I/O error.

The log capture contained:

• 262 structured null-read diagnostics
• 37 Cannot read properties of null (reading 'id') exceptions
• 104 browser-side disk I/O error occurrences
• 111 SharedWorker upload failures caused by disk I/O error

This appears to rule out cause (3), involving old entries in #mapIdToPendingTx. It seems to leave either a missing or incomplete WAL transaction, or #readTx() failing to read a valid transaction.

[rhashimoto]

This is great, thank you!

{
  "txId": 4703,
  "nextTxId": 4704,
  "pendingCleanupCount": 0,
  "removedPendingTransactionCount": 0,
  "pendingKeys": [4705, 4706, 4707, "..."],
  "activeOffset": 32,
  "activeHeader": {
    "nextTxId": 4704,
    "salt1": 4225561170,
    "salt2": 3208497155
  },
  "options": {
    "autoCheckpoint": true
  }
}

At the first occurrence, the pending keys were 4705 through 4733. They continued accumulating while transaction 4704 remained missing.

A missing transaction in #mapIdToPendingTx can just be a race condition, where the broadcast transaction isn't received before the connection tries to bring things up to date. But that explanation seems impossible here because dozens of broadcasts for subsequent transactions have arrived. That message appears to be missing entirely (i.e. not just late).

A missing message isn't entirely unexpected...but it should almost never happen. The way this is expected to occur is when a connection dies in the very small window between writing a transaction to the WAL and broadcasting its existence. I have a hard time believing that is what you're seeing so consistently.

I'm thinking that it's more likely that a connection that was supposed to write transaction 4704 instead wrote transaction 4705, and that mis-numbering is probably related to the WAL file change. If the same connection also wrote all the subsequent transactions, it wouldn't be affected by the gap and could produce this invalid state.

Now I need to stare at the code for a bit. Will keep you posted.

[rhashimoto]

I'm thinking that it's more likely that a connection that was supposed to write transaction 4704 instead wrote transaction 4705, and that mis-numbering is probably related to the WAL file change.

I haven't been able to find a way for this to happen just by examining the code. I looked both on my own and had Antigravity suggest possible scenarios and none of them look feasible. I could have a blind spot reading my own code, so this doesn't definitively rule out this cause, but I'm moving on for now.

Because the problem repeats on retry, I think we can conclude this is not a race condition caused by non-POSIX behavior. Even if a write on a different handle isn't immediately visible, it's going to be there after 262 tries over 13 minutes.

I have been manually tracing transaction propagation between connections, and it works exactly as expected with everything I tried. It seems like the problem must either be triggered by some unusual state combination, or it's a race condition.

I'm probably 0 for 2 on my guesses at the cause, so my intuition hasn't been great so far, but now I'm wondering if the VFS failed to handle some earlier error properly (e.g. out of storage quota) and that left it in an unexpected state. @darshanp40 do your logs show anything unusual happening before these errors start? Also, do you know whether or not this is an incognito context (which would have a very restricted quota)?

[darshanp40]

@rhashimoto I have shared the complete browser and shared worker logs with the powersync team today. They will share it with you offline.

[rhashimoto]

@darshanp40 I got the log, thanks! It doesn't appear that any strange behavior precedes the null crash. Unfortunately, that hasn't put me significantly closer to understanding the cause.

I would like to try generating some more state that I will store in the instance and ask you to add that to the data you capture when the crash occurs. Does that sound okay?

[darshanp40]

@rhashimoto Till the time we figure out the root cause and fix for this, I will try to put a DB file rotation logic in order to unblock our production users. Let me know if you think that's going to be problematic in any sense. Your inputs matter a lot.
In a parallel world we are also getting an error saying "database disk image is malformed" for some users which ultimately again goes down to the "disk I/O error".
I have put Claude for doing an independent research on this since it has connectivity to our Sentry, so that we can figure out a deterministic way of reproducing this error, let's see what it comes up with.

[simolus3]

@bean1352 found a way to reproduce this that triggers it fairly reliably in a playwright session. It is in this repository on the disk-io-repro branch. The demo uses the PowerSync SDK, but I removed everything that connects to an external service so I hope this is the same underlying issue ¹.

For me at least, following the steps in REPRO.md reproduces it pretty consistently (around 80% of the time after a few rounds). You can ignore references to data syncing, removing sync still triggers it for me. The script works by executing writes in multiple tabs and then randomly reloading tabs occasionally.

I have applied the speculative migration commit (6e6da12) to our wa-sqlite fork, but that didn't change things.

I have changed the relevant branch in advanceTxId to:

        const keys = [...this.#mapIdToPendingTx.keys()];
        const txId = this.#txId;

        // Read the transaction from the WAL file.
        tx = this.#readTx();

        if (tx == null) {
          throw new Error(
            `Unexpected null tx in advanceTxId read. txId: ${txId}; keys: ${keys.join(", ")}`,
          );
        }
      }

When the error is first thrown, the message is Unexpected null tx in advanceTxId read. txId: 37; keys: 42.

Footnotes

1. Of course, there's a chance we're doing something stupid in the PowerSync SDK. We can also try to reproduce this in a project without any other dependencies if necessary. ↩

[darshanp40]

@simolus3 Thanks for the repro repo and the root-cause writeup — that let us pin this down properly. We could get Claude to build a deterministic version and a tested fix, no multi-tab timing luck involved. Sharing here in case it's useful before you go further.

Confirming the mechanism, without the reload race

Your writeup nails it: #followFileChange only accepts salt1 + 1, and #advanceTxId deletes the pending transaction from #mapIdToPendingTx before #skipTx can throw, so the id is lost permanently and #txId never moves past it.

We reproduced all three symptoms in isolation — no real multi-tab reload, no timing race — by directly engineering the internal precondition and delivering it through the real, unmodified #handleMessage path via a genuine BroadcastChannel message (same shape a real peer's broadcast takes, nothing forged beyond ordinary public fields):

• invalid WAL file (5/5 runs): force a connection's #activeHeader.salt1 far behind a real generation, then hand it the transaction it's owed. #skipTx throws every time.
• disk I/O error (2/2): after that, inject a further pending entry directly into #mapIdToPendingTx (skips BroadcastChannel timing) and issue a real INSERT on the same connection. isolateForWrite() hits the same broken loop inside jLock — a plain synchronous call — so the throw propagates synchronously into jLock's own try/catch and surfaces as SQLITE_IOERR_LOCK → Error: disk I/O error.
• database disk image is malformed (3/3): the other branch of #skipTx — force the view to exactly one generation behind (not far off). followFileChange's +1 check then matches a real file by coincidence, but the wrong one relative to what the transaction actually names. No throw — it silently adopts the wrong physical file. The next read pulls real, checksum-valid bytes from a real file at an offset that lands mid-b-tree-page rather than on a page boundary, and SQLite's own page-structure check reports corruption. (Point it at page 1 instead of a later page and you get file is not a database — same mechanism, SQLite's other corruption check.)

A fix, tested against all three

// 1. Don't lose the transaction if #skipTx throws.
if (this.#mapIdToPendingTx.has(nextTxId)) {
  tx = this.#mapIdToPendingTx.get(nextTxId);
  this.#skipTx(tx);
  this.#mapIdToPendingTx.delete(tx.id);   // moved after skipTx succeeds
}

// 2. Adopt whichever real file actually matches, not just "one hop forward".
#adoptFileForSalt1(targetSalt1) {
  for (const candidate of this.#waHandles) {
    const header = this.#readFileHeader(candidate);
    if (header?.salt1 === targetSalt1) {
      this.#activeHandle = candidate;
      this.#activeHeader = header;
      this.#activeOffset = FILE_HEADER_SIZE;
      return true;
    }
  }
  return false;
}
// #skipTx calls this instead of #followFileChange(null) when salts mismatch.

// 3. Never activate a null transaction.
tx = this.#readTx();
if (!tx) { /* diagnostic */ break; }   // was: falls through to #activateTx(tx)

Fix 2 is the one that actually matters for correctness — there are only ever two physical WAL files, so checking both against the transaction's real, verified salt (rather than assuming "the inactive one, if it's exactly one ahead") closes the gap regardless of how many generations behind a connection is, and it closes the malformed case specifically because it never adopts on a coincidental match anymore — only a confirmed one.

Re-ran all three reproductions against the patched code:

• invalid WAL file case → #skipTx now finds and adopts the real generation cleanly (skipTx-followed, activeHeaderSalt1After matches the transaction's own waSalt1) instead of throwing.
• malformed case → confirmed the file it adopts is now exactly the one the transaction names, not a coincidental one — the specific mechanism is closed.
• Clean end-to-end check with no synthetic data at all: paused a connection before a writer even started, let it miss a real swap and every real transaction while blind, unpaused it with the writer still running live. Result: no throw, no uncaught error, correct final row count on the read.

Opened #349 with the fix plus the reproduction harness (writer/reader workers + the HTML pages that trigger each error deterministically, and a fourth that verifies the fix against a genuinely-missed real swap with no synthetic data at all).