equipped 5.2.9 → 5.3.0

package/dist/cjs/orm/adapters/mongodb/index.cjs

@@ -0,0 +1,3299 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/orm/adapters/mongodb/index.ts
+var mongodb_exports = {};
+__export(mongodb_exports, {
+  MongoDbAdapter: () => MongoDbAdapter
+});
+module.exports = __toCommonJS(mongodb_exports);
+var import_node_async_hooks = require("async_hooks");
+var import_mongodb = require("mongodb");
+var import_valleyed5 = require("valleyed");
+
+// src/errors/equippedError.ts
+var EquippedError = class extends Error {
+  constructor(message, context, cause) {
+    super(message, { cause });
+    this.message = message;
+    this.context = context;
+    this.cause = cause;
+  }
+};
+
+// src/instance/index.ts
+var import_pino = __toESM(require("pino"), 1);
+var import_ulid = require("ulid");
+var import_valleyed2 = require("valleyed");
+
+// src/instance/hooks.ts
+function registerHook(hooks, record) {
+  for (const dep of record.after) {
+    if (!hooks.some((h) => h.class === dep)) {
+      const depName = dep.name || "unknown";
+      const ownerName = record.class?.name || "anonymous";
+      throw new Error(`Missing dependency: ${ownerName} declares after: [${depName}], but ${depName} is not registered`);
+    }
+  }
+  if (record.class) {
+    const tentative = [...hooks, record];
+    detectCycle(tentative);
+  }
+  hooks.push(record);
+}
+function detectCycle(hooks) {
+  const classToAfter = /* @__PURE__ */ new Map();
+  for (const h of hooks) {
+    if (!h.class) continue;
+    const existing = classToAfter.get(h.class);
+    if (existing) {
+      for (const dep of h.after) {
+        if (!existing.includes(dep)) existing.push(dep);
+      }
+    } else {
+      classToAfter.set(h.class, [...h.after]);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function visit(cls, path) {
+    if (stack.has(cls)) {
+      const cycleStart = path.indexOf(cls);
+      const cycle = [...path.slice(cycleStart), cls];
+      const names = cycle.map((c) => c.name || "unknown");
+      throw new Error(`Cycle detected: ${names.join(" \u2192 ")}`);
+    }
+    if (visited.has(cls)) return;
+    stack.add(cls);
+    path.push(cls);
+    for (const dep of classToAfter.get(cls) ?? []) {
+      visit(dep, path);
+    }
+    path.pop();
+    stack.delete(cls);
+    visited.add(cls);
+  }
+  for (const cls of classToAfter.keys()) {
+    visit(cls, []);
+  }
+}
+function resolveHookDAG(hooks, invert = false) {
+  if (hooks.length === 0) return [];
+  const classToHooks = /* @__PURE__ */ new Map();
+  const anonymous = [];
+  for (const h of hooks) {
+    if (h.class) {
+      const list = classToHooks.get(h.class);
+      if (list) list.push(h);
+      else classToHooks.set(h.class, [h]);
+    } else {
+      anonymous.push(h);
+    }
+  }
+  const classes = [...classToHooks.keys()];
+  const inDegree = /* @__PURE__ */ new Map();
+  const graph = /* @__PURE__ */ new Map();
+  for (const cls of classes) {
+    inDegree.set(cls, 0);
+    graph.set(cls, []);
+  }
+  for (const h of hooks) {
+    if (!h.class) continue;
+    for (const dep of h.after) {
+      const [from, to] = invert ? [h.class, dep] : [dep, h.class];
+      const edges = graph.get(from);
+      if (!edges.includes(to)) {
+        edges.push(to);
+        inDegree.set(to, inDegree.get(to) + 1);
+      }
+    }
+  }
+  const layers = [];
+  let queue = classes.filter((c) => inDegree.get(c) === 0);
+  while (queue.length > 0) {
+    const layer = [];
+    const next = [];
+    for (const cls of queue) {
+      layer.push(...classToHooks.get(cls) ?? []);
+    }
+    layers.push(layer);
+    for (const cls of queue) {
+      for (const neighbor of graph.get(cls) ?? []) {
+        const d = inDegree.get(neighbor) - 1;
+        inDegree.set(neighbor, d);
+        if (d === 0) next.push(neighbor);
+      }
+    }
+    queue = next;
+  }
+  if (anonymous.length > 0) {
+    const anonWithDeps = anonymous.filter((h) => h.after.length > 0);
+    const anonWithoutDeps = anonymous.filter((h) => h.after.length === 0);
+    if (anonWithDeps.length > 0) {
+      let maxLayer = -1;
+      for (const h of anonWithDeps) {
+        for (const dep of h.after) {
+          const depLayer = layers.findIndex((l) => l.some((r) => r.class === dep));
+          if (depLayer > maxLayer) maxLayer = depLayer;
+        }
+      }
+      const insertAt = maxLayer + 1;
+      if (insertAt < layers.length) {
+        layers[insertAt].push(...anonWithDeps);
+      } else {
+        layers.push(anonWithDeps);
+      }
+    }
+    if (anonWithoutDeps.length > 0) {
+      if (layers.length > 0) {
+        layers[layers.length - 1].push(...anonWithoutDeps);
+      } else {
+        layers.push(anonWithoutDeps);
+      }
+    }
+  }
+  return layers;
+}
+async function runHooks(hooks, onError = (error) => {
+  throw error;
+}, invert = false) {
+  const layers = resolveHookDAG(hooks, invert);
+  for (const layer of layers)
+    await Promise.all(
+      layer.map(async (h) => {
+        try {
+          if (typeof h.cb === "function") return await h.cb();
+          return await h.cb;
+        } catch (error) {
+          return onError(error instanceof Error ? error : new Error(`${error}`));
+        }
+      })
+    );
+}
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  class A {
+  }
+  class B {
+  }
+  class C {
+  }
+  class D {
+  }
+  const noop = () => {
+  };
+  describe("registerHook", () => {
+    test("registers a hook with no dependencies", () => {
+      const hooks = [];
+      registerHook(hooks, { cb: noop, class: A, after: [] });
+      expect(hooks).toHaveLength(1);
+    });
+    test("throws on missing dependency", () => {
+      const hooks = [];
+      expect(() => registerHook(hooks, { cb: noop, class: B, after: [A] })).toThrow(/Missing dependency.*B.*A/);
+    });
+    test("throws on cycle: A\u2192B\u2192A", () => {
+      const hooks = [];
+      registerHook(hooks, { cb: noop, class: A, after: [] });
+      registerHook(hooks, { cb: noop, class: B, after: [A] });
+      expect(() => registerHook(hooks, { cb: noop, class: A, after: [B] })).toThrow(/Cycle detected/);
+    });
+    test("throws on transitive cycle: A\u2192B\u2192C\u2192A", () => {
+      const hooks = [];
+      registerHook(hooks, { cb: noop, class: A, after: [] });
+      registerHook(hooks, { cb: noop, class: B, after: [A] });
+      registerHook(hooks, { cb: noop, class: C, after: [B] });
+      expect(() => registerHook(hooks, { cb: noop, class: A, after: [C] })).toThrow(/Cycle detected/);
+    });
+    test("allows anonymous hooks with dependencies", () => {
+      const hooks = [];
+      registerHook(hooks, { cb: noop, class: A, after: [] });
+      registerHook(hooks, { cb: noop, after: [A] });
+      expect(hooks).toHaveLength(2);
+    });
+    test("anonymous hook throws on missing dependency", () => {
+      const hooks = [];
+      expect(() => registerHook(hooks, { cb: noop, after: [A] })).toThrow(/Missing dependency.*anonymous.*A/);
+    });
+  });
+  describe("resolveHookDAG", () => {
+    test("linear chain: A \u2192 B \u2192 C", () => {
+      const hooks = [
+        { cb: noop, class: A, after: [] },
+        { cb: noop, class: B, after: [A] },
+        { cb: noop, class: C, after: [B] }
+      ];
+      const layers = resolveHookDAG(hooks);
+      expect(layers).toHaveLength(3);
+      expect(layers[0].every((h) => h.class === A)).toBe(true);
+      expect(layers[1].every((h) => h.class === B)).toBe(true);
+      expect(layers[2].every((h) => h.class === C)).toBe(true);
+    });
+    test("fan-out: A \u2192 B, A \u2192 C (B and C are parallel)", () => {
+      const hooks = [
+        { cb: noop, class: A, after: [] },
+        { cb: noop, class: B, after: [A] },
+        { cb: noop, class: C, after: [A] }
+      ];
+      const layers = resolveHookDAG(hooks);
+      expect(layers).toHaveLength(2);
+      expect(layers[0].every((h) => h.class === A)).toBe(true);
+      const secondClasses = layers[1].map((h) => h.class);
+      expect(secondClasses).toContain(B);
+      expect(secondClasses).toContain(C);
+    });
+    test("fan-in: B \u2192 D, C \u2192 D", () => {
+      const hooks = [
+        { cb: noop, class: B, after: [] },
+        { cb: noop, class: C, after: [] },
+        { cb: noop, class: D, after: [B, C] }
+      ];
+      const layers = resolveHookDAG(hooks);
+      expect(layers).toHaveLength(2);
+      const firstClasses = layers[0].map((h) => h.class);
+      expect(firstClasses).toContain(B);
+      expect(firstClasses).toContain(C);
+      expect(layers[1].every((h) => h.class === D)).toBe(true);
+    });
+    test("diamond: A \u2192 B, A \u2192 C, B \u2192 D, C \u2192 D", () => {
+      const hooks = [
+        { cb: noop, class: A, after: [] },
+        { cb: noop, class: B, after: [A] },
+        { cb: noop, class: C, after: [A] },
+        { cb: noop, class: D, after: [B, C] }
+      ];
+      const layers = resolveHookDAG(hooks);
+      expect(layers).toHaveLength(3);
+      expect(layers[0][0].class).toBe(A);
+      const midClasses = layers[1].map((h) => h.class);
+      expect(midClasses).toContain(B);
+      expect(midClasses).toContain(C);
+      expect(layers[2][0].class).toBe(D);
+    });
+    test("close-event inversion reverses the graph", () => {
+      const hooks = [
+        { cb: noop, class: A, after: [] },
+        { cb: noop, class: B, after: [A] },
+        { cb: noop, class: C, after: [B] }
+      ];
+      const layers = resolveHookDAG(hooks, true);
+      expect(layers).toHaveLength(3);
+      expect(layers[0].every((h) => h.class === C)).toBe(true);
+      expect(layers[1].every((h) => h.class === B)).toBe(true);
+      expect(layers[2].every((h) => h.class === A)).toBe(true);
+    });
+    test("close inversion: fan-out becomes fan-in", () => {
+      const hooks = [
+        { cb: noop, class: A, after: [] },
+        { cb: noop, class: B, after: [A] },
+        { cb: noop, class: C, after: [A] }
+      ];
+      const layers = resolveHookDAG(hooks, true);
+      expect(layers).toHaveLength(2);
+      const firstClasses = layers[0].map((h) => h.class);
+      expect(firstClasses).toContain(B);
+      expect(firstClasses).toContain(C);
+      expect(layers[1].every((h) => h.class === A)).toBe(true);
+    });
+    test("multiple hooks per class are all in the same layer", () => {
+      const cb1 = () => {
+      };
+      const cb2 = () => {
+      };
+      const hooks = [
+        { cb: cb1, class: A, after: [] },
+        { cb: cb2, class: A, after: [] },
+        { cb: noop, class: B, after: [A] }
+      ];
+      const layers = resolveHookDAG(hooks);
+      expect(layers).toHaveLength(2);
+      expect(layers[0]).toHaveLength(2);
+      expect(layers[0].every((h) => h.class === A)).toBe(true);
+    });
+    test("anonymous hooks without deps run at deepest level", () => {
+      const hooks = [
+        { cb: noop, class: A, after: [] },
+        { cb: noop, class: B, after: [A] },
+        { cb: noop, after: [] }
+      ];
+      const layers = resolveHookDAG(hooks);
+      expect(layers).toHaveLength(2);
+      const lastLayer = layers[layers.length - 1];
+      expect(lastLayer.some((h) => h.class === void 0)).toBe(true);
+    });
+    test("anonymous hooks with deps run after their dependencies", () => {
+      const hooks = [
+        { cb: noop, class: A, after: [] },
+        { cb: noop, class: B, after: [A] },
+        { cb: noop, class: C, after: [B] },
+        { cb: noop, after: [A] }
+      ];
+      const layers = resolveHookDAG(hooks);
+      const anonLayer = layers.findIndex((l) => l.some((h) => h.class === void 0));
+      const aLayer = layers.findIndex((l) => l.some((h) => h.class === A));
+      expect(anonLayer).toBeGreaterThan(aLayer);
+    });
+    test("empty hooks returns empty layers", () => {
+      expect(resolveHookDAG([])).toEqual([]);
+    });
+  });
+  describe("runHooks", () => {
+    test("same-depth siblings observably overlap", async () => {
+      const log = [];
+      const hooks = [
+        {
+          cb: async () => {
+            log.push("B-start");
+            await new Promise((r) => setTimeout(r, 20));
+            log.push("B-end");
+          },
+          class: B,
+          after: []
+        },
+        {
+          cb: async () => {
+            log.push("C-start");
+            await new Promise((r) => setTimeout(r, 20));
+            log.push("C-end");
+          },
+          class: C,
+          after: []
+        }
+      ];
+      await runHooks(hooks);
+      expect(log[0]).toBe("B-start");
+      expect(log[1]).toBe("C-start");
+    });
+    test("different depths run sequentially", async () => {
+      const log = [];
+      const hooks = [
+        {
+          cb: async () => {
+            log.push("A");
+          },
+          class: A,
+          after: []
+        },
+        {
+          cb: async () => {
+            log.push("B");
+          },
+          class: B,
+          after: [A]
+        }
+      ];
+      await runHooks(hooks);
+      expect(log).toEqual(["A", "B"]);
+    });
+    test("close inversion runs hooks in reverse dependency order", async () => {
+      const log = [];
+      const hooks = [
+        { cb: async () => log.push("A"), class: A, after: [] },
+        { cb: async () => log.push("B"), class: B, after: [A] },
+        { cb: async () => log.push("C"), class: C, after: [B] }
+      ];
+      await runHooks(hooks, void 0, true);
+      expect(log).toEqual(["C", "B", "A"]);
+    });
+    test("errors are routed to onError handler", async () => {
+      const errors = [];
+      const hooks = [
+        {
+          cb: () => {
+            throw new Error("boom");
+          },
+          class: A,
+          after: []
+        }
+      ];
+      await runHooks(hooks, (e) => {
+        errors.push(e);
+      });
+      expect(errors).toHaveLength(1);
+      expect(errors[0].message).toBe("boom");
+    });
+    test("raw promise callbacks are awaited", async () => {
+      const log = [];
+      const hooks = [
+        {
+          cb: Promise.resolve().then(() => log.push("resolved")),
+          class: A,
+          after: []
+        }
+      ];
+      await runHooks(hooks);
+      expect(log).toContain("resolved");
+    });
+  });
+}
+
+// src/instance/settings.ts
+var import_valleyed = require("valleyed");
+var instanceSettingsPipe = () => import_valleyed.v.object({
+  app: import_valleyed.v.object({
+    name: import_valleyed.v.string()
+  }),
+  log: import_valleyed.v.defaults(
+    import_valleyed.v.object({
+      level: import_valleyed.v.defaults(import_valleyed.v.in(["fatal", "error", "warn", "info", "debug", "trace", "silent"]), "info")
+    }),
+    {}
+  ),
+  utils: import_valleyed.v.defaults(
+    import_valleyed.v.object({
+      hashSaltRounds: import_valleyed.v.defaults(import_valleyed.v.number(), 10),
+      paginationDefaultLimit: import_valleyed.v.defaults(import_valleyed.v.number(), 100),
+      maxFileUploadSizeInMb: import_valleyed.v.defaults(import_valleyed.v.number(), 500)
+    }),
+    {}
+  )
+});
+
+// src/instance/index.ts
+var Instance = class _Instance {
+  static #id;
+  static #instance;
+  static #hooks = {};
+  settings;
+  log;
+  constructor(settings) {
+    _Instance.#instance = this;
+    this.settings = Object.freeze(settings);
+    this.log = (0, import_pino.default)({
+      level: this.settings.log.level,
+      serializers: {
+        err: import_pino.default.stdSerializers.err,
+        error: import_pino.default.stdSerializers.err,
+        req: import_pino.default.stdSerializers.req,
+        res: import_pino.default.stdSerializers.res
+      },
+      mixin: () => ({
+        instanceId: _Instance.#id
+      })
+    });
+    _Instance.#registerOnExitHandler();
+  }
+  alias(id) {
+    if (_Instance.#id !== void 0) return _Instance.crash(new EquippedError("Instance already has an alias", {}));
+    _Instance.#id = id;
+  }
+  get id() {
+    if (_Instance.#id === void 0) return _Instance.crash(new EquippedError("Instance doesnt have an alias yet", {}));
+    return _Instance.#id;
+  }
+  getScopedName(name, key = ".") {
+    return [this.settings.app.name, name].join(key);
+  }
+  async start() {
+    try {
+      await runHooks(_Instance.#hooks["setup"] ?? []);
+      await runHooks(_Instance.#hooks["start"] ?? []);
+    } catch (error) {
+      _Instance.crash(new EquippedError(`Error starting instance`, {}, error));
+    }
+  }
+  static envs(envsPipe) {
+    const envValidity = import_valleyed2.v.validate(envsPipe, process.env);
+    if (!envValidity.valid) {
+      _Instance.crash(
+        new EquippedError(`Environment variables are not valid
+${envValidity.error.toString()}`, {
+          messages: envValidity.error.messages
+        })
+      );
+    }
+    return envValidity.value;
+  }
+  static create(settings) {
+    if (_Instance.#instance) return _Instance.crash(new EquippedError("Instance has been initialized already", {}));
+    const settingsValidity = import_valleyed2.v.validate(instanceSettingsPipe(), settings);
+    if (!settingsValidity.valid) {
+      _Instance.crash(
+        new EquippedError(`Settings are not valid
+${settingsValidity.error.toString()}`, {
+          messages: settingsValidity.error.messages
+        })
+      );
+    }
+    return new _Instance(settingsValidity.value);
+  }
+  static get() {
+    if (!_Instance.#instance)
+      return _Instance.crash(
+        new EquippedError("Has not been initialized. Make sure an instance has been created before you get an instance", {})
+      );
+    return _Instance.#instance;
+  }
+  static maybeGet() {
+    return _Instance.#instance;
+  }
+  static on(event, cb, options) {
+    _Instance.#hooks[event] ??= [];
+    const record = { cb, class: options?.class, after: options?.after ?? [] };
+    registerHook(_Instance.#hooks[event], record);
+  }
+  static #registerOnExitHandler() {
+    const signals = {
+      SIGHUP: 1,
+      SIGINT: 2,
+      SIGTERM: 15
+    };
+    Object.entries(signals).forEach(([signal, code]) => {
+      process.on(signal, async () => {
+        await runHooks(_Instance.#hooks["close"] ?? [], () => {
+        }, true);
+        process.exit(128 + code);
+      });
+    });
+  }
+  static resolveBeforeCrash(cb) {
+    const value = cb();
+    _Instance.on("close", async () => await value);
+    return value;
+  }
+  static crash(error) {
+    console.error(error);
+    process.exit(1);
+  }
+  static createId(opts) {
+    return `${opts?.prefix ?? ""}${(0, import_ulid.ulid)(opts?.time?.getTime())}`;
+  }
+};
+
+// src/utilities/configurable.ts
+var import_valleyed3 = require("valleyed");
+function configurable(pipeFn, base) {
+  const pipe = pipeFn();
+  import_valleyed3.v.compile(pipe);
+  class Configurable extends base {
+    constructor(config, ...baseArgs) {
+      super(...baseArgs);
+      this.config = config;
+    }
+    static create(input, ...args) {
+      const r = import_valleyed3.v.validate(pipe, input);
+      if (!r.valid) throw r.error;
+      return new this(r.value, ...args);
+    }
+  }
+  return Configurable;
+}
+if (void 0) {
+  const { describe, test, expect, expectTypeOf } = void 0;
+  const { v: v6 } = null;
+  const testPipe = () => v6.object({
+    host: v6.string(),
+    port: v6.number()
+  });
+  class TestBase {
+    baseValue;
+    constructor() {
+      this.baseValue = "base";
+    }
+  }
+  class TestBaseWithArgs {
+    label;
+    constructor(label) {
+      this.label = label;
+    }
+  }
+  describe("configurable", () => {
+    test("validation runs in static create before constructor body executes", () => {
+      let constructorRan = false;
+      const Wrapped = configurable(testPipe, TestBase);
+      class MyClass extends Wrapped {
+        constructor(config) {
+          super(config);
+          constructorRan = true;
+        }
+      }
+      expect(() => MyClass.create({ host: 123, port: "bad" })).toThrow();
+      expect(constructorRan).toBe(false);
+      MyClass.create({ host: "localhost", port: 3e3 });
+      expect(constructorRan).toBe(true);
+    });
+    test("constructor receives validated value", () => {
+      const Wrapped = configurable(testPipe, TestBase);
+      let receivedConfig;
+      class MyClass extends Wrapped {
+        constructor(config) {
+          super(config);
+          receivedConfig = this.config;
+        }
+      }
+      MyClass.create({ host: "localhost", port: 3e3 });
+      expect(receivedConfig).toEqual({ host: "localhost", port: 3e3 });
+    });
+    test("external new is a compile error", () => {
+      const Wrapped = configurable(testPipe, TestBase);
+      class MyClass extends Wrapped {
+        constructor(config) {
+          super(config);
+        }
+      }
+      void (() => new MyClass({ host: "localhost", port: 3e3 }));
+    });
+    test("static Config resolves to PipeOutput<P> at the type level", () => {
+      const Wrapped = configurable(testPipe, TestBase);
+      class MyClass extends Wrapped {
+        constructor(config) {
+          super(config);
+        }
+      }
+      expectTypeOf().toEqualTypeOf();
+      expect(MyClass.create).toBeTypeOf("function");
+    });
+    test("ConstructorParameters<This>-based extras inference works for non-zero-arg leaf signatures", () => {
+      const Wrapped = configurable(testPipe, TestBase);
+      class MyClass extends Wrapped {
+        extra;
+        constructor(config, extra) {
+          super(config);
+          this.extra = extra;
+        }
+      }
+      const instance = MyClass.create({ host: "localhost", port: 3e3 }, 42);
+      expect(instance.extra).toBe(42);
+      expectTypeOf(instance).toHaveProperty("extra");
+      expectTypeOf(instance.extra).toEqualTypeOf();
+      void (() => MyClass.create({ host: "localhost", port: 3e3 }, "not-a-number"));
+    });
+    test("base-args forwarding works for non-zero-arg bases", () => {
+      const Wrapped = configurable(testPipe, TestBaseWithArgs);
+      class MyClass extends Wrapped {
+        constructor(config, label) {
+          super(config, label);
+        }
+      }
+      const instance = MyClass.create({ host: "localhost", port: 3e3 }, "test-label");
+      expect(instance.label).toBe("test-label");
+    });
+    test("config is accessible as protected readonly on instances", () => {
+      const Wrapped = configurable(testPipe, TestBase);
+      class MyClass extends Wrapped {
+        constructor(config) {
+          super(config);
+        }
+        getHost() {
+          return this.config.host;
+        }
+      }
+      const instance = MyClass.create({ host: "localhost", port: 3e3 });
+      expect(instance.getHost()).toBe("localhost");
+    });
+    test("accepts an abstract base class", () => {
+      class AbstractBase {
+      }
+      const Wrapped = configurable(testPipe, AbstractBase);
+      class Concrete extends Wrapped {
+        constructor(config) {
+          super(config);
+        }
+        greet() {
+          return `hello from ${this.config.host}`;
+        }
+      }
+      const instance = Concrete.create({ host: "localhost", port: 3e3 });
+      expect(instance.greet()).toBe("hello from localhost");
+      expectTypeOf(instance).toHaveProperty("config");
+    });
+  });
+}
+
+// src/orm/fields.ts
+var import_valleyed4 = require("valleyed");
+var Field = class {
+  name;
+  path;
+  constructor(name, path) {
+    this.name = name;
+    this.path = path ?? [name];
+  }
+};
+function toFieldName(field) {
+  if (field instanceof Field) return field.path.join(".");
+  return field;
+}
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  describe("Fields", () => {
+    describe("Field", () => {
+      test("stores name and defaults path to [name]", () => {
+        const f = new Field("email");
+        expect(f.name).toBe("email");
+        expect(f.path).toEqual(["email"]);
+      });
+      test("stores provided custom path", () => {
+        const f = new Field("profile", ["profile", "displayName"]);
+        expect(f.name).toBe("profile");
+        expect(f.path).toEqual(["profile", "displayName"]);
+      });
+    });
+    describe("toFieldName()", () => {
+      test("returns string input unchanged", () => {
+        expect(toFieldName("createdAt")).toBe("createdAt");
+      });
+      test("converts Field path into dot notation", () => {
+        const f = new Field("profile", ["profile", "displayName"]);
+        expect(toFieldName(f)).toBe("profile.displayName");
+      });
+    });
+    describe("SchemaField", () => {
+      test("extends Field and stores pipe", () => {
+        const mockPipe = v4.string();
+        const f = new SchemaField("email", mockPipe);
+        expect(f).toBeInstanceOf(Field);
+        expect(f.name).toBe("email");
+        expect(f.path).toEqual(["email"]);
+        expect(f.pipe).toBe(mockPipe);
+      });
+      test("stores lifecycle hooks when provided", () => {
+        const mockPipe = v4.number();
+        const f = new SchemaField("updatedAt", mockPipe, {
+          onCreate: () => 1e3,
+          onUpdate: () => 2e3
+        });
+        expect(f.onCreate?.()).toBe(1e3);
+        expect(f.onUpdate?.()).toBe(2e3);
+      });
+      test("keeps lifecycle hooks undefined when omitted", () => {
+        const mockPipe = v4.string();
+        const f = new SchemaField("name", mockPipe);
+        expect(f.onCreate).toBeUndefined();
+        expect(f.onUpdate).toBeUndefined();
+      });
+    });
+  });
+}
+
+// src/orm/filter.ts
+var Filter = class {
+  constructor(field, op, value) {
+    this.op = op;
+    this.value = value;
+    this.field = toFieldName(field);
+  }
+  field;
+};
+var FilterGroup = class _FilterGroup {
+  constructor(op = "and", children) {
+    this.op = op;
+    this.children = children ?? [];
+  }
+  children;
+  #withChild(child) {
+    return new _FilterGroup(this.op, [...this.children, child]);
+  }
+  eq(field, value) {
+    return this.#withChild(new Filter(field, "eq", value));
+  }
+  ne(field, value) {
+    return this.#withChild(new Filter(field, "ne", value));
+  }
+  gt(field, value) {
+    return this.#withChild(new Filter(field, "gt", value));
+  }
+  gte(field, value) {
+    return this.#withChild(new Filter(field, "gte", value));
+  }
+  lt(field, value) {
+    return this.#withChild(new Filter(field, "lt", value));
+  }
+  lte(field, value) {
+    return this.#withChild(new Filter(field, "lte", value));
+  }
+  in(field, value) {
+    return this.#withChild(new Filter(field, "in", value));
+  }
+  notIn(field, value) {
+    return this.#withChild(new Filter(field, "notIn", value));
+  }
+  like(field, value) {
+    return this.#withChild(new Filter(field, "like", value));
+  }
+  exists(field) {
+    return this.#withChild(new Filter(field, "exists", true));
+  }
+  notExists(field) {
+    return this.#withChild(new Filter(field, "notExists", true));
+  }
+  contains(field, value) {
+    return this.#withChild(new Filter(field, "contains", value));
+  }
+  notContains(field, value) {
+    return this.#withChild(new Filter(field, "notContains", value));
+  }
+  and(facFns) {
+    if (facFns.length === 0) throw new EquippedError("and() requires at least one filter factory", { op: "and" });
+    const group = new _FilterGroup("and", facFns.map((fn) => fn(_FilterGroup.create())));
+    return this.#withChild(group);
+  }
+  or(facFns) {
+    if (facFns.length === 0) throw new EquippedError("or() requires at least one filter factory", { op: "or" });
+    const group = new _FilterGroup("or", facFns.map((fn) => fn(_FilterGroup.create())));
+    return this.#withChild(group);
+  }
+  clone() {
+    return new _FilterGroup(
+      this.op,
+      this.children.map((c) => {
+        if (c instanceof Filter) return new Filter(c.field, c.op, structuredClone(c.value));
+        return c.clone();
+      })
+    );
+  }
+  static create() {
+    return new _FilterGroup();
+  }
+};
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  const { v: v6 } = null;
+  const { Schema } = null;
+  const UserSchema = Schema.from("users").pk("id", v6.string(), () => "u1").field("email", v6.string()).field("age", v6.number()).field("name", v6.string()).field("tags", v6.array(v6.string())).build();
+  describe("FilterGroup", () => {
+    describe("filter-op methods", () => {
+      test("eq adds a filter clause with op eq", () => {
+        const g = FilterGroup.create().eq(UserSchema.fields.age, 25);
+        expect(g.children).toHaveLength(1);
+        const f = g.children[0];
+        expect(f.field).toBe("age");
+        expect(f.op).toBe("eq");
+        expect(f.value).toBe(25);
+      });
+      test("ne adds a filter clause with op ne", () => {
+        const g = FilterGroup.create().ne("name", "Bob");
+        const f = g.children[0];
+        expect(f.op).toBe("ne");
+        expect(f.value).toBe("Bob");
+      });
+      test("gt/gte/lt/lte produce correct ops", () => {
+        const g = FilterGroup.create().gt(UserSchema.fields.age, 10).gte(UserSchema.fields.age, 20).lt(UserSchema.fields.age, 30).lte(UserSchema.fields.age, 40);
+        expect(g.children.map((c) => c.op)).toEqual(["gt", "gte", "lt", "lte"]);
+      });
+      test("in adds a filter clause with array value", () => {
+        const g = FilterGroup.create().in(UserSchema.fields.age, [1, 2, 3]);
+        const f = g.children[0];
+        expect(f.op).toBe("in");
+        expect(f.value).toEqual([1, 2, 3]);
+      });
+      test("notIn adds a filter clause with op notIn", () => {
+        const g = FilterGroup.create().notIn(UserSchema.fields.age, [4, 5]);
+        const f = g.children[0];
+        expect(f.op).toBe("notIn");
+        expect(f.value).toEqual([4, 5]);
+      });
+      test("like adds a filter clause with op like", () => {
+        const g = FilterGroup.create().like(UserSchema.fields.email, "alice");
+        const f = g.children[0];
+        expect(f.op).toBe("like");
+        expect(f.value).toBe("alice");
+      });
+      test("exists adds a filter clause with op exists", () => {
+        const g = FilterGroup.create().exists(UserSchema.fields.name);
+        const f = g.children[0];
+        expect(f.op).toBe("exists");
+      });
+      test("notExists is its own op, not a boolean form of exists", () => {
+        const g = FilterGroup.create().notExists(UserSchema.fields.name);
+        const f = g.children[0];
+        expect(f.op).toBe("notExists");
+        expect(f.op).not.toBe("exists");
+      });
+      test("contains/notContains produce correct ops", () => {
+        const g = FilterGroup.create().contains("tags", ["a"]).notContains("tags", ["b"]);
+        expect(g.children[0].op).toBe("contains");
+        expect(g.children[1].op).toBe("notContains");
+      });
+      test("all 13 filter ops produce matching Filter.op values (name-parity)", () => {
+        const g = FilterGroup.create().eq("f", 1).ne("f", 1).gt("f", 1).gte("f", 1).lt("f", 1).lte("f", 1).in("f", [1]).notIn("f", [1]).like("f", "x").exists("f").notExists("f").contains("f", [1]).notContains("f", [1]);
+        const ops = g.children.map((c) => c.op);
+        expect(ops).toEqual([
+          "eq",
+          "ne",
+          "gt",
+          "gte",
+          "lt",
+          "lte",
+          "in",
+          "notIn",
+          "like",
+          "exists",
+          "notExists",
+          "contains",
+          "notContains"
+        ]);
+      });
+    });
+    describe("raw-string field overload", () => {
+      test("accepts raw string field name", () => {
+        const g = FilterGroup.create().eq("age", 18);
+        const f = g.children[0];
+        expect(f.field).toBe("age");
+      });
+      test("accepts typed Field ref and extracts field name", () => {
+        const g = FilterGroup.create().eq(UserSchema.fields.age, 18);
+        const f = g.children[0];
+        expect(f.field).toBe("age");
+      });
+    });
+    describe("structural combinators", () => {
+      test("and() creates a nested and-group", () => {
+        const g = FilterGroup.create().and([
+          (q) => q.eq("age", 10),
+          (q) => q.eq("name", "Alice")
+        ]);
+        expect(g.children).toHaveLength(1);
+        const nested = g.children[0];
+        expect(nested.op).toBe("and");
+        expect(nested.children).toHaveLength(2);
+      });
+      test("or() creates a nested or-group", () => {
+        const g = FilterGroup.create().or([
+          (q) => q.eq("name", "Alice"),
+          (q) => q.eq("name", "Bob")
+        ]);
+        const nested = g.children[0];
+        expect(nested.op).toBe("or");
+      });
+    });
+    describe("empty-combinator rejection", () => {
+      test("and([]) throws at builder time", () => {
+        expect(() => FilterGroup.create().and([])).toThrow();
+      });
+      test("or([]) throws at builder time", () => {
+        expect(() => FilterGroup.create().or([])).toThrow();
+      });
+      test("thrown error has stack pointing at offending call", () => {
+        try {
+          FilterGroup.create().and([]);
+          expect.unreachable();
+        } catch (e) {
+          expect(e.stack).toContain("filter.ts");
+        }
+      });
+    });
+    describe("clone()", () => {
+      test("deep-clones the tree", () => {
+        const original = FilterGroup.create().eq("name", "Alice").and([(q) => q.gt("age", 20)]);
+        const cloned = original.clone();
+        expect(cloned.children).toHaveLength(2);
+        expect(cloned).not.toBe(original);
+        expect(cloned.children[0]).not.toBe(original.children[0]);
+      });
+      test("structuredClone of values \u2014 mutations on clone do not leak", () => {
+        const arr = [1, 2, 3];
+        const original = FilterGroup.create().in("ids", arr);
+        const cloned = original.clone();
+        const clonedValue = cloned.children[0].value;
+        clonedValue.push(4);
+        expect(original.children[0].value).toEqual([1, 2, 3]);
+        expect(clonedValue).toEqual([1, 2, 3, 4]);
+      });
+    });
+  });
+  describe("clone-on-step: fan-out independence", () => {
+    test(".eq() returns a new FilterGroup, not the same instance", () => {
+      const base = FilterGroup.create();
+      const a = base.eq("name", "Alice");
+      expect(a).not.toBe(base);
+    });
+    test("fan-out from shared base does not pollute either branch", () => {
+      const base = FilterGroup.create().eq("name", "Alice");
+      const branchA = base.gt("age", 20);
+      const branchB = base.lt("age", 40);
+      expect(branchA.children).toHaveLength(2);
+      expect(branchB.children).toHaveLength(2);
+      expect(base.children).toHaveLength(1);
+      expect(branchA.children[1].op).toBe("gt");
+      expect(branchB.children[1].op).toBe("lt");
+    });
+    test(".and() returns a new FilterGroup", () => {
+      const base = FilterGroup.create().eq("name", "Alice");
+      const withAnd = base.and([(q) => q.gt("age", 20)]);
+      expect(withAnd).not.toBe(base);
+      expect(base.children).toHaveLength(1);
+      expect(withAnd.children).toHaveLength(2);
+    });
+    test(".or() returns a new FilterGroup", () => {
+      const base = FilterGroup.create().eq("name", "Alice");
+      const withOr = base.or([(q) => q.gt("age", 20)]);
+      expect(withOr).not.toBe(base);
+      expect(base.children).toHaveLength(1);
+      expect(withOr.children).toHaveLength(2);
+    });
+  });
+  describe("assertNormalisedFilter", () => {
+    test("passes for valid filter referencing known fields", () => {
+      const g = FilterGroup.create().eq(UserSchema.fields.age, 25);
+      expect(() => assertNormalisedFilter(UserSchema, g)).not.toThrow();
+    });
+    test("passes for raw string field that exists on schema", () => {
+      const g = FilterGroup.create().eq("email", "test@test.com");
+      expect(() => assertNormalisedFilter(UserSchema, g)).not.toThrow();
+    });
+    test("rejects unknown field name with OrmValidationError", () => {
+      const g = FilterGroup.create().eq("unknownField", 42);
+      expect(() => assertNormalisedFilter(UserSchema, g)).toThrow(OrmValidationError);
+    });
+    test("rejected error has kind validation", () => {
+      const g = FilterGroup.create().eq("badField", 42);
+      try {
+        assertNormalisedFilter(UserSchema, g);
+        expect.unreachable();
+      } catch (e) {
+        expect(e).toBeInstanceOf(OrmValidationError);
+        expect(e.kind).toBe("validation");
+        expect(e.failures).toHaveLength(1);
+        expect(e.failures[0].field).toBe("badField");
+      }
+    });
+    test("preserves logical field names verbatim for Field refs", () => {
+      const g = FilterGroup.create().eq(UserSchema.fields.email, "a@b.com");
+      const f = g.children[0];
+      expect(f.field).toBe("email");
+      assertNormalisedFilter(UserSchema, g);
+    });
+    test("preserves logical field names verbatim for raw-string overloads", () => {
+      const g = FilterGroup.create().eq("age", 18);
+      const f = g.children[0];
+      expect(f.field).toBe("age");
+      assertNormalisedFilter(UserSchema, g);
+    });
+    test("walks nested groups to detect unknown fields", () => {
+      const g = FilterGroup.create().and([
+        (q) => q.eq("name", "Alice"),
+        (q) => q.or([(inner) => inner.eq("nonexistent", "val")])
+      ]);
+      expect(() => assertNormalisedFilter(UserSchema, g)).toThrow(OrmValidationError);
+    });
+  });
+  describe("assertNormalisedAggregate", () => {
+    const adapter = { aggregateOps: ["count"] };
+    test("passes for valid count aggregate", () => {
+      const spec = { aggregates: [{ fn: "count", alias: "total" }], groupBy: [] };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).not.toThrow();
+    });
+    test("rejects empty aggregator list", () => {
+      const spec = { aggregates: [], groupBy: [] };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        expect(e.kind).toBe("aggregate");
+      }
+    });
+    test("rejects undeclared aggregate op", () => {
+      const spec = { aggregates: [{ fn: "sum", alias: "total", field: "age" }], groupBy: [] };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures[0].alias).toBe("total");
+        expect(err.failures[0].cause).toContain("Undeclared");
+      }
+    });
+    test("rejects duplicate aliases", () => {
+      const spec = {
+        aggregates: [
+          { fn: "count", alias: "total" },
+          { fn: "count", alias: "total" }
+        ],
+        groupBy: []
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.failures.some((f) => f.alias === "total")).toBe(true);
+      }
+    });
+    test("validates where filter against schema", () => {
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: [],
+        where: FilterGroup.create().eq("unknownField", 42)
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, adapter, spec)).toThrow(OrmValidationError);
+    });
+    test("collects multiple failures", () => {
+      const spec = {
+        aggregates: [
+          { fn: "sum", alias: "x", field: "age" },
+          { fn: "avg", alias: "x", field: "age" }
+        ],
+        groupBy: []
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, adapter, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.failures.length).toBeGreaterThanOrEqual(2);
+      }
+    });
+    test("rejects unknown groupBy field", () => {
+      const allOps = { aggregateOps: ["count", "sum"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["nonexistent"]
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, allOps, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures[0].cause).toContain("groupBy");
+        expect(err.failures[0].field).toBe("nonexistent");
+      }
+    });
+    test("rejects alias colliding with groupBy field name", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "name" }],
+        groupBy: ["name"]
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, allOps, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures.some((f) => String(f.cause).includes("collides"))).toBe(true);
+      }
+    });
+    test("rejects unknown having field", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["name"],
+        having: FilterGroup.create().gt("nonexistent", 0)
+      };
+      try {
+        assertNormalisedAggregate(UserSchema, allOps, spec);
+        expect.unreachable();
+      } catch (e) {
+        const err = e;
+        expect(err.kind).toBe("aggregate");
+        expect(err.failures[0].cause).toContain("having");
+      }
+    });
+    test("having accepts alias and groupBy field names", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["name"],
+        having: FilterGroup.create().gt("total", 0).eq("name", "Alice")
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, allOps, spec)).not.toThrow();
+    });
+    test("passes valid groupBy with known schema fields", () => {
+      const allOps = { aggregateOps: ["count"] };
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["name", "age"]
+      };
+      expect(() => assertNormalisedAggregate(UserSchema, allOps, spec)).not.toThrow();
+    });
+  });
+}
+
+// src/orm/updates.ts
+var SetOp = class {
+  constructor(values) {
+    this.values = values;
+  }
+  kind = "set";
+};
+var IncOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "inc";
+};
+var MulOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "mul";
+};
+var MinOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "min";
+};
+var MaxOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "max";
+};
+var UnsetOp = class {
+  constructor(field) {
+    this.field = field;
+  }
+  kind = "unset";
+};
+var PushOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "push";
+};
+var PullOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "pull";
+};
+var PatchOp = class {
+  constructor(field, value) {
+    this.field = field;
+    this.value = value;
+  }
+  kind = "patch";
+};
+function flattenOps(ops) {
+  const data = {};
+  for (const op of ops) {
+    if (op instanceof SetOp) Object.assign(data, op.values);
+    else data[op.field] = op;
+  }
+  return data;
+}
+if (void 0) {
+  const { describe, test, expect, expectTypeOf } = void 0;
+  const { v: v6 } = null;
+  const { Schema } = null;
+  const TestSchema = Schema.from("test").pk("id", v6.string(), () => "x").field("name", v6.string()).field("age", v6.number()).field("score", v6.optional(v6.number())).field("tags", v6.array(v6.string())).field("meta", v6.object({ a: v6.number() })).field("createdAt", v6.number(), { onCreate: () => 1e3 }).field("updatedAt", v6.number(), { onCreate: () => 1e3, onUpdate: () => 2e3 }).build();
+  describe("op classes", () => {
+    test('SetOp has kind "set" and stores values', () => {
+      const op = new SetOp({ name: "Alice" });
+      expect(op.kind).toBe("set");
+      expect(op.values).toEqual({ name: "Alice" });
+    });
+    test('IncOp has kind "inc" and stores field + value', () => {
+      const op = new IncOp("age", 5);
+      expect(op.kind).toBe("inc");
+      expect(op.field).toBe("age");
+      expect(op.value).toBe(5);
+    });
+    test('MulOp has kind "mul" and stores field + value', () => {
+      const op = new MulOp("score", 3);
+      expect(op.kind).toBe("mul");
+      expect(op.field).toBe("score");
+      expect(op.value).toBe(3);
+    });
+    test('MinOp has kind "min"', () => {
+      expect(new MinOp("age", 10).kind).toBe("min");
+    });
+    test('MaxOp has kind "max"', () => {
+      expect(new MaxOp("age", 99).kind).toBe("max");
+    });
+    test('UnsetOp has kind "unset"', () => {
+      expect(new UnsetOp("score").kind).toBe("unset");
+    });
+    test('PushOp has kind "push"', () => {
+      expect(new PushOp("tags", "x").kind).toBe("push");
+    });
+    test('PullOp has kind "pull"', () => {
+      expect(new PullOp("tags", "x").kind).toBe("pull");
+    });
+    test('PatchOp has kind "patch"', () => {
+      expect(new PatchOp("meta", { a: 9 }).kind).toBe("patch");
+    });
+  });
+  describe("isUpdateOp", () => {
+    test("returns true for every op class", () => {
+      expect(isUpdateOp(new SetOp({}))).toBe(true);
+      expect(isUpdateOp(new IncOp("f", 1))).toBe(true);
+      expect(isUpdateOp(new MulOp("f", 2))).toBe(true);
+      expect(isUpdateOp(new MinOp("f", 0))).toBe(true);
+      expect(isUpdateOp(new MaxOp("f", 10))).toBe(true);
+      expect(isUpdateOp(new UnsetOp("f"))).toBe(true);
+      expect(isUpdateOp(new PushOp("f", "v"))).toBe(true);
+      expect(isUpdateOp(new PullOp("f", "v"))).toBe(true);
+      expect(isUpdateOp(new PatchOp("f", {}))).toBe(true);
+    });
+    test("returns false for non-op values", () => {
+      expect(isUpdateOp("string")).toBe(false);
+      expect(isUpdateOp(42)).toBe(false);
+      expect(isUpdateOp(null)).toBe(false);
+      expect(isUpdateOp({})).toBe(false);
+    });
+  });
+  describe("op helper functions", () => {
+    test("set() creates SetOp with values", () => {
+      const op = set({ name: "Alice", age: 30 });
+      expect(op).toBeInstanceOf(SetOp);
+      expect(op.kind).toBe("set");
+      expect(op.values).toEqual({ name: "Alice", age: 30 });
+    });
+    test("inc() creates IncOp from field ref", () => {
+      const op = inc(TestSchema.fields.age, 5);
+      expect(op).toBeInstanceOf(IncOp);
+      expect(op.field).toBe("age");
+      expect(op.value).toBe(5);
+    });
+    test("mul() creates MulOp from field ref", () => {
+      const op = mul(TestSchema.fields.age, 3);
+      expect(op).toBeInstanceOf(MulOp);
+      expect(op.field).toBe("age");
+      expect(op.value).toBe(3);
+    });
+    test("min() creates MinOp from field ref", () => {
+      const op = min(TestSchema.fields.age, 10);
+      expect(op).toBeInstanceOf(MinOp);
+      expect(op.field).toBe("age");
+    });
+    test("max() creates MaxOp from field ref", () => {
+      const op = max(TestSchema.fields.age, 99);
+      expect(op).toBeInstanceOf(MaxOp);
+      expect(op.field).toBe("age");
+    });
+    test("unset() creates UnsetOp from field ref", () => {
+      const op = unset(TestSchema.fields.score);
+      expect(op).toBeInstanceOf(UnsetOp);
+      expect(op.field).toBe("score");
+    });
+    test("push() creates PushOp from field ref", () => {
+      const op = push(TestSchema.fields.tags, "new-tag");
+      expect(op).toBeInstanceOf(PushOp);
+      expect(op.field).toBe("tags");
+      expect(op.value).toBe("new-tag");
+    });
+    test("pull() creates PullOp from field ref", () => {
+      const op = pull(TestSchema.fields.tags, "old-tag");
+      expect(op).toBeInstanceOf(PullOp);
+      expect(op.field).toBe("tags");
+    });
+    test("patch() creates PatchOp from field ref", () => {
+      const op = patch(TestSchema.fields.meta, { a: 9 });
+      expect(op).toBeInstanceOf(PatchOp);
+      expect(op.field).toBe("meta");
+      expect(op.value).toEqual({ a: 9 });
+    });
+  });
+  describe("opTouchedFields", () => {
+    test("SetOp returns all keys from values", () => {
+      expect(opTouchedFields(new SetOp({ name: "A", age: 1 }))).toEqual(["name", "age"]);
+    });
+    test("IncOp returns the field", () => {
+      expect(opTouchedFields(new IncOp("age", 1))).toEqual(["age"]);
+    });
+    test("UnsetOp returns the field", () => {
+      expect(opTouchedFields(new UnsetOp("score"))).toEqual(["score"]);
+    });
+  });
+  describe("type-level: field-category helpers", () => {
+    test("NumericFieldOf only matches numeric fields (excludes optional numeric)", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("ComparableFieldOf matches numeric and string fields (excludes optional)", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("OptionalFieldOf only matches optional fields", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("ArrayFieldOf only matches array fields", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("ObjectFieldOf only matches object fields (not arrays)", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("type-level: inc on a string field is a TS error", () => {
+    test("inc rejects non-numeric fields", () => {
+      inc(TestSchema.fields.name, 1);
+    });
+  });
+  describe("type-level: push on a non-array field is a TS error", () => {
+    test("push rejects non-array fields", () => {
+      push(TestSchema.fields.name, "val");
+    });
+  });
+  describe("type-level: per-op gating via UpdateOp<S, A>", () => {
+    test("undeclared ops resolve to never", async () => {
+      const { OrmAdapter: OrmAdapter2 } = await null;
+      class LimitedAdapter extends OrmAdapter2 {
+        schemaConfigPipe = v6.object({});
+        supportedFieldTypes = ["string", "number"];
+        updateOps = ["set", "inc"];
+      }
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("adapter with no updateOps resolves all variants to never", async () => {
+      const { OrmAdapter: OrmAdapter2 } = await null;
+      class NoOpsAdapter extends OrmAdapter2 {
+        schemaConfigPipe = v6.object({});
+        supportedFieldTypes = ["string"];
+        updateOps = [];
+      }
+      expectTypeOf().toBeNever();
+    });
+    test("adapter with all updateOps includes all variants", async () => {
+      const { OrmAdapter: OrmAdapter2 } = await null;
+      class FullAdapter extends OrmAdapter2 {
+        schemaConfigPipe = v6.object({});
+        supportedFieldTypes = ["string", "number"];
+        updateOps = ["set", "inc", "mul", "min", "max", "unset", "push", "pull", "patch"];
+      }
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+}
+
+// src/orm/adapters/mongodb/query.ts
+function compileMongoFilter(group, primaryKey) {
+  const clauses = [];
+  for (const child of group.children) {
+    const compiled = compileChild(child, primaryKey);
+    if (compiled) clauses.push(compiled);
+  }
+  if (clauses.length === 0) return {};
+  if (clauses.length === 1) return clauses[0];
+  return { $and: clauses };
+}
+function compileMongoQuery(group, options, primaryKey) {
+  const mongoFilter = compileMongoFilter(group, primaryKey);
+  const orderBys = options?.orderBy ?? [];
+  const sort = orderBys.length > 0 ? Object.fromEntries(orderBys.map((o) => [mapField(o.field, primaryKey), o.direction === "desc" ? -1 : 1])) : void 0;
+  const selects = options?.select ?? [];
+  const projection = selects.length > 0 ? Object.fromEntries(selects.map((f) => [mapField(f, primaryKey), 1])) : void 0;
+  return {
+    filter: mongoFilter,
+    sort,
+    limit: options?.limit,
+    skip: options?.offset,
+    projection
+  };
+}
+function mapField(field, primaryKey) {
+  if (field === "id" && primaryKey === "_id") return "_id";
+  return field;
+}
+function compileFilter(f, primaryKey) {
+  const field = mapField(f.field, primaryKey);
+  switch (f.op) {
+    case "eq":
+      return { [field]: { $eq: f.value } };
+    case "ne":
+      return { [field]: { $ne: f.value } };
+    case "gt":
+      return { [field]: { $gt: f.value } };
+    case "gte":
+      return { [field]: { $gte: f.value } };
+    case "lt":
+      return { [field]: { $lt: f.value } };
+    case "lte":
+      return { [field]: { $lte: f.value } };
+    case "in":
+      return { [field]: { $in: f.value } };
+    case "notIn":
+      return { [field]: { $nin: f.value } };
+    case "like":
+      return { [field]: { $regex: new RegExp(String(f.value), "i") } };
+    case "exists":
+      return { [field]: { $exists: true, $ne: null } };
+    case "notExists":
+      return { [field]: { $eq: null } };
+    case "contains":
+      return { [field]: { $all: Array.isArray(f.value) ? f.value : [f.value] } };
+    case "notContains":
+      return { [field]: { $not: { $all: Array.isArray(f.value) ? f.value : [f.value] } } };
+    default:
+      return { [field]: { $eq: f.value } };
+  }
+}
+function compileChild(child, primaryKey) {
+  if (child instanceof Filter) return compileFilter(child, primaryKey);
+  if (child instanceof FilterGroup) return compileGroup(child, primaryKey);
+  return null;
+}
+function compileGroup(group, primaryKey) {
+  const clauses = group.children.map((c) => compileChild(c, primaryKey)).filter((c) => c !== null);
+  if (clauses.length === 0) return null;
+  if (clauses.length === 1) return clauses[0];
+  return { [group.op === "or" ? "$or" : "$and"]: clauses };
+}
+function compileMongoUpdate(data) {
+  const $set = {};
+  const $inc = {};
+  const $mul = {};
+  const $min = {};
+  const $max = {};
+  const $unset = {};
+  const $push = {};
+  const $pull = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value instanceof IncOp) $inc[key] = value.value;
+    else if (value instanceof MulOp) $mul[key] = value.value;
+    else if (value instanceof MinOp) $min[key] = value.value;
+    else if (value instanceof MaxOp) $max[key] = value.value;
+    else if (value instanceof UnsetOp) $unset[key] = "";
+    else if (value instanceof PushOp) $push[key] = value.value;
+    else if (value instanceof PullOp) $pull[key] = value.value;
+    else if (value instanceof PatchOp) {
+      const patchVal = value.value;
+      for (const [subKey, subVal] of Object.entries(patchVal)) {
+        $set[`${key}.${subKey}`] = subVal;
+      }
+    } else $set[key] = value;
+  }
+  const result = {};
+  if (Object.keys($set).length) result.$set = $set;
+  if (Object.keys($inc).length) result.$inc = $inc;
+  if (Object.keys($mul).length) result.$mul = $mul;
+  if (Object.keys($min).length) result.$min = $min;
+  if (Object.keys($max).length) result.$max = $max;
+  if (Object.keys($unset).length) result.$unset = $unset;
+  if (Object.keys($push).length) result.$push = $push;
+  if (Object.keys($pull).length) result.$pull = $pull;
+  return result;
+}
+function compileMongoOps(ops) {
+  return compileMongoUpdate(flattenOps(ops));
+}
+function compileMongoAggregate(spec, primaryKey) {
+  const pipeline = [];
+  if (spec.where) {
+    const match = compileMongoFilter(spec.where, primaryKey);
+    if (Object.keys(match).length > 0) pipeline.push({ $match: match });
+  }
+  const groupId = spec.groupBy.length > 0 ? Object.fromEntries(spec.groupBy.map((f) => [f, `$${mapField(f, primaryKey)}`])) : null;
+  const accumulators = {};
+  for (const agg of spec.aggregates) {
+    const fieldRef = agg.field ? `$${mapField(agg.field, primaryKey)}` : void 0;
+    switch (agg.fn) {
+      case "count":
+        accumulators[agg.alias] = { $sum: 1 };
+        break;
+      case "countDistinct":
+        accumulators[agg.alias] = { $addToSet: fieldRef };
+        break;
+      case "sum":
+      case "avg":
+      case "min":
+      case "max":
+        accumulators[agg.alias] = { [`$${agg.fn}`]: fieldRef };
+        break;
+    }
+  }
+  pipeline.push({ $group: { _id: groupId, ...accumulators } });
+  const project = { _id: 0 };
+  for (const f of spec.groupBy) {
+    project[f] = `$_id.${f}`;
+  }
+  for (const agg of spec.aggregates) {
+    if (agg.fn === "countDistinct") {
+      project[agg.alias] = { $size: `$${agg.alias}` };
+    } else {
+      project[agg.alias] = 1;
+    }
+  }
+  pipeline.push({ $project: project });
+  if (spec.having) {
+    const havingMatch = compileMongoFilter(spec.having, "");
+    if (Object.keys(havingMatch).length > 0) pipeline.push({ $match: havingMatch });
+  }
+  return pipeline;
+}
+if (void 0) {
+  const { describe, test, expect } = void 0;
+  const { FilterGroup: FilterGroup2 } = null;
+  const { OrderBy } = null;
+  describe("compileMongoFilter", () => {
+    test("empty filter group compiles to empty object", () => {
+      const group = FilterGroup2.create();
+      expect(compileMongoFilter(group, "id")).toEqual({});
+    });
+    test("single eq filter compiles to $eq", () => {
+      const group = FilterGroup2.create().eq("name", "Alice");
+      expect(compileMongoFilter(group, "id")).toEqual({ name: { $eq: "Alice" } });
+    });
+    test("ne, gt, gte, lt, lte compile to corresponding Mongo ops", () => {
+      expect(compileMongoFilter(FilterGroup2.create().ne("age", 5), "id")).toEqual({ age: { $ne: 5 } });
+      expect(compileMongoFilter(FilterGroup2.create().gt("age", 10), "id")).toEqual({ age: { $gt: 10 } });
+      expect(compileMongoFilter(FilterGroup2.create().gte("age", 20), "id")).toEqual({ age: { $gte: 20 } });
+      expect(compileMongoFilter(FilterGroup2.create().lt("age", 30), "id")).toEqual({ age: { $lt: 30 } });
+      expect(compileMongoFilter(FilterGroup2.create().lte("age", 40), "id")).toEqual({ age: { $lte: 40 } });
+    });
+    test("in compiles to $in", () => {
+      const group = FilterGroup2.create().in("status", ["a", "b"]);
+      expect(compileMongoFilter(group, "id")).toEqual({ status: { $in: ["a", "b"] } });
+    });
+    test("notIn compiles to $nin (canonical name notIn, Mongo op $nin)", () => {
+      const group = FilterGroup2.create().notIn("status", ["x", "y"]);
+      expect(compileMongoFilter(group, "id")).toEqual({ status: { $nin: ["x", "y"] } });
+    });
+    test("like compiles to $regex with case-insensitive flag", () => {
+      const group = FilterGroup2.create().like("name", "ali");
+      const result = compileMongoFilter(group, "id");
+      expect(result.name).toEqual({ $regex: expect.any(RegExp) });
+      const regex = result.name.$regex;
+      expect(regex.flags).toBe("i");
+      expect(regex.test("Alice")).toBe(true);
+    });
+    test("exists compiles to $exists: true, $ne: null", () => {
+      const group = FilterGroup2.create().exists("val");
+      expect(compileMongoFilter(group, "id")).toEqual({ val: { $exists: true, $ne: null } });
+    });
+    test("notExists is its own op \u2014 compiles to $eq: null", () => {
+      const group = FilterGroup2.create().notExists("val");
+      expect(compileMongoFilter(group, "id")).toEqual({ val: { $eq: null } });
+    });
+    test("contains compiles to $all", () => {
+      const group = FilterGroup2.create().contains("tags", ["a", "b"]);
+      expect(compileMongoFilter(group, "id")).toEqual({ tags: { $all: ["a", "b"] } });
+    });
+    test("notContains compiles to $not: { $all }", () => {
+      const group = FilterGroup2.create().notContains("tags", ["x"]);
+      expect(compileMongoFilter(group, "id")).toEqual({ tags: { $not: { $all: ["x"] } } });
+    });
+    test("multiple clauses produce $and", () => {
+      const group = FilterGroup2.create().eq("a", 1).gt("b", 2);
+      const result = compileMongoFilter(group, "id");
+      expect(result).toEqual({ $and: [{ a: { $eq: 1 } }, { b: { $gt: 2 } }] });
+    });
+    test("nested and/or groups compile correctly", () => {
+      const group = FilterGroup2.create().and([
+        (q) => q.eq("a", 1),
+        (q) => q.or([(g) => g.eq("b", 2), (g) => g.eq("c", 3)])
+      ]);
+      const result = compileMongoFilter(group, "id");
+      expect(result).toEqual({
+        $and: [{ a: { $eq: 1 } }, { $or: [{ b: { $eq: 2 } }, { c: { $eq: 3 } }] }]
+      });
+    });
+    test("maps id field to _id when primaryKey is _id", () => {
+      const group = FilterGroup2.create().eq("id", "abc");
+      expect(compileMongoFilter(group, "_id")).toEqual({ _id: { $eq: "abc" } });
+    });
+  });
+  describe("compileMongoQuery", () => {
+    test("options: sort, limit, skip, projection", () => {
+      const group = FilterGroup2.create().eq("active", true);
+      const options = {
+        orderBy: [new OrderBy("name", "asc"), new OrderBy("age", "desc")],
+        limit: 10,
+        offset: 5,
+        select: ["name", "age"]
+      };
+      const result = compileMongoQuery(group, options, "id");
+      expect(result.filter).toEqual({ active: { $eq: true } });
+      expect(result.sort).toEqual({ name: 1, age: -1 });
+      expect(result.limit).toBe(10);
+      expect(result.skip).toBe(5);
+      expect(result.projection).toEqual({ name: 1, age: 1 });
+    });
+    test("undefined options returns undefined for sort/limit/skip/projection", () => {
+      const group = FilterGroup2.create().eq("x", 1);
+      const result = compileMongoQuery(group, void 0, "id");
+      expect(result.sort).toBeUndefined();
+      expect(result.limit).toBeUndefined();
+      expect(result.skip).toBeUndefined();
+      expect(result.projection).toBeUndefined();
+    });
+  });
+  describe("compileMongoUpdate", () => {
+    test("plain values go into $set", () => {
+      const result = compileMongoUpdate({ name: "Alice", age: 30 });
+      expect(result).toEqual({ $set: { name: "Alice", age: 30 } });
+    });
+    test("IncOp goes into $inc", () => {
+      const result = compileMongoUpdate({ count: new IncOp("count", 5) });
+      expect(result).toEqual({ $inc: { count: 5 } });
+    });
+    test("MulOp goes into $mul", () => {
+      const result = compileMongoUpdate({ score: new MulOp("score", 2) });
+      expect(result).toEqual({ $mul: { score: 2 } });
+    });
+    test("MinOp/MaxOp go into $min/$max", () => {
+      const result = compileMongoUpdate({
+        lo: new MinOp("lo", 1),
+        hi: new MaxOp("hi", 99)
+      });
+      expect(result).toEqual({ $min: { lo: 1 }, $max: { hi: 99 } });
+    });
+    test("UnsetOp goes into $unset", () => {
+      const result = compileMongoUpdate({ old: new UnsetOp("old") });
+      expect(result).toEqual({ $unset: { old: "" } });
+    });
+    test("PushOp/PullOp go into $push/$pull", () => {
+      const result = compileMongoUpdate({
+        tags: new PushOp("tags", "new"),
+        removed: new PullOp("removed", "old")
+      });
+      expect(result).toEqual({ $push: { tags: "new" }, $pull: { removed: "old" } });
+    });
+    test("PatchOp produces dot-notation $set entries", () => {
+      const result = compileMongoUpdate({ meta: new PatchOp("meta", { a: 1, b: 2 }) });
+      expect(result).toEqual({ $set: { "meta.a": 1, "meta.b": 2 } });
+    });
+    test("empty data produces empty result", () => {
+      const result = compileMongoUpdate({});
+      expect(result).toEqual({});
+    });
+  });
+  describe("compileMongoOps", () => {
+    test("SetOp values go into $set", () => {
+      const result = compileMongoOps([new SetOp2({ name: "Bob", age: 25 })]);
+      expect(result).toEqual({ $set: { name: "Bob", age: 25 } });
+    });
+    test("mixed ops compile to separate Mongo update operators", () => {
+      const result = compileMongoOps([
+        new SetOp2({ name: "Alice" }),
+        new IncOp("count", 1),
+        new PushOp("tags", "x")
+      ]);
+      expect(result).toEqual({
+        $set: { name: "Alice" },
+        $inc: { count: 1 },
+        $push: { tags: "x" }
+      });
+    });
+    test("empty ops produces empty result", () => {
+      expect(compileMongoOps([])).toEqual({});
+    });
+  });
+  describe("compileMongoAggregate", () => {
+    test("bare count produces $group with $sum:1 and $project", () => {
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: []
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $group: { _id: null, total: { $sum: 1 } } },
+        { $project: { _id: 0, total: 1 } }
+      ]);
+    });
+    test("multi-aggregator produces all accumulators in $group", () => {
+      const spec = {
+        aggregates: [
+          { fn: "count", alias: "total" },
+          { fn: "sum", field: "amount", alias: "revenue" },
+          { fn: "avg", field: "price", alias: "avgPrice" }
+        ],
+        groupBy: []
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        {
+          $group: {
+            _id: null,
+            total: { $sum: 1 },
+            revenue: { $sum: "$amount" },
+            avgPrice: { $avg: "$price" }
+          }
+        },
+        { $project: { _id: 0, total: 1, revenue: 1, avgPrice: 1 } }
+      ]);
+    });
+    test("single-column groupBy produces composite _id and $project lift", () => {
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["region"]
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $group: { _id: { region: "$region" }, total: { $sum: 1 } } },
+        { $project: { _id: 0, region: "$_id.region", total: 1 } }
+      ]);
+    });
+    test("multi-column groupBy via composite _id", () => {
+      const spec = {
+        aggregates: [{ fn: "sum", field: "amount", alias: "revenue" }],
+        groupBy: ["region", "year"]
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        {
+          $group: {
+            _id: { region: "$region", year: "$year" },
+            revenue: { $sum: "$amount" }
+          }
+        },
+        {
+          $project: {
+            _id: 0,
+            region: "$_id.region",
+            year: "$_id.year",
+            revenue: 1
+          }
+        }
+      ]);
+    });
+    test("where-only emits $match before $group", () => {
+      const spec = {
+        where: FilterGroup2.create().eq("active", true),
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: []
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $match: { active: { $eq: true } } },
+        { $group: { _id: null, total: { $sum: 1 } } },
+        { $project: { _id: 0, total: 1 } }
+      ]);
+    });
+    test("having-only emits $match after $project", () => {
+      const spec = {
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["region"],
+        having: FilterGroup2.create().gt("total", 5)
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $group: { _id: { region: "$region" }, total: { $sum: 1 } } },
+        { $project: { _id: 0, region: "$_id.region", total: 1 } },
+        { $match: { total: { $gt: 5 } } }
+      ]);
+    });
+    test("where + having produces both $match stages", () => {
+      const spec = {
+        where: FilterGroup2.create().eq("active", true),
+        aggregates: [{ fn: "sum", field: "amount", alias: "revenue" }],
+        groupBy: ["region"],
+        having: FilterGroup2.create().gte("revenue", 1e3)
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $match: { active: { $eq: true } } },
+        {
+          $group: {
+            _id: { region: "$region" },
+            revenue: { $sum: "$amount" }
+          }
+        },
+        { $project: { _id: 0, region: "$_id.region", revenue: 1 } },
+        { $match: { revenue: { $gte: 1e3 } } }
+      ]);
+    });
+    test("countDistinct uses $addToSet in $group and $size in $project", () => {
+      const spec = {
+        aggregates: [{ fn: "countDistinct", field: "userId", alias: "uniqueUsers" }],
+        groupBy: []
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $group: { _id: null, uniqueUsers: { $addToSet: "$userId" } } },
+        { $project: { _id: 0, uniqueUsers: { $size: "$uniqueUsers" } } }
+      ]);
+    });
+    test("min/max produce $min/$max accumulators", () => {
+      const spec = {
+        aggregates: [
+          { fn: "min", field: "price", alias: "lowest" },
+          { fn: "max", field: "price", alias: "highest" }
+        ],
+        groupBy: []
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        {
+          $group: {
+            _id: null,
+            lowest: { $min: "$price" },
+            highest: { $max: "$price" }
+          }
+        },
+        { $project: { _id: 0, lowest: 1, highest: 1 } }
+      ]);
+    });
+    test("field-name mapping: id field maps to _id when primaryKey is _id", () => {
+      const spec = {
+        where: FilterGroup2.create().eq("id", "abc"),
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["id"]
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $match: { _id: { $eq: "abc" } } },
+        { $group: { _id: { id: "$_id" }, total: { $sum: 1 } } },
+        { $project: { _id: 0, id: "$_id.id", total: 1 } }
+      ]);
+    });
+    test("countDistinct with groupBy combines $addToSet, groupBy lift, and $size", () => {
+      const spec = {
+        aggregates: [{ fn: "countDistinct", field: "category", alias: "uniqueCats" }],
+        groupBy: ["region"]
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        {
+          $group: {
+            _id: { region: "$region" },
+            uniqueCats: { $addToSet: "$category" }
+          }
+        },
+        {
+          $project: {
+            _id: 0,
+            region: "$_id.region",
+            uniqueCats: { $size: "$uniqueCats" }
+          }
+        }
+      ]);
+    });
+    test("all six aggregators in a single pipeline", () => {
+      const spec = {
+        aggregates: [
+          { fn: "count", alias: "total" },
+          { fn: "countDistinct", field: "status", alias: "uniqueStatuses" },
+          { fn: "sum", field: "amount", alias: "totalAmount" },
+          { fn: "avg", field: "amount", alias: "avgAmount" },
+          { fn: "min", field: "amount", alias: "minAmount" },
+          { fn: "max", field: "amount", alias: "maxAmount" }
+        ],
+        groupBy: ["region"]
+      };
+      const pipeline = compileMongoAggregate(spec, "_id");
+      expect(pipeline).toEqual([
+        {
+          $group: {
+            _id: { region: "$region" },
+            total: { $sum: 1 },
+            uniqueStatuses: { $addToSet: "$status" },
+            totalAmount: { $sum: "$amount" },
+            avgAmount: { $avg: "$amount" },
+            minAmount: { $min: "$amount" },
+            maxAmount: { $max: "$amount" }
+          }
+        },
+        {
+          $project: {
+            _id: 0,
+            region: "$_id.region",
+            total: 1,
+            uniqueStatuses: { $size: "$uniqueStatuses" },
+            totalAmount: 1,
+            avgAmount: 1,
+            minAmount: 1,
+            maxAmount: 1
+          }
+        }
+      ]);
+    });
+    test("empty where filter is omitted from pipeline", () => {
+      const spec = {
+        where: FilterGroup2.create(),
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: []
+      };
+      expect(compileMongoAggregate(spec, "_id")).toEqual([
+        { $group: { _id: null, total: { $sum: 1 } } },
+        { $project: { _id: 0, total: 1 } }
+      ]);
+    });
+  });
+}
+
+// src/orm/orm-adapter.ts
+var OrmAdapter = class {
+  queryableOps = [];
+  updateOps = [];
+  aggregateOps = [];
+  supportedFieldTypes = [];
+  onFatalError(err) {
+    const wrapped = err instanceof EquippedError ? err : new EquippedError("OrmAdapter fatal error", {}, err);
+    Instance.crash(wrapped);
+  }
+  constructor() {
+    const self = this;
+    if (typeof self.connect === "function") {
+      Instance.on("start", () => self.connect(), { class: this.constructor });
+    }
+    if (typeof self.disconnect === "function") {
+      Instance.on("close", () => self.disconnect(), { class: this.constructor });
+    }
+  }
+  use(schema, config) {
+    const self = this;
+    const emptyIterator = async function* () {
+    };
+    const use = {
+      findMany: (filter, opts) => self.findMany?.(schema, config, filter, opts) ?? Promise.resolve([]),
+      iterateMany: (filter, opts) => self.iterateMany?.(schema, config, filter, opts) ?? emptyIterator(),
+      findOne: async (filter) => {
+        const rows = await use.findMany(filter, { limit: 1 });
+        return rows[0] ?? null;
+      },
+      count: (filter) => self.count?.(schema, config, filter) ?? Promise.reject(new Error("count not implemented")),
+      createOne: async (d) => {
+        const rows = await use.createMany([d]);
+        return rows[0];
+      },
+      createMany: (d) => self.createMany?.(schema, config, d) ?? Promise.resolve([]),
+      updateMany: (filter, d) => self.updateMany?.(schema, config, filter, d) ?? Promise.resolve([]),
+      updateOne: async (filter, d) => {
+        const match = await use.findOne(filter);
+        if (!match) return null;
+        const pk = schema.pkField.name;
+        const pkFilter = FilterGroup.create().eq(pk, match[pk]);
+        const rows = await use.updateMany(pkFilter, d);
+        return rows[0] ?? null;
+      },
+      upsertOne: (filter, create, ops) => self.upsertOne?.(schema, config, filter, create, ops) ?? Promise.reject(new Error("upsertOne not implemented")),
+      deleteOne: async (filter) => {
+        const row = await use.findOne(filter);
+        if (!row) return null;
+        const pk = schema.pkField.name;
+        if (self.deleteByPk) {
+          await self.deleteByPk(schema, config, row[pk]);
+        } else if (self.deleteMany) {
+          const pkFilter = FilterGroup.create().eq(pk, row[pk]);
+          await self.deleteMany(schema, config, pkFilter);
+        }
+        return row;
+      },
+      deleteMany: (filter) => self.deleteMany?.(schema, config, filter) ?? Promise.resolve([]),
+      raw: (...args) => self.raw?.(schema, config, ...args) ?? Promise.reject(new Error("raw not implemented")),
+      aggregate: (spec) => self.aggregate?.(schema, config, spec) ?? Promise.reject(new Error("aggregate not implemented")),
+      aggregateOps: self.aggregateOps ?? []
+    };
+    return use;
+  }
+};
+if (void 0) {
+  const { describe, test, expect, vi } = void 0;
+  const { v: v6 } = null;
+  describe("OrmAdapter", () => {
+    test("subclass with connect/disconnect auto-registers Instance hooks", async () => {
+      const { Instance: Inst } = await null;
+      const onSpy = vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class TestAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        supportedFieldTypes = ["string"];
+        async connect() {
+        }
+        async disconnect() {
+        }
+      }
+      new TestAdapter();
+      expect(onSpy).toHaveBeenCalledWith("start", expect.any(Function), expect.objectContaining({ class: TestAdapter }));
+      expect(onSpy).toHaveBeenCalledWith("close", expect.any(Function), expect.objectContaining({ class: TestAdapter }));
+      onSpy.mockRestore();
+    });
+    test("subclass without connect/disconnect does not register hooks", async () => {
+      const { Instance: Inst } = await null;
+      const onSpy = vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class MinimalAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+      }
+      new MinimalAdapter();
+      expect(onSpy).not.toHaveBeenCalled();
+      onSpy.mockRestore();
+    });
+    test("capability declarations default to empty arrays", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class DefaultAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+      }
+      const adapter = new DefaultAdapter();
+      expect(adapter.queryableOps).toEqual([]);
+      expect(adapter.updateOps).toEqual([]);
+      expect(adapter.aggregateOps).toEqual([]);
+      expect(adapter.supportedFieldTypes).toEqual([]);
+      vi.restoreAllMocks();
+    });
+    test("onFatalError wraps non-EquippedError and calls Instance.crash", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      const crashSpy = vi.spyOn(Inst, "crash").mockImplementation((() => {
+        throw new Error("crash");
+      }));
+      class FatalAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        triggerFatal() {
+          this.onFatalError(new Error("something broke"));
+        }
+      }
+      const adapter = new FatalAdapter();
+      expect(() => adapter.triggerFatal()).toThrow("crash");
+      expect(crashSpy).toHaveBeenCalled();
+      vi.restoreAllMocks();
+    });
+    test("onFatalError passes through EquippedError directly", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let crashedWith;
+      vi.spyOn(Inst, "crash").mockImplementation(((err) => {
+        crashedWith = err;
+        throw err;
+      }));
+      class FatalAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        triggerFatal() {
+          this.onFatalError(new EquippedError("equipped error", { detail: "test" }));
+        }
+      }
+      const adapter = new FatalAdapter();
+      expect(() => adapter.triggerFatal()).toThrow();
+      expect(crashedWith).toBeInstanceOf(EquippedError);
+      expect(crashedWith.message).toBe("equipped error");
+      vi.restoreAllMocks();
+    });
+    test("use() creates OrmUse bridge that delegates to flat methods", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class BridgeAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        supportedFieldTypes = ["string"];
+        queryableOps = ["eq"];
+        async findMany(_s, _c, _f, _o) {
+          return [{ id: "found" }];
+        }
+        async count(_s, _c, _f) {
+          return 1;
+        }
+        async *iterateMany(_s, _c, _f, _o) {
+          yield { id: "iterated" };
+        }
+        async createMany(_s, _c, data) {
+          return data;
+        }
+      }
+      const TestSchema = Schema.from("bridge_test").pk("id", v6.string(), () => "x").build();
+      const adapter = new BridgeAdapter();
+      const ormUse = adapter.use(TestSchema, { table: "bridge_test" });
+      const rows = await ormUse.findMany(FilterGroup.create());
+      expect(rows).toEqual([{ id: "found" }]);
+      await expect(ormUse.count(FilterGroup.create())).resolves.toBe(1);
+      const iterated = [];
+      for await (const row of ormUse.iterateMany(FilterGroup.create())) iterated.push(row);
+      expect(iterated).toEqual([{ id: "iterated" }]);
+      const created = await ormUse.createOne({ id: "new" });
+      expect(created).toEqual({ id: "new" });
+      vi.restoreAllMocks();
+    });
+    test("use() bridge delegates updateMany to flat method", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class UpdateAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        supportedFieldTypes = ["string", "number"];
+        updateOps = ["set"];
+        async findMany(_s, _c, _f) {
+          return [{ id: "u1", name: "old" }];
+        }
+        async updateMany(_s, _c, _f, data) {
+          return [{ id: "u1", ...data }];
+        }
+      }
+      const TestSchema = Schema.from("upd_test").pk("id", v6.string(), () => "x").field("name", v6.string()).build();
+      const adapter = new UpdateAdapter();
+      const ormUse = adapter.use(TestSchema, { table: "upd_test" });
+      const updated = await ormUse.updateOne(FilterGroup.create().eq("id", "u1"), { name: "new" });
+      expect(updated).not.toBeNull();
+      expect(updated.name).toBe("new");
+      vi.restoreAllMocks();
+    });
+    test("use().iterateMany does not fall back to findMany when adapter omits iterateMany", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let findManyCalls = 0;
+      class FindOnlyAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        supportedFieldTypes = ["string"];
+        async findMany() {
+          findManyCalls += 1;
+          return [{ id: "found" }];
+        }
+      }
+      const TestSchema = Schema.from("iter_no_fallback").pk("id", v6.string(), () => "x").build();
+      const adapter = new FindOnlyAdapter();
+      const rows = [];
+      for await (const row of adapter.use(TestSchema, { table: "iter_no_fallback" }).iterateMany(FilterGroup.create())) rows.push(row);
+      expect(rows).toEqual([]);
+      expect(findManyCalls).toBe(0);
+      vi.restoreAllMocks();
+    });
+    test("use() bridge delegates deleteByPk via deleteOne", async () => {
+      const { Instance: Inst } = await null;
+      const { Schema } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let deletedPk = null;
+      class DeleteAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        supportedFieldTypes = ["string"];
+        async findMany(_s, _c, _f) {
+          return [{ id: "d1" }];
+        }
+        async deleteByPk(_s, _c, pk) {
+          deletedPk = pk;
+          return { id: String(pk) };
+        }
+      }
+      const TestSchema = Schema.from("del_test").pk("id", v6.string(), () => "x").build();
+      const adapter = new DeleteAdapter();
+      const ormUse = adapter.use(TestSchema, { table: "del_test" });
+      const deleted = await ormUse.deleteOne(FilterGroup.create().eq("id", "d1"));
+      expect(deleted).toEqual({ id: "d1" });
+      expect(deletedPk).toBe("d1");
+      vi.restoreAllMocks();
+    });
+    test("use() bridge delegates session to flat method", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      let sessionRan = false;
+      class SessionAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        async session(fn) {
+          sessionRan = true;
+          return fn();
+        }
+      }
+      const adapter = new SessionAdapter();
+      const result = await adapter.session(async () => 42);
+      expect(result).toBe(42);
+      expect(sessionRan).toBe(true);
+      vi.restoreAllMocks();
+    });
+    test("type-level: subclass method override enforces canonical signature", async () => {
+      const { Instance: Inst } = await null;
+      vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      class CorrectAdapter extends OrmAdapter {
+        schemaConfigPipe = v6.object({ table: v6.string() });
+        async findByPk(_s, _c, _pk) {
+          return null;
+        }
+        async createMany(_s, _c, _d) {
+          return [];
+        }
+        async raw(_s, _c, ..._args) {
+          return null;
+        }
+      }
+      const adapter = new CorrectAdapter();
+      expect(adapter.findByPk).toBeTypeOf("function");
+      expect(adapter.createMany).toBeTypeOf("function");
+      expect(adapter.raw).toBeTypeOf("function");
+      vi.restoreAllMocks();
+    });
+  });
+}
+
+// src/orm/adapters/mongodb/index.ts
+var mongoSchemaConfigPipe = () => import_valleyed5.v.object({ db: import_valleyed5.v.string(), col: import_valleyed5.v.string() });
+var mongoConnectionPipe = () => import_valleyed5.v.object({
+  uri: import_valleyed5.v.string()
+});
+var MIGRATION_TRACKER_COLLECTION = "equipped_migrations";
+var MongoDbAdapter = class extends configurable(mongoConnectionPipe, OrmAdapter) {
+  schemaConfigPipe = mongoSchemaConfigPipe();
+  queryableOps = ["eq", "ne", "gt", "gte", "lt", "lte", "in", "notIn", "like", "exists", "notExists", "contains", "notContains"];
+  updateOps = ["set", "inc", "mul", "min", "max", "unset", "push", "pull", "patch"];
+  aggregateOps = ["count", "countDistinct", "sum", "avg", "min", "max"];
+  supportedFieldTypes = ["string", "number", "boolean", "null", "object", "array", "date"];
+  client;
+  #sessionStore = new import_node_async_hooks.AsyncLocalStorage();
+  constructor(config, options) {
+    super(config);
+    this.client = new import_mongodb.MongoClient(config.uri, {
+      ...options,
+      ignoreUndefined: true
+    });
+  }
+  #getCollection(schemaCfg) {
+    return this.client.db(schemaCfg.db).collection(schemaCfg.col);
+  }
+  async connect() {
+    try {
+      await this.client.connect();
+    } catch (error) {
+      throw new EquippedError("Failed to connect MongoDB client", { adapter: "mongodb" }, error);
+    }
+  }
+  async disconnect() {
+    try {
+      await this.client.close();
+    } catch (error) {
+      throw new EquippedError("Failed to disconnect MongoDB client", { adapter: "mongodb" }, error);
+    }
+  }
+  async findByPk(schema, config, pk) {
+    const schemaCfg = config;
+    try {
+      const pkName = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      const doc = await collection.findOne(
+        { [pkName]: pk },
+        { session: this.#sessionStore.getStore() }
+      );
+      return doc;
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB findByPk failed",
+        { adapter: "mongodb", operation: "findByPk", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async createMany(_schema, config, data) {
+    const schemaCfg = config;
+    try {
+      const collection = this.#getCollection(schemaCfg);
+      const docs = data.map((d) => d);
+      await collection.insertMany(docs, { session: this.#sessionStore.getStore() });
+      return data;
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB createMany failed",
+        { adapter: "mongodb", operation: "createMany", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async updateByPk(schema, config, pk, ops) {
+    const schemaCfg = config;
+    try {
+      const pkName = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      const update = compileMongoOps(ops);
+      if (Object.keys(update).length === 0) {
+        return await collection.findOne({ [pkName]: pk }, { session: this.#sessionStore.getStore() });
+      }
+      return await collection.findOneAndUpdate(
+        { [pkName]: pk },
+        update,
+        { returnDocument: "after", session: this.#sessionStore.getStore() }
+      );
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB updateByPk failed",
+        { adapter: "mongodb", operation: "updateByPk", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async deleteByPk(schema, config, pk) {
+    const schemaCfg = config;
+    try {
+      const pkName = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      return await collection.findOneAndDelete(
+        { [pkName]: pk },
+        { session: this.#sessionStore.getStore() }
+      );
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB deleteByPk failed",
+        { adapter: "mongodb", operation: "deleteByPk", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async raw(_schema, config, pipeline) {
+    const schemaCfg = config;
+    try {
+      const collection = this.#getCollection(schemaCfg);
+      const result = await collection.aggregate(pipeline, { session: this.#sessionStore.getStore() }).toArray();
+      return result;
+    } catch (error) {
+      if (error instanceof EquippedError) throw error;
+      throw new EquippedError(
+        "MongoDB raw failed",
+        { adapter: "mongodb", operation: "raw", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async aggregate(schema, config, spec) {
+    const schemaCfg = config;
+    try {
+      const pk = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      const pipeline = compileMongoAggregate(spec, pk);
+      const result = await collection.aggregate(pipeline, { session: this.#sessionStore.getStore() }).toArray();
+      return result;
+    } catch (error) {
+      if (error instanceof EquippedError) throw error;
+      throw new EquippedError(
+        "MongoDB aggregate failed",
+        { adapter: "mongodb", operation: "aggregate", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async findMany(schema, config, filter, options) {
+    const schemaCfg = config;
+    try {
+      const pk = schema.pkField.name;
+      const { filter: mongoFilter, sort, limit, skip, projection } = compileMongoQuery(filter, options, pk);
+      const collection = this.#getCollection(schemaCfg);
+      let cursor = collection.find(mongoFilter, {
+        session: this.#sessionStore.getStore(),
+        projection
+      });
+      if (sort) cursor = cursor.sort(sort);
+      if (limit) cursor = cursor.limit(limit);
+      if (skip) cursor = cursor.skip(skip);
+      return await cursor.toArray();
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB findMany failed",
+        { adapter: "mongodb", operation: "findMany", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async count(schema, config, filter) {
+    const schemaCfg = config;
+    try {
+      const pk = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      return await collection.countDocuments(compileMongoFilter(filter, pk), { session: this.#sessionStore.getStore() });
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB count failed",
+        { adapter: "mongodb", operation: "count", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async *iterateMany(schema, config, filter, options) {
+    const schemaCfg = config;
+    let cursor;
+    try {
+      const pk = schema.pkField.name;
+      const { filter: mongoFilter, sort, limit, skip, projection } = compileMongoQuery(filter, options, pk);
+      const collection = this.#getCollection(schemaCfg);
+      cursor = collection.find(mongoFilter, {
+        session: this.#sessionStore.getStore(),
+        projection
+      });
+      if (sort) cursor = cursor.sort(sort);
+      if (limit) cursor = cursor.limit(limit);
+      if (skip) cursor = cursor.skip(skip);
+      if (options?.batchSize !== void 0) cursor = cursor.batchSize(options.batchSize);
+      for await (const row of cursor) {
+        yield row;
+      }
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB iterateMany failed",
+        { adapter: "mongodb", operation: "iterateMany", collection: schemaCfg.col },
+        error
+      );
+    } finally {
+      await cursor?.close();
+    }
+  }
+  async updateMany(schema, config, filter, data) {
+    const schemaCfg = config;
+    try {
+      const pk = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      const session = this.#sessionStore.getStore();
+      const mongoFilter = compileMongoFilter(filter, pk);
+      const matchingDocs = await collection.find(mongoFilter, { session, projection: { [pk]: 1 } }).toArray();
+      const ids = matchingDocs.map((d) => d[pk]);
+      const idFilter = { [pk]: { $in: ids } };
+      const update = compileMongoUpdate(data);
+      if (Object.keys(update).length > 0) {
+        await collection.updateMany(idFilter, update, { session });
+      }
+      return await collection.find({ [pk]: { $in: ids } }, { session }).toArray();
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB updateMany failed",
+        { adapter: "mongodb", operation: "updateMany", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async deleteMany(schema, config, filter) {
+    const schemaCfg = config;
+    try {
+      const pk = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      const session = this.#sessionStore.getStore();
+      const mongoFilter = compileMongoFilter(filter, pk);
+      const docs = await collection.find(mongoFilter, { session }).toArray();
+      if (docs.length > 0) {
+        await collection.deleteMany(mongoFilter, { session });
+      }
+      return docs;
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB deleteMany failed",
+        { adapter: "mongodb", operation: "deleteMany", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async upsertOne(schema, config, filter, create, ops) {
+    const schemaCfg = config;
+    try {
+      const pk = schema.pkField.name;
+      const collection = this.#getCollection(schemaCfg);
+      const mongoFilter = compileMongoFilter(filter, pk);
+      const updateDoc = compileMongoOps(ops);
+      const doc = await collection.findOneAndUpdate(
+        mongoFilter,
+        {
+          ...updateDoc,
+          $setOnInsert: create
+        },
+        {
+          returnDocument: "after",
+          session: this.#sessionStore.getStore(),
+          upsert: true
+        }
+      );
+      return doc;
+    } catch (error) {
+      throw new EquippedError(
+        "MongoDB upsertOne failed",
+        { adapter: "mongodb", operation: "upsertOne", collection: schemaCfg.col },
+        error
+      );
+    }
+  }
+  async session(fn) {
+    if (this.#sessionStore.getStore()) return fn();
+    try {
+      const session = await this.client.startSession();
+      try {
+        return await session.withTransaction(async () => this.#sessionStore.run(session, fn));
+      } finally {
+        await session.endSession();
+      }
+    } catch (error) {
+      if (error instanceof EquippedError) throw error;
+      throw new EquippedError("MongoDB session failed", { adapter: "mongodb", operation: "session" }, error);
+    }
+  }
+  async loadMigrations() {
+    const db = this.client.db();
+    const docs = await db.collection(MIGRATION_TRACKER_COLLECTION).find({}).toArray();
+    return docs.map((d) => ({ id: String(d._id), appliedAt: d.appliedAt }));
+  }
+  async recordMigration(id, appliedAt) {
+    const db = this.client.db();
+    await db.collection(MIGRATION_TRACKER_COLLECTION).insertOne({ _id: id, appliedAt });
+  }
+  async applyAddIndex(change) {
+    const db = this.client.db();
+    const fields = {};
+    for (const f of change.on) {
+      fields[f] = 1;
+    }
+    const name = change.name ?? `${change.table}_${change.on.join("_")}_idx`;
+    await db.collection(change.table).createIndex(fields, { unique: change.unique ?? false, name });
+  }
+  async applyDropIndex(change) {
+    const db = this.client.db();
+    const collections = await db.listCollections().toArray();
+    for (const col of collections) {
+      const indexes = await db.collection(col.name).listIndexes().toArray();
+      if (indexes.some((idx) => idx.name === change.name)) {
+        await db.collection(col.name).dropIndex(change.name);
+        return;
+      }
+    }
+  }
+  async introspect() {
+    const db = this.client.db();
+    const collections = await db.listCollections().toArray();
+    const schemas = [];
+    for (const col of collections) {
+      if (col.name === MIGRATION_TRACKER_COLLECTION) continue;
+      const rawIndexes = await db.collection(col.name).listIndexes().toArray();
+      const indexes = rawIndexes.filter((idx) => idx.name !== "_id_").map((idx) => ({
+        name: idx.name,
+        on: Object.keys(idx.key),
+        unique: !!idx.unique
+      }));
+      schemas.push({
+        name: col.name,
+        pk: void 0,
+        fields: [],
+        indexes,
+        foreignKeys: []
+      });
+    }
+    return schemas;
+  }
+};
+if (void 0) {
+  const { describe, test, expect, expectTypeOf } = void 0;
+  describe("MongoDbAdapter: class-via-configurable shape", () => {
+    test("MongoDbAdapter.create validates connection config via pipe", () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expect(adapter).toBeInstanceOf(MongoDbAdapter);
+      expect(adapter.client).toBeInstanceOf(import_mongodb.MongoClient);
+    });
+    test("MongoDbAdapter.create rejects invalid config", () => {
+      expect(() => MongoDbAdapter.create({})).toThrow();
+      expect(() => MongoDbAdapter.create({ uri: 123 })).toThrow();
+    });
+    test("readonly schemaConfigPipe declared with { db, col } shape", () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expect(adapter.schemaConfigPipe).toBeDefined();
+    });
+    test("capability declarations use as const", () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expect(adapter.supportedFieldTypes).toEqual([
+        "string",
+        "number",
+        "boolean",
+        "null",
+        "object",
+        "array",
+        "date"
+      ]);
+      expect(adapter.queryableOps).toEqual([
+        "eq",
+        "ne",
+        "gt",
+        "gte",
+        "lt",
+        "lte",
+        "in",
+        "notIn",
+        "like",
+        "exists",
+        "notExists",
+        "contains",
+        "notContains"
+      ]);
+      expect(adapter.updateOps).toEqual([
+        "set",
+        "inc",
+        "mul",
+        "min",
+        "max",
+        "unset",
+        "push",
+        "pull",
+        "patch"
+      ]);
+      expect(adapter.aggregateOps).toEqual([
+        "count",
+        "countDistinct",
+        "sum",
+        "avg",
+        "min",
+        "max"
+      ]);
+    });
+    test("underlying MongoClient exposed as readonly instance field", () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expect(adapter.client).toBeInstanceOf(import_mongodb.MongoClient);
+    });
+    test("adapter.use returns OrmUse-shaped object", async () => {
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const schema = Schema.from("test").pk("id", v6.string(), () => "x").build();
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      const use = adapter.use(schema, { db: "testdb", col: "testcol" });
+      expect(use.findMany).toBeTypeOf("function");
+      expect(use.iterateMany).toBeTypeOf("function");
+      expect(use.findOne).toBeTypeOf("function");
+      expect(use.count).toBeTypeOf("function");
+      expect(use.createOne).toBeTypeOf("function");
+      expect(use.createMany).toBeTypeOf("function");
+      expect(use.updateMany).toBeTypeOf("function");
+      expect(use.updateOne).toBeTypeOf("function");
+      expect(use.upsertOne).toBeTypeOf("function");
+      expect(use.deleteOne).toBeTypeOf("function");
+      expect(use.deleteMany).toBeTypeOf("function");
+      expect(use.raw).toBeTypeOf("function");
+    });
+    test("type-level: adapter declares all 9 canonical update ops", () => {
+      const _adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("type-level: adapter declares all 7 field types", () => {
+      const _adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("type-level: adapter declares all 13 queryable ops", () => {
+      const _adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("type-level: Repo.from with MongoDbAdapter enables all builder methods", async () => {
+      const { Repo } = await null;
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      const _TestSchema = Schema.from("test").pk("id", v6.string(), () => "x").build();
+      const _one = repo.on(_TestSchema).one();
+      const _all = repo.on(_TestSchema).all();
+      const _ref = repo.on(_TestSchema);
+      expectTypeOf(_one.create).toBeFunction();
+      expectTypeOf(_one.find).toBeFunction();
+      expectTypeOf(_one.update).toBeFunction();
+      expectTypeOf(_one.delete).toBeFunction();
+      expectTypeOf(_one.upsert).toBeFunction();
+      expectTypeOf(_all.create).toBeFunction();
+      expectTypeOf(_all.find).toBeFunction();
+      expectTypeOf(_all.count).toBeFunction();
+      expectTypeOf(_all.update).toBeFunction();
+      expectTypeOf(_all.delete).toBeFunction();
+      expectTypeOf(_ref.raw).toBeFunction();
+      expectTypeOf(repo.session).toBeFunction();
+    });
+    test("type-level: raw arg-tuple infers (pipeline: Record<string, unknown>[]) from MongoDbAdapter", async () => {
+      const { Repo } = await null;
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      const _TestSchema = Schema.from("test").pk("id", v6.string(), () => "x").build();
+      const _ref = repo.on(_TestSchema);
+      expectTypeOf(_ref.raw).parameters.toEqualTypeOf();
+    });
+    test("type-level: per-call <T> override narrows MongoDbAdapter raw return type", async () => {
+      const { Repo } = await null;
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      const _TestSchema = Schema.from("test").pk("id", v6.string(), () => "x").build();
+      const _ref = repo.on(_TestSchema);
+      expectTypeOf(_ref.raw).returns.toEqualTypeOf();
+    });
+    test("count forwards compiled filter to collection.countDocuments", async () => {
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const { FilterGroup: FilterGroup2 } = await null;
+      const schema = Schema.from("mongo_count").pk("_id", v6.string(), () => "x").field("name", v6.string()).build();
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      let capturedFilter;
+      adapter.client.db = () => ({
+        collection: () => ({
+          countDocuments: async (filter, _opts) => {
+            capturedFilter = filter;
+            return 7;
+          }
+        })
+      });
+      const result = await adapter.count(schema, { db: "testdb", col: "things" }, FilterGroup2.create().eq("name", "Alice"));
+      expect(capturedFilter).toEqual({ name: { $eq: "Alice" } });
+      expect(result).toBe(7);
+    });
+    test("raw forwards pipeline to collection.aggregate at runtime", async () => {
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const schema = Schema.from("mongo_raw").pk("id", v6.string(), () => "x").build();
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      let capturedPipeline;
+      const mockResults = [{ total: 42 }];
+      adapter.client.db = () => ({
+        collection: () => ({
+          aggregate: (pipeline, _opts) => {
+            capturedPipeline = pipeline;
+            return { toArray: async () => mockResults };
+          }
+        })
+      });
+      const result = await adapter.use(schema, { db: "testdb", col: "things" }).raw([{ $count: "total" }]);
+      expect(capturedPipeline).toEqual([{ $count: "total" }]);
+      expect(result).toEqual(mockResults);
+    });
+    test("iterateMany forwards batchSize and closes cursor on early return", async () => {
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const { FilterGroup: FilterGroup2 } = await null;
+      const { OrderBy } = await null;
+      const schema = Schema.from("mongo_iter").pk("_id", v6.string(), () => "x").field("age", v6.number()).build();
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      let capturedFindFilter;
+      let capturedFindOptions;
+      let capturedSort;
+      let capturedLimit;
+      let capturedSkip;
+      let capturedBatchSize;
+      let closeCalls = 0;
+      const cursor = {
+        sort(sort) {
+          capturedSort = sort;
+          return this;
+        },
+        limit(limit) {
+          capturedLimit = limit;
+          return this;
+        },
+        skip(skip) {
+          capturedSkip = skip;
+          return this;
+        },
+        batchSize(batchSize) {
+          capturedBatchSize = batchSize;
+          return this;
+        },
+        async close() {
+          closeCalls += 1;
+        },
+        async *[Symbol.asyncIterator]() {
+          yield { _id: "u4", age: 50 };
+          yield { _id: "u3", age: 40 };
+        }
+      };
+      adapter.client.db = () => ({
+        collection: () => ({
+          find: (filter, options) => {
+            capturedFindFilter = filter;
+            capturedFindOptions = options;
+            return cursor;
+          }
+        })
+      });
+      const rows = [];
+      for await (const row of adapter.use(schema, { db: "testdb", col: "people" }).iterateMany(FilterGroup2.create().gt("age", 19), {
+        orderBy: [new OrderBy("age", "desc")],
+        offset: 1,
+        limit: 2,
+        batchSize: 25
+      })) {
+        rows.push(row);
+        break;
+      }
+      expect(capturedFindFilter).toEqual({ age: { $gt: 19 } });
+      expect(capturedFindOptions).toEqual({ session: void 0, projection: void 0 });
+      expect(capturedSort).toEqual({ age: -1 });
+      expect(capturedLimit).toBe(2);
+      expect(capturedSkip).toBe(1);
+      expect(capturedBatchSize).toBe(25);
+      expect(rows).toEqual([{ _id: "u4", age: 50 }]);
+      expect(closeCalls).toBe(1);
+    });
+    test("iterateMany closes cursor on normal completion", async () => {
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const { FilterGroup: FilterGroup2 } = await null;
+      const schema = Schema.from("mongo_iter_complete").pk("_id", v6.string(), () => "x").field("age", v6.number()).build();
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      let closeCalls = 0;
+      const cursor = {
+        async close() {
+          closeCalls += 1;
+        },
+        async *[Symbol.asyncIterator]() {
+          yield { _id: "u1", age: 30 };
+          yield { _id: "u2", age: 40 };
+        }
+      };
+      adapter.client.db = () => ({
+        collection: () => ({
+          find: () => cursor
+        })
+      });
+      const rows = [];
+      for await (const row of adapter.use(schema, { db: "testdb", col: "people" }).iterateMany(FilterGroup2.create())) {
+        rows.push(row);
+      }
+      expect(rows).toEqual([{ _id: "u1", age: 30 }, { _id: "u2", age: 40 }]);
+      expect(closeCalls).toBe(1);
+    });
+    test("nested session returns callback without starting new transaction", () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expect(adapter.session).toBeTypeOf("function");
+    });
+    test("type-level: adapter declares all 6 canonical aggregate ops", () => {
+      const _adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expectTypeOf().toEqualTypeOf();
+    });
+    test("type-level: Repo.from with MongoDbAdapter enables aggregate method", async () => {
+      const { Repo } = await null;
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      const _TestSchema = Schema.from("test").pk("id", v6.string(), () => "x").build();
+      const _ref = repo.on(_TestSchema);
+      expectTypeOf(_ref.aggregate).toBeFunction();
+    });
+    test("aggregate forwards compiled pipeline to collection.aggregate", async () => {
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const schema = Schema.from("mongo_agg").pk("_id", v6.string(), () => "x").field("amount", v6.number()).build();
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      let capturedPipeline;
+      const mockResults = [{ total: 3, revenue: 150 }];
+      adapter.client.db = () => ({
+        collection: () => ({
+          aggregate: (pipeline, _opts) => {
+            capturedPipeline = pipeline;
+            return { toArray: async () => mockResults };
+          }
+        })
+      });
+      const result = await adapter.aggregate(schema, { db: "testdb", col: "orders" }, {
+        aggregates: [
+          { fn: "count", alias: "total" },
+          { fn: "sum", field: "amount", alias: "revenue" }
+        ],
+        groupBy: []
+      });
+      expect(capturedPipeline).toEqual([
+        { $group: { _id: null, total: { $sum: 1 }, revenue: { $sum: "$amount" } } },
+        { $project: { _id: 0, total: 1, revenue: 1 } }
+      ]);
+      expect(result).toEqual(mockResults);
+    });
+    test("aggregate with where and groupBy produces correct pipeline", async () => {
+      const { Schema } = await null;
+      const { v: v6 } = await null;
+      const { FilterGroup: FilterGroup2 } = await null;
+      const schema = Schema.from("mongo_agg2").pk("_id", v6.string(), () => "x").field("region", v6.string()).field("amount", v6.number()).build();
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      let capturedPipeline;
+      adapter.client.db = () => ({
+        collection: () => ({
+          aggregate: (pipeline, _opts) => {
+            capturedPipeline = pipeline;
+            return { toArray: async () => [{ region: "US", total: 2 }] };
+          }
+        })
+      });
+      await adapter.aggregate(schema, { db: "testdb", col: "orders" }, {
+        where: FilterGroup2.create().gt("amount", 10),
+        aggregates: [{ fn: "count", alias: "total" }],
+        groupBy: ["region"]
+      });
+      expect(capturedPipeline).toEqual([
+        { $match: { amount: { $gt: 10 } } },
+        { $group: { _id: { region: "$region" }, total: { $sum: 1 } } },
+        { $project: { _id: 0, region: "$_id.region", total: 1 } }
+      ]);
+    });
+    test("auto-wires Instance hooks for connect/disconnect", async () => {
+      const { Instance: Inst } = await null;
+      const { vi } = await null;
+      const onSpy = vi.spyOn(Inst, "on").mockImplementation(() => {
+      });
+      MongoDbAdapter.create({ uri: "mongodb://localhost:27017" });
+      expect(onSpy).toHaveBeenCalledWith("start", expect.any(Function), expect.objectContaining({ class: MongoDbAdapter }));
+      expect(onSpy).toHaveBeenCalledWith("close", expect.any(Function), expect.objectContaining({ class: MongoDbAdapter }));
+      onSpy.mockRestore();
+    });
+  });
+  describe("MongoDbAdapter: migrations", () => {
+    function mockMongoDb(adapter) {
+      const state = {
+        migrations: /* @__PURE__ */ new Map(),
+        collections: /* @__PURE__ */ new Map()
+      };
+      const getCol = (name) => {
+        if (!state.collections.has(name)) {
+          state.collections.set(name, { indexes: [] });
+        }
+        return state.collections.get(name);
+      };
+      adapter.client.db = () => ({
+        collection: (name) => {
+          if (name === MIGRATION_TRACKER_COLLECTION) {
+            return {
+              find: () => ({ toArray: async () => [...state.migrations.values()] }),
+              insertOne: async (doc) => {
+                state.migrations.set(doc._id, doc);
+              }
+            };
+          }
+          const col = getCol(name);
+          return {
+            createIndex: async (fields, opts) => {
+              col.indexes.push({ name: opts.name, key: fields, unique: opts.unique });
+            },
+            dropIndex: async (indexName) => {
+              col.indexes = col.indexes.filter((i) => i.name !== indexName);
+            },
+            listIndexes: () => ({
+              toArray: async () => [
+                { name: "_id_", key: { _id: 1 } },
+                ...col.indexes
+              ]
+            })
+          };
+        },
+        listCollections: () => ({
+          toArray: async () => [...state.collections.keys()].map((name) => ({ name }))
+        })
+      });
+      return state;
+    }
+    test("loadMigrations reads from equipped_migrations collection", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      state.migrations.set("0001", { _id: "0001", appliedAt: 1e3 });
+      state.migrations.set("0002", { _id: "0002", appliedAt: 2e3 });
+      const result = await adapter.loadMigrations();
+      expect(result).toEqual([
+        { id: "0001", appliedAt: 1e3 },
+        { id: "0002", appliedAt: 2e3 }
+      ]);
+    });
+    test("loadMigrations returns empty array when no migrations exist", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      mockMongoDb(adapter);
+      const result = await adapter.loadMigrations();
+      expect(result).toEqual([]);
+    });
+    test("recordMigration inserts into equipped_migrations with _id", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      await adapter.recordMigration("0001", 1234);
+      expect(state.migrations.has("0001")).toBe(true);
+      expect(state.migrations.get("0001")).toEqual({ _id: "0001", appliedAt: 1234 });
+    });
+    test("applyAddIndex creates index with specified name and fields", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      await adapter.applyAddIndex({ kind: "addIndex", table: "users", on: ["email"], unique: true, name: "users_email_unique" });
+      const col = state.collections.get("users");
+      expect(col.indexes).toHaveLength(1);
+      expect(col.indexes[0]).toEqual({ name: "users_email_unique", key: { email: 1 }, unique: true });
+    });
+    test("applyAddIndex auto-derives name when absent", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      await adapter.applyAddIndex({ kind: "addIndex", table: "users", on: ["email"] });
+      const col = state.collections.get("users");
+      expect(col.indexes[0].name).toBe("users_email_idx");
+    });
+    test("applyAddIndex auto-derived compound index name", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      await adapter.applyAddIndex({ kind: "addIndex", table: "orders", on: ["userId", "createdAt"] });
+      const col = state.collections.get("orders");
+      expect(col.indexes[0].name).toBe("orders_userId_createdAt_idx");
+      expect(col.indexes[0].key).toEqual({ userId: 1, createdAt: 1 });
+    });
+    test("applyDropIndex finds and drops index by scanning collections", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      state.collections.set("users", { indexes: [{ name: "users_email_idx", key: { email: 1 }, unique: true }] });
+      await adapter.applyDropIndex({ kind: "dropIndex", name: "users_email_idx" });
+      expect(state.collections.get("users").indexes).toHaveLength(0);
+    });
+    test("applyDropIndex is a no-op when index not found", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      mockMongoDb(adapter);
+      await adapter.applyDropIndex({ kind: "dropIndex", name: "nonexistent_idx" });
+    });
+    test("introspect returns DiscoveredSchema with empty fields, pk, and foreignKeys", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      state.collections.set("users", { indexes: [] });
+      state.collections.set("posts", { indexes: [] });
+      const schemas = await adapter.introspect();
+      expect(schemas).toHaveLength(2);
+      for (const s of schemas) {
+        expect(s.pk).toBeUndefined();
+        expect(s.fields).toEqual([]);
+        expect(s.foreignKeys).toEqual([]);
+      }
+    });
+    test("introspect skips _id_ index", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      state.collections.set("users", { indexes: [{ name: "users_email_idx", key: { email: 1 }, unique: false }] });
+      const schemas = await adapter.introspect();
+      expect(schemas).toHaveLength(1);
+      expect(schemas[0].indexes).toHaveLength(1);
+      expect(schemas[0].indexes[0].name).toBe("users_email_idx");
+    });
+    test("introspect skips tracker collection", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      state.collections.set("users", { indexes: [] });
+      state.collections.set(MIGRATION_TRACKER_COLLECTION, { indexes: [] });
+      const schemas = await adapter.introspect();
+      expect(schemas).toHaveLength(1);
+      expect(schemas[0].name).toBe("users");
+    });
+    test("introspect maps index keys to on array and unique flag", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      state.collections.set("orders", {
+        indexes: [
+          { name: "orders_userId_createdAt_idx", key: { userId: 1, createdAt: 1 }, unique: false },
+          { name: "orders_email_unique", key: { email: 1 }, unique: true }
+        ]
+      });
+      const schemas = await adapter.introspect();
+      expect(schemas[0].indexes).toEqual([
+        { name: "orders_userId_createdAt_idx", on: ["userId", "createdAt"], unique: false },
+        { name: "orders_email_unique", on: ["email"], unique: true }
+      ]);
+    });
+    test("adapter does not implement acquireMigrationLock", () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      expect(adapter.acquireMigrationLock).toBeUndefined();
+    });
+    test("adapter does not implement DDL apply methods", () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      expect(adapter.applyCreateTable).toBeUndefined();
+      expect(adapter.applyDropTable).toBeUndefined();
+      expect(adapter.applyAddField).toBeUndefined();
+      expect(adapter.applyDropField).toBeUndefined();
+      expect(adapter.applyModifyField).toBeUndefined();
+      expect(adapter.applyRenameTable).toBeUndefined();
+      expect(adapter.applyRenameField).toBeUndefined();
+      expect(adapter.applyAddForeignKey).toBeUndefined();
+      expect(adapter.applyDropForeignKey).toBeUndefined();
+    });
+    test("type-level: ChangeFor<MongoDbAdapter> excludes DDL variants", () => {
+      expectTypeOf().not.toBeNever();
+      expectTypeOf().not.toBeNever();
+      expectTypeOf().not.toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+      expectTypeOf().toBeNever();
+    });
+    test("type-level: Migrator.from(repo, adapter).build() works without withoutLock", async () => {
+      const { Migrator } = await null;
+      const { Repo } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      const step = Migrator.from(repo, adapter).migrations([]);
+      expectTypeOf(step).toHaveProperty("build");
+      expectTypeOf(step).toHaveProperty("withoutLock");
+    });
+    test("type-level: Migrator.from(repo, adapter).withoutLock().build() also works", async () => {
+      const { Migrator } = await null;
+      const { Repo } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      const migrator = Migrator.from(repo, adapter).migrations([]).withoutLock().build();
+      expect(migrator).toBeDefined();
+    });
+    test("end-to-end: Migrator runs addIndex + dropIndex + execute changes", async () => {
+      const { Migrator } = await null;
+      const { Repo } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      let executeRan = false;
+      const migrations = [
+        {
+          id: "0001-add-idx",
+          tx: false,
+          changes: [
+            { kind: "addIndex", table: "users", on: ["email"], unique: true }
+          ]
+        },
+        {
+          id: "0002-backfill",
+          tx: false,
+          changes: [
+            { kind: "execute", up: async () => {
+              executeRan = true;
+            } }
+          ]
+        },
+        {
+          id: "0003-drop-idx",
+          tx: false,
+          changes: [
+            { kind: "dropIndex", name: "users_email_idx" }
+          ]
+        }
+      ];
+      const migrator = Migrator.from(repo, adapter).migrations(migrations).build();
+      const result = await migrator.up();
+      expect(result.ran).toEqual(["0001-add-idx", "0002-backfill", "0003-drop-idx"]);
+      expect(executeRan).toBe(true);
+      expect(state.migrations.size).toBe(3);
+      expect(state.collections.get("users").indexes).toHaveLength(0);
+    });
+    test("introspect round-trip: addIndex then introspect sees the index", async () => {
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      const state = mockMongoDb(adapter);
+      state.collections.set("users", {
+        indexes: [{ name: "users_email_idx", key: { email: 1 }, unique: true }]
+      });
+      const schemas = await adapter.introspect();
+      expect(schemas).toHaveLength(1);
+      expect(schemas[0].name).toBe("users");
+      expect(schemas[0].pk).toBeUndefined();
+      expect(schemas[0].fields).toEqual([]);
+      expect(schemas[0].foreignKeys).toEqual([]);
+      expect(schemas[0].indexes).toEqual([
+        { name: "users_email_idx", on: ["email"], unique: true }
+      ]);
+    });
+    test("data backfill via execute change", async () => {
+      const { Migrator } = await null;
+      const { Repo } = await null;
+      const adapter = MongoDbAdapter.create({ uri: "mongodb://localhost:27017/testdb" });
+      mockMongoDb(adapter);
+      const repo = Repo.from(adapter).resolve(() => ({ db: "test", col: "test" })).build();
+      const backfilledData = [];
+      const m = {
+        id: "0001-backfill",
+        tx: false,
+        changes: [{
+          kind: "execute",
+          up: async () => {
+            backfilledData.push("user-1-normalized");
+            backfilledData.push("user-2-normalized");
+          }
+        }]
+      };
+      const migrator = Migrator.from(repo, adapter).migrations([m]).build();
+      await migrator.up();
+      expect(backfilledData).toEqual(["user-1-normalized", "user-2-normalized"]);
+    });
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MongoDbAdapter
+});
+//# sourceMappingURL=index.cjs.map