@happyvertical/smrt-core 0.43.9 → 0.44.0

package/dist/embedded-write-queue.d.ts

@@ -1,32 +1,4 @@
-/**
- * In-process write serialization for embedded database engines (#2360).
- *
- * File-backed SQLite (libsql) allows one writer at a time and the SDK opens a
- * NEW connection for every null-aware upsert attempt (`transaction("write")`),
- * with no busy timeout on either connection. Any other write on the root
- * connection while such a transaction is open — most commonly the change-feed
- * append that follows every model save — collides as `SQLITE_BUSY`, and under
- * sustained concurrency (a `Promise.all` of creates) the two sides livelock
- * through every retry tier. Before the tenant-led conflict target (#2360) the
- * null-aware path was rare (custom conflict keys with NULL values, #1246);
- * with `tenant_id` leading every tenant-scoped default key, EVERY NULL-tenant
- * (global) create takes it, so the collision became the steady state.
- *
- * The queue makes the process a single writer per database for exactly the
- * two participants of that collision:
- *
- * - a `save()` whose upsert conflict values contain NULL (the only shape the
- *   SDK routes through a second-connection transaction), and
- * - the change-feed append (a root-connection write that follows every save).
- *
- * Each hold is a LEAF database call — never an interceptor or hook — so the
- * queue cannot deadlock on nested saves. PostgreSQL is never serialized here:
- * its null-aware upsert already arbitrates through advisory locks
- * server-side, and cross-process writers exist that an in-process queue could
- * not order anyway (which is also why this queue is a mitigation for embedded
- * engines' in-process writers, not a cross-process guarantee — embedded
- * engines have no cross-process writers in supported deployments).
- */
+import { DatabaseInterface } from '@happyvertical/sql';
 interface QueueableDatabase {
     url?: string;
 }
@@ -37,10 +9,26 @@ interface QueueableDatabase {
  * handle reintroduces the livelock.
  */
 export declare function isEmbeddedDatabase(db: QueueableDatabase): boolean;
+/**
+ * Whether revision compare-and-swap needs the process-local read/upsert path.
+ *
+ * DuckDB/JSON cannot express the timestamp predicate through the generic
+ * update API, and local SQLite has only the process's writers in supported
+ * deployments. Remote LibSQL/Turso is different: other processes may write
+ * the same database, so it must use one conditional UPDATE at the server.
+ */
+export declare function usesEmbeddedRevisionFallback(db: QueueableDatabase): boolean;
 /**
  * Run `operation` after every previously queued write on the same database
  * has settled. When `serialize` is false the operation runs immediately.
  */
 export declare function withEmbeddedWriteQueue<T>(db: QueueableDatabase, serialize: boolean, operation: () => Promise<T>): Promise<T>;
+/**
+ * Serialize a complete embedded root transaction with ordinary model writes.
+ * The transaction handle is registered as a reentrant alias so saves and
+ * change-feed appends inside the callback do not queue behind their own root
+ * transaction.
+ */
+export declare function withEmbeddedWriteTransaction<T>(db: DatabaseInterface, serialize: boolean, operation: (transaction: DatabaseInterface) => Promise<T>): Promise<T>;
 export {};
 //# sourceMappingURL=embedded-write-queue.d.ts.map

package/dist/embedded-write-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-write-queue.d.ts","sourceRoot":"","sources":["../src/embedded-write-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,UAAU,iBAAiB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAMD;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAoBZ"}
+{"version":3,"file":"embedded-write-queue.d.ts","sourceRoot":"","sources":["../src/embedded-write-queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA0C5D,UAAU,iBAAiB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAG3E;AAMD;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,EAAE,EAAE,iBAAiB,EACrB,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,CAAC,WAAW,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GACxD,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/embedded-write-queue.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/embedded-write-queue.ts
 /**
 * In-process write serialization for embedded database engines (#2360).
@@ -13,15 +14,20 @@
 * with `tenant_id` leading every tenant-scoped default key, EVERY NULL-tenant
 * (global) create takes it, so the collision became the steady state.
 *
-* The queue makes the process a single writer per database for exactly the
-* two participants of that collision:
+* The queue makes the process a single writer per embedded database for:
 *
 * - a `save()` whose upsert conflict values contain NULL (the only shape the
 *   SDK routes through a second-connection transaction), and
 * - the change-feed append (a root-connection write that follows every save).
+* - every model save and delete, so the embedded revision-CAS compare/upsert
+*   fallback cannot race an ordinary save, natural-key create, or delete.
+* - a complete root `SmrtObject.withTransaction()` callback, with writes on
+*   its bound handle re-entering the same hold instead of self-deadlocking.
 *
-* Each hold is a LEAF database call — never an interceptor or hook — so the
-* queue cannot deadlock on nested saves. PostgreSQL is never serialized here:
+* Ordinary save/delete holds contain database calls only — never an
+* interceptor or hook. Explicit transaction callbacks are caller-controlled,
+* so their bound model writes re-enter the existing hold. PostgreSQL is never
+* serialized here:
 * its null-aware upsert already arbitrates through advisory locks
 * server-side, and cross-process writers exist that an in-process queue could
 * not order anyway (which is also why this queue is a mitigation for embedded
@@ -31,6 +37,7 @@
 /** Queue tail per database identity (URL string, or the handle itself). */
 var urlQueues = /* @__PURE__ */ new Map();
 var handleQueues = /* @__PURE__ */ new WeakMap();
+var activeQueueKeys = new AsyncLocalStorage();
 /**
 * Whether `db` is an embedded engine (SQLite/DuckDB/JSON — anything that is
 * not PostgreSQL). Handles without a URL are treated as embedded: serializing
@@ -40,6 +47,18 @@ var handleQueues = /* @__PURE__ */ new WeakMap();
 function isEmbeddedDatabase(db) {
 	return !/^postgres(?:ql)?:/iu.test(db?.url ?? "");
 }
+/**
+* Whether revision compare-and-swap needs the process-local read/upsert path.
+*
+* DuckDB/JSON cannot express the timestamp predicate through the generic
+* update API, and local SQLite has only the process's writers in supported
+* deployments. Remote LibSQL/Turso is different: other processes may write
+* the same database, so it must use one conditional UPDATE at the server.
+*/
+function usesEmbeddedRevisionFallback(db) {
+	const url = db?.url ?? "";
+	return isEmbeddedDatabase(db) && !/^(?:https?|libsql):\/\//iu.test(url);
+}
 function queueKey(db) {
 	return typeof db?.url === "string" && db.url.length > 0 ? db.url : db;
 }
@@ -50,7 +69,11 @@ function queueKey(db) {
 async function withEmbeddedWriteQueue(db, serialize, operation) {
 	if (!serialize) return operation();
 	const key = queueKey(db);
-	const next = ((typeof key === "string" ? urlQueues.get(key) : handleQueues.get(key)) ?? Promise.resolve()).then(operation, operation);
+	const active = activeQueueKeys.getStore();
+	if (active?.has(key)) return operation();
+	const previous = (typeof key === "string" ? urlQueues.get(key) : handleQueues.get(key)) ?? Promise.resolve();
+	const run = () => activeQueueKeys.run(/* @__PURE__ */ new Set([...active ?? [], key]), operation);
+	const next = previous.then(run, run);
 	const tail = next.catch(() => void 0);
 	if (typeof key === "string") {
 		urlQueues.set(key, tail);
@@ -60,7 +83,22 @@ async function withEmbeddedWriteQueue(db, serialize, operation) {
 	} else handleQueues.set(key, tail);
 	return next;
 }
+/**
+* Serialize a complete embedded root transaction with ordinary model writes.
+* The transaction handle is registered as a reentrant alias so saves and
+* change-feed appends inside the callback do not queue behind their own root
+* transaction.
+*/
+async function withEmbeddedWriteTransaction(db, serialize, operation) {
+	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));
+	}));
+}
 //#endregion
-export { isEmbeddedDatabase, withEmbeddedWriteQueue };
+export { isEmbeddedDatabase, usesEmbeddedRevisionFallback, withEmbeddedWriteQueue, withEmbeddedWriteTransaction };
 
 //# sourceMappingURL=embedded-write-queue.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"embedded-write-queue.js","names":[],"sources":["../src/embedded-write-queue.ts"],"sourcesContent":["/**\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 database for exactly the\n * two participants of that collision:\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 *\n * Each hold is a LEAF database call — never an interceptor or hook — so the\n * queue cannot deadlock on nested saves. PostgreSQL is never 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>>();\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 !/^postgres(?:ql)?:/iu.test(db?.url ?? '');\n}\n\nfunction queueKey(db: QueueableDatabase): string | object {\n  return typeof db?.url === 'string' && db.url.length > 0 ? db.url : db;\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 previous =\n    (typeof key === 'string' ? urlQueues.get(key) : handleQueues.get(key)) ??\n    Promise.resolve();\n  const next = previous.then(operation, operation);\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,IAAM,4BAAY,IAAI,IAA8B;AACpD,IAAM,+BAAe,IAAI,QAAkC;;;;;;;AAY3D,SAAgB,mBAAmB,IAAgC;CACjE,OAAO,CAAC,sBAAsB,KAAK,IAAI,OAAO,EAAE;AAClD;AAEA,SAAS,SAAS,IAAwC;CACxD,OAAO,OAAO,IAAI,QAAQ,YAAY,GAAG,IAAI,SAAS,IAAI,GAAG,MAAM;AACrE;;;;;AAMA,eAAsB,uBACpB,IACA,WACA,WACY;CACZ,IAAI,CAAC,WAAW,OAAO,UAAU;CAEjC,MAAM,MAAM,SAAS,EAAE;CAIvB,MAAM,SAFH,OAAO,QAAQ,WAAW,UAAU,IAAI,GAAG,IAAI,aAAa,IAAI,GAAG,MACpE,QAAQ,QAAQ,EAAA,CACI,KAAK,WAAW,SAAS;CAG/C,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"}
