@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/guides/core-concepts/persistent/datasources.md

@@ -3,7 +3,7 @@
 A DataSource manages database connections and supports **schema auto-discovery** from repositories.
 
 > [!NOTE] Connectors
-> This guide covers the **PostgreSQL connector** (`BasePostgresDataSource`, aliased as `BaseDataSource` for backward compatibility) - the primary relational engine and the one used by most applications. IGNIS also ships a **typesense connector** for full-text/vector search (see [Search & Typesense](./search-typesense)). Both implement the same engine-neutral `AbstractDataSource` contract - see [Connectors](/references/base/connectors) for the architecture.
+> This guide covers the **PostgreSQL connector** (`BasePostgresDataSource`, aliased as `BaseDataSource` for backward compatibility). It's the primary relational engine and the one used by most applications. IGNIS also ships a **SQLite connector** (`BaseSqliteDataSource`, see [SQLite](./sqlite)) and a **typesense connector** for full-text/vector search (see [Search & Typesense](./search-typesense)). All three implement the same engine-neutral `AbstractDataSource` contract - see [Connectors](/references/base/connectors) for the architecture.
 
 ## Creating a DataSource
 
@@ -57,7 +57,7 @@ export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
 ```
 
 > [!NOTE] Driver seam: the raw client goes on `this.client`
-> `this.client = new Pool(...)` is the short path: `configure()` builds only the client, and `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over it - `NodePostgresDriver` here. There is no `pool` field - the raw-client slot is `client`, whatever the client happens to be. Naming the driver class (rather than a driver-name string) is what carries `pg` into the app's bundle - a bundler only packages a real value reference, never text. The alternative is to wire a driver yourself for a custom or third-party driver: `configure()` calls `this.useDriver({ driver, schema? })`, which assigns `this.driver` **and** builds `this.connector` in one step (so the half-wired state cannot exist), bypassing `@datasource({ driver })` entirely. See [Postgres Drivers & Supabase](./postgres-drivers) for `postgres-js` and Supabase.
+> `this.client = new Pool(...)` is the short path: `configure()` builds only the client. `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over it - `NodePostgresDriver` here. There is no `pool` field - the raw-client slot is `client`, whatever the client happens to be. Naming the driver class (rather than a driver-name string) is what carries `pg` into the app's bundle. A bundler only packages a real value reference, never text. The alternative is to wire a driver yourself for a custom or third-party driver: `configure()` calls `this.useDriver({ driver, schema? })`. That assigns `this.driver` **and** builds `this.connector` in one step (so the half-wired state cannot exist), bypassing `@datasource({ driver })` entirely. See [Postgres Drivers & Supabase](./postgres-drivers) for `postgres-js` and Supabase.
 
 **How auto-discovery works:**
 

package/content/guides/core-concepts/persistent/index.md

@@ -3,7 +3,7 @@
 The persistent layer manages data using [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access and the Repository pattern for data abstraction.
 
 > [!NOTE] Connectors
-> This page and the ones below it focus on the **PostgreSQL connector** (Drizzle + relational tables), the default and most common engine. The persistence layer also ships a **typesense connector** for search (see [Search & Typesense](./search-typesense)). Both share the same engine-neutral `AbstractRepository`/`AbstractDataSource`/`AbstractEntity` contracts - see [Connectors](/references/base/connectors) for the architecture.
+> This page and the ones below it focus on the **PostgreSQL connector** (Drizzle + relational tables), the default and most common engine. The persistence layer also ships a **SQLite connector** (see [SQLite](./sqlite)) and a **typesense connector** for search (see [Search & Typesense](./search-typesense)). All three share the same engine-neutral `AbstractRepository`/`AbstractDataSource`/`AbstractEntity` contracts - see [Connectors](/references/base/connectors) for the architecture.
 
 ## Architecture Overview
 
@@ -32,6 +32,8 @@ The persistent layer manages data using [Drizzle ORM](https://orm.drizzle.team/)
 | **Repositories** | Provide type-safe CRUD operations | [Repositories Guide](./repositories.md) |
 | **Transactions** | Handle atomic multi-step operations (PostgreSQL connector only) | [Transactions Guide](./transactions.md) |
 | **Search & Typesense** | Full-text/faceted search over documents | [Search & Typesense Guide](./search-typesense.md) |
+| **PGlite** | Postgres compiled to WebAssembly, running in-process | [PGlite Guide](./pglite.md) |
+| **SQLite** | The second SQL engine, via libsql | [SQLite Guide](./sqlite.md) |
 
 ## Quick Example
 
@@ -107,6 +109,8 @@ export class Application extends BaseApplication {
   - [DataSources](./datasources) - Database connections
   - [Repositories](./repositories) - Data access layer
   - [Transactions](./transactions) - Atomic operations
+  - [PGlite](./pglite) - Postgres in-process, for tests and embedded deployment
+  - [SQLite](./sqlite) - The second SQL engine, and what it refuses
   - [Search & Typesense](./search-typesense) - The typesense connector
 
 - **Related Concepts:**

package/content/guides/core-concepts/persistent/models.md

@@ -200,7 +200,7 @@ const user = await userRepo.findById({ id: '123' });
 // { id: '123', email: 'john@example.com' }
 
 // Connector query - includes all fields
-const connector = userRepo.getConnector();
+const connector = userRepo.connector;
 const [fullUser] = await connector
   .select()
   .from(User.schema)

package/content/guides/core-concepts/persistent/pglite.md

@@ -0,0 +1,218 @@
+# PGlite - Postgres In Your Process
+
+PGlite is PostgreSQL compiled to WebAssembly. It runs inside your Node or Bun process, with no server, no port and no container. IGNIS reaches it through `PGliteDriver`, a third driver on the unchanged Postgres connector.
+
+```typescript
+import { PGlite } from '@electric-sql/pglite';
+import { datasource } from '@venizia/ignis';
+import type { TAnyDataSourceSchema, ValueOrPromise } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { PGliteDriver } from '@venizia/ignis/postgres/pglite';
+
+@datasource({ driver: PGliteDriver })
+export class TestDataSource extends BasePostgresDataSource<{}, TAnyDataSourceSchema, {}, PGlite> {
+  constructor() {
+    super({ name: TestDataSource.name, config: {} });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    this.client = new PGlite();
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    return 'memory://';
+  }
+}
+```
+
+Your models, repositories and filters do not change. PGlite reports `PostgreSQL 18.3`, so every statement the filter builder emits works unchanged - `#>>` JSON paths, `ILIKE`, regex operators, arrays, `SELECT ... FOR UPDATE`.
+
+> [!IMPORTANT] Optional peer dependency
+> `@electric-sql/pglite` is an optional peer. Only the driver class you import and name in `@datasource({ driver })` reaches your bundle.
+>
+> ```bash
+> bun add @electric-sql/pglite
+> ```
+
+## What PGlite is good for
+
+Two cases, and they are the only two worth the constraints below.
+
+**An honest test database.** Your suite gets real Postgres semantics in-process - no Docker, no fixture server, no port collisions between parallel CI jobs. A SQLite test database would answer differently from production. PGlite answers the same. IGNIS runs its own relational conformance suite this way.
+
+**Embedded deployment.** A CLI, a desktop app or an edge worker ships one data directory instead of a database service. `new PGlite('./pgdata')` creates and opens it. PGlite is a directory rather than a single file - `dumpDataDir()` is what packs it into one artifact.
+
+Anything with concurrent writers belongs on a real Postgres server. Read [the constraints](#the-constraints) before you pick PGlite for a running service.
+
+## Wiring a persistent instance
+
+Point PGlite at a directory and it persists there:
+
+```typescript
+import { PGlite } from '@electric-sql/pglite';
+import { datasource } from '@venizia/ignis';
+import type { TAnyDataSourceSchema, ValueOrPromise } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { PGliteDriver } from '@venizia/ignis/postgres/pglite';
+
+interface IDataSourceConfigs {
+  dataDir: string;
+}
+
+@datasource({ driver: PGliteDriver })
+export class EmbeddedDataSource extends BasePostgresDataSource<
+  IDataSourceConfigs,
+  TAnyDataSourceSchema,
+  {},
+  PGlite
+> {
+  constructor() {
+    super({
+      name: EmbeddedDataSource.name,
+      config: { dataDir: process.env.APP_ENV_PGLITE_DATA_DIR ?? './pgdata' },
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    this.client = new PGlite(this.settings.dataDir);
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    return this.settings.dataDir;
+  }
+}
+```
+
+`configure()` builds only the client. Naming `PGliteDriver` in the decorator is what wires the driver and the connector, lazily, on the first `getConnector()` or `beginTransaction()`.
+
+The fourth type parameter pins `getClient()` to `PGlite`. Declare it whenever you reach for the raw client - `waitReady`, `exec()`, `dumpDataDir()`.
+
+> [!NOTE] `getConnectionString()` returns a data directory, not a URL
+> There is no host, port or user to spell. IGNIS never calls this method itself - it exists for your own tooling, so return whatever identifies the database. A directory path for a persistent instance, `memory://` for an ephemeral one.
+
+## The constraints
+
+These matter more than the setup. PGlite is a single embedded Postgres instance, and it has **exactly one session**.
+
+### Transactions serialise
+
+`beginTransaction()` borrows the one session from a 1-slot pool. A second caller waits for the first transaction to commit or roll back. There is no parallelism to lose - one session cannot run two transactions anyway.
+
+A second `BEGIN` on that session would not nest and would not error. It joins the open transaction silently, and the outer `COMMIT` commits the inner writer's rows. The pool is what stops that.
+
+### A write during an open transaction is swallowed by it
+
+This is the trap. Repositories run through the pooled connector that `createConnector()` builds. On one session, that connector is inside whatever transaction happens to be open:
+
+```typescript
+const transaction = await dataSource.beginTransaction();
+
+// Runs INSIDE the transaction above, because there is only one session.
+await this.productRepository.create({ data: { name: 'widget' } });
+
+await transaction.rollback(); // The product is gone.
+```
+
+Measured, not theorised: the row does not survive the rollback.
+
+Pass the transaction explicitly, and the write is deliberate rather than accidental:
+
+```typescript
+await this.productRepository.create({
+  data: { name: 'widget' },
+  options: { transaction },
+});
+```
+
+That is PGlite, not the IGNIS driver. On a server-backed Postgres each caller gets its own connection and the problem does not exist. Under concurrency, route every write through a transaction.
+
+### The acquire timeout
+
+A transaction that never commits holds the one slot forever. Without a bound, every later `acquire()` in the process hangs silently. So the wait is bounded:
+
+| Option | Type | Default | Meaning |
+| :--- | :--- | :--- | :--- |
+| `acquireTimeoutMs` | `number` | `PGliteDriver.DEFAULT_ACQUIRE_TIMEOUT_MS` (30000) | Max ms to wait for the session before rejecting |
+| `maxWaitingClients` | `number` | unlimited | Max queued waiters; over the limit, `acquire()` rejects immediately |
+| `scope` | `string` | `'PGliteDriver'` | Logger scope |
+| `client` | `PGlite` | required | The instance the driver borrows |
+
+The timeout bounds the **wait for the slot**, never the transaction itself. It fires only under contention, so a migration or a bulk seed running alone never trips it. When it does fire you get a named error, not a dead process:
+
+```
+[PGliteDriver][acquire] Could not borrow the single PGlite session
+| [acquire] Acquire timed out after 30000ms.
+| An unreleased transaction still holds it - commit/rollback it, or raise `acquireTimeoutMs`
+```
+
+To change any of these, construct the driver yourself with `useDriver()`. That assigns the driver and builds the connector in one step, and bypasses `@datasource({ driver })`:
+
+```typescript
+override configure(): ValueOrPromise<void> {
+  const client = new PGlite(this.settings.dataDir);
+
+  this.useDriver({
+    driver: new PGliteDriver({ client, acquireTimeoutMs: 120_000 }),
+    schema: this.getSchema(),
+  });
+}
+```
+
+`size` is not an option. One slot **is** the mutual exclusion PGlite lacks, so it is pinned at 1.
+
+## Schema and migrations
+
+drizzle-kit works here - `driver: 'pglite'` means it opens the data directory itself - but that is the catch: PGlite allows one writer on the directory at a time, so `drizzle-kit migrate` cannot reach a database your app has already opened. Generate the SQL offline, and let your own process apply it at boot.
+
+Point `dbCredentials.url` at a folder path where a server config would carry a URL:
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  driver: 'pglite',
+  schema: './src/models/**/*.model.ts',
+  out: './migrations',
+  dbCredentials: { url: './pgdata' },
+});
+```
+
+```bash
+bun run drizzle-kit generate
+```
+
+Apply them in-process, at boot, before the first repository call:
+
+```typescript
+import { drizzle } from 'drizzle-orm/pglite';
+import { migrate } from 'drizzle-orm/pglite/migrator';
+
+export const applyMigrations = async (opts: { dataSource: EmbeddedDataSource }): Promise<void> => {
+  const client = opts.dataSource.getClient();
+  await client.waitReady;
+
+  await migrate(drizzle({ client }), { migrationsFolder: './migrations' });
+};
+```
+
+`migrate()` wants drizzle's own `PgliteDatabase`, which is narrower than the `getConnector()` return type. Build one over the same client - PGlite has a single session, so both handles talk to the same database.
+
+## Runnable example
+
+`examples/pglite-quickstart/` is this page as an app: a `pgTable` model with `uuid`, `jsonb` and `timestamptz`, a one-line repository, the standard CRUD controller, and a datasource that is the only file aware of PGlite.
+
+```bash
+cd examples/pglite-quickstart
+bun install
+bun run start        # http://localhost:3000/api/notes
+```
+
+## See Also
+
+- [Postgres Drivers & Supabase](./postgres-drivers) - the driver seam, `node-postgres` and `postgres-js`
+- [SQLite](./sqlite) - the other embedded engine, and what it refuses
+- [DataSources](./datasources) - schema auto-discovery and `configure()`
+- [Transactions](./transactions) - commit, rollback and connection safety
+- [Connectors](/references/base/connectors) - the engine-neutral contract

package/content/guides/core-concepts/persistent/postgres-drivers.md

@@ -1,9 +1,10 @@
 # Postgres Drivers & Supabase
 
-IGNIS talks to PostgreSQL through a **driver seam**: `IRelationalDriver` owns connection acquisition and the raw transaction control statements, and everything above it - repositories, transactions, the Casbin adapters - is driver-agnostic. Two drivers ship today:
+IGNIS talks to PostgreSQL through a **driver seam**. `IRelationalDriver` owns connection acquisition and the raw transaction control statements, and everything above it - repositories, transactions, the Casbin adapters - is driver-agnostic. Three drivers ship today:
 
 - **node-postgres** (`pg`) - the default IGNIS has always used
 - **postgres-js** (`postgres`) - required for Supabase's transaction pooler, and a faster option anywhere else
+- **PGlite** (`@electric-sql/pglite`) - Postgres compiled to WebAssembly, running in your own process. It has one session and its own constraints, so it gets [its own page](./pglite)
 
 Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies the **driver**, not the SQL dialect. The `@venizia/ignis/postgres/supabase` submodule adds the two things Supabase deployments actually need - pooler presets and an RLS auth-context helper.
 
@@ -11,8 +12,9 @@ Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies
 > `pg` and `postgres` are both **optional peer dependencies**. The `@venizia/ignis/postgres` module pulls in neither - only the driver class you import and name in `@datasource({ driver })` reaches your bundle. Install the one your app uses:
 >
 > ```bash
