tina4-nodejs 3.13.92 → 3.13.95

package/packages/orm/src/docstore.ts

@@ -6,7 +6,7 @@
  *
  *     import { getCollection, ObjectId } from "@tina4/orm";
  *
- *     const orders = getCollection("orders");          // SqliteCollection when no Mongo configured
+ *     const orders = await getCollection("orders");    // SqliteCollection when no Mongo configured
  *     const { insertedId } = await orders.insertOne({ customer_id: 1, total: 9.99 });
  *     for (const o of await orders.find({ customer_id: { $in: [1, 2] } }).sort("created_at", -1).limit(10).toArray()) {
  *       // ...
@@ -21,6 +21,11 @@
  * production runs serverless in local dev with no code change - only the backend
  * differs.
  *
+ * A configured URI with NO driver installed throws `DocStoreDriverMissing`
+ * (ADR-0033). It does NOT quietly use the local SQLite store, and it no longer
+ * surfaces a bare ERR_MODULE_NOT_FOUND that names an npm package rather than
+ * the framework decision that led there.
+ *
  * Design (the SQLite backend):
  *   - Each collection is a table `(_id TEXT PRIMARY KEY, doc TEXT)`; `doc` is JSON.
  *   - Query filters are pushed down to SQL over `json_extract(doc, '$.field')`
@@ -205,6 +210,57 @@ function extract(field: string): string {
   return `json_extract(doc, '${jsonPath(field)}')`;
 }
 
+/** A rowset over the field: one row per element of an array, one for a scalar. */
+function jsonEach(field: string): string {
+  return `json_each(doc, '${jsonPath(field)}')`;
+}
+
+/**
+ * True when the field is an ARRAY and any element satisfies `condition`.
+ *
+ * MongoDB's rule for an array-valued field is that a condition matches when ANY
+ * ELEMENT matches it. json_each yields one row per element, so EXISTS is the
+ * direct translation.
+ *
+ * The `= 'array'` guard is load-bearing: json_each over an OBJECT iterates its
+ * VALUES, and Mongo never matches an object field against one of its values -
+ * {obj: "x"} must NOT match {obj: {city: "x"}}.
+ */
+function anyElement(field: string, condition: string): string {
+  return `(${typeOf(field)} = 'array' AND EXISTS (SELECT 1 FROM ${jsonEach(field)} WHERE ${condition}))`;
+}
+
+/** Compile `field == operand` under Mongo's array rule. */
+function equality(field: string, operand: unknown): CompiledFilter {
+  const ex = extract(field);
+  if (operand === null || operand === undefined) return { where: `${ex} IS NULL`, params: [] };
+  // An array or plain object operand compares against the WHOLE value, never
+  // element-wise: {tags: ["x","y"]} is exact-array equality.
+  const composite =
+    Array.isArray(operand) ||
+    (typeof operand === "object" && !(operand instanceof ObjectId) && !(operand instanceof Date));
+  if (composite) return { where: `${ex} = ?`, params: [bind(operand)] };
+  return {
+    where: `(${ex} = ? OR ${anyElement(field, "value = ?")})`,
+    params: [bind(operand), bind(operand)],
+  };
+}
+
+/**
+ * Compile `field OP operand` under Mongo's array rule.
+ *
+ * The `<> 'array'` guard on the scalar branch removes a measured FALSE POSITIVE:
+ * json_extract of an array returns its JSON TEXT, and SQLite sorts any text above
+ * any number, so {nums: {$gt: 9}} matched [1,2,3].
+ */
+function compare(field: string, sqlOp: string, operand: unknown): CompiledFilter {
+  const ex = extract(field);
+  return {
+    where: `((${typeOf(field)} <> 'array' AND ${ex} ${sqlOp} ?) OR ${anyElement(field, `value ${sqlOp} ?`)})`,
+    params: [bind(operand), bind(operand)],
+  };
+}
+
 function typeOf(field: string): string {
   return `json_type(doc, '${jsonPath(field)}')`;
 }
@@ -265,11 +321,12 @@ export function compileFilter(query?: Record<string, unknown> | null): CompiledF
         clauses.push(compiled.where);
         params.push(...compiled.params);
       }
