@rivetkit/sqlite-wasm 2.2.1-pr.4600.b74ff3b

package/dist/tsup/index.js

@@ -0,0 +1,1557 @@
+// src/vfs.ts
+import * as VFS from "@rivetkit/sqlite/src/VFS.js";
+import {
+  Factory,
+  SQLITE_OPEN_CREATE as SQLITE_OPEN_CREATE2,
+  SQLITE_OPEN_READWRITE,
+  SQLITE_ROW
+} from "@rivetkit/sqlite";
+import { readFileSync } from "fs";
+import { createRequire } from "module";
+import path from "path";
+import { pathToFileURL } from "url";
+
+// src/kv.ts
+var CHUNK_SIZE = 4096;
+var SQLITE_PREFIX = 8;
+var SQLITE_SCHEMA_VERSION = 1;
+var META_PREFIX = 0;
+var CHUNK_PREFIX = 1;
+var FILE_TAG_MAIN = 0;
+var FILE_TAG_JOURNAL = 1;
+var FILE_TAG_WAL = 2;
+var FILE_TAG_SHM = 3;
+function getMetaKey(fileTag) {
+  const key = new Uint8Array(4);
+  key[0] = SQLITE_PREFIX;
+  key[1] = SQLITE_SCHEMA_VERSION;
+  key[2] = META_PREFIX;
+  key[3] = fileTag;
+  return key;
+}
+function getChunkKey(fileTag, chunkIndex) {
+  const key = new Uint8Array(8);
+  key[0] = SQLITE_PREFIX;
+  key[1] = SQLITE_SCHEMA_VERSION;
+  key[2] = CHUNK_PREFIX;
+  key[3] = fileTag;
+  key[4] = chunkIndex >>> 24 & 255;
+  key[5] = chunkIndex >>> 16 & 255;
+  key[6] = chunkIndex >>> 8 & 255;
+  key[7] = chunkIndex & 255;
+  return key;
+}
+function getChunkKeyRangeEnd(fileTag) {
+  const key = new Uint8Array(4);
+  key[0] = SQLITE_PREFIX;
+  key[1] = SQLITE_SCHEMA_VERSION;
+  key[2] = CHUNK_PREFIX;
+  key[3] = fileTag + 1;
+  return key;
+}
+
+// src/generated/empty-db-page.ts
+var HEADER_PREFIX = new Uint8Array([83, 81, 76, 105, 116, 101, 32, 102, 111, 114, 109, 97, 116, 32, 51, 0, 16, 0, 1, 1, 0, 64, 32, 32, 0, 0, 0, 3, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 46, 138, 17, 13, 0, 0, 0, 0, 16, 0, 0]);
+var EMPTY_DB_PAGE = (() => {
+  const page = new Uint8Array(4096);
+  page.set(HEADER_PREFIX);
+  return page;
+})();
+
+// schemas/file-meta/versioned.ts
+import { createVersionedDataHandler } from "vbare";
+
+// dist/schemas/file-meta/v1.ts
+import * as bare from "@rivetkit/bare-ts";
+var config = /* @__PURE__ */ bare.Config({});
+function readFileMeta(bc) {
+  return {
+    size: bare.readU64(bc)
+  };
+}
+function writeFileMeta(bc, x) {
+  bare.writeU64(bc, x.size);
+}
+function encodeFileMeta(x) {
+  const bc = new bare.ByteCursor(
+    new Uint8Array(config.initialBufferLength),
+    config
+  );
+  writeFileMeta(bc, x);
+  return new Uint8Array(bc.view.buffer, bc.view.byteOffset, bc.offset);
+}
+function decodeFileMeta(bytes) {
+  const bc = new bare.ByteCursor(bytes, config);
+  const result = readFileMeta(bc);
+  if (bc.offset < bc.view.byteLength) {
+    throw new bare.BareError(bc.offset, "remaining bytes");
+  }
+  return result;
+}
+
+// schemas/file-meta/versioned.ts
+var CURRENT_VERSION = 1;
+var FILE_META_VERSIONED = createVersionedDataHandler({
+  deserializeVersion: (bytes, version) => {
+    switch (version) {
+      case 1:
+        return decodeFileMeta(bytes);
+      default:
+        throw new Error(`Unknown version ${version}`);
+    }
+  },
+  serializeVersion: (data, version) => {
+    switch (version) {
+      case 1:
+        return encodeFileMeta(data);
+      default:
+        throw new Error(`Unknown version ${version}`);
+    }
+  },
+  deserializeConverters: () => [],
+  serializeConverters: () => []
+});
+
+// src/vfs.ts
+function createNodeRequire() {
+  return createRequire(
+    path.join(process.cwd(), "__rivetkit_sqlite_require__.cjs")
+  );
+}
+var TEXT_ENCODER = new TextEncoder();
+var TEXT_DECODER = new TextDecoder();
+var SQLITE_MAX_PATHNAME_BYTES = 64;
+var UINT32_SIZE = 4294967296;
+var MAX_CHUNK_INDEX = 4294967295;
+var MAX_FILE_SIZE_BYTES = (MAX_CHUNK_INDEX + 1) * CHUNK_SIZE;
+var MAX_FILE_SIZE_HI32 = Math.floor(MAX_FILE_SIZE_BYTES / UINT32_SIZE);
+var MAX_FILE_SIZE_LO32 = MAX_FILE_SIZE_BYTES % UINT32_SIZE;
+var KV_MAX_BATCH_KEYS = 128;
+var SQLITE_IOCAP_BATCH_ATOMIC = 16384;
+var SQLITE_FCNTL_BEGIN_ATOMIC_WRITE = 31;
+var SQLITE_FCNTL_COMMIT_ATOMIC_WRITE = 32;
+var SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE = 33;
+var SQLITE_ASYNC_METHODS = /* @__PURE__ */ new Set([
+  "xOpen",
+  "xClose",
+  "xRead",
+  "xWrite",
+  "xTruncate",
+  "xSync",
+  "xFileSize",
+  "xDelete",
+  "xAccess",
+  "xFileControl"
+]);
+function isSqliteEsmFactory(value) {
+  return typeof value === "function";
+}
+function isSQLiteModule(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.UTF8ToString === "function" && candidate.HEAPU8 instanceof Uint8Array;
+}
+async function loadSqliteRuntime(wasmModule) {
+  const require2 = createNodeRequire();
+  const sqliteModulePath = require2.resolve(
+    ["@rivetkit/sqlite", "dist", "wa-sqlite-async.mjs"].join("/")
+  );
+  const sqliteModule = await nativeDynamicImport(
+    pathToFileURL(sqliteModulePath).href
+  );
+  if (!isSqliteEsmFactory(sqliteModule.default)) {
+    throw new Error("Invalid SQLite ESM factory export");
+  }
+  const sqliteEsmFactory = sqliteModule.default;
+  let module;
+  if (wasmModule) {
+    module = await sqliteEsmFactory({
+      instantiateWasm(imports, receiveInstance) {
+        WebAssembly.instantiate(wasmModule, imports).then(
+          (instance) => {
+            receiveInstance(instance);
+          }
+        );
+        return {};
+      }
+    });
+  } else {
+    const sqliteDistPath = "@rivetkit/sqlite/dist/";
+    const wasmPath = require2.resolve(
+      sqliteDistPath + "wa-sqlite-async.wasm"
+    );
+    const wasmBinary = readFileSync(wasmPath);
+    module = await sqliteEsmFactory({ wasmBinary });
+  }
+  if (!isSQLiteModule(module)) {
+    throw new Error("Invalid SQLite runtime module");
+  }
+  return {
+    sqlite3: Factory(module),
+    module
+  };
+}
+async function nativeDynamicImport(specifier) {
+  try {
+    return await import(specifier);
+  } catch (directError) {
+    const importer = new Function(
+      "moduleSpecifier",
+      "return import(moduleSpecifier);"
+    );
+    try {
+      return await importer(specifier);
+    } catch {
+      throw directError;
+    }
+  }
+}
+function encodeFileMeta2(size) {
+  const meta = { size: BigInt(size) };
+  return FILE_META_VERSIONED.serializeWithEmbeddedVersion(
+    meta,
+    CURRENT_VERSION
+  );
+}
+function decodeFileMeta2(data) {
+  const meta = FILE_META_VERSIONED.deserializeWithEmbeddedVersion(data);
+  return Number(meta.size);
+}
+function isValidFileSize(size) {
+  return Number.isSafeInteger(size) && size >= 0 && size <= MAX_FILE_SIZE_BYTES;
+}
+var AsyncMutex = class {
+  #locked = false;
+  #waiting = [];
+  async acquire() {
+    while (this.#locked) {
+      await new Promise((resolve) => this.#waiting.push(resolve));
+    }
+    this.#locked = true;
+  }
+  release() {
+    this.#locked = false;
+    const next = this.#waiting.shift();
+    if (next) {
+      next();
+    }
+  }
+  async run(fn) {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+};
+var Database = class {
+  #sqlite3;
+  #handle;
+  #fileName;
+  #onClose;
+  #sqliteMutex;
+  #closed = false;
+  constructor(sqlite3, handle, fileName, onClose, sqliteMutex) {
+    this.#sqlite3 = sqlite3;
+    this.#handle = handle;
+    this.#fileName = fileName;
+    this.#onClose = onClose;
+    this.#sqliteMutex = sqliteMutex;
+  }
+  /**
+   * Execute SQL with optional row callback
+   * @param sql - SQL statement to execute
+   * @param callback - Called for each result row with (row, columns)
+   */
+  async exec(sql, callback) {
+    await this.#sqliteMutex.run(async () => {
+      await this.#sqlite3.exec(this.#handle, sql, callback);
+    });
+  }
+  /**
+   * Execute a parameterized SQL statement (no result rows)
+   * @param sql - SQL statement with ? placeholders
+   * @param params - Parameter values to bind
+   */
+  async run(sql, params) {
+    await this.#sqliteMutex.run(async () => {
+      for await (const stmt of this.#sqlite3.statements(
+        this.#handle,
+        sql
+      )) {
+        if (params) {
+          this.#sqlite3.bind_collection(stmt, params);
+        }
+        while (await this.#sqlite3.step(stmt) === SQLITE_ROW) {
+        }
+      }
+    });
+  }
+  /**
+   * Execute a parameterized SQL query and return results
+   * @param sql - SQL query with ? placeholders
+   * @param params - Parameter values to bind
+   * @returns Object with rows (array of arrays) and columns (column names)
+   */
+  async query(sql, params) {
+    return this.#sqliteMutex.run(async () => {
+      const rows = [];
+      let columns = [];
+      for await (const stmt of this.#sqlite3.statements(
+        this.#handle,
+        sql
+      )) {
+        if (params) {
+          this.#sqlite3.bind_collection(stmt, params);
+        }
+        while (await this.#sqlite3.step(stmt) === SQLITE_ROW) {
+          if (columns.length === 0) {
+            columns = this.#sqlite3.column_names(stmt);
+          }
+          rows.push(this.#sqlite3.row(stmt));
+        }
+      }
+      return { rows, columns };
+    });
+  }
+  /**
+   * Close the database
+   */
+  async close() {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    await this.#sqliteMutex.run(async () => {
+      await this.#sqlite3.close(this.#handle);
+    });
+    await this.#onClose();
+  }
+  /**
+   * Get the database file name
+   */
+  get fileName() {
+    return this.#fileName;
+  }
+  /**
+   * Get the raw @rivetkit/sqlite API (for advanced usage)
+   */
+  get sqlite3() {
+    return this.#sqlite3;
+  }
+  /**
+   * Get the raw database handle (for advanced usage)
+   */
+  get handle() {
+    return this.#handle;
+  }
+};
+var SqliteVfs = class {
+  #sqlite3 = null;
+  #sqliteSystem = null;
+  #initPromise = null;
+  #openMutex = new AsyncMutex();
+  #sqliteMutex = new AsyncMutex();
+  #instanceId;
+  #destroyed = false;
+  #openDatabases = /* @__PURE__ */ new Set();
+  #wasmModule;
+  constructor(wasmModule) {
+    this.#instanceId = crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+    this.#wasmModule = wasmModule;
+  }
+  /**
+   * Initialize @rivetkit/sqlite and VFS (called once per instance)
+   */
+  async #ensureInitialized() {
+    if (this.#destroyed) {
+      throw new Error("SqliteVfs is closed");
+    }
+    if (this.#sqlite3 && this.#sqliteSystem) {
+      return;
+    }
+    if (!this.#initPromise) {
+      this.#initPromise = (async () => {
+        const { sqlite3, module } = await loadSqliteRuntime(
+          this.#wasmModule
+        );
+        if (this.#destroyed) {
+          return;
+        }
+        this.#sqlite3 = sqlite3;
+        this.#sqliteSystem = new SqliteSystem(
+          sqlite3,
+          module,
+          `kv-vfs-${this.#instanceId}`
+        );
+        this.#sqliteSystem.register();
+      })();
+    }
+    try {
+      await this.#initPromise;
+    } catch (error) {
+      this.#initPromise = null;
+      throw error;
+    }
+  }
+  /**
+   * Open a SQLite database using KV storage backend
+   *
+   * @param fileName - The database file name (typically the actor ID)
+   * @param options - KV storage operations for this database
+   * @returns A Database instance
+   */
+  async open(fileName, options) {
+    if (this.#destroyed) {
+      throw new Error("SqliteVfs is closed");
+    }
+    await this.#openMutex.acquire();
+    try {
+      for (const db2 of this.#openDatabases) {
+        if (db2.fileName === fileName) {
+          throw new Error(
+            `SqliteVfs: fileName "${fileName}" is already open on this instance`
+          );
+        }
+      }
+      await this.#ensureInitialized();
+      if (!this.#sqlite3 || !this.#sqliteSystem) {
+        throw new Error("Failed to initialize SQLite");
+      }
+      const sqlite3 = this.#sqlite3;
+      const sqliteSystem = this.#sqliteSystem;
+      sqliteSystem.registerFile(fileName, options);
+      const db = await this.#sqliteMutex.run(
+        async () => sqlite3.open_v2(
+          fileName,
+          SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE2,
+          sqliteSystem.name
+        )
+      );
+      await this.#sqliteMutex.run(async () => {
+        await sqlite3.exec(db, "PRAGMA page_size = 4096");
+        await sqlite3.exec(db, "PRAGMA journal_mode = DELETE");
+        await sqlite3.exec(db, "PRAGMA synchronous = NORMAL");
+        await sqlite3.exec(db, "PRAGMA temp_store = MEMORY");
+        await sqlite3.exec(db, "PRAGMA auto_vacuum = NONE");
+        await sqlite3.exec(db, "PRAGMA locking_mode = EXCLUSIVE");
+      });
+      const onClose = async () => {
+        this.#openDatabases.delete(database);
+        await this.#openMutex.run(async () => {
+          sqliteSystem.unregisterFile(fileName);
+        });
+      };
+      const database = new Database(
+        sqlite3,
+        db,
+        fileName,
+        onClose,
+        this.#sqliteMutex
+      );
+      this.#openDatabases.add(database);
+      return database;
+    } finally {
+      this.#openMutex.release();
+    }
+  }
+  /**
+   * Force-close all Database handles whose fileName exactly matches the
+   * given name. Snapshots the set to an array before iterating to avoid
+   * mutation during async iteration.
+   *
+   * Uses exact file name match because short names are numeric strings
+   * ('0', '1', ..., '10', '11', ...) and a prefix match like
+   * startsWith('1') would incorrectly match '10', '11', etc., causing
+   * cross-actor corruption. Sidecar files (-journal, -wal, -shm) are not
+   * tracked as separate Database handles, so prefix matching for sidecars
+   * is not needed.
+   */
+  async forceCloseByFileName(fileName) {
+    const snapshot = [...this.#openDatabases];
+    let allSucceeded = true;
+    for (const db of snapshot) {
+      if (db.fileName === fileName) {
+        try {
+          await db.close();
+        } catch {
+          allSucceeded = false;
+          this.#openDatabases.delete(db);
+          const sqliteSystem = this.#sqliteSystem;
+          if (sqliteSystem) {
+            await this.#openMutex.run(async () => {
+              sqliteSystem.unregisterFile(db.fileName);
+            });
+          }
+        }
+      }
+    }
+    return { allSucceeded };
+  }
+  /**
+   * Force-close all open Database handles. Best-effort: errors are
+   * swallowed so this is safe to call during instance teardown.
+   */
+  async forceCloseAll() {
+    const snapshot = [...this.#openDatabases];
+    for (const db of snapshot) {
+      try {
+        await db.close();
+      } catch {
+      }
+    }
+  }
+  /**
+   * Tears down this VFS instance and releases internal references.
+   */
+  async destroy() {
+    if (this.#destroyed) {
+      return;
+    }
+    this.#destroyed = true;
+    const initPromise = this.#initPromise;
+    if (initPromise) {
+      try {
+        await initPromise;
+      } catch {
+      }
+    }
+    if (this.#sqliteSystem) {
+      await this.#sqliteSystem.close();
+    }
+    this.#sqliteSystem = null;
+    this.#sqlite3 = null;
+    this.#initPromise = null;
+  }
+  /**
+   * Alias for destroy to align with DB-style lifecycle naming.
+   */
+  async close() {
+    await this.destroy();
+  }
+};
+var SqliteSystem = class {
+  name;
+  mxPathName = SQLITE_MAX_PATHNAME_BYTES;
+  mxPathname = SQLITE_MAX_PATHNAME_BYTES;
+  #registeredFiles = /* @__PURE__ */ new Map();
+  #openFiles = /* @__PURE__ */ new Map();
+  #sqlite3;
+  #module;
+  #heapDataView;
+  #heapDataViewBuffer;
+  constructor(sqlite3, module, name) {
+    this.name = name;
+    this.#sqlite3 = sqlite3;
+    this.#module = module;
+    this.#heapDataViewBuffer = module.HEAPU8.buffer;
+    this.#heapDataView = new DataView(this.#heapDataViewBuffer);
+  }
+  async close() {
+    this.#openFiles.clear();
+    this.#registeredFiles.clear();
+  }
+  isReady() {
+    return true;
+  }
+  hasAsyncMethod(methodName) {
+    return SQLITE_ASYNC_METHODS.has(methodName);
+  }
+  /**
+   * Registers the VFS with SQLite
+   */
+  register() {
+    this.#sqlite3.vfs_register(this, false);
+  }
+  /**
+   * Registers a file with its KV options (before opening).
+   */
+  registerFile(fileName, options) {
+    this.#registeredFiles.set(fileName, options);
+  }
+  /**
+   * Unregisters a file's KV options (after closing).
+   */
+  unregisterFile(fileName) {
+    this.#registeredFiles.delete(fileName);
+  }
+  /**
+   * Resolve file path to a registered database file or one of its SQLite
+   * sidecars (-journal, -wal, -shm). File tags are reused across files
+   * because each file's KvVfsOptions routes to a separate KV namespace.
+   */
+  #resolveFile(path3) {
+    const directOptions = this.#registeredFiles.get(path3);
+    if (directOptions) {
+      return { options: directOptions, fileTag: FILE_TAG_MAIN };
+    }
+    if (path3.endsWith("-journal")) {
+      const baseName = path3.slice(0, -8);
+      const options = this.#registeredFiles.get(baseName);
+      if (options) {
+        return { options, fileTag: FILE_TAG_JOURNAL };
+      }
+    } else if (path3.endsWith("-wal")) {
+      const baseName = path3.slice(0, -4);
+      const options = this.#registeredFiles.get(baseName);
+      if (options) {
+        return { options, fileTag: FILE_TAG_WAL };
+      }
+    } else if (path3.endsWith("-shm")) {
+      const baseName = path3.slice(0, -4);
+      const options = this.#registeredFiles.get(baseName);
+      if (options) {
+        return { options, fileTag: FILE_TAG_SHM };
+      }
+    }
+    return null;
+  }
+  #resolveFileOrThrow(path3) {
+    const resolved = this.#resolveFile(path3);
+    if (resolved) {
+      return resolved;
+    }
+    if (this.#registeredFiles.size === 0) {
+      throw new Error(`No KV options registered for file: ${path3}`);
+    }
+    const registered = Array.from(this.#registeredFiles.keys()).join(", ");
+    throw new Error(
+      `Unsupported SQLite file path ${path3}. Registered base names: ${registered}.`
+    );
+  }
+  #chunkKey(file, chunkIndex) {
+    return getChunkKey(file.fileTag, chunkIndex);
+  }
+  async xOpen(_pVfs, zName, fileId, flags, pOutFlags) {
+    var _a, _b, _c;
+    const path3 = this.#decodeFilename(zName, flags);
+    if (!path3) {
+      return VFS.SQLITE_CANTOPEN;
+    }
+    const { options, fileTag } = this.#resolveFileOrThrow(path3);
+    const metaKey = getMetaKey(fileTag);
+    let sizeData;
+    try {
+      sizeData = await options.get(metaKey);
+    } catch (error) {
+      (_a = options.onError) == null ? void 0 : _a.call(options, error);
+      return VFS.SQLITE_CANTOPEN;
+    }
+    let size;
+    if (sizeData) {
+      size = decodeFileMeta2(sizeData);
+      if (!isValidFileSize(size)) {
+        return VFS.SQLITE_IOERR;
+      }
+    } else if (flags & VFS.SQLITE_OPEN_CREATE) {
+      if (fileTag === FILE_TAG_MAIN) {
+        const chunkKey = getChunkKey(fileTag, 0);
+        size = EMPTY_DB_PAGE.length;
+        try {
+          await options.putBatch([
+            [chunkKey, EMPTY_DB_PAGE],
+            [metaKey, encodeFileMeta2(size)]
+          ]);
+        } catch (error) {
+          (_b = options.onError) == null ? void 0 : _b.call(options, error);
+          return VFS.SQLITE_CANTOPEN;
+        }
+      } else {
+        size = 0;
+        try {
+          await options.put(metaKey, encodeFileMeta2(size));
+        } catch (error) {
+          (_c = options.onError) == null ? void 0 : _c.call(options, error);
+          return VFS.SQLITE_CANTOPEN;
+        }
+      }
+    } else {
+      return VFS.SQLITE_CANTOPEN;
+    }
+    this.#openFiles.set(fileId, {
+      path: path3,
+      fileTag,
+      metaKey,
+      size,
+      metaDirty: false,
+      flags,
+      options,
+      batchMode: false,
+      dirtyBuffer: null,
+      savedFileSize: 0
+    });
+    this.#writeInt32(pOutFlags, flags);
+    return VFS.SQLITE_OK;
+  }
+  async xClose(fileId) {
+    var _a, _b;
+    const file = this.#openFiles.get(fileId);
+    if (!file) {
+      return VFS.SQLITE_OK;
+    }
+    try {
+      if (file.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) {
+        await this.#delete(file.path);
+      } else if (file.metaDirty) {
+        await file.options.put(file.metaKey, encodeFileMeta2(file.size));
+        file.metaDirty = false;
+      }
+    } catch (error) {
+      (_b = (_a = file.options).onError) == null ? void 0 : _b.call(_a, error);
+      this.#openFiles.delete(fileId);
+      return VFS.SQLITE_IOERR;
+    }
+    this.#openFiles.delete(fileId);
+    return VFS.SQLITE_OK;
+  }
+  async xRead(fileId, pData, iAmt, iOffsetLo, iOffsetHi) {
+    var _a;
+    if (iAmt === 0) {
+      return VFS.SQLITE_OK;
+    }
+    const file = this.#openFiles.get(fileId);
+    if (!file) {
+      return VFS.SQLITE_IOERR_READ;
+    }
+    let data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
+    const options = file.options;
+    const requestedLength = iAmt;
+    const iOffset = delegalize(iOffsetLo, iOffsetHi);
+    if (iOffset < 0) {
+      return VFS.SQLITE_IOERR_READ;
+    }
+    const fileSize = file.size;
+    if (iOffset >= fileSize) {
+      data.fill(0);
+      return VFS.SQLITE_IOERR_SHORT_READ;
+    }
+    const startChunk = Math.floor(iOffset / CHUNK_SIZE);
+    const endChunk = Math.floor(
+      (iOffset + requestedLength - 1) / CHUNK_SIZE
+    );
+    const chunkKeys = [];
+    const chunkIndexToBuffered = /* @__PURE__ */ new Map();
+    for (let i = startChunk; i <= endChunk; i++) {
+      if (file.batchMode && file.dirtyBuffer) {
+        const buffered = file.dirtyBuffer.get(i);
+        if (buffered) {
+          chunkIndexToBuffered.set(i, buffered);
+          continue;
+        }
+      }
+      chunkKeys.push(this.#chunkKey(file, i));
+    }
+    let kvChunks;
+    try {
+      kvChunks = chunkKeys.length > 0 ? await options.getBatch(chunkKeys) : [];
+    } catch (error) {
+      (_a = options.onError) == null ? void 0 : _a.call(options, error);
+      return VFS.SQLITE_IOERR_READ;
+    }
+    data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
+    let kvIdx = 0;
+    for (let i = startChunk; i <= endChunk; i++) {
+      const chunkData = chunkIndexToBuffered.get(i) ?? kvChunks[kvIdx++];
+      const chunkOffset = i * CHUNK_SIZE;
+      const readStart = Math.max(0, iOffset - chunkOffset);
+      const readEnd = Math.min(
+        CHUNK_SIZE,
+        iOffset + requestedLength - chunkOffset
+      );
+      if (chunkData) {
+        const sourceStart = readStart;
+        const sourceEnd = Math.min(readEnd, chunkData.length);
+        const destStart = chunkOffset + readStart - iOffset;
+        if (sourceEnd > sourceStart) {
+          data.set(
+            chunkData.subarray(sourceStart, sourceEnd),
+            destStart
+          );
+        }
+        if (sourceEnd < readEnd) {
+          const zeroStart = destStart + (sourceEnd - sourceStart);
+          const zeroEnd = destStart + (readEnd - readStart);
+          data.fill(0, zeroStart, zeroEnd);
+        }
+      } else {
+        const destStart = chunkOffset + readStart - iOffset;
+        const destEnd = destStart + (readEnd - readStart);
+        data.fill(0, destStart, destEnd);
+      }
+    }
+    const actualBytes = Math.min(requestedLength, fileSize - iOffset);
+    if (actualBytes < requestedLength) {
+      data.fill(0, actualBytes);
+      return VFS.SQLITE_IOERR_SHORT_READ;
+    }
+    return VFS.SQLITE_OK;
+  }
+  async xWrite(fileId, pData, iAmt, iOffsetLo, iOffsetHi) {
+    var _a, _b;
+    if (iAmt === 0) {
+      return VFS.SQLITE_OK;
+    }
+    const file = this.#openFiles.get(fileId);
+    if (!file) {
+      return VFS.SQLITE_IOERR_WRITE;
+    }
+    let data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
+    const iOffset = delegalize(iOffsetLo, iOffsetHi);
+    if (iOffset < 0) {
+      return VFS.SQLITE_IOERR_WRITE;
+    }
+    const options = file.options;
+    const writeLength = iAmt;
+    const writeEndOffset = iOffset + writeLength;
+    if (writeEndOffset > MAX_FILE_SIZE_BYTES) {
+      return VFS.SQLITE_IOERR_WRITE;
+    }
+    const startChunk = Math.floor(iOffset / CHUNK_SIZE);
+    const endChunk = Math.floor((iOffset + writeLength - 1) / CHUNK_SIZE);
+    if (file.batchMode && file.dirtyBuffer) {
+      for (let i = startChunk; i <= endChunk; i++) {
+        const chunkOffset = i * CHUNK_SIZE;
+        const sourceStart = Math.max(0, chunkOffset - iOffset);
+        const sourceEnd = Math.min(
+          writeLength,
+          chunkOffset + CHUNK_SIZE - iOffset
+        );
+        file.dirtyBuffer.set(
+          i,
+          data.subarray(sourceStart, sourceEnd).slice()
+        );
+      }
+      const newSize2 = Math.max(file.size, writeEndOffset);
+      if (newSize2 !== file.size) {
+        file.size = newSize2;
+        file.metaDirty = true;
+      }
+      return VFS.SQLITE_OK;
+    }
+    const plans = [];
+    const chunkKeysToFetch = [];
+    for (let i = startChunk; i <= endChunk; i++) {
+      const chunkOffset = i * CHUNK_SIZE;
+      const writeStart = Math.max(0, iOffset - chunkOffset);
+      const writeEnd = Math.min(
+        CHUNK_SIZE,
+        iOffset + writeLength - chunkOffset
+      );
+      const existingBytesInChunk = Math.max(
+        0,
+        Math.min(CHUNK_SIZE, file.size - chunkOffset)
+      );
+      const needsExisting = writeStart > 0 || existingBytesInChunk > writeEnd;
+      const chunkKey = this.#chunkKey(file, i);
+      let existingChunkIndex = -1;
+      if (needsExisting) {
+        existingChunkIndex = chunkKeysToFetch.length;
+        chunkKeysToFetch.push(chunkKey);
+      }
+      plans.push({
+        chunkKey,
+        chunkOffset,
+        writeStart,
+        writeEnd,
+        existingChunkIndex
+      });
+    }
+    let existingChunks;
+    try {
+      existingChunks = chunkKeysToFetch.length > 0 ? await options.getBatch(chunkKeysToFetch) : [];
+    } catch (error) {
+      (_a = options.onError) == null ? void 0 : _a.call(options, error);
+      return VFS.SQLITE_IOERR_WRITE;
+    }
+    data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
+    const entriesToWrite = [];
+    for (const plan of plans) {
+      const existingChunk = plan.existingChunkIndex >= 0 ? existingChunks[plan.existingChunkIndex] : null;
+      let newChunk;
+      if (existingChunk) {
+        newChunk = new Uint8Array(
+          Math.max(existingChunk.length, plan.writeEnd)
+        );
+        newChunk.set(existingChunk);
+      } else {
+        newChunk = new Uint8Array(plan.writeEnd);
+      }
+      const sourceStart = plan.chunkOffset + plan.writeStart - iOffset;
+      const sourceEnd = sourceStart + (plan.writeEnd - plan.writeStart);
+      newChunk.set(
+        data.subarray(sourceStart, sourceEnd),
+        plan.writeStart
+      );
+      entriesToWrite.push([plan.chunkKey, newChunk]);
+    }
+    const previousSize = file.size;
+    const previousMetaDirty = file.metaDirty;
+    const newSize = Math.max(file.size, writeEndOffset);
+    if (newSize !== previousSize) {
+      file.size = newSize;
+      file.metaDirty = true;
+    }
+    if (file.metaDirty) {
+      entriesToWrite.push([file.metaKey, encodeFileMeta2(file.size)]);
+    }
+    try {
+      await options.putBatch(entriesToWrite);
+    } catch (error) {
+      (_b = options.onError) == null ? void 0 : _b.call(options, error);
+      file.size = previousSize;
+      file.metaDirty = previousMetaDirty;
+      return VFS.SQLITE_IOERR_WRITE;
+    }
+    if (file.metaDirty) {
+      file.metaDirty = false;
+    }
+    file.metaDirty = false;
+    return VFS.SQLITE_OK;
+  }
+  async xTruncate(fileId, sizeLo, sizeHi) {
+    var _a, _b, _c;
+    const file = this.#openFiles.get(fileId);
+    if (!file) {
+      return VFS.SQLITE_IOERR_TRUNCATE;
+    }
+    const size = delegalize(sizeLo, sizeHi);
+    if (size < 0 || size > MAX_FILE_SIZE_BYTES) {
+      return VFS.SQLITE_IOERR_TRUNCATE;
+    }
+    const options = file.options;
+    if (size >= file.size) {
+      if (size > file.size) {
+        const previousSize2 = file.size;
+        const previousMetaDirty2 = file.metaDirty;
+        file.size = size;
+        file.metaDirty = true;
+        try {
+          await options.put(file.metaKey, encodeFileMeta2(file.size));
+        } catch (error) {
+          (_a = options.onError) == null ? void 0 : _a.call(options, error);
+          file.size = previousSize2;
+          file.metaDirty = previousMetaDirty2;
+          return VFS.SQLITE_IOERR_TRUNCATE;
+        }
+        file.metaDirty = false;
+      }
+      return VFS.SQLITE_OK;
+    }
+    const lastChunkToKeep = Math.floor((size - 1) / CHUNK_SIZE);
+    const lastExistingChunk = Math.floor((file.size - 1) / CHUNK_SIZE);
+    const previousSize = file.size;
+    const previousMetaDirty = file.metaDirty;
+    file.size = size;
+    file.metaDirty = true;
+    try {
+      await options.put(file.metaKey, encodeFileMeta2(file.size));
+    } catch (error) {
+      (_b = options.onError) == null ? void 0 : _b.call(options, error);
+      file.size = previousSize;
+      file.metaDirty = previousMetaDirty;
+      return VFS.SQLITE_IOERR_TRUNCATE;
+    }
+    file.metaDirty = false;
+    try {
+      if (size > 0 && size % CHUNK_SIZE !== 0) {
+        const lastChunkKey = this.#chunkKey(file, lastChunkToKeep);
+        const lastChunkData = await options.get(lastChunkKey);
+        if (lastChunkData && lastChunkData.length > size % CHUNK_SIZE) {
+          const truncatedChunk = lastChunkData.subarray(
+            0,
+            size % CHUNK_SIZE
+          );
+          await options.put(lastChunkKey, truncatedChunk);
+        }
+      }
+      const keysToDelete = [];
+      for (let i = lastChunkToKeep + 1; i <= lastExistingChunk; i++) {
+        keysToDelete.push(this.#chunkKey(file, i));
+      }
+      for (let b = 0; b < keysToDelete.length; b += KV_MAX_BATCH_KEYS) {
+        await options.deleteBatch(
+          keysToDelete.slice(b, b + KV_MAX_BATCH_KEYS)
+        );
+      }
+    } catch (error) {
+      (_c = options.onError) == null ? void 0 : _c.call(options, error);
+      return VFS.SQLITE_IOERR_TRUNCATE;
+    }
+    return VFS.SQLITE_OK;
+  }
+  async xSync(fileId, _flags) {
+    var _a, _b;
+    const file = this.#openFiles.get(fileId);
+    if (!file || !file.metaDirty) {
+      return VFS.SQLITE_OK;
+    }
+    try {
+      await file.options.put(file.metaKey, encodeFileMeta2(file.size));
+    } catch (error) {
+      (_b = (_a = file.options).onError) == null ? void 0 : _b.call(_a, error);
+      return VFS.SQLITE_IOERR_FSYNC;
+    }
+    file.metaDirty = false;
+    return VFS.SQLITE_OK;
+  }
+  async xFileSize(fileId, pSize) {
+    const file = this.#openFiles.get(fileId);
+    if (!file) {
+      return VFS.SQLITE_IOERR_FSTAT;
+    }
+    this.#writeBigInt64(pSize, BigInt(file.size));
+    return VFS.SQLITE_OK;
+  }
+  async xDelete(_pVfs, zName, _syncDir) {
+    try {
+      await this.#delete(this.#module.UTF8ToString(zName));
+    } catch (error) {
+      return VFS.SQLITE_IOERR_DELETE;
+    }
+    return VFS.SQLITE_OK;
+  }
+  /**
+   * Internal delete implementation.
+   * Uses deleteRange for O(1) chunk deletion instead of enumerating
+   * individual chunk keys. The chunk keys for a file tag are
+   * lexicographically contiguous, so range deletion is always safe.
+   */
+  async #delete(path3) {
+    const { options, fileTag } = this.#resolveFileOrThrow(path3);
+    const metaKey = getMetaKey(fileTag);
+    const sizeData = await options.get(metaKey);
+    if (!sizeData) {
+      return;
+    }
+    await options.deleteRange(
+      getChunkKey(fileTag, 0),
+      getChunkKeyRangeEnd(fileTag)
+    );
+    await options.deleteBatch([metaKey]);
+  }
+  async xAccess(_pVfs, zName, _flags, pResOut) {
+    var _a, _b;
+    const path3 = this.#module.UTF8ToString(zName);
+    const resolved = this.#resolveFile(path3);
+    if (!resolved) {
+      this.#writeInt32(pResOut, 0);
+      return VFS.SQLITE_OK;
+    }
+    const compactMetaKey = getMetaKey(resolved.fileTag);
+    let metaData;
+    try {
+      metaData = await resolved.options.get(compactMetaKey);
+    } catch (error) {
+      (_b = (_a = resolved.options).onError) == null ? void 0 : _b.call(_a, error);
+      return VFS.SQLITE_IOERR_ACCESS;
+    }
+    this.#writeInt32(pResOut, metaData ? 1 : 0);
+    return VFS.SQLITE_OK;
+  }
+  xCheckReservedLock(_fileId, pResOut) {
+    this.#writeInt32(pResOut, 0);
+    return VFS.SQLITE_OK;
+  }
+  xLock(_fileId, _flags) {
+    return VFS.SQLITE_OK;
+  }
+  xUnlock(_fileId, _flags) {
+    return VFS.SQLITE_OK;
+  }
+  async xFileControl(fileId, flags, _pArg) {
+    var _a;
+    switch (flags) {
+      case SQLITE_FCNTL_BEGIN_ATOMIC_WRITE: {
+        const file = this.#openFiles.get(fileId);
+        if (!file) return VFS.SQLITE_NOTFOUND;
+        file.savedFileSize = file.size;
+        file.batchMode = true;
+        file.metaDirty = false;
+        file.dirtyBuffer = /* @__PURE__ */ new Map();
+        return VFS.SQLITE_OK;
+      }
+      case SQLITE_FCNTL_COMMIT_ATOMIC_WRITE: {
+        const file = this.#openFiles.get(fileId);
+        if (!file) return VFS.SQLITE_NOTFOUND;
+        const { dirtyBuffer, options } = file;
+        const maxDirtyPages = file.metaDirty ? KV_MAX_BATCH_KEYS - 1 : KV_MAX_BATCH_KEYS;
+        if (dirtyBuffer && dirtyBuffer.size > maxDirtyPages) {
+          dirtyBuffer.clear();
+          file.dirtyBuffer = null;
+          file.size = file.savedFileSize;
+          file.metaDirty = false;
+          file.batchMode = false;
+          return VFS.SQLITE_IOERR;
+        }
+        const entries = [];
+        if (dirtyBuffer) {
+          for (const [chunkIndex, data] of dirtyBuffer) {
+            entries.push([this.#chunkKey(file, chunkIndex), data]);
+          }
+          dirtyBuffer.clear();
+        }
+        if (file.metaDirty) {
+          entries.push([file.metaKey, encodeFileMeta2(file.size)]);
+        }
+        try {
+          await options.putBatch(entries);
+        } catch (error) {
+          (_a = options.onError) == null ? void 0 : _a.call(options, error);
+          file.dirtyBuffer = null;
+          file.size = file.savedFileSize;
+          file.metaDirty = false;
+          file.batchMode = false;
+          return VFS.SQLITE_IOERR;
+        }
+        file.dirtyBuffer = null;
+        file.metaDirty = false;
+        file.batchMode = false;
+        return VFS.SQLITE_OK;
+      }
+      case SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE: {
+        const file = this.#openFiles.get(fileId);
+        if (!file || !file.batchMode) return VFS.SQLITE_OK;
+        if (file.dirtyBuffer) {
+          file.dirtyBuffer.clear();
+          file.dirtyBuffer = null;
+        }
+        file.size = file.savedFileSize;
+        file.metaDirty = false;
+        file.batchMode = false;
+        return VFS.SQLITE_OK;
+      }
+      default:
+        return VFS.SQLITE_NOTFOUND;
+    }
+  }
+  // Return CHUNK_SIZE so SQLite aligns journal I/O to chunk boundaries.
+  // Must match the native VFS (kv_io_sector_size in sqlite-native/src/vfs.rs).
+  xSectorSize(_fileId) {
+    return CHUNK_SIZE;
+  }
+  xDeviceCharacteristics(_fileId) {
+    return SQLITE_IOCAP_BATCH_ATOMIC;
+  }
+  xFullPathname(_pVfs, zName, nOut, zOut) {
+    const path3 = this.#module.UTF8ToString(zName);
+    const bytes = TEXT_ENCODER.encode(path3);
+    const out = this.#module.HEAPU8.subarray(zOut, zOut + nOut);
+    if (bytes.length >= out.length) {
+      return VFS.SQLITE_IOERR;
+    }
+    out.set(bytes, 0);
+    out[bytes.length] = 0;
+    return VFS.SQLITE_OK;
+  }
+  #decodeFilename(zName, flags) {
+    if (!zName) {
+      return null;
+    }
+    if (flags & VFS.SQLITE_OPEN_URI) {
+      let pName = zName;
+      let state = 1;
+      const charCodes = [];
+      while (state) {
+        const charCode = this.#module.HEAPU8[pName++];
+        if (charCode) {
+          charCodes.push(charCode);
+          continue;
+        }
+        if (!this.#module.HEAPU8[pName]) {
+          state = null;
+        }
+        switch (state) {
+          case 1:
+            charCodes.push("?".charCodeAt(0));
+            state = 2;
+            break;
+          case 2:
+            charCodes.push("=".charCodeAt(0));
+            state = 3;
+            break;
+          case 3:
+            charCodes.push("&".charCodeAt(0));
+            state = 2;
+            break;
+        }
+      }
+      return TEXT_DECODER.decode(new Uint8Array(charCodes));
+    }
+    return this.#module.UTF8ToString(zName);
+  }
+  #heapView() {
+    const heapBuffer = this.#module.HEAPU8.buffer;
+    if (heapBuffer !== this.#heapDataViewBuffer) {
+      this.#heapDataViewBuffer = heapBuffer;
+      this.#heapDataView = new DataView(heapBuffer);
+    }
+    return this.#heapDataView;
+  }
+  #writeInt32(pointer, value) {
+    const heapByteOffset = this.#module.HEAPU8.byteOffset + pointer;
+    this.#heapView().setInt32(heapByteOffset, value, true);
+  }
+  #writeBigInt64(pointer, value) {
+    const heapByteOffset = this.#module.HEAPU8.byteOffset + pointer;
+    this.#heapView().setBigInt64(heapByteOffset, value, true);
+  }
+};
+function delegalize(lo32, hi32) {
+  const hi = hi32 >>> 0;
+  const lo = lo32 >>> 0;
+  if (hi > MAX_FILE_SIZE_HI32) {
+    return -1;
+  }
+  if (hi === MAX_FILE_SIZE_HI32 && lo > MAX_FILE_SIZE_LO32) {
+    return -1;
+  }
+  return hi * UINT32_SIZE + lo;
+}
+
+// src/pool.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { createRequire as createRequire2 } from "module";
+import path2 from "path";
+function createNodeRequire2() {
+  return createRequire2(
+    path2.join(process.cwd(), "__rivetkit_sqlite_require__.cjs")
+  );
+}
+var SqliteVfsPool = class {
+  #config;
+  #modulePromise = null;
+  #instances = /* @__PURE__ */ new Set();
+  #actorToInstance = /* @__PURE__ */ new Map();
+  #actorToHandle = /* @__PURE__ */ new Map();
+  #shuttingDown = false;
+  constructor(config2) {
+    if (!Number.isInteger(config2.actorsPerInstance) || config2.actorsPerInstance < 1) {
+      throw new Error(
+        `actorsPerInstance must be a positive integer, got ${config2.actorsPerInstance}`
+      );
+    }
+    this.#config = config2;
+  }
+  /**
+   * Compile the WASM module once and cache the promise. Subsequent calls
+   * return the same promise, avoiding redundant compilation.
+   */
+  #getModule() {
+    if (!this.#modulePromise) {
+      this.#modulePromise = (async () => {
+        const require2 = createNodeRequire2();
+        const wasmPath = require2.resolve(
+          "@rivetkit/sqlite/dist/wa-sqlite-async.wasm"
+        );
+        const wasmBinary = readFileSync2(wasmPath);
+        return WebAssembly.compile(wasmBinary);
+      })();
+      this.#modulePromise.catch(() => {
+        this.#modulePromise = null;
+      });
+    }
+    return this.#modulePromise;
+  }
+  /** Number of live WASM instances in the pool. */
+  get instanceCount() {
+    return this.#instances.size;
+  }
+  /** Number of actors currently assigned to pool instances. */
+  get actorCount() {
+    return this.#actorToInstance.size;
+  }
+  /**
+   * Acquire a pooled VFS handle for the given actor. Returns a
+   * PooledSqliteHandle with sticky assignment. If the actor is already
+   * assigned, the existing handle is returned.
+   *
+   * Bin-packing: picks the instance with the most actors that still has
+   * capacity. If all instances are full, creates a new one using the
+   * cached WASM module.
+   */
+  async acquire(actorId) {
+    if (this.#shuttingDown) {
+      throw new Error("SqliteVfsPool is shutting down");
+    }
+    const existingHandle = this.#actorToHandle.get(actorId);
+    if (existingHandle) {
+      return existingHandle;
+    }
+    let bestInstance = null;
+    let bestCount = -1;
+    for (const instance of this.#instances) {
+      if (instance.destroying) continue;
+      const count = instance.actors.size;
+      if (count < this.#config.actorsPerInstance && count > bestCount) {
+        bestInstance = instance;
+        bestCount = count;
+      }
+    }
+    if (!bestInstance) {
+      const wasmModule = await this.#getModule();
+      if (this.#shuttingDown) {
+        throw new Error("SqliteVfsPool is shutting down");
+      }
+      const existingHandleAfterAwait = this.#actorToHandle.get(actorId);
+      if (existingHandleAfterAwait) {
+        return existingHandleAfterAwait;
+      }
+      for (const instance of this.#instances) {
+        if (instance.destroying) continue;
+        const count = instance.actors.size;
+        if (count < this.#config.actorsPerInstance && count > bestCount) {
+          bestInstance = instance;
+          bestCount = count;
+        }
+      }
+      if (!bestInstance) {
+        const vfs = new SqliteVfs(wasmModule);
+        bestInstance = {
+          vfs,
+          actors: /* @__PURE__ */ new Set(),
+          shortNameCounter: 0,
+          actorShortNames: /* @__PURE__ */ new Map(),
+          availableShortNames: /* @__PURE__ */ new Set(),
+          poisonedShortNames: /* @__PURE__ */ new Set(),
+          opsInFlight: 0,
+          idleTimer: null,
+          destroying: false
+        };
+        this.#instances.add(bestInstance);
+      }
+    }
+    this.#cancelIdleTimer(bestInstance);
+    let shortName;
+    const recycled = bestInstance.availableShortNames.values().next();
+    if (!recycled.done) {
+      shortName = recycled.value;
+      bestInstance.availableShortNames.delete(shortName);
+    } else {
+      shortName = String(bestInstance.shortNameCounter++);
+    }
+    bestInstance.actors.add(actorId);
+    bestInstance.actorShortNames.set(actorId, shortName);
+    this.#actorToInstance.set(actorId, bestInstance);
+    const handle = new PooledSqliteHandle(shortName, actorId, this);
+    this.#actorToHandle.set(actorId, handle);
+    return handle;
+  }
+  /**
+   * Release an actor's assignment from the pool. Force-closes all database
+   * handles for the actor, recycles or poisons the short name, and
+   * decrements the instance refcount.
+   */
+  async release(actorId) {
+    const instance = this.#actorToInstance.get(actorId);
+    if (!instance) {
+      return;
+    }
+    const shortName = instance.actorShortNames.get(actorId);
+    if (shortName === void 0) {
+      return;
+    }
+    const { allSucceeded } = await instance.vfs.forceCloseByFileName(shortName);
+    if (allSucceeded) {
+      instance.availableShortNames.add(shortName);
+    } else {
+      instance.poisonedShortNames.add(shortName);
+    }
+    instance.actors.delete(actorId);
+    instance.actorShortNames.delete(actorId);
+    this.#actorToInstance.delete(actorId);
+    this.#actorToHandle.delete(actorId);
+    if (instance.actors.size === 0 && instance.opsInFlight === 0 && !this.#shuttingDown) {
+      this.#startIdleTimer(instance);
+    }
+  }
+  /**
+   * Track an in-flight operation on an instance. Increments opsInFlight
+   * before running fn, decrements after using try/finally to prevent
+   * drift from exceptions. If the decrement brings opsInFlight to 0
+   * with refcount also 0, starts the idle timer.
+   */
+  async #trackOp(instance, fn) {
+    instance.opsInFlight++;
+    try {
+      return await fn();
+    } finally {
+      instance.opsInFlight--;
+      if (instance.actors.size === 0 && instance.opsInFlight === 0 && !instance.destroying && !this.#shuttingDown) {
+        this.#startIdleTimer(instance);
+      }
+    }
+  }
+  /**
+   * Open a database on behalf of an actor, tracked as an in-flight
+   * operation. Used by PooledSqliteHandle to avoid exposing PoolInstance.
+   */
+  async openForActor(actorId, shortName, options) {
+    const instance = this.#actorToInstance.get(actorId);
+    if (!instance) {
+      throw new Error(
+        `Actor ${actorId} is not assigned to any pool instance`
+      );
+    }
+    return this.#trackOp(
+      instance,
+      () => instance.vfs.open(shortName, options)
+    );
+  }
+  /**
+   * Track an in-flight database operation for the given actor. Resolves the
+   * actor's pool instance and wraps the operation with opsInFlight tracking.
+   * If the actor has already been released, the operation runs without
+   * tracking since the instance may already be destroyed.
+   */
+  async trackOpForActor(actorId, fn) {
+    const instance = this.#actorToInstance.get(actorId);
+    if (!instance) {
+      return fn();
+    }
+    return this.#trackOp(instance, fn);
+  }
+  #startIdleTimer(instance) {
+    if (instance.idleTimer || instance.destroying) return;
+    const idleDestroyMs = this.#config.idleDestroyMs ?? 3e4;
+    instance.idleTimer = setTimeout(() => {
+      instance.idleTimer = null;
+      if (instance.actors.size === 0 && instance.opsInFlight === 0 && !instance.destroying) {
+        this.#destroyInstance(instance);
+      }
+    }, idleDestroyMs);
+  }
+  #cancelIdleTimer(instance) {
+    if (instance.idleTimer) {
+      clearTimeout(instance.idleTimer);
+      instance.idleTimer = null;
+    }
+  }
+  async #destroyInstance(instance) {
+    instance.destroying = true;
+    this.#cancelIdleTimer(instance);
+    this.#instances.delete(instance);
+    try {
+      await instance.vfs.forceCloseAll();
+      await instance.vfs.destroy();
+    } catch (error) {
+      console.warn("SqliteVfsPool: failed to destroy instance", error);
+    }
+  }
+  /**
+   * Graceful shutdown. Rejects new acquire() calls, cancels idle timers,
+   * force-closes all databases, destroys all VFS instances, and clears pool
+   * state.
+   */
+  async shutdown() {
+    this.#shuttingDown = true;
+    const instances = [...this.#instances];
+    for (const instance of instances) {
+      this.#cancelIdleTimer(instance);
+      this.#instances.delete(instance);
+      if (instance.opsInFlight > 0) {
+        console.warn(
+          `SqliteVfsPool: shutting down instance with ${instance.opsInFlight} in-flight operation(s). Concurrent close is safe due to Database.close() idempotency.`
+        );
+      }
+      try {
+        await instance.vfs.forceCloseAll();
+        await instance.vfs.destroy();
+      } catch (error) {
+        console.warn(
+          "SqliteVfsPool: failed to destroy instance during shutdown",
+          error
+        );
+      }
+    }
+    this.#actorToInstance.clear();
+    this.#actorToHandle.clear();
+  }
+};
+var TrackedDatabase = class {
+  #inner;
+  #pool;
+  #actorId;
+  constructor(inner, pool, actorId) {
+    this.#inner = inner;
+    this.#pool = pool;
+    this.#actorId = actorId;
+  }
+  async exec(...args) {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.exec(...args)
+    );
+  }
+  async run(...args) {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.run(...args)
+    );
+  }
+  async query(...args) {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.query(...args)
+    );
+  }
+  async close() {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.close()
+    );
+  }
+  get fileName() {
+    return this.#inner.fileName;
+  }
+};
+var PooledSqliteHandle = class {
+  #shortName;
+  #actorId;
+  #pool;
+  #released = false;
+  constructor(shortName, actorId, pool) {
+    this.#shortName = shortName;
+    this.#actorId = actorId;
+    this.#pool = pool;
+  }
+  /**
+   * Open a database on the shared instance. Uses the pool-assigned short
+   * name as the VFS file path, with the caller's KvVfsOptions for KV
+   * routing. The open call itself is tracked as an in-flight operation,
+   * and the returned Database is wrapped so that exec(), run(), query(),
+   * and close() are also tracked via opsInFlight.
+   */
+  async open(_fileName, options) {
+    if (this.#released) {
+      throw new Error("PooledSqliteHandle has been released");
+    }
+    const db = await this.#pool.openForActor(
+      this.#actorId,
+      this.#shortName,
+      options
+    );
+    return new TrackedDatabase(db, this.#pool, this.#actorId);
+  }
+  /**
+   * Release this actor's assignment back to the pool. Idempotent: calling
+   * destroy() more than once is a no-op, preventing double-release from
+   * decrementing the instance refcount below actual.
+   */
+  async destroy() {
+    if (this.#released) {
+      return;
+    }
+    this.#released = true;
+    await this.#pool.release(this.#actorId);
+  }
+};
+export {
+  Database,
+  PooledSqliteHandle,
+  SqliteVfs,
+  SqliteVfsPool
+};
+//# sourceMappingURL=index.js.map