-> bun add pg          # node-postgres
-> bun add postgres    # postgres-js (>= 3.4.0)
+> bun add pg                      # node-postgres
+> bun add postgres                # postgres-js (>= 3.4.0)
+> bun add @electric-sql/pglite    # PGlite
 > ```
 
 ## Import Paths
@@ -22,6 +24,7 @@ Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies
 | `@venizia/ignis/postgres` | `BasePostgresDataSource`, `IRelationalDriver`, repository hierarchy | no client library |
 | `@venizia/ignis/postgres/node-postgres` | `NodePostgresDriver` | `pg` |
 | `@venizia/ignis/postgres/postgres-js` | `PostgresJsDriver` | `postgres` |
+| `@venizia/ignis/postgres/pglite` | `PGliteDriver` | `@electric-sql/pglite` |
 | `@venizia/ignis/postgres/supabase` | `PoolerModes`, `buildPostgresJsOptions`, `withAuthContext`, Supabase role re-exports | `drizzle-orm/supabase` |
 
 ## Naming the Driver Class
@@ -42,12 +45,14 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
 }
 ```
 
-`configure()` only builds `this.client` - the raw `pg.Pool` (or postgres-js `Sql`) your app's connection settings produce. The base class wires the driver **and** the connector lazily, on first call to `getConnector()` or `beginTransaction()`: it reads the class named in `@datasource({ driver })`, instantiates it over `this.client`, and builds the pooled Drizzle connector from that. `getClient()` hands `this.client` back as the raw-client escape hatch. A datasource that sets neither `this.client` nor a driver (via `useDriver()`, below) throws `No driver and no client` on first use.
+`configure()` only builds `this.client` - the raw `pg.Pool` (or postgres-js `Sql`) your app's connection settings produce. The base class wires the driver **and** the connector lazily, on first call to `getConnector()` or `beginTransaction()`. It reads the class named in `@datasource({ driver })`, instantiates it over `this.client`, and builds the pooled Drizzle connector from that.
+
+`getClient()` hands `this.client` back as the raw-client escape hatch. A datasource that sets neither `this.client` nor a driver (via `useDriver()`, below) throws `No driver and no client` on first use.
 
 > [!IMPORTANT] Why a class, not a name
