@happyvertical/smrt-core 0.42.1 → 0.42.2

package/dist/system/bootstrap.d.ts

@@ -0,0 +1,9 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * Ensure every framework-owned SMRT system table exists before use.
+ *
+ * PostgreSQL provisioning is serialized in a bounded advisory-locked
+ * transaction; other engines use the schema's idempotent DDL directly.
+ */
+export declare function ensureSystemTables(db: DatabaseInterface, typeHint?: string): Promise<void>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/system/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/system/bootstrap.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAG5D,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,oBAAoB,CAAC;AAoH/E;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,iBAAiB,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/system/bootstrap.js

@@ -0,0 +1,107 @@
+import { SMRT_SCHEMA_VERSION, getSystemTableDDL } from "./schema.js";
+import { ensurePostgresChangeFeedAppendFunction } from "../change-feed.js";
+import { assertPostgresSystemTimestampsCurrent, ensureBootstrapSystemTableCompatibility, getDatabaseEngine, tableExists } from "./compatibility.js";
+import { createLogger } from "@happyvertical/logger";
+//#region src/system/bootstrap.ts
+/** Canonical, idempotent SMRT system-table provisioning. */
+var SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL = "SELECT pg_advisory_xact_lock(hashtext('smrt'), hashtext('system-tables'))";
+/**
+* Timeout budget for the PostgreSQL system-table bootstrap transaction.
+*
+* The runtime pool's session `lock_timeout`/`statement_timeout` (#2377) are
+* sized for request work. This transaction is not request work: it holds the
+* advisory lock across up to 29 sequential DDL round-trips — ~18.85 s on a
+* high-latency link at 650 ms per round trip — and a second replica cold-starting
+* against the same fresh database *waits* on that lock. Both GUCs bound that
+* wait, because `pg_advisory_xact_lock` is an ordinary statement in the lock
+* manager, so at the runtime defaults the second replica would abort with
+* "canceling statement due to lock timeout" where it previously waited and
+* succeeded.
+*
+* Five minutes is an order of magnitude above the documented worst case and
+* still bounded — this is a raise, not a disable. `SET LOCAL` scopes it to this
+* transaction, the same lever migrations use for the same reason (#2362).
+*/
+var SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL = ["SET LOCAL lock_timeout = '300000ms'", "SET LOCAL statement_timeout = '300000ms'"];
+var logger = createLogger({ level: "info" });
+function getQueryRows(result) {
+	if (Array.isArray(result)) return result;
+	if (result && typeof result === "object" && "rows" in result) {
+		const rows = result.rows;
+		if (Array.isArray(rows)) return rows;
+	}
+	return [];
+}
+async function isSystemSchemaVersionApplied(db, typeHint) {
+	const engine = getDatabaseEngine(db, typeHint);
+	if (engine === "postgres" && !await tableExists(db, "_smrt_migrations", typeHint)) return false;
+	try {
+		const versionParam = engine === "postgres" ? "$1" : "?";
+		return getQueryRows(await db.query(`SELECT 1 FROM _smrt_migrations WHERE version = ${versionParam} LIMIT 1`, SMRT_SCHEMA_VERSION)).length > 0;
+	} catch (error) {
+		if (engine === "postgres") throw error;
+		return false;
+	}
+}
+async function bootstrapSystemTables(db, typeHint) {
+	if (await isSystemSchemaVersionApplied(db, typeHint)) return;
+	await ensureBootstrapSystemTableCompatibility(db, typeHint);
+	const engine = getDatabaseEngine(db, typeHint);
+	for (const ddl of getSystemTableDDL(engine)) for (const statement of ddl.split(";").map((value) => value.trim()).filter(Boolean)) await db.query(statement);
+	await ensurePostgresChangeFeedAppendFunction(db, { typeHint });
+	await assertPostgresSystemTimestampsCurrent(db, typeHint);
+	const id = crypto.randomUUID();
+	await db.execute`
+    INSERT INTO _smrt_migrations (id, version, description)
+    VALUES (${id}, ${SMRT_SCHEMA_VERSION}, ${"Initial SMRT system tables"})
+    ON CONFLICT(version) DO NOTHING
+  `;
+}
+async function rollbackBootstrap(tx) {
+	try {
+		if (typeof tx.isActive !== "function" || tx.isActive()) await tx.rollback();
+	} catch (error) {
+		logger.warn(`[smrt] Failed to rollback system table bootstrap transaction: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Ensure every framework-owned SMRT system table exists before use.
+*
+* PostgreSQL provisioning is serialized in a bounded advisory-locked
+* transaction; other engines use the schema's idempotent DDL directly.
+*/
+async function ensureSystemTables(db, typeHint) {
+	if (getDatabaseEngine(db, typeHint) !== "postgres") {
+		await bootstrapSystemTables(db, typeHint);
+		return;
+	}
+	const beginTransaction = db.beginTransaction;
+	const transaction = db.transaction;
+	if (typeof beginTransaction === "function") {
+		const tx = await beginTransaction.call(db);
+		if (!tx) throw new Error("Database transaction could not be started");
+		try {
+			for (const sql of SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL) await tx.query(sql);
+			await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);
+			await bootstrapSystemTables(tx, typeHint);
+			await tx.commit();
+			return;
+		} catch (error) {
+			await rollbackBootstrap(tx);
+			throw error;
+		}
+	}
+	if (typeof transaction === "function") {
+		await transaction.call(db, async (tx) => {
+			for (const sql of SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL) await tx.query(sql);
+			await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);
+			await bootstrapSystemTables(tx, typeHint);
+		});
+		return;
+	}
+	throw new Error("Postgres system table bootstrap requires a transaction-capable database adapter");
+}
+//#endregion
+export { ensureSystemTables };
+
+//# sourceMappingURL=bootstrap.js.map

package/dist/system/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","names":[],"sources":["../../src/system/bootstrap.ts"],"sourcesContent":["/** Canonical, idempotent SMRT system-table provisioning. */\n\nimport { createLogger } from '@happyvertical/logger';\nimport type { DatabaseInterface, TransactionHandle } from '@happyvertical/sql';\nimport { ensurePostgresChangeFeedAppendFunction } from '../change-feed.js';\nimport {\n  assertPostgresSystemTimestampsCurrent,\n  ensureBootstrapSystemTableCompatibility,\n  getDatabaseEngine,\n  tableExists,\n} from './compatibility.js';\nimport { getSystemTableDDL, SMRT_SCHEMA_VERSION } from './schema.js';\n\nconst SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL =\n  \"SELECT pg_advisory_xact_lock(hashtext('smrt'), hashtext('system-tables'))\";\n\n/**\n * Timeout budget for the PostgreSQL system-table bootstrap transaction.\n *\n * The runtime pool's session `lock_timeout`/`statement_timeout` (#2377) are\n * sized for request work. This transaction is not request work: it holds the\n * advisory lock across up to 29 sequential DDL round-trips — ~18.85 s on a\n * high-latency link at 650 ms per round trip — and a second replica cold-starting\n * against the same fresh database *waits* on that lock. Both GUCs bound that\n * wait, because `pg_advisory_xact_lock` is an ordinary statement in the lock\n * manager, so at the runtime defaults the second replica would abort with\n * \"canceling statement due to lock timeout\" where it previously waited and\n * succeeded.\n *\n * Five minutes is an order of magnitude above the documented worst case and\n * still bounded — this is a raise, not a disable. `SET LOCAL` scopes it to this\n * transaction, the same lever migrations use for the same reason (#2362).\n */\nconst SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL = [\n  \"SET LOCAL lock_timeout = '300000ms'\",\n  \"SET LOCAL statement_timeout = '300000ms'\",\n];\nconst logger = createLogger({ level: 'info' });\n\ntype TransactionCapableDatabase = DatabaseInterface & {\n  transaction?: <T>(\n    this: DatabaseInterface,\n    callback: (tx: DatabaseInterface) => Promise<T>,\n  ) => Promise<T>;\n};\n\nfunction getQueryRows(result: unknown): Record<string, unknown>[] {\n  if (Array.isArray(result)) return result as Record<string, unknown>[];\n  if (result && typeof result === 'object' && 'rows' in result) {\n    const rows = (result as { rows?: unknown }).rows;\n    if (Array.isArray(rows)) return rows as Record<string, unknown>[];\n  }\n  return [];\n}\n\nasync function isSystemSchemaVersionApplied(\n  db: DatabaseInterface,\n  typeHint?: string,\n): Promise<boolean> {\n  const engine = getDatabaseEngine(db, typeHint);\n  if (\n    engine === 'postgres' &&\n    !(await tableExists(db, '_smrt_migrations', typeHint))\n  ) {\n    return false;\n  }\n  try {\n    const versionParam = engine === 'postgres' ? '$1' : '?';\n    const rows = await db.query(\n      `SELECT 1 FROM _smrt_migrations WHERE version = ${versionParam} LIMIT 1`,\n      SMRT_SCHEMA_VERSION,\n    );\n    return getQueryRows(rows).length > 0;\n  } catch (error) {\n    if (engine === 'postgres') throw error;\n    return false;\n  }\n}\n\nasync function bootstrapSystemTables(\n  db: DatabaseInterface,\n  typeHint?: string,\n): Promise<void> {\n  if (await isSystemSchemaVersionApplied(db, typeHint)) return;\n\n  await ensureBootstrapSystemTableCompatibility(db, typeHint);\n  const engine = getDatabaseEngine(db, typeHint);\n  for (const ddl of getSystemTableDDL(engine)) {\n    for (const statement of ddl\n      .split(';')\n      .map((value) => value.trim())\n      .filter(Boolean)) {\n      await db.query(statement);\n    }\n  }\n  await ensurePostgresChangeFeedAppendFunction(db, { typeHint });\n  await assertPostgresSystemTimestampsCurrent(db, typeHint);\n\n  const id = crypto.randomUUID();\n  const description = 'Initial SMRT system tables';\n  await db.execute`\n    INSERT INTO _smrt_migrations (id, version, description)\n    VALUES (${id}, ${SMRT_SCHEMA_VERSION}, ${description})\n    ON CONFLICT(version) DO NOTHING\n  `;\n}\n\nasync function rollbackBootstrap(tx: TransactionHandle): Promise<void> {\n  try {\n    if (typeof tx.isActive !== 'function' || tx.isActive()) await tx.rollback();\n  } catch (error) {\n    logger.warn(\n      `[smrt] Failed to rollback system table bootstrap transaction: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n  }\n}\n\n/**\n * Ensure every framework-owned SMRT system table exists before use.\n *\n * PostgreSQL provisioning is serialized in a bounded advisory-locked\n * transaction; other engines use the schema's idempotent DDL directly.\n */\nexport async function ensureSystemTables(\n  db: DatabaseInterface,\n  typeHint?: string,\n): Promise<void> {\n  if (getDatabaseEngine(db, typeHint) !== 'postgres') {\n    await bootstrapSystemTables(db, typeHint);\n    return;\n  }\n\n  const beginTransaction = db.beginTransaction;\n  const transaction = (db as TransactionCapableDatabase).transaction;\n  if (typeof beginTransaction === 'function') {\n    const tx = await beginTransaction.call(db);\n    if (!tx) throw new Error('Database transaction could not be started');\n    try {\n      // Raise the budget before taking the lock — the wait itself is what the\n      // runtime session timeouts would otherwise cancel (#2377).\n      for (const sql of SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL) await tx.query(sql);\n      await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);\n      await bootstrapSystemTables(tx, typeHint);\n      await tx.commit();\n      return;\n    } catch (error) {\n      await rollbackBootstrap(tx);\n      throw error;\n    }\n  }\n\n  if (typeof transaction === 'function') {\n    await transaction.call(db, async (tx) => {\n      for (const sql of SYSTEM_TABLE_BOOTSTRAP_TIMEOUT_SQL) await tx.query(sql);\n      await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);\n      await bootstrapSystemTables(tx, typeHint);\n    });\n    return;\n  }\n\n  throw new Error(\n    'Postgres system table bootstrap requires a transaction-capable database adapter',\n  );\n}\n"],"mappings":";;;;;;AAaA,IAAM,kCACJ;;;;;;;;;;;;;;;;;;AAmBF,IAAM,qCAAqC,CACzC,uCACA,0CACF;AACA,IAAM,SAAS,aAAa,EAAE,OAAO,OAAO,CAAC;AAS7C,SAAS,aAAa,QAA4C;CAChE,IAAI,MAAM,QAAQ,MAAM,GAAG,OAAO;CAClC,IAAI,UAAU,OAAO,WAAW,YAAY,UAAU,QAAQ;EAC5D,MAAM,OAAQ,OAA8B;EAC5C,IAAI,MAAM,QAAQ,IAAI,GAAG,OAAO;CAClC;CACA,OAAO,CAAC;AACV;AAEA,eAAe,6BACb,IACA,UACkB;CAClB,MAAM,SAAS,kBAAkB,IAAI,QAAQ;CAC7C,IACE,WAAW,cACX,CAAE,MAAM,YAAY,IAAI,oBAAoB,QAAQ,GAEpD,OAAO;CAET,IAAI;EACF,MAAM,eAAe,WAAW,aAAa,OAAO;EAKpD,OAAO,aAAa,MAJD,GAAG,MACpB,kDAAkD,aAAa,WAC/D,mBACF,CACwB,CAAC,CAAC,SAAS;CACrC,SAAS,OAAO;EACd,IAAI,WAAW,YAAY,MAAM;EACjC,OAAO;CACT;AACF;AAEA,eAAe,sBACb,IACA,UACe;CACf,IAAI,MAAM,6BAA6B,IAAI,QAAQ,GAAG;CAEtD,MAAM,wCAAwC,IAAI,QAAQ;CAC1D,MAAM,SAAS,kBAAkB,IAAI,QAAQ;CAC7C,KAAK,MAAM,OAAO,kBAAkB,MAAM,GACxC,KAAK,MAAM,aAAa,IACrB,MAAM,GAAG,CAAC,CACV,KAAK,UAAU,MAAM,KAAK,CAAC,CAAC,CAC5B,OAAO,OAAO,GACf,MAAM,GAAG,MAAM,SAAS;CAG5B,MAAM,uCAAuC,IAAI,EAAE,SAAS,CAAC;CAC7D,MAAM,sCAAsC,IAAI,QAAQ;CAExD,MAAM,KAAK,OAAO,WAAW;CAE7B,MAAM,GAAG,OAAO;;cAEJ,GAAG,IAAI,oBAAoB,IAAI,6BAAY;;;AAGzD;AAEA,eAAe,kBAAkB,IAAsC;CACrE,IAAI;EACF,IAAI,OAAO,GAAG,aAAa,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;CAC5E,SAAS,OAAO;EACd,OAAO,KACL,iEACE,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAEzD;CACF;AACF;;;;;;;AAQA,eAAsB,mBACpB,IACA,UACe;CACf,IAAI,kBAAkB,IAAI,QAAQ,MAAM,YAAY;EAClD,MAAM,sBAAsB,IAAI,QAAQ;EACxC;CACF;CAEA,MAAM,mBAAmB,GAAG;CAC5B,MAAM,cAAe,GAAkC;CACvD,IAAI,OAAO,qBAAqB,YAAY;EAC1C,MAAM,KAAK,MAAM,iBAAiB,KAAK,EAAE;EACzC,IAAI,CAAC,IAAI,MAAM,IAAI,MAAM,2CAA2C;EACpE,IAAI;GAGF,KAAK,MAAM,OAAO,oCAAoC,MAAM,GAAG,MAAM,GAAG;GACxE,MAAM,GAAG,MAAM,+BAA+B;GAC9C,MAAM,sBAAsB,IAAI,QAAQ;GACxC,MAAM,GAAG,OAAO;GAChB;EACF,SAAS,OAAO;GACd,MAAM,kBAAkB,EAAE;GAC1B,MAAM;EACR;CACF;CAEA,IAAI,OAAO,gBAAgB,YAAY;EACrC,MAAM,YAAY,KAAK,IAAI,OAAO,OAAO;GACvC,KAAK,MAAM,OAAO,oCAAoC,MAAM,GAAG,MAAM,GAAG;GACxE,MAAM,GAAG,MAAM,+BAA+B;GAC9C,MAAM,sBAAsB,IAAI,QAAQ;EAC1C,CAAC;EACD;CACF;CAEA,MAAM,IAAI,MACR,iFACF;AACF"}

package/dist/system/index.d.ts

@@ -4,6 +4,7 @@
  * System-level metadata storage for the SMRT framework.
  * All tables use _smrt_ prefix and share the application's database.
  */
+export { ensureSystemTables } from './bootstrap.js';
 export * from './compatibility.js';
 export * from './retention.js';
 export * from './types.js';

package/dist/system/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/system/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/system/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/system/index.js

@@ -1,3 +1,4 @@
 import { assertPostgresSystemTimestampsCurrent, ensureBootstrapSystemTableCompatibility, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, getDatabaseEngine, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, tableExists } from "./compatibility.js";
+import { ensureSystemTables } from "./bootstrap.js";
 import { DEFAULT_RETENTION_POLICY, clearRetentionTasks, getRetentionTasks, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, unregisterRetentionTask } from "./retention.js";
-export { DEFAULT_RETENTION_POLICY, assertPostgresSystemTimestampsCurrent, clearRetentionTasks, ensureBootstrapSystemTableCompatibility, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, getDatabaseEngine, getRetentionTasks, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, tableExists, unregisterRetentionTask };
+export { DEFAULT_RETENTION_POLICY, assertPostgresSystemTimestampsCurrent, clearRetentionTasks, ensureBootstrapSystemTableCompatibility, ensureDeferredSystemTableCompatibility, ensureDispatchSubscriptionsSystemTableCompatibility, ensureDispatchSystemTableCompatibility, ensureJobEventsSystemTableCompatibility, ensureJobsSystemTableCompatibility, ensureLegacySystemTableCompatibility, ensureSystemTables, getDatabaseEngine, getRetentionTasks, migratePostgresSystemTimestamps, planPostgresSystemTimestampMigrations, pruneAiUsage, pruneExpiredContexts, registerRetentionTask, runRetentionSweep, tableExists, unregisterRetentionTask };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-core",
-  "version": "0.42.1",
+  "version": "0.42.2",
   "description": "Core AI agent framework with standardized collections, object-relational mapping, and code generators",
   "author": "HappyVertical",
   "type": "module",
@@ -164,9 +164,9 @@
     "tsx": "^4.23.0",
     "typescript": "5.9.3",
     "yaml": "^2.9.0",
-    "@happyvertical/smrt-config": "0.42.1",
-    "@happyvertical/smrt-scanner": "0.42.1",
-    "@happyvertical/smrt-types": "0.42.1"
+    "@happyvertical/smrt-config": "0.42.2",
+    "@happyvertical/smrt-scanner": "0.42.2",
+    "@happyvertical/smrt-types": "0.42.2"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.0.0 <4.0.0",