first commit

docs/persistence/database/db-sqlite/src/conformance/conformance-suite.md

@@ -0,0 +1,64 @@
+# conformance-suite
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides `runConformanceSuite`, a driver-agnostic test factory that accepts a `DriverFactory` callback and executes a standard suite of CRUD, transaction, and rollback assertions against any SQLite driver. Running the same suite against both the Bun driver and a WASM driver ensures that both runtimes satisfy the same behavioural contract, catching driver-specific regressions before they reach production.
+
+The suite is intentionally minimal — it tests the lowest-level SQL operations that the adapter layer depends on. Higher-level tests (prepared-statement cache behaviour, migration runner idempotency, OTel counter increments) live in their respective unit test files.
+
+## Features
+
+- `runConformanceSuite(name, factory)` — registers a Vitest `describe` block named `${name} conformance`
+- Tests: table creation, SELECT, INSERT with parameters, transaction commit, transaction rollback, UPDATE, DELETE
+- `DriverFactory` interface — a single `create()` method returning `{ sqlite, close }`
+- Runs under the Bun driver via `bun-conformance.test.ts`
+
+## Usage: Basic Example
+
+```ts
+import { runConformanceSuite } from "@suaveplan/db-sqlite/src/conformance/conformance-suite";
+import { createBunDriver } from "@suaveplan/db-sqlite/drivers/bun-driver";
+
+runConformanceSuite("Bun driver", {
+  async create() {
+    return createBunDriver({ filename: ":memory:" });
+  },
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { runConformanceSuite } from "@suaveplan/db-sqlite/src/conformance/conformance-suite";
+
+// Custom driver shim for testing
+runConformanceSuite("Custom driver", {
+  async create() {
+    const driver = await MyCustomDriver.open(":memory:");
+    return { sqlite: driver.raw, close: async () => driver.close() };
+  },
+});
+```
+
+## API Reference
+
+### `DriverFactory`
+
+```ts
+interface DriverFactory {
+  create(): Promise<{ sqlite: any; close: () => Promise<void> }>;
+}
+```
+
+### `runConformanceSuite(name: string, factory: DriverFactory): void`
+
+Registers a Vitest `describe` block with 5 test cases covering the core SQLite contract.
+
+## Implementation Notes
+
+The conformance suite uses raw `sqlite.run()` / `sqlite.query().all()` calls rather than going through `SqliteAdapter` or Drizzle. This keeps the suite focused on driver-level semantics rather than adapter-layer concerns, making it useful for validating new driver implementations independently of the adapter code.
+
+Each test creates fresh tables with unique names to avoid interference between tests within the same suite run.