+{"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 !/^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\nfunction queueKey(db: QueueableDatabase): string | object {\n  return typeof db?.url === 'string' && db.url.length > 0 ? db.url : db;\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,sBAAsB,KAAK,IAAI,OAAO,EAAE;AAClD;;;;;;;;;AAUA,SAAgB,6BAA6B,IAAgC;CAC3E,MAAM,MAAM,IAAI,OAAO;CACvB,OAAO,mBAAmB,EAAE,KAAK,CAAC,4BAA4B,KAAK,GAAG;AACxE;AAEA,SAAS,SAAS,IAAwC;CACxD,OAAO,OAAO,IAAI,QAAQ,YAAY,GAAG,IAAI,SAAS,IAAI,GAAG,MAAM;AACrE;;;;;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"}

package/dist/generators/custom-action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"custom-action.d.ts","sourceRoot":"","sources":["../../src/generators/custom-action.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,CAAC;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,iBAAiB,CAAC;IACzB,8DAA8D;IAC9D,UAAU,EAAE,OAAO,CAAC;IACpB,gEAAgE;IAChE,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,+EAA+E;AAC/E,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAC7D,QAAQ,CAAC,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,IAAI,CAAC,oBAAoB,EAAE,YAAY,CAAC,EACnD,aAAa,EAAE,MAAM,GACpB,MAAM,CAER;AAED,MAAM,WAAW,kCAAkC;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;KAC7C,CAAC;IACF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAED,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1C,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kCAAkC,GAC1C,4BAA4B,CA6B9B;AAED,oEAAoE;AACpE,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,oBAAoB,GAC7B,UAAU,CAuDZ;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,oBAAoB,EAC9B,IAAI,EAAE,QAAQ,GACb,OAAO,EAAE,CAwBX;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,eAAO,MAAM,qCAAqC,0BAA0B,CAAC;AAE7E;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,GACb,mBAAmB,GAAG,SAAS,CA6BjC"}
+{"version":3,"file":"custom-action.d.ts","sourceRoot":"","sources":["../../src/generators/custom-action.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,CAAC;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,iBAAiB,CAAC;IACzB,8DAA8D;IAC9D,UAAU,EAAE,OAAO,CAAC;IACpB,gEAAgE;IAChE,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,+EAA+E;AAC/E,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAC7D,QAAQ,CAAC,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,IAAI,CAAC,oBAAoB,EAAE,YAAY,CAAC,EACnD,aAAa,EAAE,MAAM,GACpB,MAAM,CAER;AAED,MAAM,WAAW,kCAAkC;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;KAC7C,CAAC;IACF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAED,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1C,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kCAAkC,GAC1C,4BAA4B,CAmC9B;AAED,oEAAoE;AACpE,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,oBAAoB,GAC7B,UAAU,CAuDZ;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,oBAAoB,EAC9B,IAAI,EAAE,QAAQ,GACb,OAAO,EAAE,CAwBX;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,eAAO,MAAM,qCAAqC,0BAA0B,CAAC;AAE7E;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,GACb,mBAAmB,GAAG,SAAS,CA6BjC"}

package/dist/generators/custom-action.js

@@ -26,7 +26,7 @@ function resolveCustomActionMetadata(options) {
 		...options.method?.parameters ? { parameters: options.method.parameters } : {},
 		isStatic: options.method?.isStatic === true,
 		effect,
-		idempotent: configured.idempotent ?? effect === "read",
+		idempotent: configured.idempotent ?? false,
 		openWorld: configured.openWorld ?? true
 	};
 }

package/dist/generators/custom-action.js.map

