@cavulsqa/create 0.1.0 → 2.2.0

package/templates/f7-app/src/shared/database/candidates/types.ts

@@ -0,0 +1,41 @@
+import type { Dialect } from "kysely";
+
+export type StorageId =
+  | "sqlite-wasm-opfs-sahpool"
+  | "wa-sqlite-access-handle-pool"
+  | "wa-sqlite-opfs-async"
+  | "wa-sqlite-idb-batch-atomic";
+
+export interface StorageProbe {
+  supported: boolean;
+  /** Present when unsupported, phrased so the person reading it can act on it. */
+  reason?: string;
+}
+
+/**
+ * One way to persist SQLite, described well enough to choose between them without reading the code.
+ *
+ * A candidate is not a config flag: it owns its own capability check and its own lazy import, so a
+ * chain that never reaches the fourth entry never downloads the fourth entry's wasm.
+ */
+export interface StorageCandidate {
+  id: StorageId;
+  label: string;
+  /** What it costs. Every entry has one, and an entry claiming none is a lie. */
+  tradeoff: string;
+  durable: boolean;
+  /**
+   * Whether the numbers behind its position in the chain came from a device or from a vendor's
+   * README. Only one entry is currently `measured`, and the ordering says so rather than implying
+   * more confidence than we have.
+   */
+  evidence: "measured" | "expected";
+  probe: () => StorageProbe;
+  createDialect: () => Promise<Dialect>;
+}
+
+export interface StorageAttempt {
+  id: StorageId;
+  outcome: "opened" | "unsupported" | "failed";
+  detail?: string;
+}

package/templates/f7-app/src/shared/database/candidates/waSqlite.ts

@@ -0,0 +1,58 @@
+import { WaSQLiteDialect, type WaVfsKind } from "@cavulsqa/mobile-db/wa";
+import WaWorker from "../wa.worker?worker";
+import { probeIndexedDb, probeOpfsCapable } from "../storage";
+import type { StorageCandidate } from "./types";
+
+/**
+ * wa-sqlite, once per virtual file system.
+ *
+ * The alternative to the official build, and the reason it is here: its VFS layer is JavaScript, so
+ * it reaches storage the official engine has no VFS for. IndexedDB in particular is the only durable
+ * option on a WebView too old for synchronous access handles - the Chromium 86 to 108 band, which
+ * runs this app's bundle perfectly well.
+ *
+ * All three share one worker file and one dialect; only `kind` differs, and it also decides which of
+ * wa-sqlite's two wasm builds gets loaded.
+ */
+function waCandidate(
+  kind: WaVfsKind,
+  fields: Pick<StorageCandidate, "id" | "label" | "tradeoff" | "probe">,
+): StorageCandidate {
+  return {
+    ...fields,
+    durable: true,
+    // Nothing below the official pool has been on a phone yet.
+    evidence: "expected",
+    createDialect: () =>
+      Promise.resolve(
+        new WaSQLiteDialect({ worker: new WaWorker(), name: "app-wa.sqlite3", kind }),
+      ),
+  };
+}
+
+export const waAccessHandlePool = waCandidate("access-handle-pool", {
+  id: "wa-sqlite-access-handle-pool",
+  label: "wa-sqlite · OPFS access handle pool",
+  tradeoff:
+    "The same exclusive directory lock as the official pool, and the same serial worker. Here to " +
+    "measure one vendor's pool against the other's on identical storage.",
+  probe: probeOpfsCapable,
+});
+
+export const waOriginPrivateFileSystem = waCandidate("origin-private-file-system", {
+  id: "wa-sqlite-opfs-async",
+  label: "wa-sqlite · OPFS, no pool",
+  tradeoff:
+    "Runs on the Asyncify build, which wraps every call SQLite believes is synchronous - expected " +
+    "to cost raw speed and to handle concurrent access more gracefully than a pool that locks.",
+  probe: probeOpfsCapable,
+});
+
+export const waIdbBatchAtomic = waCandidate("idb-batch-atomic", {
+  id: "wa-sqlite-idb-batch-atomic",
+  label: "wa-sqlite · IndexedDB",
+  tradeoff:
+    "The slowest durable route: pages go through IndexedDB transactions rather than to a file. The " +
+    "only one that works without synchronous access handles at all.",
+  probe: probeIndexedDb,
+});