-> A driver-name string cannot carry `pg` or `postgres` into your bundle - it is just text. A dynamic `import('./node-postgres.js')` keyed off that string would defer *execution*, not *packaging*: every bundler statically resolves a literal specifier and packages whatever it points to, so a build that only used node-postgres would still fail with `Could not resolve: "postgres"` the moment postgres-js's import appeared anywhere in the module graph reachable at build time. Naming the class instead makes the driver module a real value reference - the one thing a bundler is forced to keep - which is what lets `pg` and `postgres` stay genuinely optional peers. A bare side-effect import (`import '@venizia/ignis/postgres/node-postgres'`) would not work either: `@venizia/ignis` declares `sideEffects: false`, so a bundler is free to drop an import whose exports go unused.
+> A driver-name string cannot carry `pg` or `postgres` into your bundle - it is just text. A dynamic `import('./node-postgres.js')` keyed off that string would defer *execution*, not *packaging*. Every bundler statically resolves a literal specifier and packages whatever it points to. A build that only used node-postgres would still fail with `Could not resolve: "postgres"`. The failure fires the moment postgres-js's import appears anywhere in the module graph reachable at build time. Naming the class instead makes the driver module a real value reference - the one thing a bundler is forced to keep. That's what lets `pg` and `postgres` stay genuinely optional peers. A bare side-effect import (`import '@venizia/ignis/postgres/node-postgres'`) would not work either. `@venizia/ignis` declares `sideEffects: false`, so a bundler is free to drop an import whose exports go unused.
 >
