@happyvertical/smrt-core 0.49.3 → 0.49.4

package/dist/embedded-write-queue.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { NestedTransactionError } from "@happyvertical/sql";
 //#region src/embedded-write-queue.ts
 /**
 * In-process write serialization for embedded database engines (#2360).
@@ -118,14 +119,23 @@ async function withEmbeddedWriteQueue(db, serialize, operation) {
 * change-feed appends inside the callback do not queue behind their own root
 * transaction.
 */
-async function withEmbeddedWriteTransaction(db, serialize, operation) {
+async function withEmbeddedWriteTransaction(db, serialize, operation, reuseUnsupportedNested = false) {
 	const transaction = db.transaction?.bind(db);
 	if (!transaction) throw new Error("Database transaction support is required");
-	return withEmbeddedWriteQueue(db, serialize, () => transaction((bound) => {
-		if (!serialize) return operation(bound);
-		const active = activeQueueKeys.getStore();
-		return activeQueueKeys.run(/* @__PURE__ */ new Set([...active ?? [], queueKey(bound)]), () => operation(bound));
-	}));
+	return withEmbeddedWriteQueue(db, serialize, async () => {
+		let entered = false;
+		try {
+			return await transaction((bound) => {
+				entered = true;
+				if (!serialize) return operation(bound);
+				const active = activeQueueKeys.getStore();
+				return activeQueueKeys.run(/* @__PURE__ */ new Set([...active ?? [], queueKey(bound)]), () => operation(bound));
+			});
+		} catch (error) {
+			if (reuseUnsupportedNested && !entered && error instanceof NestedTransactionError) return operation(db);
+			throw error;
+		}
+	});
 }
 //#endregion
 export { isEmbeddedDatabase, isPostgresDatabase, usesEmbeddedRevisionFallback, withEmbeddedWriteQueue, withEmbeddedWriteTransaction };

package/dist/embedded-write-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-write-queue.js","names":[],"sources":["../src/embedded-write-queue.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { DatabaseInterface } from '@happyvertical/sql';\n\n/**\n * In-process write serialization for embedded database engines (#2360).\n *\n * File-backed SQLite (libsql) allows one writer at a time and the SDK opens a\n * NEW connection for every null-aware upsert attempt (`transaction(\"write\")`),\n * with no busy timeout on either connection. Any other write on the root\n * connection while such a transaction is open — most commonly the change-feed\n * append that follows every model save — collides as `SQLITE_BUSY`, and under\n * sustained concurrency (a `Promise.all` of creates) the two sides livelock\n * through every retry tier. Before the tenant-led conflict target (#2360) the\n * null-aware path was rare (custom conflict keys with NULL values, #1246);\n * with `tenant_id` leading every tenant-scoped default key, EVERY NULL-tenant\n * (global) create takes it, so the collision became the steady state.\n *\n * The queue makes the process a single writer per embedded database for:\n *\n * - a `save()` whose upsert conflict values contain NULL (the only shape the\n *   SDK routes through a second-connection transaction), and\n * - the change-feed append (a root-connection write that follows every save).\n * - every model save and delete, so the embedded revision-CAS compare/upsert\n *   fallback cannot race an ordinary save, natural-key create, or delete.\n * - a complete root `SmrtObject.withTransaction()` callback, with writes on\n *   its bound handle re-entering the same hold instead of self-deadlocking.\n *\n * Ordinary save/delete holds contain database calls only — never an\n * interceptor or hook. Explicit transaction callbacks are caller-controlled,\n * so their bound model writes re-enter the existing hold. PostgreSQL is never\n * serialized here:\n * its null-aware upsert already arbitrates through advisory locks\n * server-side, and cross-process writers exist that an in-process queue could\n * not order anyway (which is also why this queue is a mitigation for embedded\n * engines' in-process writers, not a cross-process guarantee — embedded\n * engines have no cross-process writers in supported deployments).\n */\n\n/** Queue tail per database identity (URL string, or the handle itself). */\nconst urlQueues = new Map<string, Promise<unknown>>();\nconst handleQueues = new WeakMap<object, Promise<unknown>>();\nconst activeQueueKeys = new AsyncLocalStorage<ReadonlySet<string | object>>();\n\ninterface QueueableDatabase {\n  url?: string;\n}\n\n/**\n * Whether `db` is an embedded engine (SQLite/DuckDB/JSON — anything that is\n * not PostgreSQL). Handles without a URL are treated as embedded: serializing\n * them is at worst a throughput cost, while not serializing an embedded\n * handle reintroduces the livelock.\n */\nexport function isEmbeddedDatabase(db: QueueableDatabase): boolean {\n  return !isPostgresDatabase(db);\n}\n\n/**\n * Whether `db` is a PostgreSQL handle.\n *\n * The revision compare-and-swap predicate is dialect-specific (#2620): only\n * PostgreSQL needs the millisecond-truncating, timezone-tolerant guard, and\n * only PostgreSQL can evaluate `date_trunc`.\n */\nexport function isPostgresDatabase(db: QueueableDatabase): boolean {\n  return /^postgres(?:ql)?:/iu.test(db?.url ?? '');\n}\n\n/**\n * Whether revision compare-and-swap needs the process-local read/upsert path.\n *\n * DuckDB/JSON cannot express the timestamp predicate through the generic\n * update API, and local SQLite has only the process's writers in supported\n * deployments. Remote LibSQL/Turso is different: other processes may write\n * the same database, so it must use one conditional UPDATE at the server.\n */\nexport function usesEmbeddedRevisionFallback(db: QueueableDatabase): boolean {\n  const url = db?.url ?? '';\n  return isEmbeddedDatabase(db) && !/^(?:https?|libsql):\\/\\//iu.test(url);\n}\n\n/**\n * Whether `url` identifies a SQLite/DuckDB in-memory database that is\n * private to its own connection, as opposed to shared state.\n *\n * Bare `:memory:` and `file::memory:` (no query string) each mint a fresh,\n * connection-private database -- `resolveDuckDBUrl(':memory:')` returns it\n * unchanged, with no per-instance suffix -- so two independent handles that\n * both happen to carry this literal string are NOT the same database and\n * must not share a write-queue identity (#2707). A `cache=shared` query\n * parameter (e.g. `file::memory:?cache=shared`) is the opposite case: it is\n * SQLite's own mechanism for making an in-memory database genuinely shared\n * across connections in the process, so a URL carrying it must keep the\n * ordinary string-keyed (shared) behavior.\n */\nfunction isPerConnectionMemoryUrl(url: string): boolean {\n  if (url.includes('cache=shared')) return false;\n  return url === ':memory:' || url === 'file::memory:';\n}\n\nfunction queueKey(db: QueueableDatabase): string | object {\n  if (typeof db?.url !== 'string' || db.url.length === 0) return db;\n  return isPerConnectionMemoryUrl(db.url) ? db : db.url;\n}\n\n/**\n * Run `operation` after every previously queued write on the same database\n * has settled. When `serialize` is false the operation runs immediately.\n */\nexport async function withEmbeddedWriteQueue<T>(\n  db: QueueableDatabase,\n  serialize: boolean,\n  operation: () => Promise<T>,\n): Promise<T> {\n  if (!serialize) return operation();\n\n  const key = queueKey(db);\n  const active = activeQueueKeys.getStore();\n  if (active?.has(key)) return operation();\n  const previous =\n    (typeof key === 'string' ? urlQueues.get(key) : handleQueues.get(key)) ??\n    Promise.resolve();\n  const run = () =>\n    activeQueueKeys.run(new Set([...(active ?? []), key]), operation);\n  const next = previous.then(run, run);\n  // The stored tail must never reject, or one failed write would poison the\n  // queue for every later writer.\n  const tail = next.catch(() => undefined);\n  if (typeof key === 'string') {\n    urlQueues.set(key, tail);\n    void tail.finally(() => {\n      if (urlQueues.get(key) === tail) urlQueues.delete(key);\n    });\n  } else {\n    handleQueues.set(key, tail);\n  }\n  return next;\n}\n\n/**\n * Serialize a complete embedded root transaction with ordinary model writes.\n * The transaction handle is registered as a reentrant alias so saves and\n * change-feed appends inside the callback do not queue behind their own root\n * transaction.\n */\nexport async function withEmbeddedWriteTransaction<T>(\n  db: DatabaseInterface,\n  serialize: boolean,\n  operation: (transaction: DatabaseInterface) => Promise<T>,\n): Promise<T> {\n  const transaction = db.transaction?.bind(db);\n  if (!transaction) {\n    throw new Error('Database transaction support is required');\n  }\n  return withEmbeddedWriteQueue(db, serialize, () =>\n    transaction((bound) => {\n      if (!serialize) return operation(bound);\n      const active = activeQueueKeys.getStore();\n      return activeQueueKeys.run(\n        new Set([...(active ?? []), queueKey(bound)]),\n        () => operation(bound),\n      );\n    }),\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAM,4BAAY,IAAI,IAA8B;AACpD,IAAM,+BAAe,IAAI,QAAkC;AAC3D,IAAM,kBAAkB,IAAI,kBAAgD;;;;;;;AAY5E,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,CAAC,mBAAmB,EAAE;AAC/B;;;;;;;;AASA,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,sBAAsB,KAAK,IAAI,OAAO,EAAE;AACjD;;;;;;;;;AAUA,SAAgB,6BAA6B,IAAgC;CAC3E,MAAM,MAAM,IAAI,OAAO;CACvB,OAAO,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,KAAK,GAAG;AACxE;;;;;;;;;;;;;;;AAgBA,SAAS,yBAAyB,KAAsB;CACtD,IAAI,IAAI,SAAS,cAAc,GAAG,OAAO;CACzC,OAAO,QAAQ,cAAc,QAAQ;AACvC;AAEA,SAAS,SAAS,IAAwC;CACxD,IAAI,OAAO,IAAI,QAAQ,YAAY,GAAG,IAAI,WAAW,GAAG,OAAO;CAC/D,OAAO,yBAAyB,GAAG,GAAG,IAAI,KAAK,GAAG;AACpD;;;;;AAMA,eAAsB,uBACpB,IACA,WACA,WACY;CACZ,IAAI,CAAC,WAAW,OAAO,UAAU;CAEjC,MAAM,MAAM,SAAS,EAAE;CACvB,MAAM,SAAS,gBAAgB,SAAS;CACxC,IAAI,QAAQ,IAAI,GAAG,GAAG,OAAO,UAAU;CACvC,MAAM,YACH,OAAO,QAAQ,WAAW,UAAU,IAAI,GAAG,IAAI,aAAa,IAAI,GAAG,MACpE,QAAQ,QAAQ;CAClB,MAAM,YACJ,gBAAgB,oBAAI,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,GAAG,CAAC,GAAG,SAAS;CAClE,MAAM,OAAO,SAAS,KAAK,KAAK,GAAG;CAGnC,MAAM,OAAO,KAAK,YAAY,KAAA,CAAS;CACvC,IAAI,OAAO,QAAQ,UAAU;EAC3B,UAAU,IAAI,KAAK,IAAI;EACvB,KAAU,cAAc;GACtB,IAAI,UAAU,IAAI,GAAG,MAAM,MAAM,UAAU,OAAO,GAAG;EACvD,CAAC;CACH,OACE,aAAa,IAAI,KAAK,IAAI;CAE5B,OAAO;AACT;;;;;;;AAQA,eAAsB,6BACpB,IACA,WACA,WACY;CACZ,MAAM,cAAc,GAAG,aAAa,KAAK,EAAE;CAC3C,IAAI,CAAC,aACH,MAAM,IAAI,MAAM,0CAA0C;CAE5D,OAAO,uBAAuB,IAAI,iBAChC,aAAa,UAAU;EACrB,IAAI,CAAC,WAAW,OAAO,UAAU,KAAK;EACtC,MAAM,SAAS,gBAAgB,SAAS;EACxC,OAAO,gBAAgB,oBACrB,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,SAAS,KAAK,CAAC,CAAC,SACtC,UAAU,KAAK,CACvB;CACF,CAAC,CACH;AACF"}
+{"version":3,"file":"embedded-write-queue.js","names":[],"sources":["../src/embedded-write-queue.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport {\n  type DatabaseInterface,\n  NestedTransactionError,\n} from '@happyvertical/sql';\n\n/**\n * In-process write serialization for embedded database engines (#2360).\n *\n * File-backed SQLite (libsql) allows one writer at a time and the SDK opens a\n * NEW connection for every null-aware upsert attempt (`transaction(\"write\")`),\n * with no busy timeout on either connection. Any other write on the root\n * connection while such a transaction is open — most commonly the change-feed\n * append that follows every model save — collides as `SQLITE_BUSY`, and under\n * sustained concurrency (a `Promise.all` of creates) the two sides livelock\n * through every retry tier. Before the tenant-led conflict target (#2360) the\n * null-aware path was rare (custom conflict keys with NULL values, #1246);\n * with `tenant_id` leading every tenant-scoped default key, EVERY NULL-tenant\n * (global) create takes it, so the collision became the steady state.\n *\n * The queue makes the process a single writer per embedded database for:\n *\n * - a `save()` whose upsert conflict values contain NULL (the only shape the\n *   SDK routes through a second-connection transaction), and\n * - the change-feed append (a root-connection write that follows every save).\n * - every model save and delete, so the embedded revision-CAS compare/upsert\n *   fallback cannot race an ordinary save, natural-key create, or delete.\n * - a complete root `SmrtObject.withTransaction()` callback, with writes on\n *   its bound handle re-entering the same hold instead of self-deadlocking.\n *\n * Ordinary save/delete holds contain database calls only — never an\n * interceptor or hook. Explicit transaction callbacks are caller-controlled,\n * so their bound model writes re-enter the existing hold. PostgreSQL is never\n * serialized here:\n * its null-aware upsert already arbitrates through advisory locks\n * server-side, and cross-process writers exist that an in-process queue could\n * not order anyway (which is also why this queue is a mitigation for embedded\n * engines' in-process writers, not a cross-process guarantee — embedded\n * engines have no cross-process writers in supported deployments).\n */\n\n/** Queue tail per database identity (URL string, or the handle itself). */\nconst urlQueues = new Map<string, Promise<unknown>>();\nconst handleQueues = new WeakMap<object, Promise<unknown>>();\nconst activeQueueKeys = new AsyncLocalStorage<ReadonlySet<string | object>>();\n\ninterface QueueableDatabase {\n  url?: string;\n}\n\n/**\n * Whether `db` is an embedded engine (SQLite/DuckDB/JSON — anything that is\n * not PostgreSQL). Handles without a URL are treated as embedded: serializing\n * them is at worst a throughput cost, while not serializing an embedded\n * handle reintroduces the livelock.\n */\nexport function isEmbeddedDatabase(db: QueueableDatabase): boolean {\n  return !isPostgresDatabase(db);\n}\n\n/**\n * Whether `db` is a PostgreSQL handle.\n *\n * The revision compare-and-swap predicate is dialect-specific (#2620): only\n * PostgreSQL needs the millisecond-truncating, timezone-tolerant guard, and\n * only PostgreSQL can evaluate `date_trunc`.\n */\nexport function isPostgresDatabase(db: QueueableDatabase): boolean {\n  return /^postgres(?:ql)?:/iu.test(db?.url ?? '');\n}\n\n/**\n * Whether revision compare-and-swap needs the process-local read/upsert path.\n *\n * DuckDB/JSON cannot express the timestamp predicate through the generic\n * update API, and local SQLite has only the process's writers in supported\n * deployments. Remote LibSQL/Turso is different: other processes may write\n * the same database, so it must use one conditional UPDATE at the server.\n */\nexport function usesEmbeddedRevisionFallback(db: QueueableDatabase): boolean {\n  const url = db?.url ?? '';\n  return isEmbeddedDatabase(db) && !/^(?:https?|libsql):\\/\\//iu.test(url);\n}\n\n/**\n * Whether `url` identifies a SQLite/DuckDB in-memory database that is\n * private to its own connection, as opposed to shared state.\n *\n * Bare `:memory:` and `file::memory:` (no query string) each mint a fresh,\n * connection-private database -- `resolveDuckDBUrl(':memory:')` returns it\n * unchanged, with no per-instance suffix -- so two independent handles that\n * both happen to carry this literal string are NOT the same database and\n * must not share a write-queue identity (#2707). A `cache=shared` query\n * parameter (e.g. `file::memory:?cache=shared`) is the opposite case: it is\n * SQLite's own mechanism for making an in-memory database genuinely shared\n * across connections in the process, so a URL carrying it must keep the\n * ordinary string-keyed (shared) behavior.\n */\nfunction isPerConnectionMemoryUrl(url: string): boolean {\n  if (url.includes('cache=shared')) return false;\n  return url === ':memory:' || url === 'file::memory:';\n}\n\nfunction queueKey(db: QueueableDatabase): string | object {\n  if (typeof db?.url !== 'string' || db.url.length === 0) return db;\n  return isPerConnectionMemoryUrl(db.url) ? db : db.url;\n}\n\n/**\n * Run `operation` after every previously queued write on the same database\n * has settled. When `serialize` is false the operation runs immediately.\n */\nexport async function withEmbeddedWriteQueue<T>(\n  db: QueueableDatabase,\n  serialize: boolean,\n  operation: () => Promise<T>,\n): Promise<T> {\n  if (!serialize) return operation();\n\n  const key = queueKey(db);\n  const active = activeQueueKeys.getStore();\n  if (active?.has(key)) return operation();\n  const previous =\n    (typeof key === 'string' ? urlQueues.get(key) : handleQueues.get(key)) ??\n    Promise.resolve();\n  const run = () =>\n    activeQueueKeys.run(new Set([...(active ?? []), key]), operation);\n  const next = previous.then(run, run);\n  // The stored tail must never reject, or one failed write would poison the\n  // queue for every later writer.\n  const tail = next.catch(() => undefined);\n  if (typeof key === 'string') {\n    urlQueues.set(key, tail);\n    void tail.finally(() => {\n      if (urlQueues.get(key) === tail) urlQueues.delete(key);\n    });\n  } else {\n    handleQueues.set(key, tail);\n  }\n  return next;\n}\n\n/**\n * Serialize a complete embedded root transaction with ordinary model writes.\n * The transaction handle is registered as a reentrant alias so saves and\n * change-feed appends inside the callback do not queue behind their own root\n * transaction.\n */\nexport async function withEmbeddedWriteTransaction<T>(\n  db: DatabaseInterface,\n  serialize: boolean,\n  operation: (transaction: DatabaseInterface) => Promise<T>,\n  reuseUnsupportedNested = false,\n): Promise<T> {\n  const transaction = db.transaction?.bind(db);\n  if (!transaction) {\n    throw new Error('Database transaction support is required');\n  }\n  return withEmbeddedWriteQueue(db, serialize, async () => {\n    let entered = false;\n    try {\n      return await transaction((bound) => {\n        entered = true;\n        if (!serialize) return operation(bound);\n        const active = activeQueueKeys.getStore();\n        return activeQueueKeys.run(\n          new Set([...(active ?? []), queueKey(bound)]),\n          () => operation(bound),\n        );\n      });\n    } catch (error) {\n      // The SDK explicitly refuses no-savepoint nesting before invoking the\n      // callback or touching the enclosing transaction. A helper that needs\n      // the caller's atomic scope can use that existing handle directly. Never\n      // replay work when the callback ran, even if it threw the same error.\n      if (\n        reuseUnsupportedNested &&\n        !entered &&\n        error instanceof NestedTransactionError\n      ) {\n        return operation(db);\n      }\n      throw error;\n    }\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,IAAM,4BAAY,IAAI,IAA8B;AACpD,IAAM,+BAAe,IAAI,QAAkC;AAC3D,IAAM,kBAAkB,IAAI,kBAAgD;;;;;;;AAY5E,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,CAAC,mBAAmB,EAAE;AAC/B;;;;;;;;AASA,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,sBAAsB,KAAK,IAAI,OAAO,EAAE;AACjD;;;;;;;;;AAUA,SAAgB,6BAA6B,IAAgC;CAC3E,MAAM,MAAM,IAAI,OAAO;CACvB,OAAO,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,KAAK,GAAG;AACxE;;;;;;;;;;;;;;;AAgBA,SAAS,yBAAyB,KAAsB;CACtD,IAAI,IAAI,SAAS,cAAc,GAAG,OAAO;CACzC,OAAO,QAAQ,cAAc,QAAQ;AACvC;AAEA,SAAS,SAAS,IAAwC;CACxD,IAAI,OAAO,IAAI,QAAQ,YAAY,GAAG,IAAI,WAAW,GAAG,OAAO;CAC/D,OAAO,yBAAyB,GAAG,GAAG,IAAI,KAAK,GAAG;AACpD;;;;;AAMA,eAAsB,uBACpB,IACA,WACA,WACY;CACZ,IAAI,CAAC,WAAW,OAAO,UAAU;CAEjC,MAAM,MAAM,SAAS,EAAE;CACvB,MAAM,SAAS,gBAAgB,SAAS;CACxC,IAAI,QAAQ,IAAI,GAAG,GAAG,OAAO,UAAU;CACvC,MAAM,YACH,OAAO,QAAQ,WAAW,UAAU,IAAI,GAAG,IAAI,aAAa,IAAI,GAAG,MACpE,QAAQ,QAAQ;CAClB,MAAM,YACJ,gBAAgB,oBAAI,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,GAAG,CAAC,GAAG,SAAS;CAClE,MAAM,OAAO,SAAS,KAAK,KAAK,GAAG;CAGnC,MAAM,OAAO,KAAK,YAAY,KAAA,CAAS;CACvC,IAAI,OAAO,QAAQ,UAAU;EAC3B,UAAU,IAAI,KAAK,IAAI;EACvB,KAAU,cAAc;GACtB,IAAI,UAAU,IAAI,GAAG,MAAM,MAAM,UAAU,OAAO,GAAG;EACvD,CAAC;CACH,OACE,aAAa,IAAI,KAAK,IAAI;CAE5B,OAAO;AACT;;;;;;;AAQA,eAAsB,6BACpB,IACA,WACA,WACA,yBAAyB,OACb;CACZ,MAAM,cAAc,GAAG,aAAa,KAAK,EAAE;CAC3C,IAAI,CAAC,aACH,MAAM,IAAI,MAAM,0CAA0C;CAE5D,OAAO,uBAAuB,IAAI,WAAW,YAAY;EACvD,IAAI,UAAU;EACd,IAAI;GACF,OAAO,MAAM,aAAa,UAAU;IAClC,UAAU;IACV,IAAI,CAAC,WAAW,OAAO,UAAU,KAAK;IACtC,MAAM,SAAS,gBAAgB,SAAS;IACxC,OAAO,gBAAgB,oBACrB,IAAI,IAAI,CAAC,GAAI,UAAU,CAAC,GAAI,SAAS,KAAK,CAAC,CAAC,SACtC,UAAU,KAAK,CACvB;GACF,CAAC;EACH,SAAS,OAAO;GAKd,IACE,0BACA,CAAC,WACD,iBAAiB,wBAEjB,OAAO,UAAU,EAAE;GAErB,MAAM;EACR;CACF,CAAC;AACH"}

package/dist/embeddings/storage.d.ts

@@ -51,6 +51,22 @@ export declare class EmbeddingStorage {
         objectId: string;
         similarity: number;
     }>>;
+    /**
+     * Exact cosine top-K using bounded embedding pages and a caller-owned scope.
+     * JSON vectors are always persisted, including with native vector storage.
+     * Eligibility is checked before scoring; neither all vectors nor all eligible
+     * object IDs are materialized. The callback must fail closed on scope errors.
+     */
+    static searchSimilarBatched(db: DatabaseInterface, objectClass: string, embedding: number[], options: {
+        field: string;
+        model: string;
+        limit: number;
+        minSimilarity: number;
+        eligible: (objectIds: string[]) => Promise<boolean[]>;
+    }): Promise<Array<{
+        objectId: string;
+        similarity: number;
+    }>>;
     /**
      * Ensure the native vector column and index exist on _smrt_embeddings.
      * Called once during initialization when storage: 'native' is configured.

package/dist/embeddings/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/embeddings/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAIhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAO/C;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;OAMG;WACU,MAAM,CACjB,EAAE,EAAE,iBAAiB,EACrB,IAAI,EAAE;QACJ,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,EACD,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC;IA6ChB;;;;;;;;;;;;;OAaG;WACU,aAAa,CACxB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB;;;;;WAKG;QACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,EACN,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IA+G3D;;;;;;;OAOG;WACU,mBAAmB,CAC9B,GAAG,EAAE,iBAAiB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,IAAI,CAAC;IAShB;;;;;;;;;OASG;WACU,GAAG,CACd,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAclC;;;;;;;OAOG;WACU,YAAY,CACvB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,EAAE,CAAC;IAY7B;;;;;;;;OAQG;WACU,YAAY,CACvB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,EAAE,CAAC;IAqB7B;;;;;;;OAOG;WACU,0BAA0B,CACrC,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC;IAWpB;;;;;;OAMG;WACU,eAAe,CAC1B,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;;;;OAQG;WACU,MAAM,CACjB,EAAE,EAAE,iBAAiB,EACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;OAKG;WACU,WAAW,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IASjE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;CAexB"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/embeddings/storage.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/storage.js

@@ -119,6 +119,46 @@ var EmbeddingStorage = class EmbeddingStorage {
 		})).filter((item) => item.similarity >= minSimilarity).sort((a, b) => b.similarity - a.similarity).slice(0, limit);
 	}
 	/**
+	* Exact cosine top-K using bounded embedding pages and a caller-owned scope.
+	* JSON vectors are always persisted, including with native vector storage.
+	* Eligibility is checked before scoring; neither all vectors nor all eligible
+	* object IDs are materialized. The callback must fail closed on scope errors.
+	*/
+	static async searchSimilarBatched(db, objectClass, embedding, options) {
+		const batchSize = 64;
+		let cursor;
+		let best = [];
+		for (;;) {
+			const params = [
+				objectClass,
+				options.field,
+				options.model
+			];
+			const cursorPredicate = cursor === void 0 ? "" : " AND id > ?";
+			if (cursor !== void 0) params.push(cursor);
+			const { rows } = await db.query(`SELECT CAST(id AS VARCHAR) AS id, CAST(object_id AS VARCHAR) AS object_id, embedding FROM _smrt_embeddings
+         WHERE object_class = ? AND field_name = ? AND model = ?${cursorPredicate}
+         ORDER BY _smrt_embeddings.id ASC LIMIT ${batchSize}`, ...params);
+			if (rows.length === 0) break;
+			const allowed = await options.eligible(rows.map((row) => String(row.object_id)));
+			if (allowed.length !== rows.length || allowed.some((value) => typeof value !== "boolean")) throw new Error("Invalid embedding candidate eligibility mask");
+			for (let index = 0; index < rows.length; index++) {
+				if (!allowed[index]) continue;
+				const row = rows[index];
+				const similarity = CosineSimilarity.calculate(embedding, JSON.parse(row.embedding));
+				if (similarity >= options.minSimilarity) best.push({
+					objectId: String(row.object_id),
+					similarity
+				});
+			}
+			best.sort((a, b) => b.similarity - a.similarity || (a.objectId < b.objectId ? -1 : a.objectId > b.objectId ? 1 : 0));
+			best = best.slice(0, options.limit);
+			cursor = String(rows[rows.length - 1].id);
+			if (rows.length < batchSize) break;
+		}
+		return best;
+	}
+	/**
 	* Ensure the native vector column and index exist on _smrt_embeddings.
 	* Called once during initialization when storage: 'native' is configured.
 	*

package/dist/embeddings/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","names":[],"sources":["../../src/embeddings/storage.ts"],"sourcesContent":["/**\n * Embedding Storage Operations\n *\n * CRUD operations for the _smrt_embeddings system table.\n * Supports both JSON-based and native vector storage strategies.\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface, VectorCapabilities } from '@happyvertical/sql';\nimport { chunkArray, IN_LIST_CHUNK_SIZE } from '../utils/chunk';\nimport { toSafeInteger } from '../utils/safe-integer.js';\nimport { CosineSimilarity } from './similarity';\nimport type { StoredEmbedding } from './types';\n\nconst logger = createLogger({ level: 'info' });\n\n/** Column name for native vector storage */\nconst VECTOR_COLUMN = 'embedding_vector';\n\n/**\n * Storage operations for embeddings in _smrt_embeddings table\n */\nexport class EmbeddingStorage {\n  /**\n   * Insert or update an embedding\n   *\n   * @param db - Database interface\n   * @param data - Embedding data to store\n   * @param vector - Optional vector capabilities for native storage\n   */\n  static async upsert(\n    db: DatabaseInterface,\n    data: {\n      objectClass: string;\n      objectId: string;\n      fieldName: string;\n      contentHash: string;\n      embedding: number[];\n      model: string;\n      dimensions: number;\n      provider?: string;\n    },\n    vector?: VectorCapabilities,\n  ): Promise<void> {\n    const now = new Date().toISOString();\n    const id = randomUUID();\n\n    await db.upsert(\n      '_smrt_embeddings',\n      ['object_class', 'object_id', 'field_name', 'model'],\n      {\n        id,\n        object_class: data.objectClass,\n        object_id: data.objectId,\n        field_name: data.fieldName,\n        content_hash: data.contentHash,\n        embedding: JSON.stringify(data.embedding),\n        model: data.model,\n        dimensions: data.dimensions,\n        provider: data.provider || null,\n        created_at: now,\n        updated_at: now,\n      },\n    );\n\n    // Also store native vector if capability is available\n    if (vector) {\n      try {\n        await vector.upsertVector(\n          '_smrt_embeddings',\n          {\n            object_class: data.objectClass,\n            object_id: data.objectId,\n            field_name: data.fieldName,\n            model: data.model,\n          },\n          VECTOR_COLUMN,\n          data.embedding,\n        );\n      } catch (error) {\n        // Log but don't fail — JSON fallback is always available\n        logger.warn(\n          `[embeddings] Failed to store native vector: ${error instanceof Error ? error.message : String(error)}`,\n        );\n      }\n    }\n  }\n\n  /**\n   * Search for similar embeddings using the best available strategy.\n   *\n   * When vector capabilities are provided, delegates to database-level\n   * vector search. Otherwise falls back to loading all embeddings and\n   * computing cosine similarity in memory.\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name to search within\n   * @param embedding - Query embedding vector\n   * @param options - Search options\n   * @param vector - Optional vector capabilities for native search\n   * @returns Array of { objectId, similarity } ranked by similarity (highest first)\n   */\n  static async searchSimilar(\n    db: DatabaseInterface,\n    objectClass: string,\n    embedding: number[],\n    options: {\n      field?: string;\n      model?: string;\n      limit?: number;\n      minSimilarity?: number;\n      /**\n       * Restrict candidates to these object ids BEFORE ranking (#2365).\n       * `undefined` means no restriction; an empty array means no candidates\n       * (the search returns no results). Used by tenant-scoped collections so\n       * top-K never ranks rows the caller is not allowed to see.\n       */\n      objectIds?: string[];\n    } = {},\n    vector?: VectorCapabilities,\n  ): Promise<Array<{ objectId: string; similarity: number }>> {\n    const { field, model, limit = 10, minSimilarity = 0, objectIds } = options;\n\n    // An explicit empty candidate set means \"nothing is visible\" — never fall\n    // through to the unrestricted search.\n    if (objectIds !== undefined && objectIds.length === 0) {\n      return [];\n    }\n\n    // Native vector search path\n    if (vector) {\n      try {\n        // Build WHERE clause for class/field/model filtering.\n        // Parameter numbering starts at $2 because vector.search() reserves\n        // $1 for the query vector embedding in its internal SQL query.\n        const conditions: string[] = ['object_class = $2'];\n        const params: unknown[] = [objectClass];\n\n        if (field) {\n          conditions.push(`field_name = $${params.length + 2}`);\n          params.push(field);\n        }\n\n        if (model) {\n          conditions.push(`model = $${params.length + 2}`);\n          params.push(model);\n        }\n\n        // Candidate restriction (#2365). The id list is chunked so one query\n        // never exceeds the backend's bind-variable limit; per-chunk top-K\n        // results merge into an exact global top-K because every chunk\n        // returns its own best `limit` candidates.\n        const idChunks = objectIds\n          ? chunkArray(objectIds, IN_LIST_CHUNK_SIZE)\n          : [undefined];\n\n        const merged: Array<{ objectId: string; similarity: number }> = [];\n        for (const chunk of idChunks) {\n          const chunkConditions = [...conditions];\n          const chunkParams = [...params];\n          if (chunk) {\n            const placeholders = chunk.map(\n              (_, index) => `$${chunkParams.length + 2 + index}`,\n            );\n            chunkConditions.push(`object_id IN (${placeholders.join(', ')})`);\n            chunkParams.push(...chunk);\n          }\n\n          const results = await vector.search(\n            '_smrt_embeddings',\n            VECTOR_COLUMN,\n            embedding,\n            {\n              limit,\n              metric: 'cosine',\n              where: chunkConditions.join(' AND '),\n              params: chunkParams,\n            },\n          );\n\n          // Convert cosine distance (0=identical, 2=opposite) to similarity\n          // (1=identical, -1=opposite)\n          merged.push(\n            ...results.map((r) => ({\n              objectId: r.object_id as string,\n              similarity: 1 - r.distance,\n            })),\n          );\n        }\n\n        return merged\n          .filter((r) => r.similarity >= minSimilarity)\n          .sort((a, b) => b.similarity - a.similarity)\n          .slice(0, limit);\n      } catch (error) {\n        // Fall back to in-memory search on vector search failure\n        logger.warn(\n          `[embeddings] Native vector search failed, falling back to in-memory: ${error instanceof Error ? error.message : String(error)}`,\n        );\n      }\n    }\n\n    // In-memory fallback: load all embeddings and compute cosine similarity\n    const storedEmbeddings = await EmbeddingStorage.listForClass(\n      db,\n      objectClass,\n      field,\n      model,\n    );\n\n    // Candidate restriction (#2365): drop invisible rows BEFORE ranking so\n    // top-K is computed only over what the caller may see.\n    const allowedIds = objectIds ? new Set(objectIds) : undefined;\n    const candidates = allowedIds\n      ? storedEmbeddings.filter((stored) => allowedIds.has(stored.object_id))\n      : storedEmbeddings;\n\n    if (candidates.length === 0) {\n      return [];\n    }\n\n    return candidates\n      .map((stored) => ({\n        objectId: stored.object_id,\n        similarity: CosineSimilarity.calculate(embedding, stored.embedding),\n      }))\n      .filter((item) => item.similarity >= minSimilarity)\n      .sort((a, b) => b.similarity - a.similarity)\n      .slice(0, limit);\n  }\n\n  /**\n   * Ensure the native vector column and index exist on _smrt_embeddings.\n   * Called once during initialization when storage: 'native' is configured.\n   *\n   * @param db - Database interface\n   * @param dimensions - Vector dimensions\n   * @param vector - Vector capabilities\n   */\n  static async ensureVectorStorage(\n    _db: DatabaseInterface,\n    dimensions: number,\n    vector: VectorCapabilities,\n  ): Promise<void> {\n    await vector.ensureColumn('_smrt_embeddings', VECTOR_COLUMN, dimensions);\n    await vector.ensureIndex('_smrt_embeddings', VECTOR_COLUMN, {\n      dimensions,\n      metric: 'cosine',\n      type: 'hnsw',\n    });\n  }\n\n  /**\n   * Get a specific embedding\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @param fieldName - Field name\n   * @param model - Model used\n   * @returns Stored embedding or null\n   */\n  static async get(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n    fieldName: string,\n    model: string,\n  ): Promise<StoredEmbedding | null> {\n    const result = await db.single`\n      SELECT * FROM _smrt_embeddings\n      WHERE object_class = ${objectClass}\n        AND object_id = ${objectId}\n        AND field_name = ${fieldName}\n        AND model = ${model}\n    `;\n\n    if (!result) return null;\n\n    return EmbeddingStorage.parseRow(result);\n  }\n\n  /**\n   * Get all embeddings for an object\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @returns Array of stored embeddings\n   */\n  static async getForObject(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n  ): Promise<StoredEmbedding[]> {\n    const { rows } = await db.query(\n      `SELECT * FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,\n      objectClass,\n      objectId,\n    );\n\n    return rows.map((row: Record<string, unknown>) =>\n      EmbeddingStorage.parseRow(row),\n    );\n  }\n\n  /**\n   * List embeddings for a class (optionally filtered by field and model)\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param fieldName - Optional field filter\n   * @param model - Optional model filter\n   * @returns Array of stored embeddings\n   */\n  static async listForClass(\n    db: DatabaseInterface,\n    objectClass: string,\n    fieldName?: string,\n    model?: string,\n  ): Promise<StoredEmbedding[]> {\n    let sql = `SELECT * FROM _smrt_embeddings WHERE object_class = ?`;\n    const params: unknown[] = [objectClass];\n\n    if (fieldName) {\n      sql += ` AND field_name = ?`;\n      params.push(fieldName);\n    }\n\n    if (model) {\n      sql += ` AND model = ?`;\n      params.push(model);\n    }\n\n    const { rows } = await db.query(sql, ...params);\n\n    return rows.map((row: Record<string, unknown>) =>\n      EmbeddingStorage.parseRow(row),\n    );\n  }\n\n  /**\n   * Get object IDs that have embeddings for a specific field\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param fieldName - Field name\n   * @returns Array of object IDs\n   */\n  static async getObjectIdsWithEmbeddings(\n    db: DatabaseInterface,\n    objectClass: string,\n    fieldName: string,\n  ): Promise<string[]> {\n    const { rows } = await db.query(\n      `SELECT DISTINCT object_id FROM _smrt_embeddings\n       WHERE object_class = ? AND field_name = ?`,\n      objectClass,\n      fieldName,\n    );\n\n    return rows.map((row: Record<string, unknown>) => row.object_id as string);\n  }\n\n  /**\n   * Delete all embeddings for an object\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   */\n  static async deleteForObject(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n  ): Promise<void> {\n    await db.query(\n      `DELETE FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,\n      objectClass,\n      objectId,\n    );\n  }\n\n  /**\n   * Delete a specific embedding\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @param fieldName - Field name\n   * @param model - Model used\n   */\n  static async delete(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n    fieldName: string,\n    model: string,\n  ): Promise<void> {\n    await db.query(\n      `DELETE FROM _smrt_embeddings\n       WHERE object_class = ? AND object_id = ? AND field_name = ? AND model = ?`,\n      objectClass,\n      objectId,\n      fieldName,\n      model,\n    );\n  }\n\n  /**\n   * Check if embedding table exists\n   *\n   * @param db - Database interface\n   * @returns True if table exists\n   */\n  static async tableExists(db: DatabaseInterface): Promise<boolean> {\n    try {\n      await db.query(`SELECT 1 FROM _smrt_embeddings LIMIT 1`);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Parse a database row into StoredEmbedding\n   */\n  private static parseRow(row: Record<string, unknown>): StoredEmbedding {\n    return {\n      id: row.id as string,\n      object_class: row.object_class as string,\n      object_id: row.object_id as string,\n      field_name: row.field_name as string,\n      content_hash: row.content_hash as string,\n      embedding: JSON.parse(row.embedding as string) as number[],\n      model: row.model as string,\n      dimensions: toSafeInteger(row.dimensions, 'Embedding dimensions'),\n      provider: row.provider as string | undefined,\n      created_at: new Date(row.created_at as string),\n      updated_at: new Date(row.updated_at as string),\n    };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"storage.js","names":[],"sources":["../../src/embeddings/storage.ts"],"sourcesContent":["/**\n * Embedding Storage Operations\n *\n * CRUD operations for the _smrt_embeddings system table.\n * Supports both JSON-based and native vector storage strategies.\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface, VectorCapabilities } from '@happyvertical/sql';\nimport { chunkArray, IN_LIST_CHUNK_SIZE } from '../utils/chunk';\nimport { toSafeInteger } from '../utils/safe-integer.js';\nimport { CosineSimilarity } from './similarity';\nimport type { StoredEmbedding } from './types';\n\nconst logger = createLogger({ level: 'info' });\n\n/** Column name for native vector storage */\nconst VECTOR_COLUMN = 'embedding_vector';\n\n/**\n * Storage operations for embeddings in _smrt_embeddings table\n */\nexport class EmbeddingStorage {\n  /**\n   * Insert or update an embedding\n   *\n   * @param db - Database interface\n   * @param data - Embedding data to store\n   * @param vector - Optional vector capabilities for native storage\n   */\n  static async upsert(\n    db: DatabaseInterface,\n    data: {\n      objectClass: string;\n      objectId: string;\n      fieldName: string;\n      contentHash: string;\n      embedding: number[];\n      model: string;\n      dimensions: number;\n      provider?: string;\n    },\n    vector?: VectorCapabilities,\n  ): Promise<void> {\n    const now = new Date().toISOString();\n    const id = randomUUID();\n\n    await db.upsert(\n      '_smrt_embeddings',\n      ['object_class', 'object_id', 'field_name', 'model'],\n      {\n        id,\n        object_class: data.objectClass,\n        object_id: data.objectId,\n        field_name: data.fieldName,\n        content_hash: data.contentHash,\n        embedding: JSON.stringify(data.embedding),\n        model: data.model,\n        dimensions: data.dimensions,\n        provider: data.provider || null,\n        created_at: now,\n        updated_at: now,\n      },\n    );\n\n    // Also store native vector if capability is available\n    if (vector) {\n      try {\n        await vector.upsertVector(\n          '_smrt_embeddings',\n          {\n            object_class: data.objectClass,\n            object_id: data.objectId,\n            field_name: data.fieldName,\n            model: data.model,\n          },\n          VECTOR_COLUMN,\n          data.embedding,\n        );\n      } catch (error) {\n        // Log but don't fail — JSON fallback is always available\n        logger.warn(\n          `[embeddings] Failed to store native vector: ${error instanceof Error ? error.message : String(error)}`,\n        );\n      }\n    }\n  }\n\n  /**\n   * Search for similar embeddings using the best available strategy.\n   *\n   * When vector capabilities are provided, delegates to database-level\n   * vector search. Otherwise falls back to loading all embeddings and\n   * computing cosine similarity in memory.\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name to search within\n   * @param embedding - Query embedding vector\n   * @param options - Search options\n   * @param vector - Optional vector capabilities for native search\n   * @returns Array of { objectId, similarity } ranked by similarity (highest first)\n   */\n  static async searchSimilar(\n    db: DatabaseInterface,\n    objectClass: string,\n    embedding: number[],\n    options: {\n      field?: string;\n      model?: string;\n      limit?: number;\n      minSimilarity?: number;\n      /**\n       * Restrict candidates to these object ids BEFORE ranking (#2365).\n       * `undefined` means no restriction; an empty array means no candidates\n       * (the search returns no results). Used by tenant-scoped collections so\n       * top-K never ranks rows the caller is not allowed to see.\n       */\n      objectIds?: string[];\n    } = {},\n    vector?: VectorCapabilities,\n  ): Promise<Array<{ objectId: string; similarity: number }>> {\n    const { field, model, limit = 10, minSimilarity = 0, objectIds } = options;\n\n    // An explicit empty candidate set means \"nothing is visible\" — never fall\n    // through to the unrestricted search.\n    if (objectIds !== undefined && objectIds.length === 0) {\n      return [];\n    }\n\n    // Native vector search path\n    if (vector) {\n      try {\n        // Build WHERE clause for class/field/model filtering.\n        // Parameter numbering starts at $2 because vector.search() reserves\n        // $1 for the query vector embedding in its internal SQL query.\n        const conditions: string[] = ['object_class = $2'];\n        const params: unknown[] = [objectClass];\n\n        if (field) {\n          conditions.push(`field_name = $${params.length + 2}`);\n          params.push(field);\n        }\n\n        if (model) {\n          conditions.push(`model = $${params.length + 2}`);\n          params.push(model);\n        }\n\n        // Candidate restriction (#2365). The id list is chunked so one query\n        // never exceeds the backend's bind-variable limit; per-chunk top-K\n        // results merge into an exact global top-K because every chunk\n        // returns its own best `limit` candidates.\n        const idChunks = objectIds\n          ? chunkArray(objectIds, IN_LIST_CHUNK_SIZE)\n          : [undefined];\n\n        const merged: Array<{ objectId: string; similarity: number }> = [];\n        for (const chunk of idChunks) {\n          const chunkConditions = [...conditions];\n          const chunkParams = [...params];\n          if (chunk) {\n            const placeholders = chunk.map(\n              (_, index) => `$${chunkParams.length + 2 + index}`,\n            );\n            chunkConditions.push(`object_id IN (${placeholders.join(', ')})`);\n            chunkParams.push(...chunk);\n          }\n\n          const results = await vector.search(\n            '_smrt_embeddings',\n            VECTOR_COLUMN,\n            embedding,\n            {\n              limit,\n              metric: 'cosine',\n              where: chunkConditions.join(' AND '),\n              params: chunkParams,\n            },\n          );\n\n          // Convert cosine distance (0=identical, 2=opposite) to similarity\n          // (1=identical, -1=opposite)\n          merged.push(\n            ...results.map((r) => ({\n              objectId: r.object_id as string,\n              similarity: 1 - r.distance,\n            })),\n          );\n        }\n\n        return merged\n          .filter((r) => r.similarity >= minSimilarity)\n          .sort((a, b) => b.similarity - a.similarity)\n          .slice(0, limit);\n      } catch (error) {\n        // Fall back to in-memory search on vector search failure\n        logger.warn(\n          `[embeddings] Native vector search failed, falling back to in-memory: ${error instanceof Error ? error.message : String(error)}`,\n        );\n      }\n    }\n\n    // In-memory fallback: load all embeddings and compute cosine similarity\n    const storedEmbeddings = await EmbeddingStorage.listForClass(\n      db,\n      objectClass,\n      field,\n      model,\n    );\n\n    // Candidate restriction (#2365): drop invisible rows BEFORE ranking so\n    // top-K is computed only over what the caller may see.\n    const allowedIds = objectIds ? new Set(objectIds) : undefined;\n    const candidates = allowedIds\n      ? storedEmbeddings.filter((stored) => allowedIds.has(stored.object_id))\n      : storedEmbeddings;\n\n    if (candidates.length === 0) {\n      return [];\n    }\n\n    return candidates\n      .map((stored) => ({\n        objectId: stored.object_id,\n        similarity: CosineSimilarity.calculate(embedding, stored.embedding),\n      }))\n      .filter((item) => item.similarity >= minSimilarity)\n      .sort((a, b) => b.similarity - a.similarity)\n      .slice(0, limit);\n  }\n\n  /**\n   * Exact cosine top-K using bounded embedding pages and a caller-owned scope.\n   * JSON vectors are always persisted, including with native vector storage.\n   * Eligibility is checked before scoring; neither all vectors nor all eligible\n   * object IDs are materialized. The callback must fail closed on scope errors.\n   */\n  static async searchSimilarBatched(\n    db: DatabaseInterface,\n    objectClass: string,\n    embedding: number[],\n    options: {\n      field: string;\n      model: string;\n      limit: number;\n      minSimilarity: number;\n      eligible: (objectIds: string[]) => Promise<boolean[]>;\n    },\n  ): Promise<Array<{ objectId: string; similarity: number }>> {\n    const batchSize = 64;\n    let cursor: string | undefined;\n    let best: Array<{ objectId: string; similarity: number }> = [];\n    for (;;) {\n      const params: unknown[] = [objectClass, options.field, options.model];\n      const cursorPredicate = cursor === undefined ? '' : ' AND id > ?';\n      if (cursor !== undefined) params.push(cursor);\n      const { rows } = await db.query(\n        `SELECT CAST(id AS VARCHAR) AS id, CAST(object_id AS VARCHAR) AS object_id, embedding FROM _smrt_embeddings\n         WHERE object_class = ? AND field_name = ? AND model = ?${cursorPredicate}\n         ORDER BY _smrt_embeddings.id ASC LIMIT ${batchSize}`,\n        ...params,\n      );\n      if (rows.length === 0) break;\n      const allowed = await options.eligible(\n        rows.map((row: Record<string, unknown>) => String(row.object_id)),\n      );\n      if (\n        allowed.length !== rows.length ||\n        allowed.some((value) => typeof value !== 'boolean')\n      ) {\n        throw new Error('Invalid embedding candidate eligibility mask');\n      }\n      for (let index = 0; index < rows.length; index++) {\n        if (!allowed[index]) continue;\n        const row = rows[index];\n        const similarity = CosineSimilarity.calculate(\n          embedding,\n          JSON.parse(row.embedding as string) as number[],\n        );\n        if (similarity >= options.minSimilarity) {\n          best.push({ objectId: String(row.object_id), similarity });\n        }\n      }\n      best.sort(\n        (a, b) =>\n          b.similarity - a.similarity ||\n          (a.objectId < b.objectId ? -1 : a.objectId > b.objectId ? 1 : 0),\n      );\n      best = best.slice(0, options.limit);\n      cursor = String(rows[rows.length - 1].id);\n      if (rows.length < batchSize) break;\n    }\n    return best;\n  }\n\n  /**\n   * Ensure the native vector column and index exist on _smrt_embeddings.\n   * Called once during initialization when storage: 'native' is configured.\n   *\n   * @param db - Database interface\n   * @param dimensions - Vector dimensions\n   * @param vector - Vector capabilities\n   */\n  static async ensureVectorStorage(\n    _db: DatabaseInterface,\n    dimensions: number,\n    vector: VectorCapabilities,\n  ): Promise<void> {\n    await vector.ensureColumn('_smrt_embeddings', VECTOR_COLUMN, dimensions);\n    await vector.ensureIndex('_smrt_embeddings', VECTOR_COLUMN, {\n      dimensions,\n      metric: 'cosine',\n      type: 'hnsw',\n    });\n  }\n\n  /**\n   * Get a specific embedding\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @param fieldName - Field name\n   * @param model - Model used\n   * @returns Stored embedding or null\n   */\n  static async get(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n    fieldName: string,\n    model: string,\n  ): Promise<StoredEmbedding | null> {\n    const result = await db.single`\n      SELECT * FROM _smrt_embeddings\n      WHERE object_class = ${objectClass}\n        AND object_id = ${objectId}\n        AND field_name = ${fieldName}\n        AND model = ${model}\n    `;\n\n    if (!result) return null;\n\n    return EmbeddingStorage.parseRow(result);\n  }\n\n  /**\n   * Get all embeddings for an object\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @returns Array of stored embeddings\n   */\n  static async getForObject(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n  ): Promise<StoredEmbedding[]> {\n    const { rows } = await db.query(\n      `SELECT * FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,\n      objectClass,\n      objectId,\n    );\n\n    return rows.map((row: Record<string, unknown>) =>\n      EmbeddingStorage.parseRow(row),\n    );\n  }\n\n  /**\n   * List embeddings for a class (optionally filtered by field and model)\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param fieldName - Optional field filter\n   * @param model - Optional model filter\n   * @returns Array of stored embeddings\n   */\n  static async listForClass(\n    db: DatabaseInterface,\n    objectClass: string,\n    fieldName?: string,\n    model?: string,\n  ): Promise<StoredEmbedding[]> {\n    let sql = `SELECT * FROM _smrt_embeddings WHERE object_class = ?`;\n    const params: unknown[] = [objectClass];\n\n    if (fieldName) {\n      sql += ` AND field_name = ?`;\n      params.push(fieldName);\n    }\n\n    if (model) {\n      sql += ` AND model = ?`;\n      params.push(model);\n    }\n\n    const { rows } = await db.query(sql, ...params);\n\n    return rows.map((row: Record<string, unknown>) =>\n      EmbeddingStorage.parseRow(row),\n    );\n  }\n\n  /**\n   * Get object IDs that have embeddings for a specific field\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param fieldName - Field name\n   * @returns Array of object IDs\n   */\n  static async getObjectIdsWithEmbeddings(\n    db: DatabaseInterface,\n    objectClass: string,\n    fieldName: string,\n  ): Promise<string[]> {\n    const { rows } = await db.query(\n      `SELECT DISTINCT object_id FROM _smrt_embeddings\n       WHERE object_class = ? AND field_name = ?`,\n      objectClass,\n      fieldName,\n    );\n\n    return rows.map((row: Record<string, unknown>) => row.object_id as string);\n  }\n\n  /**\n   * Delete all embeddings for an object\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   */\n  static async deleteForObject(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n  ): Promise<void> {\n    await db.query(\n      `DELETE FROM _smrt_embeddings WHERE object_class = ? AND object_id = ?`,\n      objectClass,\n      objectId,\n    );\n  }\n\n  /**\n   * Delete a specific embedding\n   *\n   * @param db - Database interface\n   * @param objectClass - Class name\n   * @param objectId - Object ID\n   * @param fieldName - Field name\n   * @param model - Model used\n   */\n  static async delete(\n    db: DatabaseInterface,\n    objectClass: string,\n    objectId: string,\n    fieldName: string,\n    model: string,\n  ): Promise<void> {\n    await db.query(\n      `DELETE FROM _smrt_embeddings\n       WHERE object_class = ? AND object_id = ? AND field_name = ? AND model = ?`,\n      objectClass,\n      objectId,\n      fieldName,\n      model,\n    );\n  }\n\n  /**\n   * Check if embedding table exists\n   *\n   * @param db - Database interface\n   * @returns True if table exists\n   */\n  static async tableExists(db: DatabaseInterface): Promise<boolean> {\n    try {\n      await db.query(`SELECT 1 FROM _smrt_embeddings LIMIT 1`);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Parse a database row into StoredEmbedding\n   */\n  private static parseRow(row: Record<string, unknown>): StoredEmbedding {\n    return {\n      id: row.id as string,\n      object_class: row.object_class as string,\n      object_id: row.object_id as string,\n      field_name: row.field_name as string,\n      content_hash: row.content_hash as string,\n      embedding: JSON.parse(row.embedding as string) as number[],\n      model: row.model as string,\n      dimensions: toSafeInteger(row.dimensions, 'Embedding dimensions'),\n      provider: row.provider as string | undefined,\n      created_at: new Date(row.created_at as string),\n      updated_at: new Date(row.updated_at as string),\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  */
 export * from './adapters/index';
 export { buildCascadePlan, type CascadePlan, type CascadePolymorphicReference, type CascadeReference, type CascadeRegistryView, type CascadeResult, cascadeReferencesTo, normalizeOnDelete, type OnDeleteAction, runCascadeDelete, } from './cascade';
-export { type AppendChangeInput, appendChange, bumpChangeFeed, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, type ChangeFeedEntry, type ChangeFeedPage, type ChangeFeedRetention, type ChangeOperation, DEFAULT_CHANGES_LIMIT, drainChangeFeed, ensureChangeFeedTable, type GetChangesOptions, getChangesSince, getTableVersion, getTenantScopedChangesSince, MAX_CHANGES_LIMIT, pruneChangeFeed, registerChangeFeedWriter, resetChangeFeedWarnings, unregisterChangeFeedWriter, } from './change-feed';
+export { type AppendChangeBatch, type AppendChangeInput, appendChange, appendChanges, bumpChangeFeed, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, type ChangeFeedEntry, type ChangeFeedPage, type ChangeFeedRetention, type ChangeOperation, DEFAULT_CHANGES_LIMIT, drainChangeFeed, ensureChangeFeedTable, type GetChangesOptions, getChangesSince, getTableVersion, getTenantScopedChangesSince, MAX_CHANGES_LIMIT, pruneChangeFeed, registerChangeFeedWriter, resetChangeFeedWarnings, unregisterChangeFeedWriter, } from './change-feed';
 export { CHANGE_SIGNAL_CHANNEL, type ChangeSignal, type ChangeSignalListener, resetChangeSignals, stopChangeSignalListeners, subscribeToChangeSignals, } from './change-signals';
 export { applyOneToManyChildAccessors, childAccessorName, } from './child-accessors';
 export * from './class';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,cAAc,kBAAkB,CAAC;AAEjC,OAAO,EACL,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,cAAc,EACnB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,eAAe,EACf,eAAe,EACf,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,eAAe,CAAC;AAKvB,OAAO,EACL,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,+BAA+B,EAC/B,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,EAC7B,+BAA+B,EAC/B,4BAA4B,EAC5B,qBAAqB,EACrB,2BAA2B,EAC3B,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,cAAc,EACnB,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,yBAAyB,EACzB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kCAAkC,EAClC,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACrC,KAAK,2BAA2B,EAChC,KAAK,kCAAkC,EACvC,KAAK,6BAA6B,EAClC,gCAAgC,EAChC,iCAAiC,GAClC,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,EACL,UAAU,EACV,KAAK,IAAI,EACT,KAAK,aAAa,EAClB,UAAU,EACV,IAAI,EACJ,MAAM,EACN,KAAK,mBAAmB,EACxB,SAAS,EACT,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAE5B,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAEhC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,gCAAgC,GACjC,MAAM,qBAAqB,CAAC;AAE7B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,KAAK,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,cAAc,aAAa,CAAC;AAG5B,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,KAAK,eAAe,EACpB,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAE1B,cAAc,kBAAkB,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,0BAA0B,EAC1B,KAAK,iCAAiC,GACvC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,wBAAwB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAC3B,uBAAuB,EACvB,kCAAkC,GACnC,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EACL,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,EACL,kCAAkC,EAClC,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAE1B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIlE,OAAO,EACL,KAAK,oCAAoC,EACzC,6BAA6B,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,GAC7B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,OAAO,EACL,KAAK,mBAAmB,EACxB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,gBAAgB,GACtB,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,cAAc,iBAAiB,CAAC;AAGhC,cAAc,cAAc,CAAC;AAE7B,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EACL,eAAe,EACf,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,cAAc,eAAe,CAAC;AAE9B,OAAO,EACL,KAAK,EACL,cAAc,EACd,OAAO,EACP,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,EACL,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,SAAS,EACT,aAAa,EACb,SAAS,GACV,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,2BAA2B,EAC3B,aAAa,EACb,eAAe,EACf,MAAM,EACN,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -13,7 +13,7 @@ import { isEmbeddedDatabase, isPostgresDatabase, usesEmbeddedRevisionFallback, w
 import { GlobalInterceptors, createInterceptorContext, resolveGetStringFilter } from "./interceptors.js";
 import { detectEngine, generateDDLForEngine } from "./schema/ddl/index.js";
 import { SYSTEM_TABLE_NAMES, getSystemTableShapes } from "./schema/system-table-shapes.js";
-import { CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, DEFAULT_CHANGES_LIMIT, MAX_CHANGES_LIMIT, appendChange, bumpChangeFeed, drainChangeFeed, ensureChangeFeedTable, getChangesSince, getTableVersion, getTenantScopedChangesSince, pruneChangeFeed, registerChangeFeedWriter, resetChangeFeedWarnings, unregisterChangeFeedWriter } from "./change-feed.js";
+import { CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, DEFAULT_CHANGES_LIMIT, MAX_CHANGES_LIMIT, appendChange, appendChanges, bumpChangeFeed, drainChangeFeed, ensureChangeFeedTable, getChangesSince, getTableVersion, getTenantScopedChangesSince, pruneChangeFeed, registerChangeFeedWriter, resetChangeFeedWarnings, unregisterChangeFeedWriter } from "./change-feed.js";
 import { applyOneToManyChildAccessors, childAccessorName } from "./child-accessors.js";
 import { config } from "./config.js";
 import { importOptionalDependency, registerOptionalDependency } from "./lazy-external.js";
@@ -44,7 +44,7 @@ import { SmrtObject } from "./object.js";
 import { isFrameworkBaseClass } from "./registry/framework-base-classes.js";
 import { SMRT_COLLECTION_BASE_NAMES, isSmrtCollectionExtendsName } from "./registry/collection-resolution.js";
 import { ObjectRegistry, smrt } from "./registry.js";
-import { DEFAULT_FACET_LIMIT, MAX_FACET_FIELDS, MAX_FACET_LIMIT, MAX_STI_READ_SCOPE_TYPES, SmrtCollection } from "./collection.js";
+import { DEFAULT_FACET_LIMIT, EmbeddingUnavailableError, MAX_FACET_FIELDS, MAX_FACET_LIMIT, MAX_STI_READ_SCOPE_TYPES, SmrtCollection } from "./collection.js";
 import { executeCollectionReadPlan } from "./collection-read-plan.js";
 import { DEFAULT_DATA_QUERY_PAGE_LIMIT, DEFAULT_DATA_QUERY_RESULT_BYTES, DataQueryValidationError, MAX_DATA_QUERY_CURSOR_LENGTH, MAX_DATA_QUERY_FACETS, MAX_DATA_QUERY_FILTERS, MAX_DATA_QUERY_FILTER_DEPTH, MAX_DATA_QUERY_IN_VALUES, MAX_DATA_QUERY_OFFSET, MAX_DATA_QUERY_PAGE_LIMIT, MAX_DATA_QUERY_REQUEST_BYTES, MAX_DATA_QUERY_RESULT_BYTES, MAX_DATA_QUERY_WARNINGS, canonicalizeDataQuery, createDataQueryFingerprint, normalizeDataQueryRequest, normalizeDataQueryResult, normalizeDataQuerySchema } from "./data-query.js";
 import { isDatabaseInterface, resolveDatabase } from "./database.js";
@@ -92,4 +92,4 @@ import "./system/index.js";
 import { getTestDatabase } from "./testing/database.js";
 import "./tools/index.js";
 import { smrtPlugin } from "./vite-plugin/index.js";
-export { AGENT_SURFACE_HASH_PREFIX, AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, BOOTED_PROVENANCE, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CRUD_OPERATIONS, ConfigurationError, ContentHasher, CosineSimilarity, DEFAULT_AI_COST_RATES, DEFAULT_CHANGES_LIMIT, DEFAULT_DATA_QUERY_PAGE_LIMIT, DEFAULT_DATA_QUERY_RESULT_BYTES, DEFAULT_EMBEDDING_CONFIG, DEFAULT_EVENTS_HEARTBEAT_MS, DEFAULT_EVENTS_MAX_SUBSCRIBERS, DEFAULT_EVENTS_RETRY_AFTER_SECONDS, DEFAULT_FACET_LIMIT, DEFAULT_LEARNING_CONFIG, DEFAULT_LIST_LIMIT, DEFAULT_LIST_ORDER_BY, DEFAULT_POSTGRES_TIMEOUTS, DEFAULT_RETENTION_POLICY, DIAGNOSTICS_DEFAULT_LIMIT, DataQueryValidationError, DatabaseError, Dispatch, DispatchBus, DispatchCollection, DispatchSubscription, DispatchSubscriptionCollection, EmbeddingProvider, EmbeddingStorage, ErrorUtils, FilesystemError, GlobalInterceptors, LearningMemory, LiveSchemaParityError, MAX_CHANGES_LIMIT, MAX_DATA_QUERY_CURSOR_LENGTH, MAX_DATA_QUERY_FACETS, MAX_DATA_QUERY_FILTERS, MAX_DATA_QUERY_FILTER_DEPTH, MAX_DATA_QUERY_IN_VALUES, MAX_DATA_QUERY_OFFSET, MAX_DATA_QUERY_PAGE_LIMIT, MAX_DATA_QUERY_REQUEST_BYTES, MAX_DATA_QUERY_RESULT_BYTES, MAX_DATA_QUERY_WARNINGS, MAX_FACET_FIELDS, MAX_FACET_LIMIT, MAX_LIST_LIMIT, MAX_STI_READ_SCOPE_TYPES, MAX_SYNC_APPLY_BATCH_SIZE, MCPGenerator, MCP_STABLE_CATALOG_TTL_MS, MODULE_DOC_HASH_PREFIX, ManifestBuilder, ManifestGenerator, ManifestManager, MetricsAdapter, NetworkError, ObjectRegistry, PLAYBOOK_PREFLIGHT_CAPABILITY, PLAYBOOK_PREFLIGHT_ROUTE_SEGMENT, POSTGRES_REVISION_GUARD_EXPRESSION, POSTGRES_TIMEOUT_ENV_VARS, PRIVATE_READ_CACHE_CONTROL, PubSubAdapter, QueryBoundsError, QueryOrderByError, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, SYNC_APPLY_ROUTE_SEGMENTS, SYNC_APPLY_UUID_PATTERN, SYSTEM_DIAGNOSTICS_TABLES, SYSTEM_TABLE_NAMES, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applyPostgresPermissions, applyPostgresRuntimeTimeouts, applySyncWritablePolicy, assertPlainJson, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildCascadePlan, buildChangeEventStream, buildCustomActionInputSchema, buildCustomActionInvocationArgs, buildDefaultListOrderBy, buildDomainKnowledgeManifest, bumpChangeFeed, canonicalReadRepresentation, canonicalizeDataQuery, cascadeReferencesTo, changeEventSubscribersAtCapacity, checkLiveSchemaParity, childAccessorName, classifyDatabaseError, classifyDialectMessage, classifyMethodWireability, classifyParameterWireability, clearRetentionTasks, clone, coerceCustomActionArgument, collectForeignKeyOrphanCounts, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createClassNamePredicate, createDataQueryFingerprint, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createManifestClassNamePredicate, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, customActionParameterInputName, declaredTypeAcceptsDate, declaresRuntimeRestRoute, declaresRuntimeRestRouteShape, detectEngine, discoverManifestEntry, discoverScopedPackageDirectories, drainChangeFeed, ensureBootstrapSystemTableCompatibility, ensureCacheInvalidationListener, ensureChangeFeedTable, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, ensureSystemTables, estimateAiUsageCost, eventStreamCapacityExceededResponse, executeCollectionReadPlan, executeToolCall, executeToolCalls, field, findManifestEntryByQualifiedName, foreignKey, formatToolResults, generateDDLForEngine, generateOpenAPISpec, generateSchemaDiff, generateToolFromMethod, generateToolManifest, getAdapterInfo, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getRetentionTasks, getSQLFromDiff, getSystemTableShapes, getTableVersion, getTenantScopedChangesSince, getTestDatabase, handlePlaybookPreflightRoute, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isAbortedTransactionError, isAdvisoryOnlyChange, isApiActionEnabledForObject, isCrudOperation, isCrudToolAction, isDatabaseInterface, isDeterministicDatabaseError, isEmbeddedDatabase, isFrameworkBaseClass, isFromPackage, isLazyConfigSentinel, isManualOrAdvisoryChange, isNotNullViolationError, isPostgresDatabase, isQualifiedName, isRestActionRoutable, isRestRoutePublic, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isTransientDatabaseError, isType, isUniqueViolationError, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, method, migratePostgresSystemTimestamps, normalizeCustomActionFailure, normalizeDataQueryRequest, normalizeDataQueryResult, normalizeDataQuerySchema, normalizeEventsMaxSubscribers, normalizeOnDelete, normalizeTypedHttpError, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, planForeignKeyCreation, planPostgresPermissions, planPostgresSystemTimestampMigrations, postgresRevisionCandidates, postgresRevisionCondition, processSyncApplyBatch, pruneAiUsage, pruneChangeFeed, pruneExpiredContexts, qualifiedNamesEqual, queryStringDecoderFor, readAgentModuleDocs, readDispatchHealth, readJobHealth, readMethodDecoratorConfig, readMigrationStatus, readPackageAgentDoc, readRecentChanges, readRegistryDrift, readScheduleHealth, readSystemDiagnostics, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerCompatibleMethodDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, registerRetentionTask, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveAgentModuleDocPaths, resolveApiMethodExposure, resolveCustomActionMetadata, resolveDatabase, resolveDbCacheKey, resolveDeclaredScopeMismatch, resolveDispatchTenantId, resolveDispatchTenantScope, resolveEffectiveActionMetadata, resolveGetStringFilter, resolveLazyConfig, resolveListLimit, resolveListOffset, resolveMCPToolListCacheHint, resolvePostgresTimeouts, resolveReadCacheControl, resolveRegisteredObjectName, resolveTenantEtagDiscriminator, restFieldReadPermissions, restMethodForApiAction, runCascadeDelete, runRetentionSweep, runWithTenantGate, safeParse, safeStringify, sanitizeMessagePaths, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, snapshotRegistry, sortMCPTools, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, toCustomActionBoolean, toCustomActionDate, toCustomActionNumber, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, unregisterRetentionTask, usesEmbeddedRevisionFallback, validatePostgresPermissionContract, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized, withEmbeddedWriteQueue, withEmbeddedWriteTransaction };
+export { AGENT_SURFACE_HASH_PREFIX, AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, BOOTED_PROVENANCE, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CRUD_OPERATIONS, ConfigurationError, ContentHasher, CosineSimilarity, DEFAULT_AI_COST_RATES, DEFAULT_CHANGES_LIMIT, DEFAULT_DATA_QUERY_PAGE_LIMIT, DEFAULT_DATA_QUERY_RESULT_BYTES, DEFAULT_EMBEDDING_CONFIG, DEFAULT_EVENTS_HEARTBEAT_MS, DEFAULT_EVENTS_MAX_SUBSCRIBERS, DEFAULT_EVENTS_RETRY_AFTER_SECONDS, DEFAULT_FACET_LIMIT, DEFAULT_LEARNING_CONFIG, DEFAULT_LIST_LIMIT, DEFAULT_LIST_ORDER_BY, DEFAULT_POSTGRES_TIMEOUTS, DEFAULT_RETENTION_POLICY, DIAGNOSTICS_DEFAULT_LIMIT, DataQueryValidationError, DatabaseError, Dispatch, DispatchBus, DispatchCollection, DispatchSubscription, DispatchSubscriptionCollection, EmbeddingProvider, EmbeddingStorage, EmbeddingUnavailableError, ErrorUtils, FilesystemError, GlobalInterceptors, LearningMemory, LiveSchemaParityError, MAX_CHANGES_LIMIT, MAX_DATA_QUERY_CURSOR_LENGTH, MAX_DATA_QUERY_FACETS, MAX_DATA_QUERY_FILTERS, MAX_DATA_QUERY_FILTER_DEPTH, MAX_DATA_QUERY_IN_VALUES, MAX_DATA_QUERY_OFFSET, MAX_DATA_QUERY_PAGE_LIMIT, MAX_DATA_QUERY_REQUEST_BYTES, MAX_DATA_QUERY_RESULT_BYTES, MAX_DATA_QUERY_WARNINGS, MAX_FACET_FIELDS, MAX_FACET_LIMIT, MAX_LIST_LIMIT, MAX_STI_READ_SCOPE_TYPES, MAX_SYNC_APPLY_BATCH_SIZE, MCPGenerator, MCP_STABLE_CATALOG_TTL_MS, MODULE_DOC_HASH_PREFIX, ManifestBuilder, ManifestGenerator, ManifestManager, MetricsAdapter, NetworkError, ObjectRegistry, PLAYBOOK_PREFLIGHT_CAPABILITY, PLAYBOOK_PREFLIGHT_ROUTE_SEGMENT, POSTGRES_REVISION_GUARD_EXPRESSION, POSTGRES_TIMEOUT_ENV_VARS, PRIVATE_READ_CACHE_CONTROL, PubSubAdapter, QueryBoundsError, QueryOrderByError, RuntimeError, SMRT_COLLECTION_BASE_NAMES, SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY, SYNC_APPLY_ROUTE_SEGMENTS, SYNC_APPLY_UUID_PATTERN, SYSTEM_DIAGNOSTICS_TABLES, SYSTEM_TABLE_NAMES, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, appendChanges, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applyPostgresPermissions, applyPostgresRuntimeTimeouts, applySyncWritablePolicy, assertPlainJson, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildCascadePlan, buildChangeEventStream, buildCustomActionInputSchema, buildCustomActionInvocationArgs, buildDefaultListOrderBy, buildDomainKnowledgeManifest, bumpChangeFeed, canonicalReadRepresentation, canonicalizeDataQuery, cascadeReferencesTo, changeEventSubscribersAtCapacity, checkLiveSchemaParity, childAccessorName, classifyDatabaseError, classifyDialectMessage, classifyMethodWireability, classifyParameterWireability, clearRetentionTasks, clone, coerceCustomActionArgument, collectForeignKeyOrphanCounts, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createClassNamePredicate, createDataQueryFingerprint, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createManifestClassNamePredicate, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, customActionParameterInputName, declaredTypeAcceptsDate, declaresRuntimeRestRoute, declaresRuntimeRestRouteShape, detectEngine, discoverManifestEntry, discoverScopedPackageDirectories, drainChangeFeed, ensureBootstrapSystemTableCompatibility, ensureCacheInvalidationListener, ensureChangeFeedTable, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, ensureSystemTables, estimateAiUsageCost, eventStreamCapacityExceededResponse, executeCollectionReadPlan, executeToolCall, executeToolCalls, field, findManifestEntryByQualifiedName, foreignKey, formatToolResults, generateDDLForEngine, generateOpenAPISpec, generateSchemaDiff, generateToolFromMethod, generateToolManifest, getAdapterInfo, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getRetentionTasks, getSQLFromDiff, getSystemTableShapes, getTableVersion, getTenantScopedChangesSince, getTestDatabase, handlePlaybookPreflightRoute, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isAbortedTransactionError, isAdvisoryOnlyChange, isApiActionEnabledForObject, isCrudOperation, isCrudToolAction, isDatabaseInterface, isDeterministicDatabaseError, isEmbeddedDatabase, isFrameworkBaseClass, isFromPackage, isLazyConfigSentinel, isManualOrAdvisoryChange, isNotNullViolationError, isPostgresDatabase, isQualifiedName, isRestActionRoutable, isRestRoutePublic, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isTransientDatabaseError, isType, isUniqueViolationError, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, method, migratePostgresSystemTimestamps, normalizeCustomActionFailure, normalizeDataQueryRequest, normalizeDataQueryResult, normalizeDataQuerySchema, normalizeEventsMaxSubscribers, normalizeOnDelete, normalizeTypedHttpError, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, planForeignKeyCreation, planPostgresPermissions, planPostgresSystemTimestampMigrations, postgresRevisionCandidates, postgresRevisionCondition, processSyncApplyBatch, pruneAiUsage, pruneChangeFeed, pruneExpiredContexts, qualifiedNamesEqual, queryStringDecoderFor, readAgentModuleDocs, readDispatchHealth, readJobHealth, readMethodDecoratorConfig, readMigrationStatus, readPackageAgentDoc, readRecentChanges, readRegistryDrift, readScheduleHealth, readSystemDiagnostics, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerCompatibleMethodDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, registerRetentionTask, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveAgentModuleDocPaths, resolveApiMethodExposure, resolveCustomActionMetadata, resolveDatabase, resolveDbCacheKey, resolveDeclaredScopeMismatch, resolveDispatchTenantId, resolveDispatchTenantScope, resolveEffectiveActionMetadata, resolveGetStringFilter, resolveLazyConfig, resolveListLimit, resolveListOffset, resolveMCPToolListCacheHint, resolvePostgresTimeouts, resolveReadCacheControl, resolveRegisteredObjectName, resolveTenantEtagDiscriminator, restFieldReadPermissions, restMethodForApiAction, runCascadeDelete, runRetentionSweep, runWithTenantGate, safeParse, safeStringify, sanitizeMessagePaths, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, snapshotRegistry, sortMCPTools, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, toCustomActionBoolean, toCustomActionDate, toCustomActionNumber, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, unregisterRetentionTask, usesEmbeddedRevisionFallback, validatePostgresPermissionContract, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized, withEmbeddedWriteQueue, withEmbeddedWriteTransaction };

package/dist/interceptors.d.ts

@@ -16,6 +16,22 @@ export interface InterceptorContext {
     /** Additional metadata */
     metadata?: Record<string, unknown>;
 }
+/** One instance and its original context in a compatible bulk lifecycle. */
+export interface BulkMutationEntry {
+    instance: SmrtObject;
+    context: InterceptorContext;
+}
+/**
+ * Explicit consent to grouped persistence. Unknown mutation interceptors retain
+ * the sequential lifecycle. Compatibility must not perform I/O or mutate state.
+ * Before hooks must be pure apart from instance/context mutation: preparation
+ * can discover an unsupported row shape and return to the ordinary lifecycle.
+ */
+export interface BulkMutationCapability {
+    compatible(className: string): boolean;
+    afterSave?(entries: BulkMutationEntry[]): Promise<void>;
+    afterDelete?(entries: BulkMutationEntry[]): Promise<void>;
+}
 /**
  * Options for list operations
  */
@@ -54,6 +70,8 @@ export interface QueryInterceptResult {
  * or return modified data to transform the operation.
  */
 export interface CollectionInterceptor {
+    /** Opt in only when grouping before/persist/after phases is safe. */
+    bulkMutation?: BulkMutationCapability;
     /** Unique identifier for this interceptor (for debugging/unregistration) */
     name?: string;
     /** Priority for execution order (higher = earlier). Default: 0 */
@@ -226,6 +244,10 @@ export declare class GlobalInterceptors {
      * @internal Called by SmrtCollection.query()
      */
     static executeAfterQuery<T extends SmrtObject>(className: string, results: T[], context: InterceptorContext): Promise<T[]>;
+    /** Whether every registered mutation interceptor consents to batching. */
+    static supportsBulkMutation(className: string): boolean;
+    /** Run the approved completion once per interceptor, preserving priority. */
+    static executeBulkAfter(operation: 'afterSave' | 'afterDelete', entries: BulkMutationEntry[]): Promise<void>;
     /**
      * Execute beforeSave interceptors
      * @internal Called by SmrtObject.save()

package/dist/interceptors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"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"}

package/dist/interceptors.js

@@ -158,6 +158,18 @@ var GlobalInterceptors = class {
 		}
 		return result;
 	}
+	/** Whether every registered mutation interceptor consents to batching. */
+	static supportsBulkMutation(className) {
+		return this.interceptors.every((interceptor) => !(interceptor.beforeSave || interceptor.afterSave || interceptor.beforeDelete || interceptor.afterDelete) || interceptor.bulkMutation?.compatible(className) === true);
+	}
+	/** Run the approved completion once per interceptor, preserving priority. */
+	static async executeBulkAfter(operation, entries) {
+		for (const interceptor of this.interceptors) {
+			const bulk = interceptor.bulkMutation?.[operation];
+			if (bulk) await bulk(entries);
+			else for (const { instance, context } of entries) await interceptor[operation]?.(instance, context);
+		}
+	}
 	/**
 	* Execute beforeSave interceptors
 	* @internal Called by SmrtObject.save()

package/dist/interceptors.js.map

@@ -1 +1 @@
-{"version":3,"file":"interceptors.js","names":[],"sources":["../src/interceptors.ts"],"sourcesContent":["/**\n * Global Interceptors System for SMRT Collections and Objects\n *\n * Provides a plugin architecture for intercepting collection and object operations.\n * This enables external packages (like @happyvertical/smrt-tenancy) to register\n * interceptors without creating circular dependencies.\n *\n * Pattern: Static methods on GlobalInterceptors class with globalThis state\n * (matches ObjectRegistry pattern for cross-module state sharing)\n *\n * @example Basic interceptor registration\n * ```typescript\n * import { GlobalInterceptors } from '@happyvertical/smrt-core';\n *\n * // Register a beforeList interceptor\n * GlobalInterceptors.register({\n *   beforeList(className, options) {\n *     console.log(`Listing ${className}`);\n *     return options; // Return modified options\n *   }\n * });\n * ```\n *\n * @example Tenancy interceptor (from smrt-tenancy)\n * ```typescript\n * GlobalInterceptors.register({\n *   beforeList(className, options, context) {\n *     const tenantId = getCurrentTenantId();\n *     if (tenantId && isTenantScoped(className)) {\n *       return {\n *         ...options,\n *         where: { ...options.where, tenantId }\n *       };\n *     }\n *     return options;\n *   },\n *   beforeSave(instance, context) {\n *     // Validate tenant on save\n *   }\n * });\n * ```\n *\n * @see https://github.com/happyvertical/smrt/issues/675\n */\n\nimport type { SmrtObject } from './object.js';\n\n/**\n * Context passed to interceptors with operation metadata\n */\nexport interface InterceptorContext {\n  /** Name of the SMRT class being operated on */\n  className: string;\n  /** Exact registered identity when the simple class name is ambiguous. */\n  qualifiedClassName?: string;\n  /** Name of the collection (if applicable) */\n  collectionName?: string;\n  /** Timestamp of the operation */\n  timestamp: Date;\n  /** Operation type for debugging */\n  operation: 'list' | 'get' | 'query' | 'save' | 'delete';\n  /** Additional metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Options for list operations\n */\nexport interface ListOptions {\n  /** AND-only object or DNF (outer OR, inner AND) collection predicate. */\n  where?: Record<string, unknown> | Record<string, unknown>[][];\n  orderBy?: string | string[];\n  limit?: number;\n  offset?: number;\n  select?: readonly string[];\n  include?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Options for query operations (raw SQL)\n */\nexport interface QueryOptions {\n  /** The raw SQL query */\n  sql: string;\n  /** Query parameters */\n  params: unknown[];\n  /** If true, allow raw SQL on tenant-scoped classes (requires explicit opt-in) */\n  allowRawOnTenantScoped?: boolean;\n}\n\n/**\n * Result from query interceptor - can modify SQL or throw to block\n */\nexport interface QueryInterceptResult {\n  sql: string;\n  params: unknown[];\n}\n\n/**\n * Interface for collection/object interceptors\n *\n * All methods are optional. Return void to pass through unchanged,\n * or return modified data to transform the operation.\n */\nexport interface CollectionInterceptor {\n  /** Unique identifier for this interceptor (for debugging/unregistration) */\n  name?: string;\n\n  /** Priority for execution order (higher = earlier). Default: 0 */\n  priority?: number;\n\n  /**\n   * Called before list() operations\n   * @param className - Name of the class being listed\n   * @param options - List options (where, orderBy, limit, select, etc.)\n   * @param context - Operation context\n   * @returns Modified options or void to pass through\n   */\n  beforeList?(\n    className: string,\n    options: ListOptions,\n    context: InterceptorContext,\n  ): ListOptions | Promise<ListOptions> | void | Promise<void>;\n\n  /**\n   * Called after list() operations with results\n   * @param className - Name of the class\n   * @param results - Array of hydrated instances\n   * @param context - Operation context\n   * @returns Modified results or void to pass through\n   */\n  afterList?<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): T[] | Promise<T[]> | void | Promise<void>;\n\n  /**\n   * Called before get() operations\n   * @param className - Name of the class\n   * @param filter - ID, slug, or filter object\n   * @param context - Operation context\n   * @returns Modified filter or void to pass through\n   */\n  beforeGet?(\n    className: string,\n    filter: string | Record<string, unknown>,\n    context: InterceptorContext,\n  ):\n    | string\n    | Record<string, unknown>\n    | Promise<string | Record<string, unknown>>\n    | void\n    | Promise<void>;\n\n  /**\n   * Called after get() operations with result\n   * @param className - Name of the class\n   * @param instance - Hydrated instance or null if not found\n   * @param context - Operation context\n   * @returns Modified instance, null, or void to pass through\n   */\n  afterGet?<T extends SmrtObject>(\n    className: string,\n    instance: T | null,\n    context: InterceptorContext,\n  ): T | null | Promise<T | null> | void | Promise<void>;\n\n  /**\n   * Called before query() operations (raw SQL)\n   * @param className - Name of the class\n   * @param options - Query options with SQL and params\n   * @param context - Operation context\n   * @returns Modified query options, or throw to block the query\n   */\n  beforeQuery?(\n    className: string,\n    options: QueryOptions,\n    context: InterceptorContext,\n  ):\n    | QueryInterceptResult\n    | Promise<QueryInterceptResult>\n    | void\n    | Promise<void>;\n\n  /**\n   * Called after query() operations with results\n   * @param className - Name of the class\n   * @param results - Array of hydrated instances\n   * @param context - Operation context\n   * @returns Modified results or void to pass through\n   */\n  afterQuery?<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): T[] | Promise<T[]> | void | Promise<void>;\n\n  /**\n   * Called before save() operations\n   * @param instance - The object being saved\n   * @param context - Operation context\n   * @returns void (modify instance in place) or throw to block\n   */\n  beforeSave?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called after save() operations\n   * @param instance - The saved object\n   * @param context - Operation context\n   */\n  afterSave?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called before delete() operations\n   * @param instance - The object being deleted\n   * @param context - Operation context\n   * @returns void or throw to block\n   */\n  beforeDelete?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called after delete() operations\n   * @param instance - The deleted object\n   * @param context - Operation context\n   */\n  afterDelete?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n}\n\n/**\n * Extend globalThis to include interceptors state.\n * Using globalThis ensures all module instances share the same interceptors,\n * which is critical in monorepos where the same package can be loaded\n * from different paths.\n *\n * @see ObjectRegistry for similar pattern\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __smrtInterceptors: unknown[] | undefined;\n}\n\n/**\n * Global Interceptors Registry\n *\n * Manages collection/object interceptors for the SMRT framework.\n * External packages can register interceptors to hook into operations\n * without modifying core code.\n */\nexport class GlobalInterceptors {\n  /**\n   * Get the global interceptors array (lazy-initialized)\n   */\n  private static get interceptors(): CollectionInterceptor[] {\n    if (!globalThis.__smrtInterceptors) {\n      globalThis.__smrtInterceptors = [];\n    }\n    return globalThis.__smrtInterceptors as CollectionInterceptor[];\n  }\n\n  /**\n   * Register an interceptor\n   *\n   * @param interceptor - The interceptor to register\n   * @example\n   * ```typescript\n   * GlobalInterceptors.register({\n   *   name: 'tenancy',\n   *   priority: 100,\n   *   beforeList(className, options) {\n   *     // Add tenant filtering\n   *     return { ...options, where: { ...options.where, tenantId: 'xxx' } };\n   *   }\n   * });\n   * ```\n   */\n  static register(interceptor: CollectionInterceptor): void {\n    // Check for duplicate by name\n    if (interceptor.name) {\n      const existing = this.interceptors.findIndex(\n        (i) => i.name === interceptor.name,\n      );\n      if (existing >= 0) {\n        // Replace existing interceptor with same name\n        this.interceptors[existing] = interceptor;\n        this.sortByPriority();\n        return;\n      }\n    }\n\n    this.interceptors.push(interceptor);\n    this.sortByPriority();\n  }\n\n  /**\n   * Unregister an interceptor by reference or name\n   *\n   * @param interceptorOrName - The interceptor instance or name to remove\n   * @returns true if removed, false if not found\n   */\n  static unregister(\n    interceptorOrName: CollectionInterceptor | string,\n  ): boolean {\n    const idx =\n      typeof interceptorOrName === 'string'\n        ? this.interceptors.findIndex((i) => i.name === interceptorOrName)\n        : this.interceptors.indexOf(interceptorOrName);\n\n    if (idx >= 0) {\n      this.interceptors.splice(idx, 1);\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Clear all interceptors (useful for testing)\n   */\n  static clear(): void {\n    globalThis.__smrtInterceptors = [];\n  }\n\n  /**\n   * Get all registered interceptors (readonly)\n   */\n  static getAll(): readonly CollectionInterceptor[] {\n    return [...this.interceptors];\n  }\n\n  /**\n   * Check if any interceptors are registered\n   */\n  static hasInterceptors(): boolean {\n    return this.interceptors.length > 0;\n  }\n\n  /**\n   * Sort interceptors by priority (higher priority first)\n   */\n  private static sortByPriority(): void {\n    this.interceptors.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────\n  // Execution methods - called by SmrtCollection and SmrtObject\n  // ─────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Execute beforeList interceptors\n   * @internal Called by SmrtCollection.list()\n   */\n  static async executeBeforeList(\n    className: string,\n    options: ListOptions,\n    context: InterceptorContext,\n  ): Promise<ListOptions> {\n    let result = options;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeList) {\n        const modified = await interceptor.beforeList(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterList interceptors\n   * @internal Called by SmrtCollection.list()\n   */\n  static async executeAfterList<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): Promise<T[]> {\n    let result = results;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterList) {\n        const modified = await interceptor.afterList(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified as T[];\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeGet interceptors\n   * @internal Called by SmrtCollection.get()\n   */\n  static async executeBeforeGet(\n    className: string,\n    filter: string | Record<string, unknown>,\n    context: InterceptorContext,\n  ): Promise<string | Record<string, unknown>> {\n    let result = filter;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeGet) {\n        const modified = await interceptor.beforeGet(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterGet interceptors\n   * @internal Called by SmrtCollection.get()\n   */\n  static async executeAfterGet<T extends SmrtObject>(\n    className: string,\n    instance: T | null,\n    context: InterceptorContext,\n  ): Promise<T | null> {\n    let result = instance;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterGet) {\n        const modified = await interceptor.afterGet(className, result, context);\n        if (modified !== undefined) {\n          result = modified as T | null;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeQuery interceptors\n   * @internal Called by SmrtCollection.query()\n   */\n  static async executeBeforeQuery(\n    className: string,\n    options: QueryOptions,\n    context: InterceptorContext,\n  ): Promise<QueryInterceptResult> {\n    let result: QueryInterceptResult = {\n      sql: options.sql,\n      params: options.params,\n    };\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeQuery) {\n        const modified = await interceptor.beforeQuery(\n          className,\n          { ...options, ...result },\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterQuery interceptors\n   * @internal Called by SmrtCollection.query()\n   */\n  static async executeAfterQuery<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): Promise<T[]> {\n    let result = results;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterQuery) {\n        const modified = await interceptor.afterQuery(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified as T[];\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeSave interceptors\n   * @internal Called by SmrtObject.save()\n   */\n  static async executeBeforeSave(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeSave) {\n        await interceptor.beforeSave(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute afterSave interceptors\n   * @internal Called by SmrtObject.save()\n   */\n  static async executeAfterSave(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterSave) {\n        await interceptor.afterSave(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute beforeDelete interceptors\n   * @internal Called by SmrtObject.delete()\n   */\n  static async executeBeforeDelete(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeDelete) {\n        await interceptor.beforeDelete(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute afterDelete interceptors\n   * @internal Called by SmrtObject.delete()\n   */\n  static async executeAfterDelete(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterDelete) {\n        await interceptor.afterDelete(instance, context);\n      }\n    }\n  }\n}\n\n/**\n * Canonical UUID shape used by `SmrtCollection.get()` to decide whether a\n * string filter is an id or a slug.\n */\nconst GET_STRING_FILTER_UUID_PATTERN =\n  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n/**\n * Resolve a string filter to the WHERE shape `SmrtCollection.get()` gives it:\n * a UUID string becomes `{ id }`, anything else becomes the natural-key lookup\n * `{ slug, context: '' }`.\n *\n * This is the single source of truth for that string-filter contract. Any\n * `beforeGet` interceptor that rewrites a string filter into an object filter\n * MUST resolve it through this helper first — the tenancy interceptor used to\n * rewrite every string to `{ id: filter, tenantId }`, which broke get-by-slug\n * under an active tenant context (null on SQLite, a uuid cast error on\n * PostgreSQL native-uuid id columns). See #2365.\n *\n * @param filter - The string filter passed to `get()`\n * @returns The object filter `get()` would build for that string\n */\nexport function resolveGetStringFilter(\n  filter: string,\n): { id: string } | { slug: string; context: string } {\n  return GET_STRING_FILTER_UUID_PATTERN.test(filter)\n    ? { id: filter }\n    : { slug: filter, context: '' };\n}\n\n/**\n * Helper function to create an interceptor context\n * @internal\n */\nexport function createInterceptorContext(\n  className: string,\n  operation: InterceptorContext['operation'],\n  collectionName?: string,\n  metadata?: Record<string, unknown>,\n  qualifiedClassName?: string,\n): InterceptorContext {\n  return {\n    className,\n    collectionName,\n    operation,\n    timestamp: new Date(),\n    metadata,\n    qualifiedClassName,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"interceptors.js","names":[],"sources":["../src/interceptors.ts"],"sourcesContent":["/**\n * Global Interceptors System for SMRT Collections and Objects\n *\n * Provides a plugin architecture for intercepting collection and object operations.\n * This enables external packages (like @happyvertical/smrt-tenancy) to register\n * interceptors without creating circular dependencies.\n *\n * Pattern: Static methods on GlobalInterceptors class with globalThis state\n * (matches ObjectRegistry pattern for cross-module state sharing)\n *\n * @example Basic interceptor registration\n * ```typescript\n * import { GlobalInterceptors } from '@happyvertical/smrt-core';\n *\n * // Register a beforeList interceptor\n * GlobalInterceptors.register({\n *   beforeList(className, options) {\n *     console.log(`Listing ${className}`);\n *     return options; // Return modified options\n *   }\n * });\n * ```\n *\n * @example Tenancy interceptor (from smrt-tenancy)\n * ```typescript\n * GlobalInterceptors.register({\n *   beforeList(className, options, context) {\n *     const tenantId = getCurrentTenantId();\n *     if (tenantId && isTenantScoped(className)) {\n *       return {\n *         ...options,\n *         where: { ...options.where, tenantId }\n *       };\n *     }\n *     return options;\n *   },\n *   beforeSave(instance, context) {\n *     // Validate tenant on save\n *   }\n * });\n * ```\n *\n * @see https://github.com/happyvertical/smrt/issues/675\n */\n\nimport type { SmrtObject } from './object.js';\n\n/**\n * Context passed to interceptors with operation metadata\n */\nexport interface InterceptorContext {\n  /** Name of the SMRT class being operated on */\n  className: string;\n  /** Exact registered identity when the simple class name is ambiguous. */\n  qualifiedClassName?: string;\n  /** Name of the collection (if applicable) */\n  collectionName?: string;\n  /** Timestamp of the operation */\n  timestamp: Date;\n  /** Operation type for debugging */\n  operation: 'list' | 'get' | 'query' | 'save' | 'delete';\n  /** Additional metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/** One instance and its original context in a compatible bulk lifecycle. */\nexport interface BulkMutationEntry {\n  instance: SmrtObject;\n  context: InterceptorContext;\n}\n\n/**\n * Explicit consent to grouped persistence. Unknown mutation interceptors retain\n * the sequential lifecycle. Compatibility must not perform I/O or mutate state.\n * Before hooks must be pure apart from instance/context mutation: preparation\n * can discover an unsupported row shape and return to the ordinary lifecycle.\n */\nexport interface BulkMutationCapability {\n  compatible(className: string): boolean;\n  afterSave?(entries: BulkMutationEntry[]): Promise<void>;\n  afterDelete?(entries: BulkMutationEntry[]): Promise<void>;\n}\n\n/**\n * Options for list operations\n */\nexport interface ListOptions {\n  /** AND-only object or DNF (outer OR, inner AND) collection predicate. */\n  where?: Record<string, unknown> | Record<string, unknown>[][];\n  orderBy?: string | string[];\n  limit?: number;\n  offset?: number;\n  select?: readonly string[];\n  include?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Options for query operations (raw SQL)\n */\nexport interface QueryOptions {\n  /** The raw SQL query */\n  sql: string;\n  /** Query parameters */\n  params: unknown[];\n  /** If true, allow raw SQL on tenant-scoped classes (requires explicit opt-in) */\n  allowRawOnTenantScoped?: boolean;\n}\n\n/**\n * Result from query interceptor - can modify SQL or throw to block\n */\nexport interface QueryInterceptResult {\n  sql: string;\n  params: unknown[];\n}\n\n/**\n * Interface for collection/object interceptors\n *\n * All methods are optional. Return void to pass through unchanged,\n * or return modified data to transform the operation.\n */\nexport interface CollectionInterceptor {\n  /** Opt in only when grouping before/persist/after phases is safe. */\n  bulkMutation?: BulkMutationCapability;\n\n  /** Unique identifier for this interceptor (for debugging/unregistration) */\n  name?: string;\n\n  /** Priority for execution order (higher = earlier). Default: 0 */\n  priority?: number;\n\n  /**\n   * Called before list() operations\n   * @param className - Name of the class being listed\n   * @param options - List options (where, orderBy, limit, select, etc.)\n   * @param context - Operation context\n   * @returns Modified options or void to pass through\n   */\n  beforeList?(\n    className: string,\n    options: ListOptions,\n    context: InterceptorContext,\n  ): ListOptions | Promise<ListOptions> | void | Promise<void>;\n\n  /**\n   * Called after list() operations with results\n   * @param className - Name of the class\n   * @param results - Array of hydrated instances\n   * @param context - Operation context\n   * @returns Modified results or void to pass through\n   */\n  afterList?<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): T[] | Promise<T[]> | void | Promise<void>;\n\n  /**\n   * Called before get() operations\n   * @param className - Name of the class\n   * @param filter - ID, slug, or filter object\n   * @param context - Operation context\n   * @returns Modified filter or void to pass through\n   */\n  beforeGet?(\n    className: string,\n    filter: string | Record<string, unknown>,\n    context: InterceptorContext,\n  ):\n    | string\n    | Record<string, unknown>\n    | Promise<string | Record<string, unknown>>\n    | void\n    | Promise<void>;\n\n  /**\n   * Called after get() operations with result\n   * @param className - Name of the class\n   * @param instance - Hydrated instance or null if not found\n   * @param context - Operation context\n   * @returns Modified instance, null, or void to pass through\n   */\n  afterGet?<T extends SmrtObject>(\n    className: string,\n    instance: T | null,\n    context: InterceptorContext,\n  ): T | null | Promise<T | null> | void | Promise<void>;\n\n  /**\n   * Called before query() operations (raw SQL)\n   * @param className - Name of the class\n   * @param options - Query options with SQL and params\n   * @param context - Operation context\n   * @returns Modified query options, or throw to block the query\n   */\n  beforeQuery?(\n    className: string,\n    options: QueryOptions,\n    context: InterceptorContext,\n  ):\n    | QueryInterceptResult\n    | Promise<QueryInterceptResult>\n    | void\n    | Promise<void>;\n\n  /**\n   * Called after query() operations with results\n   * @param className - Name of the class\n   * @param results - Array of hydrated instances\n   * @param context - Operation context\n   * @returns Modified results or void to pass through\n   */\n  afterQuery?<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): T[] | Promise<T[]> | void | Promise<void>;\n\n  /**\n   * Called before save() operations\n   * @param instance - The object being saved\n   * @param context - Operation context\n   * @returns void (modify instance in place) or throw to block\n   */\n  beforeSave?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called after save() operations\n   * @param instance - The saved object\n   * @param context - Operation context\n   */\n  afterSave?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called before delete() operations\n   * @param instance - The object being deleted\n   * @param context - Operation context\n   * @returns void or throw to block\n   */\n  beforeDelete?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called after delete() operations\n   * @param instance - The deleted object\n   * @param context - Operation context\n   */\n  afterDelete?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n}\n\n/**\n * Extend globalThis to include interceptors state.\n * Using globalThis ensures all module instances share the same interceptors,\n * which is critical in monorepos where the same package can be loaded\n * from different paths.\n *\n * @see ObjectRegistry for similar pattern\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __smrtInterceptors: unknown[] | undefined;\n}\n\n/**\n * Global Interceptors Registry\n *\n * Manages collection/object interceptors for the SMRT framework.\n * External packages can register interceptors to hook into operations\n * without modifying core code.\n */\nexport class GlobalInterceptors {\n  /**\n   * Get the global interceptors array (lazy-initialized)\n   */\n  private static get interceptors(): CollectionInterceptor[] {\n    if (!globalThis.__smrtInterceptors) {\n      globalThis.__smrtInterceptors = [];\n    }\n    return globalThis.__smrtInterceptors as CollectionInterceptor[];\n  }\n\n  /**\n   * Register an interceptor\n   *\n   * @param interceptor - The interceptor to register\n   * @example\n   * ```typescript\n   * GlobalInterceptors.register({\n   *   name: 'tenancy',\n   *   priority: 100,\n   *   beforeList(className, options) {\n   *     // Add tenant filtering\n   *     return { ...options, where: { ...options.where, tenantId: 'xxx' } };\n   *   }\n   * });\n   * ```\n   */\n  static register(interceptor: CollectionInterceptor): void {\n    // Check for duplicate by name\n    if (interceptor.name) {\n      const existing = this.interceptors.findIndex(\n        (i) => i.name === interceptor.name,\n      );\n      if (existing >= 0) {\n        // Replace existing interceptor with same name\n        this.interceptors[existing] = interceptor;\n        this.sortByPriority();\n        return;\n      }\n    }\n\n    this.interceptors.push(interceptor);\n    this.sortByPriority();\n  }\n\n  /**\n   * Unregister an interceptor by reference or name\n   *\n   * @param interceptorOrName - The interceptor instance or name to remove\n   * @returns true if removed, false if not found\n   */\n  static unregister(\n    interceptorOrName: CollectionInterceptor | string,\n  ): boolean {\n    const idx =\n      typeof interceptorOrName === 'string'\n        ? this.interceptors.findIndex((i) => i.name === interceptorOrName)\n        : this.interceptors.indexOf(interceptorOrName);\n\n    if (idx >= 0) {\n      this.interceptors.splice(idx, 1);\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Clear all interceptors (useful for testing)\n   */\n  static clear(): void {\n    globalThis.__smrtInterceptors = [];\n  }\n\n  /**\n   * Get all registered interceptors (readonly)\n   */\n  static getAll(): readonly CollectionInterceptor[] {\n    return [...this.interceptors];\n  }\n\n  /**\n   * Check if any interceptors are registered\n   */\n  static hasInterceptors(): boolean {\n    return this.interceptors.length > 0;\n  }\n\n  /**\n   * Sort interceptors by priority (higher priority first)\n   */\n  private static sortByPriority(): void {\n    this.interceptors.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────\n  // Execution methods - called by SmrtCollection and SmrtObject\n  // ─────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Execute beforeList interceptors\n   * @internal Called by SmrtCollection.list()\n   */\n  static async executeBeforeList(\n    className: string,\n    options: ListOptions,\n    context: InterceptorContext,\n  ): Promise<ListOptions> {\n    let result = options;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeList) {\n        const modified = await interceptor.beforeList(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterList interceptors\n   * @internal Called by SmrtCollection.list()\n   */\n  static async executeAfterList<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): Promise<T[]> {\n    let result = results;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterList) {\n        const modified = await interceptor.afterList(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified as T[];\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeGet interceptors\n   * @internal Called by SmrtCollection.get()\n   */\n  static async executeBeforeGet(\n    className: string,\n    filter: string | Record<string, unknown>,\n    context: InterceptorContext,\n  ): Promise<string | Record<string, unknown>> {\n    let result = filter;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeGet) {\n        const modified = await interceptor.beforeGet(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterGet interceptors\n   * @internal Called by SmrtCollection.get()\n   */\n  static async executeAfterGet<T extends SmrtObject>(\n    className: string,\n    instance: T | null,\n    context: InterceptorContext,\n  ): Promise<T | null> {\n    let result = instance;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterGet) {\n        const modified = await interceptor.afterGet(className, result, context);\n        if (modified !== undefined) {\n          result = modified as T | null;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeQuery interceptors\n   * @internal Called by SmrtCollection.query()\n   */\n  static async executeBeforeQuery(\n    className: string,\n    options: QueryOptions,\n    context: InterceptorContext,\n  ): Promise<QueryInterceptResult> {\n    let result: QueryInterceptResult = {\n      sql: options.sql,\n      params: options.params,\n    };\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeQuery) {\n        const modified = await interceptor.beforeQuery(\n          className,\n          { ...options, ...result },\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterQuery interceptors\n   * @internal Called by SmrtCollection.query()\n   */\n  static async executeAfterQuery<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): Promise<T[]> {\n    let result = results;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterQuery) {\n        const modified = await interceptor.afterQuery(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified as T[];\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /** Whether every registered mutation interceptor consents to batching. */\n  static supportsBulkMutation(className: string): boolean {\n    return this.interceptors.every(\n      (interceptor) =>\n        !(\n          interceptor.beforeSave ||\n          interceptor.afterSave ||\n          interceptor.beforeDelete ||\n          interceptor.afterDelete\n        ) || interceptor.bulkMutation?.compatible(className) === true,\n    );\n  }\n\n  /** Run the approved completion once per interceptor, preserving priority. */\n  static async executeBulkAfter(\n    operation: 'afterSave' | 'afterDelete',\n    entries: BulkMutationEntry[],\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      const bulk = interceptor.bulkMutation?.[operation];\n      if (bulk) {\n        await bulk(entries);\n      } else {\n        for (const { instance, context } of entries) {\n          await interceptor[operation]?.(instance, context);\n        }\n      }\n    }\n  }\n\n  /**\n   * Execute beforeSave interceptors\n   * @internal Called by SmrtObject.save()\n   */\n  static async executeBeforeSave(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeSave) {\n        await interceptor.beforeSave(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute afterSave interceptors\n   * @internal Called by SmrtObject.save()\n   */\n  static async executeAfterSave(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterSave) {\n        await interceptor.afterSave(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute beforeDelete interceptors\n   * @internal Called by SmrtObject.delete()\n   */\n  static async executeBeforeDelete(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeDelete) {\n        await interceptor.beforeDelete(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute afterDelete interceptors\n   * @internal Called by SmrtObject.delete()\n   */\n  static async executeAfterDelete(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterDelete) {\n        await interceptor.afterDelete(instance, context);\n      }\n    }\n  }\n}\n\n/**\n * Canonical UUID shape used by `SmrtCollection.get()` to decide whether a\n * string filter is an id or a slug.\n */\nconst GET_STRING_FILTER_UUID_PATTERN =\n  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n/**\n * Resolve a string filter to the WHERE shape `SmrtCollection.get()` gives it:\n * a UUID string becomes `{ id }`, anything else becomes the natural-key lookup\n * `{ slug, context: '' }`.\n *\n * This is the single source of truth for that string-filter contract. Any\n * `beforeGet` interceptor that rewrites a string filter into an object filter\n * MUST resolve it through this helper first — the tenancy interceptor used to\n * rewrite every string to `{ id: filter, tenantId }`, which broke get-by-slug\n * under an active tenant context (null on SQLite, a uuid cast error on\n * PostgreSQL native-uuid id columns). See #2365.\n *\n * @param filter - The string filter passed to `get()`\n * @returns The object filter `get()` would build for that string\n */\nexport function resolveGetStringFilter(\n  filter: string,\n): { id: string } | { slug: string; context: string } {\n  return GET_STRING_FILTER_UUID_PATTERN.test(filter)\n    ? { id: filter }\n    : { slug: filter, context: '' };\n}\n\n/**\n * Helper function to create an interceptor context\n * @internal\n */\nexport function createInterceptorContext(\n  className: string,\n  operation: InterceptorContext['operation'],\n  collectionName?: string,\n  metadata?: Record<string, unknown>,\n  qualifiedClassName?: string,\n): InterceptorContext {\n  return {\n    className,\n    collectionName,\n    operation,\n    timestamp: new Date(),\n    metadata,\n    qualifiedClassName,\n  };\n}\n"],"mappings":"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"}

package/dist/junction.d.ts

@@ -10,10 +10,16 @@ import { SmrtObject } from './object';
  */
 export type JunctionAttachOptions = Record<string, unknown>;
 /**
- * Options passed to `byLeft` / `byRight` / `detach` — additional WHERE filters
- * narrowing the operation. Keys must match camelCase column names.
+ * Options passed to `byLeft` / `byRight` / `detach`.
+ *
+ * `limit` and `offset` bound reads made through `byLeft` / `byRight`; all
+ * remaining keys are additional WHERE filters narrowing the operation. Keys
+ * must match camelCase column names.
  */
-export type JunctionFilterOptions = Record<string, unknown>;
+export type JunctionFilterOptions = Record<string, unknown> & {
+    limit?: number;
+    offset?: number;
+};
 export declare abstract class SmrtJunction<TItem extends SmrtObject> extends SmrtCollection<TItem> {
     /**
      * Internal marker used by `SmrtCollection.create` to detect that this
@@ -91,6 +97,9 @@ export declare abstract class SmrtJunction<TItem extends SmrtObject> extends Smr
      *  2. Creates a new row for each `rightId`, spreading `opts` into the row data.
      *  3. If `positionField` is set and `opts` doesn't specify it, assigns the array index.
      *
+     * Compatible models use grouped persistence while preserving delete/create
+     * identity and feed semantics. Unsupported hooks, overrides, shapes, or batch
+     * bounds retain the sequential path; see agents/object-runtime.md.
      * Not transactional — partial failure leaves the table in a mixed state.
      * For atomic replaces, wrap the call in your own DB transaction.
      */