-    } else if (value === null) {
-      clauses.push(`${extract(key)} IS NULL`);
     } else {
-      clauses.push(`${extract(key)} = ?`);
-      params.push(bind(value));
+      // equality - the same helper $eq uses, so the array rule applies whether
+      // the filter reads {tags: "x"} or {tags: {$eq: "x"}}
+      const compiled = equality(key, value);
+      clauses.push(compiled.where);
+      params.push(...compiled.params);
     }
   }
 
@@ -279,27 +336,37 @@ export function compileFilter(query?: Record<string, unknown> | null): CompiledF
 function compileOp(field: string, op: string, operand: unknown): CompiledFilter {
   const ex = extract(field);
   if (op in COMPARATORS) {
-    return { where: `${ex} ${COMPARATORS[op]} ?`, params: [bind(operand)] };
+    return compare(field, COMPARATORS[op], operand);
   }
   if (op === "$eq") {
-    if (operand === null) return { where: `${ex} IS NULL`, params: [] };
-    return { where: `${ex} = ?`, params: [bind(operand)] };
+    return equality(field, operand);
   }
   if (op === "$ne") {
     if (operand === null) return { where: `${ex} IS NOT NULL`, params: [] };
-    return { where: `(${ex} <> ? OR ${ex} IS NULL)`, params: [bind(operand)] };
+    const eq = equality(field, operand);
+    // A MISSING field satisfies $ne in Mongo, and SQL's NOT(NULL) is NULL rather
+    // than true - so the IS NULL arm is required, not decoration.
+    return { where: `(NOT (${eq.where}) OR ${ex} IS NULL)`, params: eq.params };
   }
   if (op === "$in") {
     const items = Array.isArray(operand) ? operand : [];
     if (items.length === 0) return { where: "0", params: [] };
     const placeholders = items.map(() => "?").join(",");
-    return { where: `${ex} IN (${placeholders})`, params: items.map(bind) };
+    const bound = items.map(bind);
+    return {
+      where: `(${ex} IN (${placeholders}) OR ${anyElement(field, `value IN (${placeholders})`)})`,
+      params: [...bound, ...bound],
+    };
   }
   if (op === "$nin") {
     const items = Array.isArray(operand) ? operand : [];
     if (items.length === 0) return { where: "1", params: [] };
     const placeholders = items.map(() => "?").join(",");
-    return { where: `(${ex} NOT IN (${placeholders}) OR ${ex} IS NULL)`, params: items.map(bind) };
+    const bound = items.map(bind);
+    return {
+      where: `(NOT (${ex} IN (${placeholders}) OR ${anyElement(field, `value IN (${placeholders})`)}) OR ${ex} IS NULL)`,
+      params: [...bound, ...bound],
+    };
   }
   if (op === "$exists") {
     // json_type is NULL when the path is absent; present-but-null still has a type.
@@ -310,7 +377,10 @@ function compileOp(field: string, op: string, operand: unknown): CompiledFilter
     if (operand !== null && typeof operand === "object") {
       pattern = (operand as Record<string, unknown>).$regex ?? "";
     }
-    return { where: `${ex} REGEXP ?`, params: [String(pattern)] };
+    return {
+      where: `((${typeOf(field)} <> 'array' AND ${ex} REGEXP ?) OR ${anyElement(field, "value REGEXP ?")})`,
+      params: [String(pattern), String(pattern)],
+    };
   }
   throw new Error(`DocStore: unsupported query operator '${op}'`);
 }
@@ -417,73 +487,151 @@ export interface DeleteResult {
   deletedCount: number;
 }
 
+/**
+ * Decode a stored JSON document (rehydrating ObjectId/Date), with an optional
+ * projection. Module-level because it is a PURE function of its inputs - it was
+ * a public `load` method on the collection only so the Cursor could reach it,
+ * which ADR-0025 corollary 1 forbids.
+ */
+function loadDoc(docText: string, projection?: Record<string, unknown> | null): Record<string, unknown> {
+  const doc = decodeValue(JSON.parse(docText)) as Record<string, unknown>;
+  return projection ? project(doc, projection) : doc;
+}
+
+/** Encode a document for storage. Pure, for the same reason as loadDoc. */
+function dumpDoc(document: Record<string, unknown>): string {
+  return JSON.stringify(encodeValue(document));
+}
+
 // ── Cursor ───────────────────────────────────────────────────────────────────
 
 /** Lazy result cursor. Builds and runs SQL only when materialised (toArray). */