@@ -1 +1 @@
-{"version":3,"file":"custom-action.js","names":[],"sources":["../../src/generators/custom-action.ts"],"sourcesContent":["/**\n * Canonical custom-action metadata and transport-safe result helpers.\n *\n * Custom actions are intentionally distinct from generated CRUD. Their target\n * is derived from method metadata: instance methods target an item and static\n * methods target the collection. API route configuration may shape an HTTP\n * route, but it cannot change a method's receiver.\n */\n\nimport type { ToolEffect } from '../registry/types.js';\nimport type { MethodDefinition } from '../scanner/types.js';\nimport { convertTypeToJsonSchema } from '../tools/tool-generator.js';\n\nexport type CustomActionScope = 'item' | 'collection';\nexport type { ToolEffect } from '../registry/types.js';\n\nexport interface CustomActionMetadata {\n  scope: CustomActionScope;\n  /** An item-targeted action requires its target identifier. */\n  idRequired: boolean;\n  /** Present only when scanner/manifest metadata is available. */\n  parameters?: MethodDefinition['parameters'];\n  /** Collection actions on a model class invoke its static method. */\n  isStatic: boolean;\n  /** Browser/agent-visible effect. Omitted declarations fail closed. */\n  effect?: ToolEffect;\n  /** Whether repeating the action with the same arguments is safe. */\n  idempotent?: boolean;\n  /** Whether the opaque action may interact outside the SMRT application. */\n  openWorld?: boolean;\n}\n\n/** Fully resolved metadata returned by {@link resolveCustomActionMetadata}. */\nexport type ResolvedCustomActionMetadata = CustomActionMetadata &\n  Required<Pick<CustomActionMetadata, 'effect' | 'idempotent' | 'openWorld'>>;\n\n/**\n * Return the transport field for a method parameter. Flat tool and CLI\n * transports reserve `id` for receiver parsing even when a collection action\n * rejects it, so every action parameter named `id` is exposed as `actionId`.\n * REST already has separate path/body namespaces.\n */\nexport function customActionParameterInputName(\n  _metadata: Pick<CustomActionMetadata, 'idRequired'>,\n  parameterName: string,\n): string {\n  return parameterName === 'id' ? 'actionId' : parameterName;\n}\n\nexport interface ResolveCustomActionMetadataOptions {\n  actionName: string;\n  method?: {\n    isStatic?: boolean;\n    parameters?: MethodDefinition['parameters'];\n  };\n  apiConfig?: unknown;\n  /** Collection-class actions have a collection receiver even when non-static. */\n  defaultScope?: CustomActionScope;\n}\n\ntype JsonSchema = Record<string, unknown>;\ntype ToolArgs = Record<string, unknown>;\n\n/**\n * Resolve the target contract shared by MCP, generated REST, CLI discovery,\n * and WebMCP. A missing manifest method retains the historical item-shaped\n * schema; runtime callers may still provide their legacy collection fallback.\n */\nexport function resolveCustomActionMetadata(\n  options: ResolveCustomActionMetadataOptions,\n): ResolvedCustomActionMetadata {\n  const defaultScope =\n    options.defaultScope ?? (options.method?.isStatic ? 'collection' : 'item');\n  const requestedScope = readConfiguredScope(\n    options.apiConfig,\n    options.actionName,\n  );\n  // A route-only scope override cannot manufacture a receiver. A normal\n  // instance method is always item-targeted; a static model method and a\n  // recognized collection-class method are always collection-targeted. Keep\n  // a matching explicit value for diagnostics/config round-tripping only.\n  const scope = requestedScope === defaultScope ? requestedScope : defaultScope;\n  const configured = readConfiguredToolMetadata(\n    options.apiConfig,\n    options.actionName,\n  );\n  const effect = configured.effect ?? 'destructive';\n\n  return {\n    scope,\n    idRequired: scope === 'item',\n    ...(options.method?.parameters\n      ? { parameters: options.method.parameters }\n      : {}),\n    isStatic: options.method?.isStatic === true,\n    effect,\n    idempotent: configured.idempotent ?? effect === 'read',\n    openWorld: configured.openWorld ?? true,\n  };\n}\n\n/** Build the custom-action portion of an MCP/WebMCP JSON Schema. */\nexport function buildCustomActionInputSchema(\n  metadata: CustomActionMetadata,\n): JsonSchema {\n  const properties: Record<string, JsonSchema> = {};\n  const required: string[] = [];\n\n  if (metadata.idRequired) {\n    properties.id = {\n      type: 'string',\n      description: 'ID of the object to execute action on',\n    };\n    required.push('id');\n  }\n\n  // Absent metadata is the legacy options-bag contract. Do not infer direct\n  // positional arguments from runtime function arity: it is lossy after\n  // transpilation and would make discovery non-deterministic.\n  if (!metadata.parameters) {\n    properties.options = {\n      type: 'object',\n      description: 'Additional options for the custom action',\n      additionalProperties: true,\n    };\n  } else if (\n    metadata.parameters.length === 1 &&\n    metadata.parameters[0]?.name === 'options'\n  ) {\n    const parameter = metadata.parameters[0];\n    properties.options = {\n      ...convertTypeToJsonSchema(parameter.type),\n      description: 'Options for the custom action',\n      ...(parameter.default !== undefined\n        ? { default: parameter.default }\n        : {}),\n    };\n    if (!parameter.optional) required.push('options');\n  } else {\n    for (const parameter of metadata.parameters) {\n      const inputName = customActionParameterInputName(\n        metadata,\n        parameter.name,\n      );\n      properties[inputName] = {\n        ...convertTypeToJsonSchema(parameter.type),\n        ...(parameter.default !== undefined\n          ? { default: parameter.default }\n          : {}),\n      };\n      if (!parameter.optional) required.push(inputName);\n    }\n  }\n\n  return {\n    type: 'object',\n    properties,\n    ...(required.length > 0 ? { required } : {}),\n  };\n}\n\n/**\n * Translate a transport object into the method's call arguments. Legacy\n * actions retain their single options-bag invocation; scanner metadata enables\n * an exact positional projection without changing legacy action behavior.\n */\nexport function buildCustomActionInvocationArgs(\n  metadata: CustomActionMetadata,\n  args: ToolArgs,\n): unknown[] {\n  const { id: _id, options, ...directArgs } = args;\n\n  if (!metadata.parameters) {\n    return [\n      isRecord(options) && Object.keys(options).length > 0\n        ? options\n        : directArgs,\n    ];\n  }\n  if (metadata.parameters.length === 0) return [];\n  if (\n    metadata.parameters.length === 1 &&\n    metadata.parameters[0]?.name === 'options'\n  ) {\n    // Preserve `undefined` (and an explicit `null`) so JavaScript default\n    // parameter initializers and intentional null handling retain their native\n    // semantics. Legacy options bags still receive an empty object below.\n    return [options];\n  }\n  return metadata.parameters.map(\n    (parameter) =>\n      args[customActionParameterInputName(metadata, parameter.name)],\n  );\n}\n\n/**\n * Domain-neutral returned-failure convention for custom actions. The explicit\n * `ok: false` marker prevents successful opaque values such as `{ code,\n * message }` from being reclassified as failures by a transport.\n */\nexport interface CustomActionFailure {\n  ok: false;\n  code: string;\n  message: string;\n  status: number;\n  details?: unknown;\n  retryable?: boolean;\n  correlationId?: string;\n}\n\n/** Stable MCP `_meta` member shared with the app discovery contract (#2181). */\nexport const SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY = 'io.happyvertical/smrt';\n\n/**\n * Detect, validate, and redact an explicitly returned custom-action failure.\n * Unknown return values remain opaque successes. `status` defaults to 400 so\n * REST callers receive non-2xx semantics even when an adapter omits it.\n */\nexport function normalizeCustomActionFailure(\n  value: unknown,\n): CustomActionFailure | undefined {\n  if (!isRecord(value) || value.ok !== false) return undefined;\n  if (typeof value.code !== 'string' || typeof value.message !== 'string') {\n    return undefined;\n  }\n\n  const status =\n    typeof value.status === 'number' &&\n    Number.isInteger(value.status) &&\n    value.status >= 400 &&\n    value.status <= 599\n      ? value.status\n      : 400;\n\n  return {\n    ok: false,\n    code: value.code,\n    message: redactText(value.message),\n    status,\n    ...(Object.hasOwn(value, 'details')\n      ? { details: redactValue(value.details) }\n      : {}),\n    ...(typeof value.retryable === 'boolean'\n      ? { retryable: value.retryable }\n      : {}),\n    ...(typeof value.correlationId === 'string'\n      ? { correlationId: value.correlationId }\n      : {}),\n  };\n}\n\nfunction readConfiguredScope(\n  apiConfig: unknown,\n  actionName: string,\n): CustomActionScope | undefined {\n  if (!isRecord(apiConfig) || !isRecord(apiConfig.routes)) return undefined;\n  const route = apiConfig.routes[actionName];\n  return isRecord(route) &&\n    (route.scope === 'item' || route.scope === 'collection')\n    ? route.scope\n    : undefined;\n}\n\nfunction readConfiguredToolMetadata(\n  apiConfig: unknown,\n  actionName: string,\n): {\n  effect?: ToolEffect;\n  idempotent?: boolean;\n  openWorld?: boolean;\n} {\n  if (!isRecord(apiConfig) || !isRecord(apiConfig.routes)) return {};\n  const route = apiConfig.routes[actionName];\n  if (!isRecord(route)) return {};\n  const effect =\n    route.effect === 'read' ||\n    route.effect === 'write' ||\n    route.effect === 'destructive'\n      ? route.effect\n      : undefined;\n  if (\n    effect === 'read' &&\n    (route.method === 'PUT' ||\n      route.method === 'PATCH' ||\n      route.method === 'DELETE')\n  ) {\n    throw new Error(\n      `Custom action ${actionName} cannot declare a read effect for a ${route.method} route`,\n    );\n  }\n  return {\n    ...(effect ? { effect } : {}),\n    ...(typeof route.idempotent === 'boolean'\n      ? { idempotent: route.idempotent }\n      : {}),\n    ...(typeof route.openWorld === 'boolean'\n      ? { openWorld: route.openWorld }\n      : {}),\n  };\n}\n\nfunction redactValue(value: unknown, seen = new WeakSet<object>()): unknown {\n  if (typeof value === 'string') return redactText(value);\n  if (value === null || typeof value !== 'object') return value;\n  if (seen.has(value)) return '[REDACTED]';\n  seen.add(value);\n  if (Array.isArray(value))\n    return value.map((entry) => redactValue(entry, seen));\n  const prototype = Object.getPrototypeOf(value);\n  if (prototype !== Object.prototype && prototype !== null) return '[REDACTED]';\n  const result: Record<string, unknown> = {};\n  for (const [key, nested] of Object.entries(value)) {\n    result[key] = isSensitiveKey(key)\n      ? '[REDACTED]'\n      : redactValue(nested, seen);\n  }\n  return result;\n}\n\nfunction redactText(value: string): string {\n  return value\n    .replace(/\\bBearer\\s+[^\\s,;]+/giu, 'Bearer [REDACTED]')\n    .replace(\n      /\\b(token|secret|password|api[_-]?key)=([^\\s&]+)/giu,\n      '$1=[REDACTED]',\n    );\n}\n\nfunction isSensitiveKey(key: string): boolean {\n  return /(?:token|secret|password|authorization|cookie|credential|api[_-]?key)/iu.test(\n    key,\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n"],"mappings":"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"}
+{"version":3,"file":"custom-action.js","names":[],"sources":["../../src/generators/custom-action.ts"],"sourcesContent":["/**\n * Canonical custom-action metadata and transport-safe result helpers.\n *\n * Custom actions are intentionally distinct from generated CRUD. Their target\n * is derived from method metadata: instance methods target an item and static\n * methods target the collection. API route configuration may shape an HTTP\n * route, but it cannot change a method's receiver.\n */\n\nimport type { ToolEffect } from '../registry/types.js';\nimport type { MethodDefinition } from '../scanner/types.js';\nimport { convertTypeToJsonSchema } from '../tools/tool-generator.js';\n\nexport type CustomActionScope = 'item' | 'collection';\nexport type { ToolEffect } from '../registry/types.js';\n\nexport interface CustomActionMetadata {\n  scope: CustomActionScope;\n  /** An item-targeted action requires its target identifier. */\n  idRequired: boolean;\n  /** Present only when scanner/manifest metadata is available. */\n  parameters?: MethodDefinition['parameters'];\n  /** Collection actions on a model class invoke its static method. */\n  isStatic: boolean;\n  /** Browser/agent-visible effect. Omitted declarations fail closed. */\n  effect?: ToolEffect;\n  /** Whether repeating the action with the same arguments is safe. */\n  idempotent?: boolean;\n  /** Whether the opaque action may interact outside the SMRT application. */\n  openWorld?: boolean;\n}\n\n/** Fully resolved metadata returned by {@link resolveCustomActionMetadata}. */\nexport type ResolvedCustomActionMetadata = CustomActionMetadata &\n  Required<Pick<CustomActionMetadata, 'effect' | 'idempotent' | 'openWorld'>>;\n\n/**\n * Return the transport field for a method parameter. Flat tool and CLI\n * transports reserve `id` for receiver parsing even when a collection action\n * rejects it, so every action parameter named `id` is exposed as `actionId`.\n * REST already has separate path/body namespaces.\n */\nexport function customActionParameterInputName(\n  _metadata: Pick<CustomActionMetadata, 'idRequired'>,\n  parameterName: string,\n): string {\n  return parameterName === 'id' ? 'actionId' : parameterName;\n}\n\nexport interface ResolveCustomActionMetadataOptions {\n  actionName: string;\n  method?: {\n    isStatic?: boolean;\n    parameters?: MethodDefinition['parameters'];\n  };\n  apiConfig?: unknown;\n  /** Collection-class actions have a collection receiver even when non-static. */\n  defaultScope?: CustomActionScope;\n}\n\ntype JsonSchema = Record<string, unknown>;\ntype ToolArgs = Record<string, unknown>;\n\n/**\n * Resolve the target contract shared by MCP, generated REST, CLI discovery,\n * and WebMCP. A missing manifest method retains the historical item-shaped\n * schema; runtime callers may still provide their legacy collection fallback.\n */\nexport function resolveCustomActionMetadata(\n  options: ResolveCustomActionMetadataOptions,\n): ResolvedCustomActionMetadata {\n  const defaultScope =\n    options.defaultScope ?? (options.method?.isStatic ? 'collection' : 'item');\n  const requestedScope = readConfiguredScope(\n    options.apiConfig,\n    options.actionName,\n  );\n  // A route-only scope override cannot manufacture a receiver. A normal\n  // instance method is always item-targeted; a static model method and a\n  // recognized collection-class method are always collection-targeted. Keep\n  // a matching explicit value for diagnostics/config round-tripping only.\n  const scope = requestedScope === defaultScope ? requestedScope : defaultScope;\n  const configured = readConfiguredToolMetadata(\n    options.apiConfig,\n    options.actionName,\n  );\n  const effect = configured.effect ?? 'destructive';\n\n  return {\n    scope,\n    idRequired: scope === 'item',\n    ...(options.method?.parameters\n      ? { parameters: options.method.parameters }\n      : {}),\n    isStatic: options.method?.isStatic === true,\n    effect,\n    // Per-field fail-closed default (#2587, CapabilityDeclaration in\n    // @happyvertical/smrt-types): an omitted `idempotent` resolves to\n    // `false` regardless of the declared `effect` — a declared 'read'\n    // action is not guaranteed idempotent (e.g. a dequeue-shaped read that\n    // advances state), so a caller who wants the idempotent hint must\n    // declare it explicitly.\n    idempotent: configured.idempotent ?? false,\n    openWorld: configured.openWorld ?? true,\n  };\n}\n\n/** Build the custom-action portion of an MCP/WebMCP JSON Schema. */\nexport function buildCustomActionInputSchema(\n  metadata: CustomActionMetadata,\n): JsonSchema {\n  const properties: Record<string, JsonSchema> = {};\n  const required: string[] = [];\n\n  if (metadata.idRequired) {\n    properties.id = {\n      type: 'string',\n      description: 'ID of the object to execute action on',\n    };\n    required.push('id');\n  }\n\n  // Absent metadata is the legacy options-bag contract. Do not infer direct\n  // positional arguments from runtime function arity: it is lossy after\n  // transpilation and would make discovery non-deterministic.\n  if (!metadata.parameters) {\n    properties.options = {\n      type: 'object',\n      description: 'Additional options for the custom action',\n      additionalProperties: true,\n    };\n  } else if (\n    metadata.parameters.length === 1 &&\n    metadata.parameters[0]?.name === 'options'\n  ) {\n    const parameter = metadata.parameters[0];\n    properties.options = {\n      ...convertTypeToJsonSchema(parameter.type),\n      description: 'Options for the custom action',\n      ...(parameter.default !== undefined\n        ? { default: parameter.default }\n        : {}),\n    };\n    if (!parameter.optional) required.push('options');\n  } else {\n    for (const parameter of metadata.parameters) {\n      const inputName = customActionParameterInputName(\n        metadata,\n        parameter.name,\n      );\n      properties[inputName] = {\n        ...convertTypeToJsonSchema(parameter.type),\n        ...(parameter.default !== undefined\n          ? { default: parameter.default }\n          : {}),\n      };\n      if (!parameter.optional) required.push(inputName);\n    }\n  }\n\n  return {\n    type: 'object',\n    properties,\n    ...(required.length > 0 ? { required } : {}),\n  };\n}\n\n/**\n * Translate a transport object into the method's call arguments. Legacy\n * actions retain their single options-bag invocation; scanner metadata enables\n * an exact positional projection without changing legacy action behavior.\n */\nexport function buildCustomActionInvocationArgs(\n  metadata: CustomActionMetadata,\n  args: ToolArgs,\n): unknown[] {\n  const { id: _id, options, ...directArgs } = args;\n\n  if (!metadata.parameters) {\n    return [\n      isRecord(options) && Object.keys(options).length > 0\n        ? options\n        : directArgs,\n    ];\n  }\n  if (metadata.parameters.length === 0) return [];\n  if (\n    metadata.parameters.length === 1 &&\n    metadata.parameters[0]?.name === 'options'\n  ) {\n    // Preserve `undefined` (and an explicit `null`) so JavaScript default\n    // parameter initializers and intentional null handling retain their native\n    // semantics. Legacy options bags still receive an empty object below.\n    return [options];\n  }\n  return metadata.parameters.map(\n    (parameter) =>\n      args[customActionParameterInputName(metadata, parameter.name)],\n  );\n}\n\n/**\n * Domain-neutral returned-failure convention for custom actions. The explicit\n * `ok: false` marker prevents successful opaque values such as `{ code,\n * message }` from being reclassified as failures by a transport.\n */\nexport interface CustomActionFailure {\n  ok: false;\n  code: string;\n  message: string;\n  status: number;\n  details?: unknown;\n  retryable?: boolean;\n  correlationId?: string;\n}\n\n/** Stable MCP `_meta` member shared with the app discovery contract (#2181). */\nexport const SMRT_CUSTOM_ACTION_ERROR_METADATA_KEY = 'io.happyvertical/smrt';\n\n/**\n * Detect, validate, and redact an explicitly returned custom-action failure.\n * Unknown return values remain opaque successes. `status` defaults to 400 so\n * REST callers receive non-2xx semantics even when an adapter omits it.\n */\nexport function normalizeCustomActionFailure(\n  value: unknown,\n): CustomActionFailure | undefined {\n  if (!isRecord(value) || value.ok !== false) return undefined;\n  if (typeof value.code !== 'string' || typeof value.message !== 'string') {\n    return undefined;\n  }\n\n  const status =\n    typeof value.status === 'number' &&\n    Number.isInteger(value.status) &&\n    value.status >= 400 &&\n    value.status <= 599\n      ? value.status\n      : 400;\n\n  return {\n    ok: false,\n    code: value.code,\n    message: redactText(value.message),\n    status,\n    ...(Object.hasOwn(value, 'details')\n      ? { details: redactValue(value.details) }\n      : {}),\n    ...(typeof value.retryable === 'boolean'\n      ? { retryable: value.retryable }\n      : {}),\n    ...(typeof value.correlationId === 'string'\n      ? { correlationId: value.correlationId }\n      : {}),\n  };\n}\n\nfunction readConfiguredScope(\n  apiConfig: unknown,\n  actionName: string,\n): CustomActionScope | undefined {\n  if (!isRecord(apiConfig) || !isRecord(apiConfig.routes)) return undefined;\n  const route = apiConfig.routes[actionName];\n  return isRecord(route) &&\n    (route.scope === 'item' || route.scope === 'collection')\n    ? route.scope\n    : undefined;\n}\n\nfunction readConfiguredToolMetadata(\n  apiConfig: unknown,\n  actionName: string,\n): {\n  effect?: ToolEffect;\n  idempotent?: boolean;\n  openWorld?: boolean;\n} {\n  if (!isRecord(apiConfig) || !isRecord(apiConfig.routes)) return {};\n  const route = apiConfig.routes[actionName];\n  if (!isRecord(route)) return {};\n  const effect =\n    route.effect === 'read' ||\n    route.effect === 'write' ||\n    route.effect === 'destructive'\n      ? route.effect\n      : undefined;\n  if (\n    effect === 'read' &&\n    (route.method === 'PUT' ||\n      route.method === 'PATCH' ||\n      route.method === 'DELETE')\n  ) {\n    throw new Error(\n      `Custom action ${actionName} cannot declare a read effect for a ${route.method} route`,\n    );\n  }\n  return {\n    ...(effect ? { effect } : {}),\n    ...(typeof route.idempotent === 'boolean'\n      ? { idempotent: route.idempotent }\n      : {}),\n    ...(typeof route.openWorld === 'boolean'\n      ? { openWorld: route.openWorld }\n      : {}),\n  };\n}\n\nfunction redactValue(value: unknown, seen = new WeakSet<object>()): unknown {\n  if (typeof value === 'string') return redactText(value);\n  if (value === null || typeof value !== 'object') return value;\n  if (seen.has(value)) return '[REDACTED]';\n  seen.add(value);\n  if (Array.isArray(value))\n    return value.map((entry) => redactValue(entry, seen));\n  const prototype = Object.getPrototypeOf(value);\n  if (prototype !== Object.prototype && prototype !== null) return '[REDACTED]';\n  const result: Record<string, unknown> = {};\n  for (const [key, nested] of Object.entries(value)) {\n    result[key] = isSensitiveKey(key)\n      ? '[REDACTED]'\n      : redactValue(nested, seen);\n  }\n  return result;\n}\n\nfunction redactText(value: string): string {\n  return value\n    .replace(/\\bBearer\\s+[^\\s,;]+/giu, 'Bearer [REDACTED]')\n    .replace(\n      /\\b(token|secret|password|api[_-]?key)=([^\\s&]+)/giu,\n      '$1=[REDACTED]',\n    );\n}\n\nfunction isSensitiveKey(key: string): boolean {\n  return /(?:token|secret|password|authorization|cookie|credential|api[_-]?key)/iu.test(\n    key,\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n"],"mappings":"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"}