-> Two tests pin this from different angles: `packages/core/src/__tests__/connectors/postgres/no-eager-driver-import.test.ts` proves no barrel **loads** a driver package in a fresh process (the runtime module graph), and `packages/core/src/__tests__/connectors/postgres/bundle/optional-peers.test.ts` proves no barrel gets a driver package **packaged** by a real bundler.
+> Two tests pin this from different angles. `packages/core-server/src/__tests__/connectors/postgres/no-eager-driver-import.test.ts` proves no barrel **loads** a driver package in a fresh process (the runtime module graph). `packages/core-server/src/__tests__/connectors/postgres/bundle/optional-peers.test.ts` proves no barrel gets a driver package **packaged** by a real bundler.
 
 ## Using postgres-js
 
@@ -84,11 +89,11 @@ new NodePostgresDriver({ client: pool }); // client must expose connect() AND to
 new PostgresJsDriver({ client: sql });    // client must expose reserve() AND unsafe()
 ```
 
-`NodePostgresDriver` rejects a bare `pg.Client` - it exposes `connect()` too, but has no pool accounting and cannot hand out a dedicated connection per transaction. `PostgresJsDriver` rejects a `pg.Pool` the same way. You will not normally construct these yourself: `wireDriverFromMetadata()` does it for you from `this.client`, so this validation fires the first time a datasource wired the wrong client behind the wrong `@datasource({ driver })` class.
+`NodePostgresDriver` rejects a bare `pg.Client` - it exposes `connect()` too, but has no pool accounting and cannot hand out a dedicated connection per transaction. `PostgresJsDriver` rejects a `pg.Pool` the same way. You will not normally construct these yourself: `wireDriverFromMetadata()` does it for you from `this.client`. This validation fires the first time a datasource wired the wrong client behind the wrong `@datasource({ driver })` class.
 
 ## Custom or Third-Party Drivers: `useDriver()`
 
-For a driver IGNIS does not ship, wire it explicitly with `useDriver()` - it assigns the driver **and** builds the pooled connector in one step, so the half-wired state (driver set, connector forgotten) cannot exist:
+For a driver IGNIS does not ship, wire it explicitly with `useDriver()`. It assigns the driver **and** builds the pooled connector in one step, so the half-wired state (driver set, connector forgotten) cannot exist:
 
 ```typescript
 export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