-export class Cursor {
-  private _sort: [string, number][] = [];
-  private _limit: number | null = null;
-  private _skip = 0;
+/** The three sort spellings a real FindCursor accepts. */
+export type SortSpec =
+  | string
+  | [string, number][]
+  | Record<string, number>
+  | Map<string, number>;
+
+/**
+ * Normalise the driver's three sort spellings to a list of [key, direction].
+ *
+ * ADR-0036. A real `FindCursor.sort()` accepts a key plus a direction, a list
+ * of `[key, direction]` pairs, OR an object/Map - and the driver is the shape
+ * this fallback imitates (ADR-0025). The object form used to throw
+ * `TypeError: keyOrList is not iterable` here. Measured 2026-08-04 against a
+ * real MongoDB: the object spelling worked on the driver and threw on the
+ * fallback, in three of the four frameworks.
+ */
+export function sortSpec(keyOrList: SortSpec, direction = 1): [string, number][] {
+  if (typeof keyOrList === "string") return [[keyOrList, direction]];
+  if (keyOrList instanceof Map) return [...keyOrList.entries()];
+  if (Array.isArray(keyOrList)) return keyOrList.map(([k, d]) => [k, d]);
+  return Object.entries(keyOrList).map(([k, d]) => [k, d]);
+}
 
+export class Cursor {
+  #sort: [string, number][] = [];
+  #limit: number | null = null;
+  #skip = 0;
+
+  readonly #conn: DatabaseSync;
+  readonly #quoted: string;
+  readonly #where: string;
+  readonly #params: unknown[];
+  readonly #projection?: Record<string, unknown> | null;
+
+  /**
+   * The cursor receives WHAT IT NEEDS, not the collection it came from.
+   *
+   * It used to hold the collection and reach back for `connection`, `quoted` and
+   * `load` - which is the only reason those three were public. ADR-0025
+   * corollary 1: anything the fallback needs internally is private, and a real
+   * FindCursor exposes none of them. Handing over the two values and calling the
+   * module-level loader removes the back-reference AND the public surface.
+   */
   constructor(
-    private readonly collection: SqliteCollection,
-    private readonly where: string,
-    private readonly params: unknown[],
-    private readonly projection?: Record<string, unknown> | null,
-  ) {}
-
-  sort(keyOrList: string | [string, number][], direction = 1): this {
-    if (typeof keyOrList === "string") {
-      this._sort.push([keyOrList, direction]);
-    } else {
-      for (const [k, d] of keyOrList) this._sort.push([k, d]);
-    }
+    conn: DatabaseSync,
+    quoted: string,
+    where: string,
+    params: unknown[],
+    projection?: Record<string, unknown> | null,
+  ) {
+    this.#conn = conn;
+    this.#quoted = quoted;
+    this.#where = where;
+    this.#params = params;
+    this.#projection = projection;
+  }
+
+  sort(keyOrList: SortSpec, direction = 1): this {
+    for (const pair of sortSpec(keyOrList, direction)) this.#sort.push(pair);
     return this;
   }
 
   limit(n: number): this {
-    this._limit = Math.trunc(n);
+    this.#limit = Math.trunc(n);
     return this;
   }
 
   skip(n: number): this {
-    this._skip = Math.trunc(n);
+    this.#skip = Math.trunc(n);
     return this;
   }
 
-  private buildSql(): string {
-    let sql = `SELECT doc FROM ${this.collection.quoted} WHERE ${this.where}`;
-    if (this._sort.length) {
-      const order = this._sort
+  #buildSql(): string {
+    let sql = `SELECT doc FROM ${this.#quoted} WHERE ${this.#where}`;
+    if (this.#sort.length) {
+      const order = this.#sort
         .map(([k, d]) => `${extract(k)} ${d < 0 ? "DESC" : "ASC"}`)
         .join(", ");
       sql += ` ORDER BY ${order}`;
     }
-    if (this._limit !== null) {
-      sql += ` LIMIT ${Math.trunc(this._limit)}`;
-      if (this._skip) sql += ` OFFSET ${Math.trunc(this._skip)}`;
-    } else if (this._skip) {
-      sql += ` LIMIT -1 OFFSET ${Math.trunc(this._skip)}`;
+    if (this.#limit !== null) {
+      sql += ` LIMIT ${Math.trunc(this.#limit)}`;
+      if (this.#skip) sql += ` OFFSET ${Math.trunc(this.#skip)}`;
+    } else if (this.#skip) {
+      sql += ` LIMIT -1 OFFSET ${Math.trunc(this.#skip)}`;
     }
     return sql;
   }
 
-  /** Materialise the cursor into an array of decoded documents. */
-  toArray(): Record<string, unknown>[] {
-    const rows = this.collection.connection
-      .prepare(this.buildSql())
-      .all(...(this.params as never[])) as { doc: string }[];
-    return rows.map((r) => this.collection.load(r.doc, this.projection));
+  /**
+   * Materialise the cursor into an array of decoded documents.
+   *
+   * ASYNC because the driver's FindCursor.toArray() is async (ADR-0025 clause
+   * 3). The work underneath is synchronous - node:sqlite has no async API - but
+   * the SHAPE is what a call site sees, and a shape that changes with the
+   * provider is the defect this fixes.
+   */
+  async toArray(): Promise<Record<string, unknown>[]> {
+    const rows = this.#conn
+      .prepare(this.#buildSql())
+      .all(...(this.#params as never[])) as { doc: string }[];
+    return rows.map((r) => loadDoc(r.doc, this.#projection));
   }
 
-  /** Alias for toArray() (pymongo's to_list / driver's toArray). */
-  toList(length?: number): Record<string, unknown>[] {
-    const out = this.toArray();
-    return length === undefined ? out : out.slice(0, length);
-  }
-
-  [Symbol.iterator](): Iterator<Record<string, unknown>> {
-    return this.toArray()[Symbol.iterator]();
+  /**
+   * Async iteration, matching the driver.
+   *
+   * NOTE: there is deliberately no [Symbol.iterator] here. A real FindCursor
+   * has ONLY Symbol.asyncIterator, so `for (const doc of cursor)` is a
+   * fallback-only spelling - it works locally and throws "is not iterable" the
+   * moment TINA4_MONGO_URI is set. Use `for await (const doc of cursor)`.
+   *
+   * toList() is gone for the same reason: the driver's FindCursor has no such
+   * method.
+   *
+   * ADR-0035 restored the uniform spellings in ruby and php through a
+   * delegator, and deliberately did NOT do so here. A delegator can only supply
+   * a method that is POSSIBLE on the real provider, and a synchronous iterator
+   * is not: a FindCursor is async-only. Adding one back on the fallback alone
+   * would recreate ADR-0025's worst measured defect - identical source changing
+   * TYPE, with a truthy Promise passing `if (doc)` for a document that does not
+   * exist. That is ADR-0025 corollary 3, which ADR-0035 keeps.
+   */
+  async *[Symbol.asyncIterator](): AsyncIterator<Record<string, unknown>> {
+    for (const doc of await this.toArray()) yield doc;
   }
 }
 
@@ -491,49 +639,40 @@ export class Cursor {
 
 /** A SQLite-backed collection exposing the everyday MongoDB driver API. */
 export class SqliteCollection {
-  readonly quoted: string;
+  readonly #quoted: string;
+  readonly #conn: DatabaseSync;
+  readonly #name: string;
 
-  constructor(
-    readonly connection: DatabaseSync,
-    private readonly name: string,
-  ) {
+  constructor(conn: DatabaseSync, name: string) {
+    this.#conn = conn;
+    this.#name = name;
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
       throw new Error(`DocStore: invalid collection name '${name}'`);
     }
-    this.quoted = `"${name}"`;
-    this.connection.exec(
-      `CREATE TABLE IF NOT EXISTS ${this.quoted} (_id TEXT PRIMARY KEY, doc TEXT NOT NULL)`,
+    this.#quoted = `"${name}"`;
+    this.#conn.exec(
+      `CREATE TABLE IF NOT EXISTS ${this.#quoted} (_id TEXT PRIMARY KEY, doc TEXT NOT NULL)`,
     );
   }
 
-  private dump(document: Record<string, unknown>): string {
-    return JSON.stringify(encodeValue(document));
-  }
-
-  /** Decode a stored JSON document (rehydrating ObjectId/Date), with optional projection. */
-  load(docText: string, projection?: Record<string, unknown> | null): Record<string, unknown> {
-    const doc = decodeValue(JSON.parse(docText)) as Record<string, unknown>;
-    return projection ? project(doc, projection) : doc;
-  }
-
   // -- writes --
-  insertOne(document: Record<string, unknown>): InsertOneResult {
+  async insertOne(document: Record<string, unknown>): Promise<InsertOneResult> {
     const doc = { ...document };
     if (!("_id" in doc)) doc._id = new ObjectId();
-    this.connection
-      .prepare(`INSERT INTO ${this.quoted} (_id, doc) VALUES (?, ?)`)
-      .run(idKey(doc._id), this.dump(doc));
+    this.#conn
+      .prepare(`INSERT INTO ${this.#quoted} (_id, doc) VALUES (?, ?)`)
+      .run(idKey(doc._id), dumpDoc(doc));
     return { acknowledged: true, insertedId: doc._id };
   }
 
-  insertMany(documents: Record<string, unknown>[]): InsertManyResult {
+  async insertMany(documents: Record<string, unknown>[]): Promise<InsertManyResult> {
     const ids: unknown[] = [];
-    const stmt = this.connection.prepare(`INSERT INTO ${this.quoted} (_id, doc) VALUES (?, ?)`);
+    const stmt = this.#conn.prepare(`INSERT INTO ${this.#quoted} (_id, doc) VALUES (?, ?)`);
     for (const document of documents) {
       const doc = { ...document };
       if (!("_id" in doc)) doc._id = new ObjectId();
       ids.push(doc._id);
-      stmt.run(idKey(doc._id), this.dump(doc));
+      stmt.run(idKey(doc._id), dumpDoc(doc));
     }
     return { acknowledged: true, insertedIds: ids };
   }
@@ -541,35 +680,35 @@ export class SqliteCollection {
   // -- reads --
   find(filter?: Record<string, unknown> | null, projection?: Record<string, unknown> | null): Cursor {
     const { where, params } = compileFilter(filter ?? {});
-    return new Cursor(this, where, params, projection);
+    return new Cursor(this.#conn, this.#quoted, where, params, projection);
   }
 
-  findOne(
+  async findOne(
     filter?: Record<string, unknown> | null,
     projection?: Record<string, unknown> | null,
-  ): Record<string, unknown> | null {
-    const results = this.find(filter, projection).limit(1).toArray();
+  ): Promise<Record<string, unknown> | null> {
+    const results = await this.find(filter, projection).limit(1).toArray();
     return results.length ? results[0] : null;
   }
 
-  countDocuments(filter?: Record<string, unknown> | null): number {
+  async countDocuments(filter?: Record<string, unknown> | null): Promise<number> {
     const { where, params } = compileFilter(filter ?? {});
-    const row = this.connection
-      .prepare(`SELECT count(*) AS c FROM ${this.quoted} WHERE ${where}`)
+    const row = this.#conn
+      .prepare(`SELECT count(*) AS c FROM ${this.#quoted} WHERE ${where}`)
       .get(...(params as never[])) as { c: number | bigint };
     return Number(row.c);
   }
 
-  estimatedDocumentCount(): number {
-    const row = this.connection
-      .prepare(`SELECT count(*) AS c FROM ${this.quoted}`)
+  async estimatedDocumentCount(): Promise<number> {
+    const row = this.#conn
+      .prepare(`SELECT count(*) AS c FROM ${this.#quoted}`)
       .get() as { c: number | bigint };
     return Number(row.c);
   }
 
-  distinct(key: string, filter?: Record<string, unknown> | null): unknown[] {
+  async distinct(key: string, filter?: Record<string, unknown> | null): Promise<unknown[]> {
     const seen: unknown[] = [];
-    for (const doc of this.find(filter).toArray()) {
+    for (const doc of await this.find(filter).toArray()) {
       const v = doc[key];
       if (!seen.some((s) => valuesEqual(s, v))) seen.push(v);
     }
@@ -577,28 +716,28 @@ export class SqliteCollection {
   }
 
   // -- updates (filter pushed to SQL; mutation applied per matched doc) --
-  private matchingRows(filter?: Record<string, unknown> | null): { _id: string; doc: string }[] {
+  #matchingRows(filter?: Record<string, unknown> | null): { _id: string; doc: string }[] {
     const { where, params } = compileFilter(filter ?? {});
-    return this.connection
-      .prepare(`SELECT _id, doc FROM ${this.quoted} WHERE ${where}`)
+    return this.#conn
+      .prepare(`SELECT _id, doc FROM ${this.#quoted} WHERE ${where}`)
       .all(...(params as never[])) as { _id: string; doc: string }[];
   }
 
-  private firstMatch(filter?: Record<string, unknown> | null): { _id: string; doc: string } | null {
+  #firstMatch(filter?: Record<string, unknown> | null): { _id: string; doc: string } | null {
     const { where, params } = compileFilter(filter ?? {});
-    const row = this.connection
-      .prepare(`SELECT _id, doc FROM ${this.quoted} WHERE ${where} LIMIT 1`)
+    const row = this.#conn
+      .prepare(`SELECT _id, doc FROM ${this.#quoted} WHERE ${where} LIMIT 1`)
       .get(...(params as never[])) as { _id: string; doc: string } | undefined;
     return row ?? null;
   }
 
-  private writeBack(oldId: string, newDoc: Record<string, unknown>): void {
-    this.connection
-      .prepare(`UPDATE ${this.quoted} SET _id = ?, doc = ? WHERE _id = ?`)
-      .run(idKey(newDoc._id), this.dump(newDoc), oldId);
+  #writeBack(oldId: string, newDoc: Record<string, unknown>): void {
+    this.#conn
+      .prepare(`UPDATE ${this.#quoted} SET _id = ?, doc = ? WHERE _id = ?`)
+      .run(idKey(newDoc._id), dumpDoc(newDoc), oldId);
   }
 
-  private doUpsert(filter: Record<string, unknown> | null | undefined, update: Record<string, unknown>): UpdateResult {
+  async #doUpsert(filter: Record<string, unknown> | null | undefined, update: Record<string, unknown>): Promise<UpdateResult> {
     // Seed a document from the filter's equality terms, then apply the update.
     const seed: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(filter ?? {})) {
@@ -608,56 +747,56 @@ export class SqliteCollection {
     }
     const doc = applyUpdate(seed, update);
     if (!("_id" in doc)) doc._id = new ObjectId();
-    this.insertOne(doc);
+    await this.insertOne(doc);
     return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: doc._id };
   }
 
-  updateOne(
+  async updateOne(
     filter: Record<string, unknown> | null | undefined,
     update: Record<string, unknown>,
     options?: { upsert?: boolean },
-  ): UpdateResult {
-    const row = this.firstMatch(filter);
+  ): Promise<UpdateResult> {
+    const row = this.#firstMatch(filter);
     if (!row) {
-      if (options?.upsert) return this.doUpsert(filter, update);
+      if (options?.upsert) return this.#doUpsert(filter, update);
       return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
     }
     const doc = decodeValue(JSON.parse(row.doc)) as Record<string, unknown>;
     const newDoc = applyUpdate(doc, update);
-    this.writeBack(row._id, newDoc);
+    this.#writeBack(row._id, newDoc);
     return { acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null };
   }
 
-  updateMany(
+  async updateMany(
     filter: Record<string, unknown> | null | undefined,
     update: Record<string, unknown>,
     options?: { upsert?: boolean },
-  ): UpdateResult {
-    const rows = this.matchingRows(filter);
-    if (rows.length === 0 && options?.upsert) return this.doUpsert(filter, update);
+  ): Promise<UpdateResult> {
+    const rows = this.#matchingRows(filter);
+    if (rows.length === 0 && options?.upsert) return this.#doUpsert(filter, update);
     let matched = 0;
     let modified = 0;
     for (const row of rows) {
       matched += 1;
       const doc = decodeValue(JSON.parse(row.doc)) as Record<string, unknown>;
       const newDoc = applyUpdate(doc, update);
-      this.writeBack(row._id, newDoc);
+      this.#writeBack(row._id, newDoc);
       modified += 1;
     }
     return { acknowledged: true, matchedCount: matched, modifiedCount: modified, upsertedId: null };
   }
 
-  replaceOne(
+  async replaceOne(
     filter: Record<string, unknown> | null | undefined,
     replacement: Record<string, unknown>,
     options?: { upsert?: boolean },
-  ): UpdateResult {
-    const row = this.firstMatch(filter);
+  ): Promise<UpdateResult> {
+    const row = this.#firstMatch(filter);
     if (!row) {
       if (options?.upsert) {
         const doc = { ...replacement };
         if (!("_id" in doc)) doc._id = new ObjectId();
-        this.insertOne(doc);
+        await this.insertOne(doc);
         return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: doc._id };
       }
       return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
@@ -667,28 +806,28 @@ export class SqliteCollection {
       const existing = decodeValue(JSON.parse(row.doc)) as Record<string, unknown>;
       doc._id = existing._id;
     }
-    this.writeBack(row._id, doc);
+    this.#writeBack(row._id, doc);
     return { acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null };
   }
 
   // -- deletes --
-  deleteOne(filter?: Record<string, unknown> | null): DeleteResult {
-    const row = this.firstMatch(filter);
+  async deleteOne(filter?: Record<string, unknown> | null): Promise<DeleteResult> {
+    const row = this.#firstMatch(filter);
     if (!row) return { acknowledged: true, deletedCount: 0 };
-    this.connection.prepare(`DELETE FROM ${this.quoted} WHERE _id = ?`).run(row._id);
+    this.#conn.prepare(`DELETE FROM ${this.#quoted} WHERE _id = ?`).run(row._id);
     return { acknowledged: true, deletedCount: 1 };
   }
 
-  deleteMany(filter?: Record<string, unknown> | null): DeleteResult {
+  async deleteMany(filter?: Record<string, unknown> | null): Promise<DeleteResult> {
     const { where, params } = compileFilter(filter ?? {});
-    const result = this.connection
-      .prepare(`DELETE FROM ${this.quoted} WHERE ${where}`)
+    const result = this.#conn
+      .prepare(`DELETE FROM ${this.#quoted} WHERE ${where}`)
       .run(...(params as never[]));
     return { acknowledged: true, deletedCount: Number(result.changes) };
   }
 
-  drop(): void {
-    this.connection.exec(`DROP TABLE IF EXISTS ${this.quoted}`);
+  async drop(): Promise<void> {
+    this.#conn.exec(`DROP TABLE IF EXISTS ${this.#quoted}`);
   }
 }
 
@@ -758,16 +897,41 @@ export class SqliteDatabase {
 }
 
 /**
- * The configured Mongo URI, reusing the app-wide queue/session env vars.
- * Canonical TINA4_SESSION_MONGO_URI; TINA4_SESSION_MONGO_URL is a legacy alias.
+ * A Mongo URI is configured but the MongoDB driver is not installed.
+ *
+ * ADR-0024 rule 3, settled for DocStore by ADR-0033: a provider that cannot
+ * honour an operation must RAISE, naming the provider and what is missing.
+ * Node already threw here, but with a bare ERR_MODULE_NOT_FOUND that named an
+ * npm package and not the framework decision that led there - so the outcome
+ * was loud but undocumented, and different from the other three frameworks.
+ */
+export class DocStoreDriverMissing extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DocStoreDriverMissing";
+  }
+}
+
+/**
+ * The env var that supplied the URI, or "" when none did.
+ *
+ * Named separately so an error can tell the operator WHICH variable to unset
+ * without ever printing its value - a Mongo URI routinely carries
+ * `user:password@`.
+ *
+ * Canonical TINA4_MONGO_URI, then the session-layer TINA4_SESSION_MONGO_URI;
+ * TINA4_SESSION_MONGO_URL is a legacy alias.
  */
+const MONGO_URI_VARS = ["TINA4_MONGO_URI", "TINA4_SESSION_MONGO_URI", "TINA4_SESSION_MONGO_URL"] as const;
+
+function mongoUriSource(): string {
+  return MONGO_URI_VARS.find((name) => (process.env[name] ?? "").trim() !== "") ?? "";
+}
+
+/** The configured Mongo URI, reusing the app-wide queue/session env vars. */
 function mongoUri(): string {
-  return (
-    process.env.TINA4_MONGO_URI ||
-    process.env.TINA4_SESSION_MONGO_URI ||
-    process.env.TINA4_SESSION_MONGO_URL ||
-    ""
-  ).trim();
+  const source = mongoUriSource();
+  return source ? (process.env[source] ?? "").trim() : "";
 }
 
 /** True when no Mongo is configured, so the SQLite fallback is in effect. */
@@ -792,22 +956,99 @@ function getDb(): SqliteDatabase {
  * `mongodb` driver is installed); otherwise a `SqliteCollection` backed by the
  * local SQLite file. Same call sites either way - only the backend differs.
  *
- * The real-Mongo path is async (the driver connects lazily), so this returns a
- * Promise when Mongo is configured. In serverless mode it returns a
- * SqliteCollection synchronously (the common local-dev case).
+ * ALWAYS async, on BOTH providers (ADR-0025 clause 3).
+ *
+ * It used to return a SqliteCollection SYNCHRONOUSLY in serverless mode and a
+ * Promise on the real-Mongo path. That made identical source change TYPE when
+ * TINA4_MONGO_URI was set, and a Promise is always truthy - so un-awaited code
+ * read a real document locally and a thenable in production, and `if (doc)`
+ * succeeded for a document that did not exist. The driver cannot become sync,
+ * so the fallback becomes async.
  */
-export function getCollection(name: string): SqliteCollection | Promise<unknown> {
+export async function getCollection(name: string): Promise<SqliteCollection | unknown> {
   if (isServerless()) {
     return getDb().getCollection(name);
   }
-  return (async () => {
-    const { MongoClient } = await import("mongodb");
-    const uri = mongoUri();
-    const dbName = process.env.TINA4_MONGO_DB || process.env.TINA4_SESSION_MONGO_DB || "tina4";
-    const client = new MongoClient(uri);
-    await client.connect();
-    return client.db(dbName).collection(name);
-  })();
+  const dbName = process.env.TINA4_MONGO_DB || process.env.TINA4_SESSION_MONGO_DB || "tina4";
+  const { db } = await mongoConnection(mongoUri(), dbName);
+  return db.collection(name);
+}
+
+/** One connected client per (uri, database), keyed so a reconfigure gets its own. */
+const mongoClients = new Map<string, Promise<{ client: any; db: any }>>();
+
+/**
+ * Return the shared client for this (uri, database), connecting once.
+ *
+ * MEASURED 2026-08-03 against a real MongoDB: getCollection() used to construct
+ * a `new MongoClient` on EVERY call and never close it, so 20 calls left 40
+ * server connections open and the count grew without bound. It was invisible in
+ * development because the SQLite fallback has no connections at all - a resource
+ * leak that only exists AFTER the swap to the real provider.
+ *
+ * The map holds the in-flight PROMISE rather than the resolved client. Caching
+ * the resolved value would leave a check-then-act window in which two
+ * concurrent callers both miss the cache and both build a client - which is the
+ * same leak, just rarer and harder to see. A failed connect is evicted so a
+ * transient outage cannot poison the entry for the life of the process.
+ *
+ * A missing driver is reported at provider RESOLUTION - the import, before the
+ * connect - so no network I/O is needed to establish it.
+ */
+async function importMongoDriver(): Promise<any> {
+  try {
+    return await import("mongodb");
+  } catch (error: any) {
+    // Only a genuinely UNRESOLVABLE `mongodb` becomes the documented error.
+    // Anything else - the driver present but one of ITS imports failing, a
+    // syntax error, a native binding problem - is re-thrown untouched, because
+    // relabelling it would send the operator to install a package they already
+    // have.
+    const unresolvable =
+      error?.code === "ERR_MODULE_NOT_FOUND" && String(error?.message ?? "").includes("'mongodb'");
+    if (!unresolvable) throw error;
+
+    const source = mongoUriSource() || "TINA4_MONGO_URI";
+    throw new DocStoreDriverMissing(
+      `Tina4 DocStore: ${source} is set, so the MongoDB provider is selected, but its ` +
+        `driver is not installed (npm package 'mongodb'). Install it with ` +
+        `\`npm install mongodb\`, or unset ${source} to use the local SQLite store.`,
+    );
+  }
+}
+
+function mongoConnection(uri: string, dbName: string): Promise<{ client: any; db: any }> {
+  const key = `${uri}\u0000${dbName}`;
+  let pending = mongoClients.get(key);
+  if (!pending) {
+    pending = (async () => {
+      const { MongoClient } = await importMongoDriver();
+      const client = new MongoClient(uri);
+      await client.connect();
+      return { client, db: client.db(dbName) };
+    })();
+    mongoClients.set(key, pending);
+    pending.catch(() => mongoClients.delete(key));
+  }
+  return pending;
+}
+
+/**
+ * Close every DocStore connection: the SQLite store and all Mongo clients.
+ *
+ * A pooled client keeps the event loop alive, so a script or test that touches
+ * the real provider needs a way to let the process end on its own.
+ */
+export async function closeDocStore(): Promise<void> {
+  const pending = [...mongoClients.values()];
+  mongoClients.clear();
+  await Promise.allSettled(
+    pending.map(async (p) => {
+      const { client } = await p;
+      await client.close();
+    }),
+  );
+  resetDefaultStore();
 }
 
 /** Drop the cached default SQLite store (test helper). */