package/dist/generators/mcp-emit.d.ts

@@ -16,9 +16,9 @@
  *   `node .smrt/mcp-server/index.js` runs instead of dying on
  *   `SyntaxError: Unexpected identifier 'CallToolRequest'`.
  *
- * Transpilation uses the `typescript` package that `@happyvertical/smrt-core`
- * already depends on, imported lazily so that merely importing the generators
- * does not pull the compiler into memory.
+ * Transpilation uses `oxc-transform`, which strips the generated source's
+ * erasable TypeScript syntax without making the TypeScript compiler a runtime
+ * dependency of `@happyvertical/smrt-core` (#2339).
  */
 /** Language a generated file is written in, derived from its extension. */
 export type GeneratedSourceLanguage = 'typescript' | 'javascript';
@@ -49,10 +49,9 @@ export declare function generatedSiblingExtension(outputPath: string): Generated
 /**
  * Transpile generated TypeScript to runnable ESM JavaScript.
  *
- * `verbatimModuleSyntax` keeps every value import the template emits (an
- * unused-looking import must not be elided: the generated server relies on
- * side effects and on imports whose only use is inside emitted switch cases),
- * while type-only import specifiers are dropped.
+ * Generated source is constrained to erasable TypeScript syntax, so OXC can
+ * strip annotations and type-only import specifiers while leaving the ES
+ * module's runtime imports intact.
  *
  * @param source - Generated TypeScript source
  * @param label - Target path or name reported in transpile diagnostics

package/dist/generators/mcp-emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-emit.d.ts","sourceRoot":"","sources":["../../src/generators/mcp-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG,YAAY,CAAC;AAElE,wDAAwD;AACxD,MAAM,MAAM,wBAAwB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAqBvE;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,GACjB,uBAAuB,CAQzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,GACjB,wBAAwB,CAO1B;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,KAAK,SAAyB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAiCjB;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,uBAAuB,EACjC,KAAK,SAAyB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAKjB"}
+{"version":3,"file":"mcp-emit.d.ts","sourceRoot":"","sources":["../../src/generators/mcp-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG,YAAY,CAAC;AAElE,wDAAwD;AACxD,MAAM,MAAM,wBAAwB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAiCvE;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,GACjB,uBAAuB,CAQzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,GACjB,wBAAwB,CAO1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,KAAK,SAAyB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAejB;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,uBAAuB,EACjC,KAAK,SAAyB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAKjB"}

package/dist/generators/mcp-emit.js

@@ -5,6 +5,15 @@ var TYPESCRIPT_EXTENSIONS = [".ts", ".mts"];
 * so a CommonJS target can never run whatever language it is written in.
 */
 var COMMONJS_EXTENSIONS = [".cjs", ".cts"];
+/**
+* Load OXC only for JavaScript emission. Core exports every generator from its
+* package root, so loading native OXC bindings at module evaluation would make
+* ordinary ORM and TypeScript-output consumers depend on this optional path.
+*/
+async function loadOxcTransform() {
+	const { transform } = await import("oxc-transform");
+	return transform;
+}
 function assertModuleTarget(outputPath, lowerCased) {
 	const commonJs = COMMONJS_EXTENSIONS.find((extension) => lowerCased.endsWith(extension));
 	if (commonJs) throw new Error(`Cannot generate an MCP server at '${outputPath}': the generated server is an ES module, so a ${commonJs} target cannot run. Use .js/.mjs for JavaScript or .ts/.mts for TypeScript.`);
@@ -43,22 +52,11 @@ function generatedSiblingExtension(outputPath) {
 	return ".js";
 }
 /**
-* Load the TypeScript compiler API lazily.
-*
-* `typescript` is CommonJS: Node's ESM interop exposes the whole API on
-* `default`, while bundlers hand back the namespace itself.
-*/
-async function loadTypeScript() {
-	const imported = await import("typescript");
-	return imported.default ?? imported;
-}
-/**
 * Transpile generated TypeScript to runnable ESM JavaScript.
 *
-* `verbatimModuleSyntax` keeps every value import the template emits (an
-* unused-looking import must not be elided: the generated server relies on
-* side effects and on imports whose only use is inside emitted switch cases),
-* while type-only import specifiers are dropped.
+* Generated source is constrained to erasable TypeScript syntax, so OXC can
+* strip annotations and type-only import specifiers while leaving the ES
+* module's runtime imports intact.
 *
 * @param source - Generated TypeScript source
 * @param label - Target path or name reported in transpile diagnostics
@@ -66,25 +64,15 @@ async function loadTypeScript() {
 * @throws When the generated source is not valid TypeScript
 */
 async function transpileGeneratedSource(source, label = "generated MCP source") {
-	const ts = await loadTypeScript();
-	const { outputText, diagnostics } = ts.transpileModule(source, {
-		fileName: "smrt-generated-mcp-source.ts",
-		reportDiagnostics: true,
-		compilerOptions: {
-			target: ts.ScriptTarget.ESNext,
-			module: ts.ModuleKind.ESNext,
-			moduleResolution: ts.ModuleResolutionKind.Bundler,
-			verbatimModuleSyntax: true,
-			removeComments: false,
-			newLine: ts.NewLineKind.LineFeed
-		}
+	const { code, errors } = await (await loadOxcTransform())("smrt-generated-mcp-source.ts", source, {
+		lang: "ts",
+		sourceType: "module"
 	});
-	const errors = (diagnostics ?? []).filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
 	if (errors.length > 0) {
-		const details = errors.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, " ")).join("; ");
+		const details = errors.map((diagnostic) => diagnostic.message).join("; ");
 		throw new Error(`Failed to transpile generated MCP source (${label}): ${details}`);
 	}
-	return outputText;
+	return code;
 }
 /**
 * Render generated TypeScript for the requested output language.

package/dist/generators/mcp-emit.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-emit.js","names":[],"sources":["../../src/generators/mcp-emit.ts"],"sourcesContent":["/**\n * Emit helpers for generated MCP server sources.\n *\n * The MCP generators build their output as TypeScript source: the runtime\n * template carries type-only imports, type annotations, and generics. Whatever\n * the caller asked for as `outputPath` decides how that source has to be\n * written (#2279):\n *\n * - `.ts` / `.mts` — write the TypeScript verbatim. The consumer runs it\n *   through `tsx` or Node's type stripping, which is what the repository's own\n *   MCP conformance fixture does. The generated source therefore has to stay\n *   erasable-syntax-only.\n * - `.cjs` / `.cts` — rejected. Generated servers are ES modules, so a\n *   CommonJS target cannot run in any language.\n * - anything else (`.js` by default) — transpile to JavaScript first, so\n *   `node .smrt/mcp-server/index.js` runs instead of dying on\n *   `SyntaxError: Unexpected identifier 'CallToolRequest'`.\n *\n * Transpilation uses the `typescript` package that `@happyvertical/smrt-core`\n * already depends on, imported lazily so that merely importing the generators\n * does not pull the compiler into memory.\n */\n\n/** Language a generated file is written in, derived from its extension. */\nexport type GeneratedSourceLanguage = 'typescript' | 'javascript';\n\n/** Extension a generated module may be written with. */\nexport type GeneratedSourceExtension = '.ts' | '.mts' | '.js' | '.mjs';\n\nconst TYPESCRIPT_EXTENSIONS = ['.ts', '.mts'];\n\n/**\n * Generated servers are ES modules — they use `import` and `import.meta.url` —\n * so a CommonJS target can never run whatever language it is written in.\n */\nconst COMMONJS_EXTENSIONS = ['.cjs', '.cts'];\n\nfunction assertModuleTarget(outputPath: string, lowerCased: string): void {\n  const commonJs = COMMONJS_EXTENSIONS.find((extension) =>\n    lowerCased.endsWith(extension),\n  );\n  if (commonJs) {\n    throw new Error(\n      `Cannot generate an MCP server at '${outputPath}': the generated server is an ES module, so a ${commonJs} target cannot run. Use .js/.mjs for JavaScript or .ts/.mts for TypeScript.`,\n    );\n  }\n}\n\n/**\n * Decide how a generated file must be written from the path the caller asked\n * for. Unknown extensions emit JavaScript: `node` is the documented way to run\n * a generated server, so JavaScript is the safe default.\n *\n * @param outputPath - Path the generated file will be written to\n * @returns The language the file contents must be written in\n * @throws When the path asks for a CommonJS target\n */\nexport function resolveGeneratedSourceLanguage(\n  outputPath: string,\n): GeneratedSourceLanguage {\n  const lowerCased = outputPath.toLowerCase();\n  assertModuleTarget(outputPath, lowerCased);\n  return TYPESCRIPT_EXTENSIONS.some((extension) =>\n    lowerCased.endsWith(extension),\n  )\n    ? 'typescript'\n    : 'javascript';\n}\n\n/**\n * Extension for modules emitted alongside a generated entry point, so the\n * modular server's relative imports resolve to files that exist on disk *and*\n * are loaded with the entry's own module semantics. An `.mjs` entry point in a\n * CommonJS package needs `.mjs` siblings, not `.js` ones that Node would then\n * parse as CommonJS.\n *\n * @param outputPath - Path of the generated entry point\n * @returns The extension every sibling module is written with\n * @throws When the path asks for a CommonJS target\n */\nexport function generatedSiblingExtension(\n  outputPath: string,\n): GeneratedSourceExtension {\n  const lowerCased = outputPath.toLowerCase();\n  assertModuleTarget(outputPath, lowerCased);\n  if (lowerCased.endsWith('.mts')) return '.mts';\n  if (lowerCased.endsWith('.ts')) return '.ts';\n  if (lowerCased.endsWith('.mjs')) return '.mjs';\n  return '.js';\n}\n\ntype TypeScriptApi = typeof import('typescript');\n\n/**\n * Load the TypeScript compiler API lazily.\n *\n * `typescript` is CommonJS: Node's ESM interop exposes the whole API on\n * `default`, while bundlers hand back the namespace itself.\n */\nasync function loadTypeScript(): Promise<TypeScriptApi> {\n  const imported = (await import('typescript')) as TypeScriptApi & {\n    default?: TypeScriptApi;\n  };\n  return imported.default ?? imported;\n}\n\n/**\n * Transpile generated TypeScript to runnable ESM JavaScript.\n *\n * `verbatimModuleSyntax` keeps every value import the template emits (an\n * unused-looking import must not be elided: the generated server relies on\n * side effects and on imports whose only use is inside emitted switch cases),\n * while type-only import specifiers are dropped.\n *\n * @param source - Generated TypeScript source\n * @param label - Target path or name reported in transpile diagnostics\n * @returns Equivalent JavaScript source\n * @throws When the generated source is not valid TypeScript\n */\nexport async function transpileGeneratedSource(\n  source: string,\n  label = 'generated MCP source',\n): Promise<string> {\n  const ts = await loadTypeScript();\n\n  const { outputText, diagnostics } = ts.transpileModule(source, {\n    // The input is always TypeScript regardless of where it will be written;\n    // a `.js` file name here would make the compiler parse it as JavaScript.\n    fileName: 'smrt-generated-mcp-source.ts',\n    reportDiagnostics: true,\n    compilerOptions: {\n      target: ts.ScriptTarget.ESNext,\n      module: ts.ModuleKind.ESNext,\n      moduleResolution: ts.ModuleResolutionKind.Bundler,\n      verbatimModuleSyntax: true,\n      removeComments: false,\n      newLine: ts.NewLineKind.LineFeed,\n    },\n  });\n\n  const errors = (diagnostics ?? []).filter(\n    (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,\n  );\n  if (errors.length > 0) {\n    const details = errors\n      .map((diagnostic) =>\n        ts.flattenDiagnosticMessageText(diagnostic.messageText, ' '),\n      )\n      .join('; ');\n    throw new Error(\n      `Failed to transpile generated MCP source (${label}): ${details}`,\n    );\n  }\n\n  return outputText;\n}\n\n/**\n * Render generated TypeScript for the requested output language.\n *\n * @param source - Generated TypeScript source\n * @param language - Language the file must be written in\n * @param label - Target path or name reported in transpile diagnostics\n * @returns Source ready to be written to disk\n */\nexport async function renderGeneratedSource(\n  source: string,\n  language: GeneratedSourceLanguage,\n  label = 'generated MCP source',\n): Promise<string> {\n  if (language === 'typescript') {\n    return source;\n  }\n  return transpileGeneratedSource(source, label);\n}\n"],"mappings":";AA6BA,IAAM,wBAAwB,CAAC,OAAO,MAAM;;;;;AAM5C,IAAM,sBAAsB,CAAC,QAAQ,MAAM;AAE3C,SAAS,mBAAmB,YAAoB,YAA0B;CACxE,MAAM,WAAW,oBAAoB,MAAM,cACzC,WAAW,SAAS,SAAS,CAC/B;CACA,IAAI,UACF,MAAM,IAAI,MACR,qCAAqC,WAAW,gDAAgD,SAAS,4EAC3G;AAEJ;;;;;;;;;;AAWA,SAAgB,+BACd,YACyB;CACzB,MAAM,aAAa,WAAW,YAAY;CAC1C,mBAAmB,YAAY,UAAU;CACzC,OAAO,sBAAsB,MAAM,cACjC,WAAW,SAAS,SAAS,CAC/B,IACI,eACA;AACN;;;;;;;;;;;;AAaA,SAAgB,0BACd,YAC0B;CAC1B,MAAM,aAAa,WAAW,YAAY;CAC1C,mBAAmB,YAAY,UAAU;CACzC,IAAI,WAAW,SAAS,MAAM,GAAG,OAAO;CACxC,IAAI,WAAW,SAAS,KAAK,GAAG,OAAO;CACvC,IAAI,WAAW,SAAS,MAAM,GAAG,OAAO;CACxC,OAAO;AACT;;;;;;;AAUA,eAAe,iBAAyC;CACtD,MAAM,WAAY,MAAM,OAAO;CAG/B,OAAO,SAAS,WAAW;AAC7B;;;;;;;;;;;;;;AAeA,eAAsB,yBACpB,QACA,QAAQ,wBACS;CACjB,MAAM,KAAK,MAAM,eAAe;CAEhC,MAAM,EAAE,YAAY,gBAAgB,GAAG,gBAAgB,QAAQ;EAG7D,UAAU;EACV,mBAAmB;EACnB,iBAAiB;GACf,QAAQ,GAAG,aAAa;GACxB,QAAQ,GAAG,WAAW;GACtB,kBAAkB,GAAG,qBAAqB;GAC1C,sBAAsB;GACtB,gBAAgB;GAChB,SAAS,GAAG,YAAY;EAC1B;CACF,CAAC;CAED,MAAM,UAAU,eAAe,CAAC,EAAA,CAAG,QAChC,eAAe,WAAW,aAAa,GAAG,mBAAmB,KAChE;CACA,IAAI,OAAO,SAAS,GAAG;EACrB,MAAM,UAAU,OACb,KAAK,eACJ,GAAG,6BAA6B,WAAW,aAAa,GAAG,CAC7D,CAAC,CACA,KAAK,IAAI;EACZ,MAAM,IAAI,MACR,6CAA6C,MAAM,KAAK,SAC1D;CACF;CAEA,OAAO;AACT;;;;;;;;;AAUA,eAAsB,sBACpB,QACA,UACA,QAAQ,wBACS;CACjB,IAAI,aAAa,cACf,OAAO;CAET,OAAO,yBAAyB,QAAQ,KAAK;AAC/C"}
+{"version":3,"file":"mcp-emit.js","names":[],"sources":["../../src/generators/mcp-emit.ts"],"sourcesContent":["/**\n * Emit helpers for generated MCP server sources.\n *\n * The MCP generators build their output as TypeScript source: the runtime\n * template carries type-only imports, type annotations, and generics. Whatever\n * the caller asked for as `outputPath` decides how that source has to be\n * written (#2279):\n *\n * - `.ts` / `.mts` — write the TypeScript verbatim. The consumer runs it\n *   through `tsx` or Node's type stripping, which is what the repository's own\n *   MCP conformance fixture does. The generated source therefore has to stay\n *   erasable-syntax-only.\n * - `.cjs` / `.cts` — rejected. Generated servers are ES modules, so a\n *   CommonJS target cannot run in any language.\n * - anything else (`.js` by default) — transpile to JavaScript first, so\n *   `node .smrt/mcp-server/index.js` runs instead of dying on\n *   `SyntaxError: Unexpected identifier 'CallToolRequest'`.\n *\n * Transpilation uses `oxc-transform`, which strips the generated source's\n * erasable TypeScript syntax without making the TypeScript compiler a runtime\n * dependency of `@happyvertical/smrt-core` (#2339).\n */\n\n/** Language a generated file is written in, derived from its extension. */\nexport type GeneratedSourceLanguage = 'typescript' | 'javascript';\n\n/** Extension a generated module may be written with. */\nexport type GeneratedSourceExtension = '.ts' | '.mts' | '.js' | '.mjs';\n\nconst TYPESCRIPT_EXTENSIONS = ['.ts', '.mts'];\n\n/**\n * Generated servers are ES modules — they use `import` and `import.meta.url` —\n * so a CommonJS target can never run whatever language it is written in.\n */\nconst COMMONJS_EXTENSIONS = ['.cjs', '.cts'];\n\ntype OxcTransform = typeof import('oxc-transform').transform;\n\n/**\n * Load OXC only for JavaScript emission. Core exports every generator from its\n * package root, so loading native OXC bindings at module evaluation would make\n * ordinary ORM and TypeScript-output consumers depend on this optional path.\n */\nasync function loadOxcTransform(): Promise<OxcTransform> {\n  const { transform } = await import('oxc-transform');\n  return transform;\n}\n\nfunction assertModuleTarget(outputPath: string, lowerCased: string): void {\n  const commonJs = COMMONJS_EXTENSIONS.find((extension) =>\n    lowerCased.endsWith(extension),\n  );\n  if (commonJs) {\n    throw new Error(\n      `Cannot generate an MCP server at '${outputPath}': the generated server is an ES module, so a ${commonJs} target cannot run. Use .js/.mjs for JavaScript or .ts/.mts for TypeScript.`,\n    );\n  }\n}\n\n/**\n * Decide how a generated file must be written from the path the caller asked\n * for. Unknown extensions emit JavaScript: `node` is the documented way to run\n * a generated server, so JavaScript is the safe default.\n *\n * @param outputPath - Path the generated file will be written to\n * @returns The language the file contents must be written in\n * @throws When the path asks for a CommonJS target\n */\nexport function resolveGeneratedSourceLanguage(\n  outputPath: string,\n): GeneratedSourceLanguage {\n  const lowerCased = outputPath.toLowerCase();\n  assertModuleTarget(outputPath, lowerCased);\n  return TYPESCRIPT_EXTENSIONS.some((extension) =>\n    lowerCased.endsWith(extension),\n  )\n    ? 'typescript'\n    : 'javascript';\n}\n\n/**\n * Extension for modules emitted alongside a generated entry point, so the\n * modular server's relative imports resolve to files that exist on disk *and*\n * are loaded with the entry's own module semantics. An `.mjs` entry point in a\n * CommonJS package needs `.mjs` siblings, not `.js` ones that Node would then\n * parse as CommonJS.\n *\n * @param outputPath - Path of the generated entry point\n * @returns The extension every sibling module is written with\n * @throws When the path asks for a CommonJS target\n */\nexport function generatedSiblingExtension(\n  outputPath: string,\n): GeneratedSourceExtension {\n  const lowerCased = outputPath.toLowerCase();\n  assertModuleTarget(outputPath, lowerCased);\n  if (lowerCased.endsWith('.mts')) return '.mts';\n  if (lowerCased.endsWith('.ts')) return '.ts';\n  if (lowerCased.endsWith('.mjs')) return '.mjs';\n  return '.js';\n}\n\n/**\n * Transpile generated TypeScript to runnable ESM JavaScript.\n *\n * Generated source is constrained to erasable TypeScript syntax, so OXC can\n * strip annotations and type-only import specifiers while leaving the ES\n * module's runtime imports intact.\n *\n * @param source - Generated TypeScript source\n * @param label - Target path or name reported in transpile diagnostics\n * @returns Equivalent JavaScript source\n * @throws When the generated source is not valid TypeScript\n */\nexport async function transpileGeneratedSource(\n  source: string,\n  label = 'generated MCP source',\n): Promise<string> {\n  const transform = await loadOxcTransform();\n  const { code, errors } = await transform(\n    'smrt-generated-mcp-source.ts',\n    source,\n    { lang: 'ts', sourceType: 'module' },\n  );\n  if (errors.length > 0) {\n    const details = errors.map((diagnostic) => diagnostic.message).join('; ');\n    throw new Error(\n      `Failed to transpile generated MCP source (${label}): ${details}`,\n    );\n  }\n\n  return code;\n}\n\n/**\n * Render generated TypeScript for the requested output language.\n *\n * @param source - Generated TypeScript source\n * @param language - Language the file must be written in\n * @param label - Target path or name reported in transpile diagnostics\n * @returns Source ready to be written to disk\n */\nexport async function renderGeneratedSource(\n  source: string,\n  language: GeneratedSourceLanguage,\n  label = 'generated MCP source',\n): Promise<string> {\n  if (language === 'typescript') {\n    return source;\n  }\n  return transpileGeneratedSource(source, label);\n}\n"],"mappings":";AA6BA,IAAM,wBAAwB,CAAC,OAAO,MAAM;;;;;AAM5C,IAAM,sBAAsB,CAAC,QAAQ,MAAM;;;;;;AAS3C,eAAe,mBAA0C;CACvD,MAAM,EAAE,cAAc,MAAM,OAAO;CACnC,OAAO;AACT;AAEA,SAAS,mBAAmB,YAAoB,YAA0B;CACxE,MAAM,WAAW,oBAAoB,MAAM,cACzC,WAAW,SAAS,SAAS,CAC/B;CACA,IAAI,UACF,MAAM,IAAI,MACR,qCAAqC,WAAW,gDAAgD,SAAS,4EAC3G;AAEJ;;;;;;;;;;AAWA,SAAgB,+BACd,YACyB;CACzB,MAAM,aAAa,WAAW,YAAY;CAC1C,mBAAmB,YAAY,UAAU;CACzC,OAAO,sBAAsB,MAAM,cACjC,WAAW,SAAS,SAAS,CAC/B,IACI,eACA;AACN;;;;;;;;;;;;AAaA,SAAgB,0BACd,YAC0B;CAC1B,MAAM,aAAa,WAAW,YAAY;CAC1C,mBAAmB,YAAY,UAAU;CACzC,IAAI,WAAW,SAAS,MAAM,GAAG,OAAO;CACxC,IAAI,WAAW,SAAS,KAAK,GAAG,OAAO;CACvC,IAAI,WAAW,SAAS,MAAM,GAAG,OAAO;CACxC,OAAO;AACT;;;;;;;;;;;;;AAcA,eAAsB,yBACpB,QACA,QAAQ,wBACS;CAEjB,MAAM,EAAE,MAAM,WAAW,OAAM,MADP,iBAAiB,EAAA,CAEvC,gCACA,QACA;EAAE,MAAM;EAAM,YAAY;CAAS,CACrC;CACA,IAAI,OAAO,SAAS,GAAG;EACrB,MAAM,UAAU,OAAO,KAAK,eAAe,WAAW,OAAO,CAAC,CAAC,KAAK,IAAI;EACxE,MAAM,IAAI,MACR,6CAA6C,MAAM,KAAK,SAC1D;CACF;CAEA,OAAO;AACT;;;;;;;;;AAUA,eAAsB,sBACpB,QACA,UACA,QAAQ,wBACS;CACjB,IAAI,aAAa,cACf,OAAO;CAET,OAAO,yBAAyB,QAAQ,KAAK;AAC/C"}

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export { classifyDatabaseError, classifyDialectMessage, type DatabaseErrorClassi
 export { applyPendingDecoratorRegistrations, type CompatiblePropertyDecorator, type CompatiblePropertyDecoratorContext, type LegacyPropertyDecoratorTarget, registerCompatibleFieldDecorator, } from './decorators/compatibility';
 export { type CrossPackageRefOptions, crossPackageRef, type FieldOptions, type FieldUIHints, field, foreignKey, type Meta, manyToMany, meta, type NumericFieldOptions, oneToMany, type RelationshipFieldOptions, type TextFieldOptions, } from './decorators/index';
 export * from './dispatch/index';
+export { isEmbeddedDatabase, usesEmbeddedRevisionFallback, withEmbeddedWriteQueue, withEmbeddedWriteTransaction, } from './embedded-write-queue';
 export * from './embeddings/index';
 export * from './errors';
 export { createFilesystemAdapter, type FilesystemAdapterFactory, registerFilesystemAdapterFactory, } from './filesystem-loader';

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":"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"}

package/dist/index.js

@@ -9,6 +9,7 @@ import { buildCascadePlan, cascadeReferencesTo, normalizeOnDelete, runCascadeDel
 import { CACHE_INVALIDATION_CHANNEL, broadcastCacheInvalidation, ensureCacheInvalidationListener, getCacheGeneration, invalidateCollectionCache, resetCollectionCache, resolveDbCacheKey, stopCacheInvalidationListeners } from "./collection-cache.js";
 import { CHANGE_SIGNAL_CHANNEL, resetChangeSignals, stopChangeSignalListeners, subscribeToChangeSignals } from "./change-signals.js";
 import { isTenantScopedClassResolved, resolveDispatchTenantId, resolveDispatchTenantScope, setDispatchTenantResolver, setTenantScopedClassResolver } from "./dispatch/tenant-resolver.js";
+import { isEmbeddedDatabase, usesEmbeddedRevisionFallback, withEmbeddedWriteQueue, withEmbeddedWriteTransaction } from "./embedded-write-queue.js";
 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";
@@ -65,7 +66,7 @@ import { generateOpenAPISpec, setupSwaggerUI } from "./generators/swagger.js";
 import "./generators/index.js";
 import { SmrtHierarchical } from "./hierarchical.js";
 import { SmrtJunction } from "./junction.js";
-import { MODULE_DOC_HASH_PREFIX, buildDomainKnowledgeManifest, readAgentModuleDocs, resolveAgentModuleDocPaths } from "./knowledge.js";
+import { AGENT_SURFACE_HASH_PREFIX, MODULE_DOC_HASH_PREFIX, buildDomainKnowledgeManifest, readAgentModuleDocs, resolveAgentModuleDocPaths } from "./knowledge.js";
 import { getClassConfigResolvers, getConfigResolver, isLazyConfigSentinel, listConfigResolvers, registerConfigResolver, resetConfigResolvers, resolveLazyConfig, unregisterConfigResolver } from "./lazy-config.js";
 import { DEFAULT_LEARNING_CONFIG, LearningMemory } from "./learning/memory.js";
 import { ManifestBuilder } from "./manifest/generator.js";
@@ -84,4 +85,4 @@ import "./system/index.js";
 import { getTestDatabase } from "./testing/database.js";
 import "./tools/index.js";
 import { smrtPlugin } from "./vite-plugin/index.js";
-export { AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CLIGenerator, 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, 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, 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_TABLE_NAMES, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applyPostgresRuntimeTimeouts, applySyncWritablePolicy, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildCascadePlan, buildChangeEventStream, buildCustomActionInputSchema, buildCustomActionInvocationArgs, buildDefaultListOrderBy, buildDomainKnowledgeManifest, bumpChangeFeed, canonicalReadRepresentation, canonicalizeDataQuery, cascadeReferencesTo, changeEventSubscribersAtCapacity, checkLiveSchemaParity, childAccessorName, classifyDatabaseError, classifyDialectMessage, clearRetentionTasks, clone, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createDataQueryFingerprint, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, customActionParameterInputName, detectEngine, discoverManifestEntry, 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, getCLIHandler, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getRetentionTasks, getSQLFromDiff, getSystemTableShapes, getTableVersion, getTenantScopedChangesSince, getTestDatabase, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isAbortedTransactionError, isAdvisoryOnlyChange, isDatabaseInterface, isDeterministicDatabaseError, isFromPackage, isLazyConfigSentinel, isManualOrAdvisoryChange, isNotNullViolationError, isQualifiedName, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isTransientDatabaseError, isType, isUniqueViolationError, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, migratePostgresSystemTimestamps, normalizeCustomActionFailure, normalizeDataQueryRequest, normalizeDataQueryResult, normalizeDataQuerySchema, normalizeEventsMaxSubscribers, normalizeOnDelete, normalizeTypedHttpError, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, planForeignKeyCreation, planPostgresSystemTimestampMigrations, processSyncApplyBatch, pruneAiUsage, pruneChangeFeed, pruneExpiredContexts, qualifiedNamesEqual, readAgentModuleDocs, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, registerRetentionTask, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveAgentModuleDocPaths, resolveCustomActionMetadata, resolveDatabase, resolveDbCacheKey, resolveDispatchTenantId, resolveDispatchTenantScope, resolveGetStringFilter, resolveLazyConfig, resolveListLimit, resolveListOffset, resolveMCPToolListCacheHint, resolvePostgresTimeouts, resolveReadCacheControl, resolveTenantEtagDiscriminator, runCascadeDelete, runRetentionSweep, runWithTenantGate, safeParse, safeStringify, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupCLI, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, sortMCPTools, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, unregisterRetentionTask, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized };
+export { AGENT_SURFACE_HASH_PREFIX, AIError, APIGenerator, AiUsageCollector, AiUsagePersistenceHandler, CACHE_INVALIDATION_CHANNEL, CHANGE_FEED_INTERCEPTOR_NAME, CHANGE_FEED_TABLE, CHANGE_SIGNAL_CHANNEL, CLIGenerator, 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, 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, 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_TABLE_NAMES, SchemaComparer, SignalBus, SignalSanitizer, SmrtClass, SmrtCollection, SmrtError, SmrtHierarchical, SmrtJunction, SmrtMCPServer, SmrtObject, SmrtPolymorphicAssociation, TenantIsolationError, ValidationError, ValidationReport, ValidationUtils, appendChange, applyOneToManyChildAccessors, applyPendingDecoratorRegistrations, applyPostgresRuntimeTimeouts, applySyncWritablePolicy, assertPostgresSystemTimestampsCurrent, broadcastCacheInvalidation, buildCascadePlan, buildChangeEventStream, buildCustomActionInputSchema, buildCustomActionInvocationArgs, buildDefaultListOrderBy, buildDomainKnowledgeManifest, bumpChangeFeed, canonicalReadRepresentation, canonicalizeDataQuery, cascadeReferencesTo, changeEventSubscribersAtCapacity, checkLiveSchemaParity, childAccessorName, classifyDatabaseError, classifyDialectMessage, clearRetentionTasks, clone, computeBodyEtag, computeRuntimeWebManifestHash, computeTableVersionEtag, conditionalJsonResponse, config, convertTypeToJsonSchema, createDataQueryFingerprint, createDispatchBus, createFilesystemAdapter, createInterceptorContext, createMCPServer, createQualifiedName, createRestServer, createSmrtClient, createSmrtServer, crossPackageRef, customActionParameterInputName, detectEngine, discoverManifestEntry, 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, getCLIHandler, getCacheGeneration, getChangesSince, getClassConfigResolvers, getClassName, getConfigResolver, getDatabaseEngine, getManifest, getPackageFromQualifiedName, getRetentionTasks, getSQLFromDiff, getSystemTableShapes, getTableVersion, getTenantScopedChangesSince, getTestDatabase, hasActionableChanges, ifNoneMatchHasConcreteMatch, ifNoneMatchSatisfied, importOptionalDependency, invalidateCollectionCache, isAbortedTransactionError, isAdvisoryOnlyChange, isDatabaseInterface, isDeterministicDatabaseError, isEmbeddedDatabase, isFromPackage, isLazyConfigSentinel, isManualOrAdvisoryChange, isNotNullViolationError, isQualifiedName, isSmrtCollectionExtendsName, isStaleWrite, isTenantScopedClassResolved, isTransientDatabaseError, isType, isUniqueViolationError, isValid, listConfigResolvers, loadExternalManifest, loadExternalManifestSync, loadLocalTestManifestSync, loadManifestFromPathSync, manifest, manyToMany, meta, migratePostgresSystemTimestamps, normalizeCustomActionFailure, normalizeDataQueryRequest, normalizeDataQueryResult, normalizeDataQuerySchema, normalizeEventsMaxSubscribers, normalizeOnDelete, normalizeTypedHttpError, oneToMany, parse, parseQualifiedName, parseSyncApplyBatch, payloadMatchesRow, planForeignKeyCreation, planPostgresSystemTimestampMigrations, processSyncApplyBatch, pruneAiUsage, pruneChangeFeed, pruneExpiredContexts, qualifiedNamesEqual, readAgentModuleDocs, registerChangeFeedWriter, registerCompatibleFieldDecorator, registerConfigResolver, registerFilesystemAdapterFactory, registerOptionalDependency, registerRetentionTask, resetChangeFeedWarnings, resetChangeSignals, resetCollectionCache, resetConfigResolvers, resetVerifiedTables, resolveAgentModuleDocPaths, resolveCustomActionMetadata, resolveDatabase, resolveDbCacheKey, resolveDispatchTenantId, resolveDispatchTenantScope, resolveGetStringFilter, resolveLazyConfig, resolveListLimit, resolveListOffset, resolveMCPToolListCacheHint, resolvePostgresTimeouts, resolveReadCacheControl, resolveTenantEtagDiscriminator, runCascadeDelete, runRetentionSweep, runWithTenantGate, safeParse, safeStringify, setDispatchTenantResolver, setTenantEntryPointRunner, setTenantScopedClassResolver, setupCLI, setupSwaggerUI, shouldIncludeMethod, signalVisibleToTenant, smrt, smrtPlugin, smrt as smrtRegistry, sortMCPTools, startRestServer, staticManifest, stopCacheInvalidationListeners, stopChangeSignalListeners, stringify, subscribeToChangeSignals, tableExists, tryReserveChangeEventSubscriberSlot, unregisterChangeFeedWriter, unregisterConfigResolver, unregisterRetentionTask, usesEmbeddedRevisionFallback, validateSyncApplyItem, validateToolCall, versionConditionalResponse, warnIfSharedCacheNeutralized, withEmbeddedWriteQueue, withEmbeddedWriteTransaction };

package/dist/knowledge.d.ts

@@ -1,4 +1,4 @@
-import { DomainKnowledgeConfig, DomainKnowledgeManifest, DomainKnowledgeModuleDoc } from '@happyvertical/smrt-types';
+import { DomainKnowledgeAgentSurface, DomainKnowledgeConfig, DomainKnowledgeManifest, DomainKnowledgeModuleDoc } from '@happyvertical/smrt-types';
 import { SmartObjectManifest } from './scanner/types.js';
 /**
  * Minimal package.json shape consumed by the knowledge builder.
@@ -17,9 +17,25 @@ export interface BuildDomainKnowledgeOptions {
     packageJson?: PackageJsonLike;
     manifestPath?: string;
     config?: DomainKnowledgeConfig;
+    /**
+     * The package's declared view intents and playbooks (#2591), produced by the
+     * scanner's agent-surface matcher.
+     *
+     * Passed in rather than scanned here for one reason: the scanner carries a
+     * native parser binary, and `smrt-core`'s main entry is browser-reachable.
+     * The Vite plugin already imports the scanner lazily on the Node side and is
+     * the one caller that writes this artifact, so it does the scan and hands the
+     * result over.
+     */
+    agentSurface?: DomainKnowledgeAgentSurface;
 }
 /** `sourceHashes` key prefix for a linked module doc, e.g. `moduleDoc:agents/crm.md`. */
 export declare const MODULE_DOC_HASH_PREFIX = "moduleDoc:";
+/**
+ * `sourceHashes` key prefix for a module declaring a view intent or playbook,
+ * e.g. `agentSurface:src/lib/orders.intents.ts` (#2591).
+ */
+export declare const AGENT_SURFACE_HASH_PREFIX = "agentSurface:";
 /**
  * Module doc paths linked from a package's `AGENTS.md`, relative to the package
  * root and in document order.

package/dist/knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EAGrB,uBAAuB,EAEvB,wBAAwB,EAIzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAG5B;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AA2CD,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,EAAE,CAgBV;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,wBAAwB,EAAE,CAM5B;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,uBAAuB,CAqEzB"}
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,2BAA2B,EAC3B,qBAAqB,EAGrB,uBAAuB,EAEvB,wBAAwB,EAIzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,oBAAoB,CAAC;AAG5B;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,2BAA2B,CAAC;CAC5C;AA2CD,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,EAAE,CAgBV;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,wBAAwB,EAAE,CAM5B;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,uBAAuB,CAgFzB"}