@@ -101,10 +106,10 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
 }
 ```
 
-`useDriver()` bypasses `@datasource({ driver })` entirely - you never need to name a class in the decorator when you wire the driver yourself in `configure()`.
+`useDriver()` bypasses `@datasource({ driver })` entirely. You never need to name a class in the decorator when you wire the driver yourself in `configure()`.
 
 > [!WARNING] postgres-js cannot destroy a poisoned connection
-> After a failed `COMMIT` or `ROLLBACK`, node-postgres **destroys** the connection instead of pooling it - the session may still hold an open transaction that the next borrower would inherit. postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so the connection is returned to the pool anyway. This asymmetry is real and IGNIS does not paper over it; it is pinned by the driver's own tests.
+> After a failed `COMMIT` or `ROLLBACK`, node-postgres **destroys** the connection instead of pooling it. The session may still hold an open transaction that the next borrower would inherit. postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so the connection is returned to the pool anyway. This asymmetry is real and IGNIS does not paper over it; it is pinned by the driver's own tests.
 
 ## The Driver Contract
 
@@ -125,9 +130,9 @@ interface IRelationalConnection<Schema> {
 }
 ```
 
-`acquire()` matters for transactions: `BEGIN` and `COMMIT` must land on the same backend, so each explicit transaction gets a dedicated connection (`pool.connect()` for pg, `sql.reserve()` for postgres-js - the reason for the `>= 3.4.0` floor).
+`acquire()` matters for transactions: `BEGIN` and `COMMIT` must land on the same backend. Each explicit transaction therefore gets a dedicated connection (`pool.connect()` for pg, `sql.reserve()` for postgres-js) - that's the reason for the `>= 3.4.0` floor.
 
-The connection is checked out of the pool before Drizzle is constructed on top of it. If that constructor throws - a malformed discovered schema, a drizzle mismatch - both drivers catch the error, release the connection back to the pool first, and rethrow. Without this, every failed `acquire()` would strand a connection, and the pool would exhaust after enough of them.
+The connection is checked out of the pool before Drizzle is constructed on top of it. If that constructor throws - a malformed discovered schema, a drizzle mismatch - both drivers catch the error. They release the connection back to the pool first, and rethrow. Without this, every failed `acquire()` would strand a connection, and the pool would exhaust after enough of them.
 
 `execute()` resolves to the neutral `IStatementResult` (`{ count }` - the same `count` the repository verbs speak). Each driver maps its native result shape at its own boundary; nothing above the seam ever inspects a driver-specific type.
 
