first commit

docs/api-stack/api/api-db-sqlite-memory/src/engine/register-engine.md

@@ -0,0 +1,77 @@
+# `registerSqliteMemoryEngine`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Registers the in-memory SQLite adapter under `engine: "sqlite-memory"` in the open `@suaveplan/api-db-adapter` engine registry. Once called, any consumer that constructs an adapter via `createDbAdapter({ engine: "sqlite-memory", ... })` receives an instance produced by this package. The TypeScript-side declaration-merge into `DatabaseEngineRegistry` means the engine name is accepted as a string-literal-typed argument with no cast.
+
+This is the bridge that lets `@suaveplan/api-host/testing`'s Stage-5 `createTestHost` boot a plugin entirely against an in-memory SQLite without changing any of The adapter code paths. The registration is idempotent — calling twice replaces the previous factory — and the function returns a disposer so tests can unregister the engine in `afterEach`.
+
+## Features
+
+- Type-level: `declare module` extends `DatabaseEngineRegistry` with `"sqlite-memory": true`.
+- Runtime: `registerEngine("sqlite-memory", factory)` against the api-db-adapter registry.
+- Factory honours `DbAdapterOptions.url` → `filename` so callers may write `engine: "sqlite-memory"` + `url: ":memory:"` (or a file path).
+- Forwards `tenantColumn` + `autoInjectInserts` so The wrapper composes correctly on top.
+- Returns a disposer `() => boolean` that unregisters the engine.
+
+## Usage: Basic
+
+```ts
+import { createDbAdapter } from "@suaveplan/api-db-adapter";
+import { registerSqliteMemoryEngine } from "@suaveplan/api-db-sqlite-memory/engine";
+
+const dispose = registerSqliteMemoryEngine();
+const adapter = await createDbAdapter({
+    engine: "sqlite-memory",
+    url: ":memory:",
+});
+await adapter.admin.execute("CREATE TABLE t (id INTEGER PRIMARY KEY)");
+await adapter.close();
+dispose();
+```
+
+## Usage: Advanced
+
+Test lifecycle with deterministic registry teardown:
+
+```ts
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    it,
+} from "@suaveplan/testing/runner";
+import { createDbAdapter } from "@suaveplan/api-db-adapter";
+import { registerSqliteMemoryEngine } from "@suaveplan/api-db-sqlite-memory/engine";
+
+describe("plugin install", () => {
+    let dispose: () => boolean;
+    beforeEach(() => {
+        dispose = registerSqliteMemoryEngine();
+    });
+    afterEach(() => {
+        dispose();
+    });
+
+    it("resolves the engine sentinel", { timeout: 5000 }, async () => {
+        const adapter = await createDbAdapter({
+            engine: "sqlite-memory",
+            url: ":memory:",
+            tenantColumn: "tenant_id",
+        });
+        await adapter.close();
+    });
+});
+```
+
+## API Reference
+
+- `registerSqliteMemoryEngine()` — returns a disposer `() => boolean`.
+
+## Implementation Notes
+
+The declaration-merge happens inside this module so the type extension is only visible after the consumer imports from `@suaveplan/api-db-sqlite-memory/engine` (or the package root, which re-exports). That keeps the engine sentinel scoped to plugins that opt in, matching the design intent of the open `DatabaseEngineRegistry`. The factory normalises an empty or `"sqlite-memory:"` url to `":memory:"` because `createDbAdapter`'s Zod schema requires `url` to be non-empty — without this normalisation, callers would have to write `url: ":memory:"` redundantly even when the engine name already implies it.