diag(web): extend instrumentation to read-path RPC + per-file reads (#421 Codex review)

Codex correctly flagged that the diagnostic would miss the actual #418 stall:

1. (P2) The trace stopped at initializeDatabase, but the loading screen then
   awaits ping -> fetchSchema -> fetchTableCount/fetchTableData (viewer.js). A
   hang in any of those would show 'establishConnection complete' then nothing,
   with no unmatched 'start'. Now the browser facade wraps ping, fetchSchema,
   fetchTableCount, fetchTableData, getTableInfo, getPragmas in diagStep too.

2. (P2) loadDatabaseFiles was a single wrapper hiding three awaits (stat, main
   readFile, optional -wal readFile via Promise.all). A never-settling -wal read
   over vscode-vfs would hang the open with no specific marker. loadDatabaseFiles
   now takes an optional diag callback and logs each fs op independently.

tsc clean; build worker-free; workerFactory_browser.test.ts passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zknpr

src/workerFactory.ts

@@ -247,7 +247,7 @@ async function createInProcessWasmDatabaseConnection(
       // Browser mode always reads database bytes through the VS Code filesystem.
       // There is no file-path fast path because the web extension host cannot
       // access local disk paths directly.
-      const [dbContent, walContent] = await diagStep('loadDatabaseFiles', () => loadDatabaseFiles(fileUri));
+      const [dbContent, walContent] = await diagStep('loadDatabaseFiles', () => loadDatabaseFiles(fileUri, diag));
       diag(`  db bytes=${dbContent?.byteLength ?? 'null'} wal bytes=${walContent?.byteLength ?? 'null'}`);
 
       // Preload sql.js WASM bytes from the extension assets directory so
@@ -298,20 +298,25 @@ async function createInProcessWasmDatabaseConnection(
           endpoint.updateCellBatch(table, updates),
         addColumn: (table: string, column: string, type: string, defaultValue?: string) =>
           endpoint.addColumn(table, column, type, defaultValue),
+        // The read-path methods below run during the loading screen (viewer.js
+        // awaits ping -> fetchSchema -> fetchTableCount/fetchTableData on open).
+        // Wrap them in diagStep so a stall in any of THEM — not just
+        // establishConnection's awaits — is pinpointed by the last unmatched
+        // "start" in the trace. (#418 diagnostic)
         fetchTableData: (table: string, options: TableQueryOptions) =>
-          endpoint.fetchTableData(table, options),
+          diagStep(`fetchTableData(${table})`, () => endpoint.fetchTableData(table, options)),
         fetchTableCount: (table: string, options: TableCountOptions) =>
-          endpoint.fetchTableCount(table, options),
+          diagStep(`fetchTableCount(${table})`, () => endpoint.fetchTableCount(table, options)),
         fetchSchema: () =>
-          endpoint.fetchSchema(),
+          diagStep('fetchSchema', () => endpoint.fetchSchema()),
         getTableInfo: (table: string) =>
-          endpoint.getTableInfo(table),
+          diagStep(`getTableInfo(${table})`, () => endpoint.getTableInfo(table)),
         getPragmas: () =>
-          endpoint.getPragmas(),
+          diagStep('getPragmas', () => endpoint.getPragmas()),
         setPragma: (pragma: string, value: CellValue) =>
           endpoint.setPragma(pragma, value),
         ping: () =>
-          endpoint.ping(),
+          diagStep('ping', () => endpoint.ping()),
         writeToFile: (path: string) =>
           endpoint.writeToFile(path)
       };
@@ -541,10 +546,16 @@ async function createWorkerBackedWasmDatabaseConnection(
  * Load database file and optional WAL file.
  *
  * @param uri - Database file URI
+ * @param diag - Optional diagnostic logger (#418). When provided, each internal
+ *   filesystem await (stat, main readFile, optional -wal readFile) is logged
+ *   separately so a stall in one specific call is identifiable. The -wal read is
+ *   a prime suspect: reading a (usually nonexistent) `-wal` over vscode-vfs may
+ *   never settle in the web extension host.
  * @returns Tuple of [database content, WAL content]
  */
 async function loadDatabaseFiles(
-  uri: vsc.Uri
+  uri: vsc.Uri,
+  diag?: (message: string) => void
 ): Promise<[Uint8Array | null, Uint8Array | null]> {
   // Untitled documents start empty
   if (uri.scheme === 'untitled') {
@@ -554,17 +565,30 @@ async function loadDatabaseFiles(
   const maxSize = getMaximumFileSizeBytes();
 
   // Check file size
+  diag?.('▶ fs.stat(db) … start');
   const fileStat = await Promise.resolve(vsc.workspace.fs.stat(uri)).catch(() => ({ size: 0 }));
+  diag?.(`  ✓ fs.stat(db) ok (size=${fileStat.size})`);
   if (maxSize !== 0 && fileStat.size > maxSize) {
     throw new Error(`File size (${(fileStat.size / (1024 * 1024)).toFixed(2)} MB) exceeds the maximum allowed size (${(maxSize / (1024 * 1024)).toFixed(2)} MB). Configure 'sqliteExplorer.maxFileSize' to increase the limit.`);
   }
 
   // Construct WAL file URI
   const walUri = uri.with({ path: uri.path + '-wal' });
 
-  // Read both files concurrently
+  // Read both files concurrently. Log each independently so a hang in the main
+  // DB read vs. the optional -wal read is distinguishable in the #418 trace.
   return Promise.all([
-    vsc.workspace.fs.readFile(uri),
-    Promise.resolve(vsc.workspace.fs.readFile(walUri)).catch(() => null)
+    (async () => {
+      diag?.('▶ fs.readFile(db) … start');
+      const r = await vsc.workspace.fs.readFile(uri);
+      diag?.(`  ✓ fs.readFile(db) ok (${r?.byteLength ?? 'null'} bytes)`);
+      return r;
+    })(),
+    (async () => {
+      diag?.('▶ fs.readFile(-wal, optional) … start');
+      const r = await Promise.resolve(vsc.workspace.fs.readFile(walUri)).catch(() => null);
+      diag?.(`  ✓ fs.readFile(-wal) settled (${r ? r.byteLength + ' bytes' : 'absent'})`);
+      return r;
+    })()
   ]);
 }