@@ -143,7 +148,7 @@ Supabase exposes three ways in, and one of them silently breaks prepared stateme
 | `PoolerModes.SESSION` | 5432 (pooler) | yes | pooled, one backend per client session |
 | `PoolerModes.TRANSACTION` | 6543 | **no** | serverless / many short-lived connections |
 
-The transaction pooler (Supavisor) rebinds the backend per transaction, so a server-side prepared statement created on one backend simply is not there next time. `buildPostgresJsOptions` encodes this so you cannot forget it:
+The transaction pooler (Supavisor) rebinds the backend per transaction, so a server-side prepared statement created on one backend is not there next time. `buildPostgresJsOptions` encodes this so you cannot forget it:
 
 ```typescript
 import { datasource } from '@venizia/ignis';
@@ -191,11 +196,12 @@ try {
 Three properties make this safe under a transaction-mode pooler:
 
 - `claims` is **bound as a query parameter**, never interpolated into SQL text.
-- `role` must be a bare identifier (`/^[a-z_][a-z0-9_]*$/`) because `set local role $1` is not valid SQL - a role taken from a JWT and interpolated unvalidated would be a privilege-escalation vector. Validation runs **before** any statement, so a rejected call leaves the session untouched.
+- `role` must be a bare identifier (`/^[a-z_][a-z0-9_]*$/`) because `set local role $1` is not valid SQL. A role taken from a JWT and interpolated unvalidated would be a privilege-escalation vector.
+- Validation runs **before** any statement, so a rejected call leaves the session untouched.
 - Everything is `SET LOCAL` / `set_config(..., true)` - transaction-scoped. A plain `SET` would leak the caller's identity to the next borrower of the pooled connection, and is deliberately not offered.
 
 The submodule also re-exports Drizzle's Supabase helpers (`anonRole`, `authenticatedRole`, `serviceRole`, `authUid`, `authUsers`, ...) so RLS-aware schema files need one import.
 
 ## Adding a Driver
 
-One file under `src/connectors/postgres/drivers/`, implementing the four verbs above, plus a fake client and a test that runs the shared conformance suite (`run({ driver, buildDriverProbe })` in `src/__tests__/connectors/postgres/drivers/conformance/`). Register a sub-path export and an optional peer dependency; never re-export the driver from the drivers barrel - that is what would make its package load eagerly for everyone.
+One file under `src/connectors/postgres/drivers/`, implementing the four verbs above. Add a fake client and a test that runs the shared conformance suite (`run({ driver, buildDriverProbe })` in `src/__tests__/connectors/postgres/drivers/conformance/`). Register a sub-path export and an optional peer dependency. Never re-export the driver from the drivers barrel - that is what would make its package load eagerly for everyone.

package/content/guides/core-concepts/persistent/search-meilisearch.md

@@ -1,6 +1,6 @@
 # Search & Meilisearch
 
-IGNIS ships a **meilisearch connector** under `@venizia/ignis/meilisearch`. It shares the entire search paradigm with the Typesense connector - the same `@model`/`@repository`/`@datasource` decorators, the same `defineSearchCollection` field DSL, the same repository tiers and controller factory - all of which live in the engine-neutral `@venizia/ignis/search` module.
+IGNIS ships a **meilisearch connector** under `@venizia/ignis/meilisearch`. It shares the entire search paradigm with the Typesense connector: the same `@model`/`@repository`/`@datasource` decorators and the same `defineSearchCollection` field DSL. It also shares the same repository tiers and controller factory. All of that lives in the engine-neutral `@venizia/ignis/search` module.
 
 What it does **not** share is the pretence that the two engines are the same. Where Meilisearch differs from Typesense, IGNIS surfaces the difference rather than papering over it.
 
@@ -53,7 +53,7 @@ Meilisearch is **schemaless**: it has no field schema at all. A collection there
 | `synonyms` | a flat `synonyms` dictionary |
 | `engineOverrides.meilisearch` | merged last onto settings |
 
-The `searchable` and `filterable` flags are **load-bearing here** and are silently dropped by the Typesense compiler, which indexes every field by default. If no field declares `searchable`, IGNIS leaves `searchableAttributes` at Meilisearch's own `['*']` default rather than emitting an empty array, which would disable search entirely.
+The `searchable` and `filterable` flags are **load-bearing here** and are silently dropped by the Typesense compiler, which indexes every field by default. If no field declares `searchable`, IGNIS leaves `searchableAttributes` at Meilisearch's own `['*']` default. Emitting an empty array instead would disable search entirely.
 
 ## The DataSource
 
@@ -93,7 +93,7 @@ await repository.create({ data: article });
 // The document is retrievable here. No sleep, no retry loop.
 ```
 