package/templates/f7-app/src/shared/database/database.ts

@@ -1,9 +1,13 @@
-import { Capacitor } from "@capacitor/core";
-import { Kysely } from "kysely";
+import { Kysely, sql, type Dialect } from "kysely";
 import { Migrator } from "kysely/migration";
-import { createMobileDatabase, runWrite, type MobileDatabase } from "@cavulsqa/mobile-db";
+import { runWrite, type MobileDatabase } from "@cavulsqa/mobile-db/core";
 import { createChangeBus, createReactiveDb } from "@cavulsqa/reactive-db";
+import { pragmaProfile, pragmasFor } from "@/app/pragmas.config";
+import { storageChain } from "@/app/storage.config";
+import type { StorageId } from "./candidates";
+import type { StorageAttempt, StorageCandidate } from "./candidates";
 import { migrations } from "./migrations";
+import { describeOpenFailure } from "./storage";
 import type { Database } from "./schema";
 
 /**
@@ -13,27 +17,57 @@ import type { Database } from "./schema";
  */
 export const changeBus = createChangeBus();
 
+const RETRY_DELAY_MS = 400;
+
 let database: MobileDatabase<Database> | null = null;
+let chosen: StorageCandidate | null = null;
+let attempts: StorageAttempt[] = [];
+let applied: string[] = [];
 
 /**
- * On a device the database is a real SQLite file behind the Capacitor plugin.
+ * Wraps a Kysely instance in the shape the app consumes, and runs the migrations.
  *
- * In a browser it is sql.js in memory, via the dialect `@cavulsqa/mobile-db` already ships for its
- * own tests. That is deliberate: the plugin's web mode needs a `jeep-sqlite` element plus a
- * `sql-wasm.wasm` whose build must match the glue jeep-sqlite bundles - a pairing outside this
- * template's control that breaks on any upstream bump. This path has no assets to serve and no
- * version to keep in step; the cost is that browser data does not survive a reload, which for a
- * template running `vp dev` is the honest trade.
+ * Shared by every candidate: they differ in how bytes reach storage and in nothing above that, which
+ * is what makes the chain swappable at all.
  */