-The cost is real and worth knowing: each write polls until its task completes. The client SDK's own `waitForTask` defaults to a 5-second timeout, which is far too short for a bulk import, so IGNIS never relies on it - configure `taskTimeoutMs` instead. A task that fails raises the standard sanitized dependency error; one that never terminates raises a `core.search_engine.task_timeout`.
+The cost is real and worth knowing: each write polls until its task completes. The client SDK's own `waitForTask` defaults to a 5-second timeout, which is far too short for a bulk import. IGNIS never relies on it - configure `taskTimeoutMs` instead. A task that fails raises the standard sanitized dependency error; one that never terminates raises a `core.search_engine.task_timeout`.
 
 If you want fire-and-forget writes, reach the raw client:
 
@@ -108,7 +108,7 @@ Meilisearch's search route reports `estimatedTotalHits`, and its exhaustive `tot
 
 IGNIS never counts through the search route. `count()` calls `POST /documents/fetch` with `limit: 0` and reads the exact `total`, which the engine's own documentation states is unaffected by `maxTotalHits`. A filtered count over 50,000 matching documents returns 50,000.
 
-`ISearchResult.isFoundExact` reports the truth for the **search** route: always `true` on Typesense, and on Meilisearch `true` only in the exhaustive page mode. It travels all the way out through the generated REST response, so an API consumer paginating your endpoint can tell an estimate from an exhaustive count.
+`ISearchResult.isFoundExact` reports the truth for the **search** route: always `true` on Typesense, and on Meilisearch `true` only in the exhaustive page mode. It travels all the way out through the generated REST response. An API consumer paginating your endpoint can tell an estimate from an exhaustive count.
 
 ## Capability differences are compile-time, not runtime
 
@@ -141,25 +141,35 @@ class PortableRepository extends DefaultSearchRepository<TDocument> {
 
 ## Behaviours to know before you commit
 
-**`create()` rejects duplicates, but the check is not atomic.** Meilisearch's `addDocuments` is add-or-replace; it has no conditional insert. To honour the neutral contract (Typesense's `create()` returns 409 on a duplicate id), IGNIS reads the id first and throws `409 core.search_engine.already_exists` if it exists. Two concurrent creates of the same id can both pass that check, and the second write wins. If you want last-write-wins, call `upsert()` and say so.
+**`create()` rejects duplicates, but the check is not atomic.** Meilisearch's `addDocuments` is add-or-replace; it has no conditional insert. The neutral contract says `create()` returns 409 on a duplicate id, matching Typesense.
+
+To honour it, IGNIS reads the id first and throws `409 core.search_engine.already_exists` if it exists. Two concurrent creates of the same id can both pass that check, and the second write wins. If you want last-write-wins, call `upsert()` and say so.
 
 **`updateById` on a missing id throws `404`, it does not upsert.** Meilisearch's `updateDocuments` is add-or-update, so a missing id would silently fabricate a record. IGNIS checks existence before any write and throws `404 core.search_engine.not_found` instead - matching Typesense and the neutral contract. (This is the deliberate search-family divergence from the PostgreSQL connector, where a missing-id `updateById` is a silent `{ count: 0 }`.)
 
-**`updateBy` is emulated and is not atomic.** Meilisearch has no update-by-filter endpoint. IGNIS pages primary keys out of `documents/fetch`, then issues merge-`PUT` batches. A concurrent write to a matched document may be overwritten. The experimental `documents/edit` route would do this server-side, but it is gated behind a feature flag, is documented as breaking between minor versions, and has an open correctness bug - so IGNIS does not use it.
+**`updateBy` is emulated and is not atomic.** Meilisearch has no update-by-filter endpoint. IGNIS pages primary keys out of `documents/fetch`, then issues merge-`PUT` batches. A concurrent write to a matched document may be overwritten.
+
+The experimental `documents/edit` route would do this server-side, but it is gated behind a feature flag and documented as breaking between minor versions. It also has an open correctness bug, so IGNIS does not use it.
+
+**`import`/`createAll` is batch-atomic.** Documents are added in batches, each batch's task awaited before the next starts. A batch either lands whole or throws, so `count.fail` is structurally always `0`.
 
-**`import`/`createAll` is batch-atomic.** Documents are added in batches, each batch's task awaited before the next starts. A batch either lands whole or throws, so `count.fail` is structurally always `0`. When a batch fails, the batches after the failure point did not land and the thrown error's `details` carry `{ totalCount, processedCount }` so a caller can resume from `processedCount` rather than replaying the whole import.
+When a batch fails, the batches after the failure point did not land. The thrown error's `details` carry `{ totalCount, processedCount }`, so a caller can resume from `processedCount` rather than replaying the whole import.
 
-**Meilisearch error classification reads the real SDK error shape.** A thrown `MeilisearchApiError` carries its body under `error.cause.code` and its HTTP status under `error.response.status`, not top-level `code`/`httpStatus`. Reading only the flat shape misclassifies a legitimate 404 (for example the existence probe inside `create()`) as an unrelated 503 dependency failure; the classifier checks both the flat shape (task-error responses) and the nested `cause`/`response` shape (thrown SDK errors).
+**Meilisearch error classification reads the real SDK error shape.** A thrown `MeilisearchApiError` carries its body under `error.cause.code` and its HTTP status under `error.response.status`, not top-level `code`/`httpStatus`. Reading only the flat shape misclassifies a legitimate 404 (for example the existence probe inside `create()`) as an unrelated 503 dependency failure. The classifier checks both the flat shape (task-error responses) and the nested `cause`/`response` shape (thrown SDK errors).
 
-**`createCollection`/`ensureCollection` are idempotent.** An `index_already_exists` failure is tolerated and logged rather than thrown, so boot-time provisioning against an already-provisioned collection (a restart, a second app instance) succeeds instead of crashing.
+**`createCollection`/`ensureCollection` are idempotent.** An `index_already_exists` failure is tolerated and logged rather than thrown. Boot-time provisioning against an already-provisioned collection (a restart, a second app instance) succeeds instead of crashing.
 
-**`hiddenProperties` is supported on Meilisearch via JS-side stripping, not engine-side exclusion.** Meilisearch has no per-query field-exclusion param (only the index-level `displayedAttributes` setting), so the dialect does not attempt to translate `hiddenFields` - it deliberately passes them through untranslated. The guarantee is upheld one layer up: `SearchBaseRepository` strips hidden fields from every document `find()`/`findOne()`/`search()` returns before it reaches the caller, so a model with `hiddenProperties` works identically to Typesense from the caller's point of view - no throw, no leak.
+**`hiddenProperties` is supported on Meilisearch via JS-side stripping, not engine-side exclusion.** Meilisearch has no per-query field-exclusion param (only the index-level `displayedAttributes` setting), so the dialect does not attempt to translate `hiddenFields`. It deliberately passes them through untranslated.
+
+The guarantee is upheld one layer up: `SearchBaseRepository` strips hidden fields from every document `find()`/`findOne()`/`search()` returns before it reaches the caller. A model with `hiddenProperties` works identically to Typesense from the caller's point of view - no throw, no leak.
 
 **A geopoint field must be named `_geo`.** Meilisearch supports exactly one geo field, shaped `{ lat, lng }`, under that reserved name. The compiler throws on any other name, and on a second geo field.
 
 **Vector distance is cosine only.** `field.vector(..., { distance: 'l2' })` throws.
 
-**Engine-specific knobs never reach the neutral schema.** The neutral search input carries only fields every engine supports; Typesense-only tuning (`num_typos`, `pinned_hits`, `preset`, ...) travels through `engineParams` with wire names and is passed verbatim to the engine - so sending Typesense knobs to a Meilisearch datasource is a caller error, and the dialect still raises a named error for known-foreign knobs arriving via untyped input. Use `engineParams` (or `mode: 'raw'`) for Meilisearch-native tuning such as `rankingScoreThreshold`.
+**Engine-specific knobs never reach the neutral schema.** The neutral search input carries only fields every engine supports. Typesense-only tuning (`num_typos`, `pinned_hits`, `preset`, ...) travels through `engineParams` with wire names and is passed verbatim to the engine. Sending it to a Meilisearch datasource is a caller error.
+
+The dialect still raises a named error for known-foreign knobs arriving via untyped input. Use `engineParams` (or `mode: 'raw'`) for Meilisearch-native tuning such as `rankingScoreThreshold`.
 
 **`multiSearch` batches but does not merge.** `union: true` throws. Meilisearch merges results through its `federation` option, which this connector does not model, so `getCapabilities()` honestly reports `union: false`.
 
@@ -169,7 +179,7 @@ class PortableRepository extends DefaultSearchRepository<TDocument> {
 
 Vector fields compile to `embedders`, and `mode: 'semantic'` / `mode: 'hybrid'` translate to Meilisearch's `hybrid: { semanticRatio, embedder }` plus an optional `vector`. The neutral `alpha` maps to `semanticRatio`; `mode: 'semantic'` pins it to `1.0`, and an omitted `alpha` on `hybrid` defaults to `0.5`.
 
-This path is compiled and translated but is **not exercised end to end** by the framework's test suite, and Meilisearch has moved its vector store in and out of `/experimental-features` across server versions. Verify against your target server version before depending on it.
+This path is compiled and translated but is **not exercised end to end** by the framework's test suite. Meilisearch has also moved its vector store in and out of `/experimental-features` across server versions. Verify against your target server version before depending on it.
 
 ## Adding another search engine