-async function openWebDatabase(): Promise<MobileDatabase<Database>> {
-  const { createSqlJsDialect } = await import("@cavulsqa/mobile-db/testing");
-  const db = new Kysely<Database>({ dialect: await createSqlJsDialect() });
+async function fromDialect(dialect: Dialect): Promise<MobileDatabase<Database>> {
+  const db = new Kysely<Database>({ dialect });
+
+  /**
+   * Before the migrations, and identically for every engine. SQLite's defaults are per-build, so two
+   * engines left on their own are not comparable - a difference in `synchronous` alone can look like
+   * one engine being half as fast as the other.
+   */
+  applied = [];
+  for (const pragma of pragmasFor(pragmaProfile)) {
+    try {
+      await sql.raw(pragma).execute(db);
+      applied.push(pragma);
+    } catch (error) {
+      // A VFS that refuses a journal mode is worth knowing about, not worth failing over.
+      applied.push(`${pragma} -> rejected: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+  }
 
-  await new Migrator({
+  /**
+   * `migrateToLatest` reports failure in its return value rather than throwing, so an unchecked call
+   * boots an app whose tables were never created - which is exactly what happened: a deleted
+   * migration made kysely refuse the whole set, and the failure only surfaced later as
+   * "no such table" from the first query that needed one.
+   */
+  const migration = await new Migrator({
     db,
     provider: { getMigrations: () => Promise.resolve(migrations) },
   }).migrateToLatest();
 
+  if (migration.error) {
+    const failed = migration.results?.find((result) => result.status === "Error")?.migrationName;
+    // kysely types the error as unknown, and a non-Error would stringify to [object Object].
+    const detail =
+      migration.error instanceof Error ? migration.error.message : JSON.stringify(migration.error);
+    throw new Error(`migration failed${failed ? ` at ${failed}` : ""}: ${detail}`);
+  }
+
   return {
     db,
     write: (ctx, work) =>
@@ -42,31 +76,115 @@ async function openWebDatabase(): Promise<MobileDatabase<Database>> {
         emitTableChange: (table) => changeBus.emit(table, "bulk"),
       }),
     getRawConnection: () => {
-      throw new Error("no native connection in a browser");
+      throw new Error("the OPFS engine has no native connection");
     },
     close: () => db.destroy(),
   };
 }
 
+/** Which candidate the open database is using, for anything that reports or measures. */
+export function activeStorage(): StorageCandidate {
+  if (!chosen) throw new Error("openDatabase() must be awaited before the storage is known");
+  return chosen;
+}
+
+export function activeStorageLabel(): string {
+  return activeStorage().label;
+}
+
+/** The PRAGMAs that actually took, so a measurement can state its own configuration. */
+export function activePragmas(): readonly string[] {
+  return applied;
+}
+
+/** Every step of the walk, including the candidates that were skipped and why. */
+export function storageAttempts(): readonly StorageAttempt[] {
+  return attempts;
+}
+
+/**
+ * Walks the chain in `storage.config.ts` and keeps the first candidate that opens.
+ *
+ * A candidate is skipped when it says the device cannot support it, and dropped when it says so by
+ * throwing. Every step is recorded: which were skipped and why, which failed and with what, and
+ * which won - because a silent fallback to a slower or non-durable engine is the kind of thing that
+ * gets discovered weeks later by someone wondering why the app is slow.
+ */
+const FORCE_KEY = "app.storage.force";
+
+/**
+ * Pins the chain to one candidate, for benchmarking.
+ *
+ * Set `localStorage.app.storage.force` to a candidate id and only that engine is tried - not moved
+ * to the front, the *only* one - because a benchmark that quietly fell through to a different engine
+ * would report the wrong engine's numbers. An unknown id is ignored rather than bricking the app.
+ */
+function forcedChain(): StorageCandidate[] {
+  let forced: string | null = null;
+  try {
+    forced = localStorage.getItem(FORCE_KEY);
+  } catch {
+    // Storage disabled; the full chain is the right answer anyway.
+  }
+  if (!forced) return storageChain;
+
+  const pinned = storageChain.find((candidate) => candidate.id === (forced as StorageId));
+  return pinned ? [pinned] : storageChain;
+}
+
 export async function openDatabase(): Promise<MobileDatabase<Database>> {
   if (database) return database;
+  if (!storageChain.length) throw new Error("storageChain is empty: nothing can open the database");
 
-  database =
-    Capacitor.getPlatform() === "web"
-      ? await openWebDatabase()
-      : await createMobileDatabase<Database>({
-          name: "app",
-          migrations,
-          emitTableChange: (table) => changeBus.emit(table, "bulk"),
-          /**
-           * One native connection cannot serve two writers. This serialises writes and transactions
-           * while leaving reads parallel, because the native bridge pipelines concurrent calls and
-           * queueing reads costs several times the latency on a screen loading with `Promise.all`.
-           */
-          serializeAccess: true,
-        });
+  attempts = [];
 
-  return database;
+  const chain = forcedChain();
+
+  for (const candidate of chain) {
+    const probe = candidate.probe();
+    if (!probe.supported) {
+      attempts.push({ id: candidate.id, outcome: "unsupported", detail: probe.reason });
+      continue;
+    }
+
+    try {
+      database = await openCandidate(candidate);
+      chosen = candidate;
+      attempts.push({ id: candidate.id, outcome: "opened" });
+      return database;
+    } catch (error) {
+      attempts.push({ id: candidate.id, outcome: "failed", detail: describeOpenFailure(error) });
+    }
+  }
+
+  // Every candidate's reason, because "the database would not open" on its own helps nobody.
+  const summary = attempts
+    .map(
+      (attempt) =>
+        `${attempt.id}: ${attempt.outcome}${attempt.detail ? ` - ${attempt.detail}` : ""}`,
+    )
+    .join("; ");
+  throw new Error(`No storage engine could open the database. ${summary}`);
+}
+
+/**
+ * One retry per candidate, because the pool VFSes take an exclusive lock on their directory and the
+ * usual reason it is held is a process on its way out - a crash, or a relaunch racing the old
+ * WebView's teardown. Its handles are released when that process dies, so the same open succeeds a
+ * moment later. Exactly one retry: past that, the chain moving on is the better answer.
+ */
+async function openCandidate(candidate: StorageCandidate): Promise<MobileDatabase<Database>> {
+  try {
+    return await fromDialect(await candidate.createDialect());
+  } catch (first) {
+    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+    try {
+      return await fromDialect(await candidate.createDialect());
+    } catch {
+      // The first error is the honest one; the retry's is a duplicate of it.
+      throw first;
+    }
+  }
 }
 
 export function getDatabase(): MobileDatabase<Database> {
@@ -83,4 +201,7 @@ export const rdb = createReactiveDb<Database>({
 export async function closeDatabase(): Promise<void> {
   await database?.close();
   database = null;
+  chosen = null;
+  attempts = [];
+  applied = [];
 }

package/templates/f7-app/src/shared/database/migrations.ts

@@ -1,4 +1,4 @@
-import { createTableWithDefaults, type MigrationSet } from "@cavulsqa/mobile-db";
+import { createTableWithDefaults, type MigrationSet } from "@cavulsqa/mobile-db/core";
 import { sql } from "kysely";
 
 /**
@@ -78,4 +78,146 @@ export const migrations: MigrationSet = {
       await sql`PRAGMA foreign_keys = ON`.execute(db);
     },
   },
+
+  /**
+   * A tombstone, and it has to stay.
+   *
+   * This migration created the two-table benchmark that 003 replaced. Deleting the entry rather than
+   * emptying it is what broke the app: kysely records applied migrations by key, finds one recorded
+   * that the provider no longer offers, calls the history corrupted and applies *nothing* - so 003
+   * never ran and the first query failed with "no such table: bench_order_line".
+   *
+   * An applied migration is a fact about databases in the world. It can stop doing anything; it
+   * cannot stop existing.
+   */
+  "002_benchmark": {
+    up: async () => {
+      // Its tables are created and dropped by 003; there is nothing left for this to do.
+    },
+  },
+
+  /**
+   * The benchmark's tables, replacing the two-table version outright - this is R&D and nothing
+   * depends on the old shape.
+   *
+   * Indexed where a screen would index: foreign keys, the columns joins and filters use, and one
+   * composite for the stock lookup. `bench_customer.notes` is deliberately left unindexed so the
+   * LIKE case measures a genuine scan, and `bench_order.total_cents` too, so one case has to sort
+   * without help.
+   */
+  "003_benchmark_scale": {
+    up: async (db) => {
+      await db.schema.dropTable("bench_child").ifExists().execute();
+      await db.schema.dropTable("bench_parent").ifExists().execute();
+
+      await db.schema
+        .createTable("bench_region")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_city")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("region_id", "integer", (col) => col.notNull().references("bench_region.id"))
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_customer")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("city_id", "integer", (col) => col.notNull().references("bench_city.id"))
+        .addColumn("code", "text", (col) => col.notNull().unique())
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("notes", "text", (col) => col.notNull().defaultTo(""))
+        .addColumn("credit_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .addColumn("created_at", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_category")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_product")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("category_id", "integer", (col) => col.notNull().references("bench_category.id"))
+        .addColumn("sku", "text", (col) => col.notNull().unique())
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_warehouse")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_stock")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("warehouse_id", "integer", (col) =>
+          col.notNull().references("bench_warehouse.id"),
+        )
+        .addColumn("product_id", "integer", (col) => col.notNull().references("bench_product.id"))
+        .addColumn("quantity", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_order")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("customer_id", "integer", (col) =>
+          col.notNull().references("bench_customer.id").onDelete("cascade"),
+        )
+        .addColumn("reference", "text", (col) => col.notNull())
+        .addColumn("status", "text", (col) => col.notNull().defaultTo("draft"))
+        .addColumn("created_at", "text", (col) => col.notNull())
+        .addColumn("total_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_order_line")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("order_id", "integer", (col) =>
+          col.notNull().references("bench_order.id").onDelete("cascade"),
+        )
+        .addColumn("product_id", "integer", (col) => col.notNull().references("bench_product.id"))
+        .addColumn("quantity", "integer", (col) => col.notNull().defaultTo(1))
+        .addColumn("unit_price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_payment")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("order_id", "integer", (col) =>
+          col.notNull().references("bench_order.id").onDelete("cascade"),
+        )
+        .addColumn("amount_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .addColumn("method", "text", (col) => col.notNull())
+        .addColumn("created_at", "text", (col) => col.notNull())
+        .execute();
+
+      for (const [name, table, column] of [
+        ["idx_bench_city_region", "bench_city", "region_id"],
+        ["idx_bench_customer_city", "bench_customer", "city_id"],
+        ["idx_bench_product_category", "bench_product", "category_id"],
+        ["idx_bench_order_customer", "bench_order", "customer_id"],
+        ["idx_bench_order_status", "bench_order", "status"],
+        ["idx_bench_line_order", "bench_order_line", "order_id"],
+        ["idx_bench_line_product", "bench_order_line", "product_id"],
+        ["idx_bench_payment_order", "bench_payment", "order_id"],
+      ] as const) {
+        await db.schema.createIndex(name).on(table).column(column).execute();
+      }
+
+      // Composite, because a stock lookup filters on both and neither alone is selective enough.
+      await db.schema
+        .createIndex("idx_bench_stock_warehouse_product")
+        .on("bench_stock")
+        .columns(["warehouse_id", "product_id"])
+        .execute();
+    },
+  },
 };

package/templates/f7-app/src/shared/database/opfs.worker.ts

@@ -0,0 +1,5 @@
+import { runOpfsWorker } from "@cavulsqa/mobile-db/opfs";
+
+// The whole worker. It lives in the app rather than the package because only the app's bundler can
+// emit a worker and the sqlite3.wasm it loads; the logic is all in @cavulsqa/mobile-db.
+runOpfsWorker();

package/templates/f7-app/src/shared/database/schema.ts

@@ -56,4 +56,98 @@ export interface Database {
   order_line: OrderLineTable;
   tag: TagTable;
   customer_tag: CustomerTagTable;
+  bench_region: BenchRegionTable;
+  bench_city: BenchCityTable;
+  bench_customer: BenchCustomerTable;
+  bench_category: BenchCategoryTable;
+  bench_product: BenchProductTable;
+  bench_warehouse: BenchWarehouseTable;
+  bench_stock: BenchStockTable;
+  bench_order: BenchOrderTable;
+  bench_order_line: BenchOrderLineTable;
+  bench_payment: BenchPaymentTable;
+}
+
+/**
+ * The benchmark's own tables, deliberately separate from the app's.
+ *
+ * Ten tables at roughly 100k rows, shaped like a distribution domain - regions down to order lines,
+ * plus stock and payments - because the questions worth answering are about joins across a real
+ * cardinality spread, not about two tables with a foreign key. A five-level join here touches a
+ * 10-row table and a 40k-row table in the same query, which is where planners and indexes start to
+ * matter.
+ *
+ * Measuring against the app's own tables would either corrupt them or force a rollback, and a
+ * rolled-back transaction never pays the commit - most of what a write costs on a phone.
+ */
+export interface BenchRegionTable {
+  id: Generated<number>;
+  name: string;
+}
+
+export interface BenchCityTable {
+  id: Generated<number>;
+  region_id: number;
+  name: string;
+}
+
+export interface BenchCustomerTable {
+  id: Generated<number>;
+  city_id: number;
+  code: string;
+  name: string;
+  /** Unindexed on purpose: the LIKE case needs a genuine full scan over 5k rows. */
+  notes: string;
+  credit_cents: number;
+  created_at: string;
+}
+
+export interface BenchCategoryTable {
+  id: Generated<number>;
+  name: string;
+}
+
+export interface BenchProductTable {
+  id: Generated<number>;
+  category_id: number;
+  sku: string;
+  name: string;
+  price_cents: number;
+}
+
+export interface BenchWarehouseTable {
+  id: Generated<number>;
+  name: string;
+}
+
+export interface BenchStockTable {
+  id: Generated<number>;
+  warehouse_id: number;
+  product_id: number;
+  quantity: number;
+}
+
+export interface BenchOrderTable {
+  id: Generated<number>;
+  customer_id: number;
+  reference: string;
+  status: string;
+  created_at: string;
+  total_cents: number;
+}
+
+export interface BenchOrderLineTable {
+  id: Generated<number>;
+  order_id: number;
+  product_id: number;
+  quantity: number;
+  unit_price_cents: number;
+}
+
+export interface BenchPaymentTable {
+  id: Generated<number>;
+  order_id: number;
+  amount_cents: number;
+  method: string;
+  created_at: string;
 }

package/templates/f7-app/src/shared/database/storage.ts

@@ -0,0 +1,94 @@
+import type { StorageProbe } from "./candidates/types";
+
+export type { StorageProbe };
+
+/**
+ * Capability checks and failure diagnosis, shared by the candidates.
+ *
+ * The chain itself lives in `app/storage.config.ts` and each engine in `candidates/`; this is only
+ * the part they have in common - deciding whether a device can host OPFS at all, and turning an
+ * engine's failure into a sentence somebody can act on.
+ */
+
+/**
+ * Only what the main thread can honestly observe.
+ *
+ * The tempting check - `"createSyncAccessHandle" in FileSystemFileHandle.prototype` - is wrong here
+ * and rejected a phone on WebView 150 that had been running OPFS happily: synchronous access handles
+ * are Worker-only in Chromium, so the method is absent from the main-thread prototype on *every*
+ * device, new or old. `navigator.storage.getDirectory` is visible from both scopes, so that is the
+ * whole of what can be pre-checked.
+ *
+ * Anything finer belongs to the engine. `describeOpenFailure` turns its error into something a
+ * person can act on, which is what the pre-check was reaching for in the first place.
+ */
+export function probeOpfsCapable(): StorageProbe {
+  if (typeof navigator === "undefined" || !navigator.storage?.getDirectory) {
+    return {
+      supported: false,
+      reason:
+        "This WebView has no Origin Private File System, so the database cannot be stored. Update " +
+        "Android System WebView from the Play Store - it updates separately from Android itself.",
+    };
+  }
+
+  return { supported: true };
+}
+
+/**
+ * The engine is the authority on whether it can open, so its failure is wrapped rather than
+ * predicted. A missing synchronous access handle surfaces from inside wasm initialisation, where the
+ * message names an internal symbol and not the thing to do about it.
+ */
+export function probeIndexedDb(): StorageProbe {
+  if (typeof indexedDB === "undefined") {
+    return {
+      supported: false,
+      reason: "This WebView has no IndexedDB, which leaves nowhere to keep the database.",
+    };
+  }
+  return { supported: true };
+}
+
+export function describeOpenFailure(error: unknown): string {
+  const detail = error instanceof Error ? error.message : String(error);
+
+  if (/SyncAccessHandle|createSyncAccessHandle|sahpool|SAH/i.test(detail)) {
+    return (
+      "SQLite could not take a synchronous file handle. Either this WebView is too old - update " +
+      "Android System WebView from the Play Store, it updates separately from Android - or another " +
+      `copy of the app still holds the database open. (${detail})`
+    );
+  }
+
+  return `The database could not be opened: ${detail}`;
+}
+
+/**
+ * The Chromium version behind this WebView, which is the number that decides whether OPFS works.
+ *
+ * Worth surfacing rather than reasoning about: Android System WebView updates from the Play Store
+ * independently of Android itself, so the OS version says nothing useful. A phone on Android 7 with
+ * a current WebView is fine; a phone on Android 14 that has never reached the Play Store may not be.
+ */
+export function webviewVersion(): number | null {
+  if (typeof navigator === "undefined") return null;
+  const match = /Chrome\/(\d+)/.exec(navigator.userAgent);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * OPFS arrived in Chromium 86, synchronous access handles followed, and the combination is reported
+ * stable in WebView from 109. 109 is used rather than the earlier number because this value only
+ * ever produces advice: too low and a phone in the gap is told its WebView is fine before failing
+ * anyway, while too high only ever suggests an update that does no harm.
+ *
+ * A floor, never a gate. A vendor WebView build can differ either way, so the app probes and wraps
+ * the engine's real failure rather than letting this number decide anything.
+ */
+export const MINIMUM_CHROMIUM_FOR_OPFS = 109;
+
+export function webviewLikelyTooOld(): boolean {
+  const version = webviewVersion();
+  return version !== null && version < MINIMUM_CHROMIUM_FOR_OPFS;
+}