@fragno-dev/db 0.1.15 → 0.2.0

package/dist/fragments/internal-fragment.d.ts

@@ -1,19 +1,53 @@
 import { AnyColumn, AnyRelation, Column, FragnoId, IdColumn, Index, Schema, Table } from "../schema/create.js";
+import { RetryPolicy } from "../query/unit-of-work/retry-policy.js";
 import { DatabaseHandlerContext, DatabaseRequestStorage, DatabaseServiceContext, FragnoPublicConfigWithDatabase, ImplicitDatabaseDependencies } from "../db-fragment-definition-builder.js";
 import * as _fragno_dev_core0 from "@fragno-dev/core";
+import { InstantiatedFragmentFromDefinition } from "@fragno-dev/core";
 
 //#region src/fragments/internal-fragment.d.ts
-declare const internalFragmentDef: _fragno_dev_core0.FragmentDefinition<{}, FragnoPublicConfigWithDatabase, ImplicitDatabaseDependencies<Schema<Record<"fragno_db_settings", Table<Record<string, AnyColumn> & Record<"id", IdColumn<"varchar(30)", string | FragnoId | null, FragnoId>> & Record<"key", Column<"string", string, string>> & Record<"value", Column<"string", string, string>>, Record<string, AnyRelation>, Record<string, Index<AnyColumn[], readonly string[]>> & Record<"unique_key", Index<readonly [Column<"string", string, string>] & AnyColumn[], readonly ["key"]>>>>>>, {}, {
+declare const internalFragmentDef: _fragno_dev_core0.FragmentDefinition<{}, FragnoPublicConfigWithDatabase, ImplicitDatabaseDependencies<Schema<Record<"fragno_db_settings", Table<Record<string, AnyColumn> & Record<"id", IdColumn<"varchar(30)", string | FragnoId | null, FragnoId>> & Record<"key", Column<"string", string, string>> & Record<"value", Column<"string", string, string>>, Record<string, AnyRelation>, Record<string, Index<AnyColumn[], readonly string[]>> & Record<"unique_key", Index<readonly [Column<"string", string, string>] & AnyColumn[], readonly ["key"]>>>> & Record<"fragno_hooks", Table<Record<string, AnyColumn> & Record<"id", IdColumn<"varchar(30)", string | FragnoId | null, FragnoId>> & Record<"namespace", Column<"string", string, string>> & Record<"hookName", Column<"string", string, string>> & Record<"payload", Column<"json", unknown, unknown>> & Record<"status", Column<"string", string, string>> & Record<"attempts", Column<"integer", number | null, number>> & Record<"maxAttempts", Column<"integer", number | null, number>> & Record<"lastAttemptAt", Column<"timestamp", Date | null, Date | null>> & Record<"nextRetryAt", Column<"timestamp", Date | null, Date | null>> & Record<"error", Column<"string", string | null, string | null>> & Record<"createdAt", Column<"timestamp", Date | null, Date>> & Record<"nonce", Column<"string", string, string>>, Record<string, AnyRelation>, Record<string, Index<AnyColumn[], readonly string[]>> & Record<"idx_namespace_status_retry", Index<readonly [Column<"string", string, string>, Column<"string", string, string>, Column<"timestamp", Date | null, Date | null>] & AnyColumn[], readonly ["namespace", "status", "nextRetryAt"]>> & Record<"idx_nonce", Index<readonly [Column<"string", string, string>] & AnyColumn[], readonly ["nonce"]>>>>>>, {}, {
   settingsService: {
-    get(key: string): Promise<{
+    get(namespace: string, key: string): Promise<{
       id: FragnoId;
       key: string;
       value: string;
     } | undefined>;
-    set(key: string, value: string): Promise<void>;
+    set(namespace: string, key: string, value: string): Promise<void>;
     delete(id: FragnoId): Promise<void>;
   };
-}, {}, {}, DatabaseServiceContext, DatabaseHandlerContext, DatabaseRequestStorage, {}>;
+} & {
+  hookService: {
+    /**
+     * Get pending hook events for processing.
+     * Returns all pending events for the given namespace that are ready to be processed.
+     */
+    getPendingHookEvents(namespace: string): Promise<{
+      id: FragnoId;
+      hookName: string;
+      payload: unknown;
+      attempts: number;
+      maxAttempts: number;
+      nonce: string;
+    }[]>;
+    /**
+     * Mark a hook event as completed.
+     */
+    markHookCompleted(eventId: FragnoId): void;
+    /**
+     * Mark a hook event as failed and schedule next retry.
+     */
+    markHookFailed(eventId: FragnoId, error: string, attempts: number, retryPolicy: RetryPolicy): void;
+    /**
+     * Mark a hook event as processing (to prevent concurrent execution).
+     */
+    markHookProcessing(eventId: FragnoId): void;
+  };
+}, {}, {}, DatabaseServiceContext<{}>, DatabaseHandlerContext<{}>, DatabaseRequestStorage, {}>;
+/**
+ * Type representing an instantiated internal fragment.
+ * This is the fragment that manages Fragno's internal settings table.
+ */
+type InternalFragmentInstance = InstantiatedFragmentFromDefinition<typeof internalFragmentDef>;
 //#endregion
-export { internalFragmentDef };
+export { InternalFragmentInstance, internalFragmentDef };
 //# sourceMappingURL=internal-fragment.d.ts.map

package/dist/fragments/internal-fragment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-fragment.d.ts","names":[],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":[],"mappings":";;;;;AA6Ba,cAAA,mBAuDH,oBAvDsB,kBAuDtB,CAAA,CAAA,CAAA,EAvDsB,8BAuDtB,EAvDsB,4BAuDtB,CAvDsB,MAuDtB,CAvDsB,MAuDtB,CAAA,oBAAA,EAvDsB,KAuDtB,CAvDsB,MAuDtB,CAAA,MAAA,EAvDsB,SAAA,CAuDtB,GAvDsB,MAuDtB,CAAA,IAAA,EAvDsB,QAuDtB,CAAA,aAAA,EAAA,MAAA,GAvDsB,QAuDtB,GAAA,IAAA,EAvDsB,QAuDtB,CAAA,CAAA,GAvDsB,MAuDtB,CAAA,KAAA,EAvDsB,MAuDtB,CAAA,QAAA,EAAA,MAAA,EAAA,MAAA,CAAA,CAAA,GAvDsB,MAuDtB,CAAA,OAAA,EAvDsB,MAuDtB,CAAA,QAAA,EAAA,MAAA,EAAA,MAAA,CAAA,CAAA,EAvDsB,MAuDtB,CAAA,MAAA,EAvDsB,WAAA,CAuDtB,EAvDsB,MAuDtB,CAAA,MAAA,EAvDsB,KAuDtB,CAvDsB,SAAA,EAuDtB,EAAA,SAAA,MAAA,EAAA,CAAA,CAAA,GAvDsB,MAuDtB,CAAA,YAAA,EAvDsB,KAuDtB,CAAA,SAAA,CAvDsB,MAuDtB,CAAA,QAAA,EAAA,MAAA,EAAA,MAAA,CAAA,CAAA,GAvDsB,SAAA,EAuDtB,EAAA,SAAA,CAAA,KAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,EAAA;EAvDsB,eAAA,EAAA;IAAA,GAAA,CAAA,GAAA,EAAA,MAAA,CAAA,EAkBF,OAlBE,CAAA;MAAA,EAAA,EAkBY,QAlBZ;MAAA,GAAA,EAAA,MAAA;MAAA,KAAA,EAAA,MAAA;IAAA,CAAA,GAAA,SAAA,CAAA;IAAA,GAAA,CAAA,GAAA,EAAA,MAAA,EAAA,KAAA,EAAA,MAAA,CAAA,EA0BU,OA1BV,CAAA,IAAA,CAAA;IAAA,MAAA,CAAA,EAAA,EAgDT,QAhDS,CAAA,EAgDD,OAhDC,CAAA,IAAA,CAAA;EAAA,CAAA;CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,CAAA,wBAAA,wBAAA,wBAAA,EAAA,CAAA,CAAA,CAAA"}
+{"version":3,"file":"internal-fragment.d.ts","names":[],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/fragments/internal-fragment.js

@@ -5,35 +5,107 @@ import { DatabaseFragmentDefinitionBuilder } from "../db-fragment-definition-bui
 //#region src/fragments/internal-fragment.ts
 const SETTINGS_TABLE_NAME = "fragno_db_settings";
 const SETTINGS_NAMESPACE = "fragno-db-settings";
-const settingsSchema = schema((s) => {
+const internalSchema = schema((s) => {
 	return s.addTable(SETTINGS_TABLE_NAME, (t) => {
 		return t.addColumn("id", idColumn()).addColumn("key", column("string")).addColumn("value", column("string")).createIndex("unique_key", ["key"], { unique: true });
+	}).addTable("fragno_hooks", (t) => {
+		return t.addColumn("id", idColumn()).addColumn("namespace", column("string")).addColumn("hookName", column("string")).addColumn("payload", column("json")).addColumn("status", column("string")).addColumn("attempts", column("integer").defaultTo(0)).addColumn("maxAttempts", column("integer").defaultTo(5)).addColumn("lastAttemptAt", column("timestamp").nullable()).addColumn("nextRetryAt", column("timestamp").nullable()).addColumn("error", column("string").nullable()).addColumn("createdAt", column("timestamp").defaultTo((b) => b.now())).addColumn("nonce", column("string")).createIndex("idx_namespace_status_retry", [
+			"namespace",
+			"status",
+			"nextRetryAt"
+		]).createIndex("idx_nonce", ["nonce"]);
 	});
 });
-const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(new FragmentDefinitionBuilder("$fragno-internal-fragment"), settingsSchema, "").providesService("settingsService", ({ defineService }) => {
+const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(new FragmentDefinitionBuilder("$fragno-internal-fragment"), internalSchema, "").providesService("settingsService", ({ defineService }) => {
 	return defineService({
-		async get(key) {
-			const [results] = await this.uow(settingsSchema).find(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", `${SETTINGS_NAMESPACE}.${key}`))).retrievalPhase;
+		async get(namespace, key) {
+			const fullKey = `${namespace}.${key}`;
+			const [results] = await this.uow(internalSchema).find(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", fullKey))).retrievalPhase;
 			return results?.[0];
 		},
-		async set(key, value) {
-			const uow = this.uow(settingsSchema);
-			const [existing] = await uow.find(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", `${SETTINGS_NAMESPACE}.${key}`))).retrievalPhase;
+		async set(namespace, key, value) {
+			const fullKey = `${namespace}.${key}`;
+			const uow = this.uow(internalSchema);
+			const [existing] = await uow.find(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", fullKey))).retrievalPhase;
 			if (existing?.[0]) uow.update(SETTINGS_TABLE_NAME, existing[0].id, (b) => b.set({ value }).check());
 			else uow.create(SETTINGS_TABLE_NAME, {
-				key: `${SETTINGS_NAMESPACE}.${key}`,
+				key: fullKey,
 				value
 			});
 			await uow.mutationPhase;
 		},
 		async delete(id) {
-			const uow = this.uow(settingsSchema);
+			const uow = this.uow(internalSchema);
 			uow.delete(SETTINGS_TABLE_NAME, id);
 			await uow.mutationPhase;
 		}
 	});
+}).providesService("hookService", ({ defineService }) => {
+	return defineService({
+		async getPendingHookEvents(namespace) {
+			const [events] = await this.uow(internalSchema).find("fragno_hooks", (b) => b.whereIndex("idx_namespace_status_retry", (eb) => eb.and(eb("namespace", "=", namespace), eb("status", "=", "pending")))).retrievalPhase;
+			const now = /* @__PURE__ */ new Date();
+			return events.filter((event) => {
+				if (!event.nextRetryAt) return true;
+				return event.nextRetryAt <= now;
+			}).map((event) => ({
+				id: event.id,
+				hookName: event.hookName,
+				payload: event.payload,
+				attempts: event.attempts,
+				maxAttempts: event.maxAttempts,
+				nonce: event.nonce
+			}));
+		},
+		markHookCompleted(eventId) {
+			this.uow(internalSchema).update("fragno_hooks", eventId, (b) => b.set({
+				status: "completed",
+				lastAttemptAt: /* @__PURE__ */ new Date()
+			}).check());
+		},
+		markHookFailed(eventId, error, attempts, retryPolicy) {
+			const uow = this.uow(internalSchema);
+			const newAttempts = attempts + 1;
+			if (retryPolicy.shouldRetry(newAttempts - 1)) {
+				const delayMs = retryPolicy.getDelayMs(newAttempts - 1);
+				const nextRetryAt = new Date(Date.now() + delayMs);
+				uow.update("fragno_hooks", eventId, (b) => b.set({
+					status: "pending",
+					attempts: newAttempts,
+					lastAttemptAt: /* @__PURE__ */ new Date(),
+					nextRetryAt,
+					error
+				}).check());
+			} else uow.update("fragno_hooks", eventId, (b) => b.set({
+				status: "failed",
+				attempts: newAttempts,
+				lastAttemptAt: /* @__PURE__ */ new Date(),
+				error
+			}).check());
+		},
+		markHookProcessing(eventId) {
+			this.uow(internalSchema).update("fragno_hooks", eventId, (b) => b.set({
+				status: "processing",
+				lastAttemptAt: /* @__PURE__ */ new Date()
+			}).check());
+		}
+	});
 }).build();
+async function getSchemaVersionFromDatabase(fragment, namespace) {
+	try {
+		return await fragment.inContext(async function() {
+			const version = await this.uow(async ({ executeRetrieve }) => {
+				const version$1 = fragment.services.settingsService.get(namespace, "schema_version");
+				await executeRetrieve();
+				return version$1;
+			});
+			return version ? parseInt(version.value, 10) : 0;
+		});
+	} catch {
+		return 0;
+	}
+}
 
 //#endregion
-export { SETTINGS_NAMESPACE, SETTINGS_TABLE_NAME, internalFragmentDef, settingsSchema };
+export { SETTINGS_NAMESPACE, SETTINGS_TABLE_NAME, getSchemaVersionFromDatabase, internalFragmentDef, internalSchema };
 //# sourceMappingURL=internal-fragment.js.map

package/dist/fragments/internal-fragment.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal-fragment.js","names":[],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":["import { FragmentDefinitionBuilder } from \"@fragno-dev/core\";\nimport {\n  DatabaseFragmentDefinitionBuilder,\n  type DatabaseHandlerContext,\n  type DatabaseRequestStorage,\n  type DatabaseServiceContext,\n  type FragnoPublicConfigWithDatabase,\n  type ImplicitDatabaseDependencies,\n} from \"../db-fragment-definition-builder\";\nimport type { FragnoId } from \"../schema/create\";\nimport { schema, idColumn, column } from \"../schema/create\";\n\n// Constants for Fragno's internal settings table\nexport const SETTINGS_TABLE_NAME = \"fragno_db_settings\" as const;\nexport const SETTINGS_NAMESPACE = \"fragno-db-settings\" as const;\n\n// Settings schema for storing Fragno's internal key-value settings\nexport const settingsSchema = schema((s) => {\n  return s.addTable(SETTINGS_TABLE_NAME, (t) => {\n    return t\n      .addColumn(\"id\", idColumn())\n      .addColumn(\"key\", column(\"string\"))\n      .addColumn(\"value\", column(\"string\"))\n      .createIndex(\"unique_key\", [\"key\"], { unique: true });\n  });\n});\n\n// This uses DatabaseFragmentDefinitionBuilder directly\n// to avoid circular dependency (it doesn't need to link to itself)\nexport const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(\n  new FragmentDefinitionBuilder<\n    {},\n    FragnoPublicConfigWithDatabase,\n    ImplicitDatabaseDependencies<typeof settingsSchema>,\n    {},\n    {},\n    {},\n    {},\n    DatabaseServiceContext,\n    DatabaseHandlerContext,\n    DatabaseRequestStorage\n  >(\"$fragno-internal-fragment\"),\n  settingsSchema,\n  \"\", // intentionally blank namespace so there is no prefix\n)\n  .providesService(\"settingsService\", ({ defineService }) => {\n    return defineService({\n      async get(key: string): Promise<{ id: FragnoId; key: string; value: string } | undefined> {\n        const uow = this.uow(settingsSchema).find(SETTINGS_TABLE_NAME, (b) =>\n          b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", `${SETTINGS_NAMESPACE}.${key}`)),\n        );\n        const [results] = await uow.retrievalPhase;\n        return results?.[0];\n      },\n\n      async set(key: string, value: string) {\n        const uow = this.uow(settingsSchema);\n\n        // First, find if the key already exists\n        const findUow = uow.find(SETTINGS_TABLE_NAME, (b) =>\n          b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", `${SETTINGS_NAMESPACE}.${key}`)),\n        );\n        const [existing] = await findUow.retrievalPhase;\n\n        if (existing?.[0]) {\n          uow.update(SETTINGS_TABLE_NAME, existing[0].id, (b) => b.set({ value }).check());\n        } else {\n          uow.create(SETTINGS_TABLE_NAME, {\n            key: `${SETTINGS_NAMESPACE}.${key}`,\n            value,\n          });\n        }\n\n        // Await mutation phase - will throw if mutation fails\n        await uow.mutationPhase;\n      },\n\n      async delete(id: FragnoId) {\n        const uow = this.uow(settingsSchema);\n        uow.delete(SETTINGS_TABLE_NAME, id);\n        await uow.mutationPhase;\n      },\n    });\n  })\n  .build();\n"],"mappings":";;;;;AAaA,MAAa,sBAAsB;AACnC,MAAa,qBAAqB;AAGlC,MAAa,iBAAiB,QAAQ,MAAM;AAC1C,QAAO,EAAE,SAAS,sBAAsB,MAAM;AAC5C,SAAO,EACJ,UAAU,MAAM,UAAU,CAAC,CAC3B,UAAU,OAAO,OAAO,SAAS,CAAC,CAClC,UAAU,SAAS,OAAO,SAAS,CAAC,CACpC,YAAY,cAAc,CAAC,MAAM,EAAE,EAAE,QAAQ,MAAM,CAAC;GACvD;EACF;AAIF,MAAa,sBAAsB,IAAI,kCACrC,IAAI,0BAWF,4BAA4B,EAC9B,gBACA,GACD,CACE,gBAAgB,oBAAoB,EAAE,oBAAoB;AACzD,QAAO,cAAc;EACnB,MAAM,IAAI,KAAgF;GAIxF,MAAM,CAAC,WAAW,MAHN,KAAK,IAAI,eAAe,CAAC,KAAK,sBAAsB,MAC9D,EAAE,WAAW,eAAe,OAAO,GAAG,OAAO,KAAK,GAAG,mBAAmB,GAAG,MAAM,CAAC,CACnF,CAC2B;AAC5B,UAAO,UAAU;;EAGnB,MAAM,IAAI,KAAa,OAAe;GACpC,MAAM,MAAM,KAAK,IAAI,eAAe;GAMpC,MAAM,CAAC,YAAY,MAHH,IAAI,KAAK,sBAAsB,MAC7C,EAAE,WAAW,eAAe,OAAO,GAAG,OAAO,KAAK,GAAG,mBAAmB,GAAG,MAAM,CAAC,CACnF,CACgC;AAEjC,OAAI,WAAW,GACb,KAAI,OAAO,qBAAqB,SAAS,GAAG,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC;OAEhF,KAAI,OAAO,qBAAqB;IAC9B,KAAK,GAAG,mBAAmB,GAAG;IAC9B;IACD,CAAC;AAIJ,SAAM,IAAI;;EAGZ,MAAM,OAAO,IAAc;GACzB,MAAM,MAAM,KAAK,IAAI,eAAe;AACpC,OAAI,OAAO,qBAAqB,GAAG;AACnC,SAAM,IAAI;;EAEb,CAAC;EACF,CACD,OAAO"}
+{"version":3,"file":"internal-fragment.js","names":["version"],"sources":["../../src/fragments/internal-fragment.ts"],"sourcesContent":["import { FragmentDefinitionBuilder } from \"@fragno-dev/core\";\nimport type { InstantiatedFragmentFromDefinition } from \"@fragno-dev/core\";\nimport {\n  DatabaseFragmentDefinitionBuilder,\n  type DatabaseHandlerContext,\n  type DatabaseRequestStorage,\n  type DatabaseServiceContext,\n  type FragnoPublicConfigWithDatabase,\n  type ImplicitDatabaseDependencies,\n} from \"../db-fragment-definition-builder\";\nimport type { FragnoId } from \"../schema/create\";\nimport { schema, idColumn, column } from \"../schema/create\";\nimport type { RetryPolicy } from \"../query/unit-of-work/retry-policy\";\n\n// Constants for Fragno's internal settings table\nexport const SETTINGS_TABLE_NAME = \"fragno_db_settings\" as const;\n// FIXME: In some places we simply use empty string \"\" as namespace, which is not correct.\nexport const SETTINGS_NAMESPACE = \"fragno-db-settings\" as const;\n\nexport const internalSchema = schema((s) => {\n  return s\n    .addTable(SETTINGS_TABLE_NAME, (t) => {\n      return t\n        .addColumn(\"id\", idColumn())\n        .addColumn(\"key\", column(\"string\"))\n        .addColumn(\"value\", column(\"string\"))\n        .createIndex(\"unique_key\", [\"key\"], { unique: true });\n    })\n    .addTable(\"fragno_hooks\", (t) => {\n      return t\n        .addColumn(\"id\", idColumn())\n        .addColumn(\"namespace\", column(\"string\"))\n        .addColumn(\"hookName\", column(\"string\"))\n        .addColumn(\"payload\", column(\"json\"))\n        .addColumn(\"status\", column(\"string\")) // \"pending\" | \"processing\" | \"completed\" | \"failed\"\n        .addColumn(\"attempts\", column(\"integer\").defaultTo(0))\n        .addColumn(\"maxAttempts\", column(\"integer\").defaultTo(5))\n        .addColumn(\"lastAttemptAt\", column(\"timestamp\").nullable())\n        .addColumn(\"nextRetryAt\", column(\"timestamp\").nullable())\n        .addColumn(\"error\", column(\"string\").nullable())\n        .addColumn(\n          \"createdAt\",\n          column(\"timestamp\").defaultTo((b) => b.now()),\n        )\n        .addColumn(\"nonce\", column(\"string\"))\n        .createIndex(\"idx_namespace_status_retry\", [\"namespace\", \"status\", \"nextRetryAt\"])\n        .createIndex(\"idx_nonce\", [\"nonce\"]);\n    });\n});\n\n// This uses DatabaseFragmentDefinitionBuilder directly\n// to avoid circular dependency (it doesn't need to link to itself)\nexport const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(\n  new FragmentDefinitionBuilder<\n    {},\n    FragnoPublicConfigWithDatabase,\n    ImplicitDatabaseDependencies<typeof internalSchema>,\n    {},\n    {},\n    {},\n    {},\n    DatabaseServiceContext<{}>,\n    DatabaseHandlerContext,\n    DatabaseRequestStorage\n  >(\"$fragno-internal-fragment\"),\n  internalSchema,\n  \"\", // intentionally blank namespace so there is no prefix\n)\n  .providesService(\"settingsService\", ({ defineService }) => {\n    return defineService({\n      async get(\n        namespace: string,\n        key: string,\n      ): Promise<{ id: FragnoId; key: string; value: string } | undefined> {\n        const fullKey = `${namespace}.${key}`;\n        const uow = this.uow(internalSchema).find(SETTINGS_TABLE_NAME, (b) =>\n          b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", fullKey)),\n        );\n        const [results] = await uow.retrievalPhase;\n        return results?.[0];\n      },\n\n      async set(namespace: string, key: string, value: string) {\n        const fullKey = `${namespace}.${key}`;\n        const uow = this.uow(internalSchema);\n\n        // First, find if the key already exists\n        const findUow = uow.find(SETTINGS_TABLE_NAME, (b) =>\n          b.whereIndex(\"unique_key\", (eb) => eb(\"key\", \"=\", fullKey)),\n        );\n        const [existing] = await findUow.retrievalPhase;\n\n        if (existing?.[0]) {\n          uow.update(SETTINGS_TABLE_NAME, existing[0].id, (b) => b.set({ value }).check());\n        } else {\n          uow.create(SETTINGS_TABLE_NAME, {\n            key: fullKey,\n            value,\n          });\n        }\n\n        // Await mutation phase - will throw if mutation fails\n        await uow.mutationPhase;\n      },\n\n      async delete(id: FragnoId) {\n        const uow = this.uow(internalSchema);\n        uow.delete(SETTINGS_TABLE_NAME, id);\n        await uow.mutationPhase;\n      },\n    });\n  })\n  .providesService(\"hookService\", ({ defineService }) => {\n    // TODO(Wilco): re-implement this better\n    return defineService({\n      /**\n       * Get pending hook events for processing.\n       * Returns all pending events for the given namespace that are ready to be processed.\n       */\n      async getPendingHookEvents(namespace: string): Promise<\n        {\n          id: FragnoId;\n          hookName: string;\n          payload: unknown;\n          attempts: number;\n          maxAttempts: number;\n          nonce: string;\n        }[]\n      > {\n        const uow = this.uow(internalSchema).find(\"fragno_hooks\", (b) =>\n          b.whereIndex(\"idx_namespace_status_retry\", (eb) =>\n            eb.and(eb(\"namespace\", \"=\", namespace), eb(\"status\", \"=\", \"pending\")),\n          ),\n        );\n\n        const [events] = await uow.retrievalPhase;\n\n        // Filter for pending status and events ready for retry\n        const now = new Date();\n        const ready = events.filter((event) => {\n          // FIXME(Wilco): this should be handled by the database query, but there seems to be an issue.\n          if (!event.nextRetryAt) {\n            return true; // Newly created events (nextRetryAt = null) are ready\n          }\n          return event.nextRetryAt <= now; // Only include if retry time has passed\n        });\n\n        return ready.map((event) => ({\n          id: event.id,\n          hookName: event.hookName,\n          payload: event.payload,\n          attempts: event.attempts,\n          maxAttempts: event.maxAttempts,\n          nonce: event.nonce,\n        }));\n      },\n\n      /**\n       * Mark a hook event as completed.\n       */\n      markHookCompleted(eventId: FragnoId): void {\n        const uow = this.uow(internalSchema);\n        uow.update(\"fragno_hooks\", eventId, (b) =>\n          b.set({ status: \"completed\", lastAttemptAt: new Date() }).check(),\n        );\n      },\n\n      /**\n       * Mark a hook event as failed and schedule next retry.\n       */\n      markHookFailed(\n        eventId: FragnoId,\n        error: string,\n        attempts: number,\n        retryPolicy: RetryPolicy,\n      ): void {\n        const uow = this.uow(internalSchema);\n\n        const newAttempts = attempts + 1;\n        const shouldRetry = retryPolicy.shouldRetry(newAttempts - 1);\n\n        if (shouldRetry) {\n          const delayMs = retryPolicy.getDelayMs(newAttempts - 1);\n          const nextRetryAt = new Date(Date.now() + delayMs);\n          uow.update(\"fragno_hooks\", eventId, (b) =>\n            b\n              .set({\n                status: \"pending\",\n                attempts: newAttempts,\n                lastAttemptAt: new Date(),\n                nextRetryAt,\n                error,\n              })\n              .check(),\n          );\n        } else {\n          uow.update(\"fragno_hooks\", eventId, (b) =>\n            b\n              .set({\n                status: \"failed\",\n                attempts: newAttempts,\n                lastAttemptAt: new Date(),\n                error,\n              })\n              .check(),\n          );\n        }\n      },\n\n      /**\n       * Mark a hook event as processing (to prevent concurrent execution).\n       */\n      markHookProcessing(eventId: FragnoId): void {\n        const uow = this.uow(internalSchema);\n        uow.update(\"fragno_hooks\", eventId, (b) =>\n          b.set({ status: \"processing\", lastAttemptAt: new Date() }).check(),\n        );\n      },\n    });\n  })\n  .build();\n\n/**\n * Type representing an instantiated internal fragment.\n * This is the fragment that manages Fragno's internal settings table.\n */\nexport type InternalFragmentInstance = InstantiatedFragmentFromDefinition<\n  typeof internalFragmentDef\n>;\n\nexport async function getSchemaVersionFromDatabase(\n  fragment: InternalFragmentInstance,\n  namespace: string,\n): Promise<number> {\n  try {\n    const version = await fragment.inContext(async function () {\n      const version = await this.uow(async ({ executeRetrieve }) => {\n        const version = fragment.services.settingsService.get(namespace, \"schema_version\");\n        await executeRetrieve();\n        return version;\n      });\n\n      return version ? parseInt(version.value, 10) : 0;\n    });\n    return version;\n  } catch {\n    return 0;\n  }\n}\n"],"mappings":"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"}

package/dist/hooks/hooks.d.ts

@@ -0,0 +1,51 @@
+import { RetryPolicy } from "../query/unit-of-work/retry-policy.js";
+
+//#region src/hooks/hooks.d.ts
+
+/**
+ * Context available in hook functions via `this`.
+ * Contains the nonce for idempotency and database access.
+ */
+interface HookContext {
+  /**
+   * Unique nonce for this transaction.
+   * Use this for idempotency checks in your hook implementation.
+   */
+  nonce: string;
+}
+/**
+ * A hook function signature.
+ * Hooks receive a typed payload and access context via `this`.
+ */
+type HookFn<TPayload = unknown> = (payload: TPayload) => void | Promise<void>;
+/**
+ * Map of hook names to hook functions.
+ * Used for type-safe hook definitions and triggering.
+ */
+type HooksMap = Record<string, HookFn<any>>;
+/**
+ * Extract the payload type from a hook function.
+ */
+type HookPayload<T> = T extends HookFn<infer P> ? P : never;
+/**
+ * Options for triggering a hook.
+ */
+interface TriggerHookOptions {
+  /**
+   * Optional retry policy override for this specific hook trigger.
+   * If not provided, uses the default retry policy.
+   */
+  retryPolicy?: RetryPolicy;
+}
+/**
+ * Internal representation of a triggered hook.
+ * Stored in the Unit of Work before execution.
+ */
+interface TriggeredHook {
+  hookName: string;
+  payload: unknown;
+  options?: TriggerHookOptions;
+}
+//#endregion
+export { HookContext, HookFn, HookPayload, HooksMap, TriggerHookOptions, TriggeredHook };
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","names":[],"sources":["../../src/hooks/hooks.ts"],"sourcesContent":[],"mappings":";;;;AASA;AAYA;AAOA;AAKA;AAA6B,UAxBZ,WAAA,CAwBY;EAAU;;;AAKvC;EAYiB,KAAA,EAAA,MAAA;;;;;;KA7BL,uCAAuC,oBAAoB;;;;;KAO3D,QAAA,GAAW,eAAe;;;;KAK1B,iBAAiB,UAAU,kBAAkB;;;;UAKxC,kBAAA;;;;;gBAKD;;;;;;UAOC,aAAA;;;YAGL"}

package/dist/hooks/hooks.js

@@ -0,0 +1,88 @@
+import { ExponentialBackoffRetryPolicy } from "../query/unit-of-work/retry-policy.js";
+
+//#region src/hooks/hooks.ts
+/**
+* Add hook events as mutation operations to the UOW.
+* This should be called before executeMutations() so hook records are created
+* in the same transaction as the user's mutations.
+*/
+function prepareHookMutations(uow, config) {
+	const { namespace, internalFragment, defaultRetryPolicy } = config;
+	const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+	const triggeredHooks = uow.getTriggeredHooks();
+	if (triggeredHooks.length === 0) return;
+	const internalSchema = internalFragment.$internal.deps.schema;
+	const internalUow = uow.forSchema(internalSchema);
+	for (const hook of triggeredHooks) {
+		const maxAttempts = (hook.options?.retryPolicy ?? retryPolicy).shouldRetry(4) ? 5 : 1;
+		internalUow.create("fragno_hooks", {
+			namespace,
+			hookName: hook.hookName,
+			payload: hook.payload,
+			status: "pending",
+			attempts: 0,
+			maxAttempts,
+			lastAttemptAt: null,
+			nextRetryAt: null,
+			error: null,
+			nonce: uow.nonce
+		});
+	}
+}
+/**
+* Process pending hook events after the transaction has committed.
+* This should be called in the onSuccess callback after executeMutations().
+*/
+async function processHooks(config) {
+	const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;
+	const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+	await internalFragment.inContext(async function() {
+		return await this.uow(async ({ executeRetrieve, executeMutate }) => {
+			const pendingEventsPromise = internalFragment.services.hookService.getPendingHookEvents(namespace);
+			await executeRetrieve();
+			const pendingEvents = await pendingEventsPromise;
+			if (pendingEvents.length === 0) return;
+			const processedEvents = await Promise.allSettled(pendingEvents.map(async (event) => {
+				const hookFn = hooks[event.hookName];
+				if (!hookFn) return {
+					eventId: event.id,
+					status: "failed",
+					error: `Hook '${event.hookName}' not found in hooks map`,
+					attempts: event.attempts,
+					maxAttempts: event.maxAttempts
+				};
+				try {
+					const hookContext = { nonce: event.nonce };
+					await hookFn.call(hookContext, event.payload);
+					return {
+						eventId: event.id,
+						status: "completed"
+					};
+				} catch (error) {
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					return {
+						eventId: event.id,
+						status: "failed",
+						error: errorMessage,
+						attempts: event.attempts,
+						maxAttempts: event.maxAttempts
+					};
+				}
+			}));
+			for (const processedEvent of processedEvents) {
+				if (processedEvent.status === "rejected") continue;
+				const { eventId, status } = processedEvent.value;
+				if (status === "completed") internalFragment.services.hookService.markHookCompleted(eventId);
+				else if (status === "failed") {
+					const { error, attempts } = processedEvent.value;
+					internalFragment.services.hookService.markHookFailed(eventId, error, attempts, retryPolicy);
+				}
+			}
+			await executeMutate();
+		});
+	});
+}
+
+//#endregion
+export { prepareHookMutations, processHooks };
+//# sourceMappingURL=hooks.js.map

package/dist/hooks/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","names":["hookContext: HookContext"],"sources":["../../src/hooks/hooks.ts"],"sourcesContent":["import type { RetryPolicy } from \"../query/unit-of-work/retry-policy\";\nimport { ExponentialBackoffRetryPolicy } from \"../query/unit-of-work/retry-policy\";\nimport type { IUnitOfWork } from \"../query/unit-of-work/unit-of-work\";\nimport type { InternalFragmentInstance } from \"../fragments/internal-fragment\";\n\n/**\n * Context available in hook functions via `this`.\n * Contains the nonce for idempotency and database access.\n */\nexport interface HookContext {\n  /**\n   * Unique nonce for this transaction.\n   * Use this for idempotency checks in your hook implementation.\n   */\n  nonce: string;\n}\n\n/**\n * A hook function signature.\n * Hooks receive a typed payload and access context via `this`.\n */\nexport type HookFn<TPayload = unknown> = (payload: TPayload) => void | Promise<void>;\n\n/**\n * Map of hook names to hook functions.\n * Used for type-safe hook definitions and triggering.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type HooksMap = Record<string, HookFn<any>>;\n\n/**\n * Extract the payload type from a hook function.\n */\nexport type HookPayload<T> = T extends HookFn<infer P> ? P : never;\n\n/**\n * Options for triggering a hook.\n */\nexport interface TriggerHookOptions {\n  /**\n   * Optional retry policy override for this specific hook trigger.\n   * If not provided, uses the default retry policy.\n   */\n  retryPolicy?: RetryPolicy;\n}\n\n/**\n * Internal representation of a triggered hook.\n * Stored in the Unit of Work before execution.\n */\nexport interface TriggeredHook {\n  hookName: string;\n  payload: unknown;\n  options?: TriggerHookOptions;\n}\n\n/**\n * Configuration for hook processing.\n */\nexport interface HookProcessorConfig {\n  hooks: HooksMap;\n  namespace: string;\n  internalFragment: InternalFragmentInstance;\n  defaultRetryPolicy?: RetryPolicy;\n}\n\n/**\n * Add hook events as mutation operations to the UOW.\n * This should be called before executeMutations() so hook records are created\n * in the same transaction as the user's mutations.\n */\nexport function prepareHookMutations(uow: IUnitOfWork, config: HookProcessorConfig): void {\n  const { namespace, internalFragment, defaultRetryPolicy } = config;\n  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });\n\n  const triggeredHooks = uow.getTriggeredHooks();\n\n  if (triggeredHooks.length === 0) {\n    return;\n  }\n\n  const internalSchema = internalFragment.$internal.deps.schema;\n  const internalUow = uow.forSchema(internalSchema);\n\n  for (const hook of triggeredHooks) {\n    const hookRetryPolicy = hook.options?.retryPolicy ?? retryPolicy;\n    const maxAttempts = hookRetryPolicy.shouldRetry(4) ? 5 : 1;\n    internalUow.create(\"fragno_hooks\", {\n      namespace,\n      hookName: hook.hookName,\n      payload: hook.payload,\n      status: \"pending\",\n      attempts: 0,\n      maxAttempts,\n      lastAttemptAt: null,\n      nextRetryAt: null,\n      error: null,\n      nonce: uow.nonce,\n    });\n  }\n}\n\n/**\n * Process pending hook events after the transaction has committed.\n * This should be called in the onSuccess callback after executeMutations().\n */\nexport async function processHooks(config: HookProcessorConfig): Promise<void> {\n  const { hooks, namespace, internalFragment, defaultRetryPolicy } = config;\n  const retryPolicy = defaultRetryPolicy ?? new ExponentialBackoffRetryPolicy({ maxRetries: 5 });\n\n  await internalFragment.inContext(async function () {\n    return await this.uow(async ({ executeRetrieve, executeMutate }) => {\n      const pendingEventsPromise =\n        internalFragment.services.hookService.getPendingHookEvents(namespace);\n      await executeRetrieve();\n\n      const pendingEvents = await pendingEventsPromise;\n\n      if (pendingEvents.length === 0) {\n        return;\n      }\n\n      const processedEvents = await Promise.allSettled(\n        pendingEvents.map(async (event) => {\n          const hookFn = hooks[event.hookName];\n          if (!hookFn) {\n            return {\n              eventId: event.id,\n              status: \"failed\" as const,\n              error: `Hook '${event.hookName}' not found in hooks map`,\n              attempts: event.attempts,\n              maxAttempts: event.maxAttempts,\n            };\n          }\n\n          try {\n            const hookContext: HookContext = { nonce: event.nonce };\n            await hookFn.call(hookContext, event.payload);\n            return {\n              eventId: event.id,\n              status: \"completed\" as const,\n            };\n          } catch (error) {\n            const errorMessage = error instanceof Error ? error.message : String(error);\n            return {\n              eventId: event.id,\n              status: \"failed\" as const,\n              error: errorMessage,\n              attempts: event.attempts,\n              maxAttempts: event.maxAttempts,\n            };\n          }\n        }),\n      );\n\n      for (const processedEvent of processedEvents) {\n        if (processedEvent.status === \"rejected\") {\n          continue;\n        }\n\n        const { eventId, status } = processedEvent.value;\n\n        if (status === \"completed\") {\n          internalFragment.services.hookService.markHookCompleted(eventId);\n        } else if (status === \"failed\") {\n          const { error, attempts } = processedEvent.value;\n          internalFragment.services.hookService.markHookFailed(\n            eventId,\n            error,\n            attempts,\n            retryPolicy,\n          );\n        }\n      }\n\n      await executeMutate();\n    });\n  });\n}\n"],"mappings":";;;;;;;;AAuEA,SAAgB,qBAAqB,KAAkB,QAAmC;CACxF,MAAM,EAAE,WAAW,kBAAkB,uBAAuB;CAC5D,MAAM,cAAc,sBAAsB,IAAI,8BAA8B,EAAE,YAAY,GAAG,CAAC;CAE9F,MAAM,iBAAiB,IAAI,mBAAmB;AAE9C,KAAI,eAAe,WAAW,EAC5B;CAGF,MAAM,iBAAiB,iBAAiB,UAAU,KAAK;CACvD,MAAM,cAAc,IAAI,UAAU,eAAe;AAEjD,MAAK,MAAM,QAAQ,gBAAgB;EAEjC,MAAM,eADkB,KAAK,SAAS,eAAe,aACjB,YAAY,EAAE,GAAG,IAAI;AACzD,cAAY,OAAO,gBAAgB;GACjC;GACA,UAAU,KAAK;GACf,SAAS,KAAK;GACd,QAAQ;GACR,UAAU;GACV;GACA,eAAe;GACf,aAAa;GACb,OAAO;GACP,OAAO,IAAI;GACZ,CAAC;;;;;;;AAQN,eAAsB,aAAa,QAA4C;CAC7E,MAAM,EAAE,OAAO,WAAW,kBAAkB,uBAAuB;CACnE,MAAM,cAAc,sBAAsB,IAAI,8BAA8B,EAAE,YAAY,GAAG,CAAC;AAE9F,OAAM,iBAAiB,UAAU,iBAAkB;AACjD,SAAO,MAAM,KAAK,IAAI,OAAO,EAAE,iBAAiB,oBAAoB;GAClE,MAAM,uBACJ,iBAAiB,SAAS,YAAY,qBAAqB,UAAU;AACvE,SAAM,iBAAiB;GAEvB,MAAM,gBAAgB,MAAM;AAE5B,OAAI,cAAc,WAAW,EAC3B;GAGF,MAAM,kBAAkB,MAAM,QAAQ,WACpC,cAAc,IAAI,OAAO,UAAU;IACjC,MAAM,SAAS,MAAM,MAAM;AAC3B,QAAI,CAAC,OACH,QAAO;KACL,SAAS,MAAM;KACf,QAAQ;KACR,OAAO,SAAS,MAAM,SAAS;KAC/B,UAAU,MAAM;KAChB,aAAa,MAAM;KACpB;AAGH,QAAI;KACF,MAAMA,cAA2B,EAAE,OAAO,MAAM,OAAO;AACvD,WAAM,OAAO,KAAK,aAAa,MAAM,QAAQ;AAC7C,YAAO;MACL,SAAS,MAAM;MACf,QAAQ;MACT;aACM,OAAO;KACd,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAC3E,YAAO;MACL,SAAS,MAAM;MACf,QAAQ;MACR,OAAO;MACP,UAAU,MAAM;MAChB,aAAa,MAAM;MACpB;;KAEH,CACH;AAED,QAAK,MAAM,kBAAkB,iBAAiB;AAC5C,QAAI,eAAe,WAAW,WAC5B;IAGF,MAAM,EAAE,SAAS,WAAW,eAAe;AAE3C,QAAI,WAAW,YACb,kBAAiB,SAAS,YAAY,kBAAkB,QAAQ;aACvD,WAAW,UAAU;KAC9B,MAAM,EAAE,OAAO,aAAa,eAAe;AAC3C,sBAAiB,SAAS,YAAY,eACpC,SACA,OACA,UACA,YACD;;;AAIL,SAAM,eAAe;IACrB;GACF"}

package/dist/migration-engine/generation-engine.d.ts

@@ -1,5 +1,4 @@
 import { AnySchema } from "../schema/create.js";
-import { PreparedMigration } from "./create.js";
 import { FragnoDatabase } from "../mod.js";
 
 //#region src/migration-engine/generation-engine.d.ts
@@ -14,7 +13,6 @@ interface GenerationInternalResult {
   namespace: string;
   fromVersion: number;
   toVersion: number;
-  preparedMigration?: PreparedMigration;
 }
 interface ExecuteMigrationResult {
   namespace: string;

package/dist/migration-engine/generation-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generation-engine.d.ts","names":[],"sources":["../../src/migration-engine/generation-engine.ts"],"sourcesContent":[],"mappings":";;;;;UAeiB,sBAAA;;EAAA,IAAA,EAAA,MAAA;EAMA,SAAA,EAAA,MAAA;AASjB;AAOsB,UAhBL,wBAAA,CAgB+B;EAEN,MAAA,EAAA,MAAA;EAAf,IAAA,EAAA,MAAA;EAEd,SAAA,EAAA,MAAA;EAMF,WAAA,EAAA,MAAA;EAAR,SAAA,EAAA,MAAA;EAAO,iBAAA,CAAA,EApBY,iBAoBZ;AA8KV;AAAgF,UA/L/D,sBAAA,CA+L+D;EAAf,SAAA,EAAA,MAAA;EACpD,UAAA,EAAA,OAAA;EACF,WAAA,EAAA,MAAA;EAAR,SAAA,EAAA,MAAA;;AA0Ja,iBApVM,0BAqVb,CAAA,yBAnVkB,cAoVxB,CApVuC,SAoVjB,EAAA,GAAA,CAAA,EAAA,CAAA,CAAA,SAAA,EAlVZ,UAkVY,EAAA,QAAA,EAAA;;;;IA5UtB,QAAQ;;;;;;;;iBA8KW,2CAA2C,eAAe,yBACnE,aACV,QAAQ;;;;;;;;;;;iBA0JK,6BAAA,QACP,6BACN"}
+{"version":3,"file":"generation-engine.d.ts","names":[],"sources":["../../src/migration-engine/generation-engine.ts"],"sourcesContent":[],"mappings":";;;;UAciB,sBAAA;;EAAA,IAAA,EAAA,MAAA;EAMA,SAAA,EAAA,MAAA;AAQjB;AAOsB,UAfL,wBAAA,CAe+B;EAEN,MAAA,EAAA,MAAA;EAAf,IAAA,EAAA,MAAA;EAEd,SAAA,EAAA,MAAA;EAMF,WAAA,EAAA,MAAA;EAAR,SAAA,EAAA,MAAA;;AA2ImB,UA5JL,sBAAA,CA4JsB;EAAyC,SAAA,EAAA,MAAA;EAAf,UAAA,EAAA,OAAA;EACpD,WAAA,EAAA,MAAA;EACF,SAAA,EAAA,MAAA;;AAAD,iBAvJY,0BAuJZ,CAAA,yBArJiB,cAqJjB,CArJgC,SAqJhC,EAAA,GAAA,CAAA,EAAA,CAAA,CAAA,SAAA,EAnJG,UAmJH,EAAA,QAAA,EAAA;EAiJM,IAAA,CAAA,EAAA,MAAA;;;IA9Rb,QAAQ;;;;;;;;iBA2IW,2CAA2C,eAAe,yBACnE,aACV,QAAQ;;;;;;;;;;;iBAiJK,6BAAA,QACP,6BACN"}

package/dist/migration-engine/generation-engine.js

@@ -1,5 +1,5 @@
 import { instantiate } from "../packages/fragno/dist/api/fragment-instantiator.js";
-import { SETTINGS_NAMESPACE, SETTINGS_TABLE_NAME, internalFragmentDef, settingsSchema } from "../fragments/internal-fragment.js";
+import { SETTINGS_NAMESPACE, getSchemaVersionFromDatabase, internalFragmentDef, internalSchema } from "../fragments/internal-fragment.js";
 import { fragnoDatabaseAdapterNameFakeSymbol, fragnoDatabaseAdapterVersionFakeSymbol } from "../adapters/adapters.js";
 
 //#region src/migration-engine/generation-engine.ts
@@ -11,7 +11,7 @@ async function generateMigrationsOrSchema(databases, options) {
 		if (options?.toVersion !== void 0 || options?.fromVersion !== void 0) console.warn("⚠️ Warning: --from and --to version options are not supported when generating schemas for multiple fragments and will be ignored.");
 		const fragmentsMap = /* @__PURE__ */ new Map();
 		fragmentsMap.set("", {
-			schema: settingsSchema,
+			schema: internalSchema,
 			namespace: ""
 		});
 		for (const db of databases) if (!fragmentsMap.has(db.namespace)) fragmentsMap.set(db.namespace, {
@@ -24,53 +24,33 @@ async function generateMigrationsOrSchema(databases, options) {
 			namespace: firstDb.namespace
 		}];
 	}
-	if (!adapter.createMigrationEngine) throw new Error("Adapter does not support migration-based schema generation. Ensure your adapter implements createMigrationEngine.");
+	if (!adapter.prepareMigrations) throw new Error("Adapter does not support migration-based schema generation. Ensure your adapter implements prepareMigrations.");
 	if (!await adapter.isConnectionHealthy()) throw new Error("Database connection is not healthy. Please check your database connection and try again.");
-	const internalFragment = instantiate(internalFragmentDef).withConfig({}).withOptions({ databaseAdapter: adapter }).build();
-	let settingsSourceVersion;
-	try {
-		const result = await internalFragment.inContext(async function() {
-			return await this.uow(async ({ executeRetrieve }) => {
-				const v = internalFragment.services.settingsService.get("version");
-				await executeRetrieve();
-				return v;
-			});
-		});
-		if (!result) settingsSourceVersion = 0;
-		else settingsSourceVersion = parseInt(result.value);
-	} catch {
-		settingsSourceVersion = 0;
-	}
+	const settingsSourceVersion = await getSchemaVersionFromDatabase(instantiate(internalFragmentDef).withConfig({}).withOptions({ databaseAdapter: adapter }).build(), SETTINGS_NAMESPACE);
 	const generatedFiles = [];
-	const settingsMigrator = adapter.createMigrationEngine(settingsSchema, "");
-	const settingsTargetVersion = settingsSchema.version;
-	const settingsMigration = await settingsMigrator.prepareMigrationTo(settingsTargetVersion, { fromVersion: settingsSourceVersion });
-	if (!settingsMigration.getSQL) throw new Error("Migration engine does not support SQL generation. Ensure your adapter's migration engine provides getSQL().");
-	const settingsSql = settingsMigration.getSQL();
+	const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
+	const settingsTargetVersion = internalSchema.version;
+	const settingsSql = settingsPreparedMigrations.getSQL(settingsSourceVersion, settingsTargetVersion);
 	if (settingsSql.trim()) generatedFiles.push({
 		schema: settingsSql,
 		path: "settings-migration.sql",
 		namespace: "",
 		fromVersion: settingsSourceVersion,
-		toVersion: settingsTargetVersion,
-		preparedMigration: settingsMigration
+		toVersion: settingsTargetVersion
 	});
 	for (const db of databases) {
 		const dbAdapter = db.adapter;
-		if (!dbAdapter.createMigrationEngine) throw new Error(`Adapter for ${db.namespace} does not support schema generation. Ensure your adapter implements either createSchemaGenerator or createMigrationEngine.`);
-		const migrator = dbAdapter.createMigrationEngine(db.schema, db.namespace);
+		if (!dbAdapter.prepareMigrations) throw new Error(`Adapter for ${db.namespace} does not support schema generation. Ensure your adapter implements either createSchemaGenerator or prepareMigrations.`);
+		const preparedMigrations = dbAdapter.prepareMigrations(db.schema, db.namespace);
 		const targetVersion = options?.toVersion ?? db.schema.version;
 		const sourceVersion = options?.fromVersion ?? 0;
-		const preparedMigration = await migrator.prepareMigrationTo(targetVersion, { fromVersion: sourceVersion });
-		if (!preparedMigration.getSQL) throw new Error("Migration engine does not support SQL generation. Ensure your adapter's migration engine provides getSQL().");
-		const sql = preparedMigration.getSQL();
+		const sql = preparedMigrations.getSQL(sourceVersion, targetVersion);
 		if (sql.trim()) generatedFiles.push({
 			schema: sql,
 			path: "schema.sql",
 			namespace: db.namespace,
 			fromVersion: sourceVersion,
-			toVersion: targetVersion,
-			preparedMigration
+			toVersion: targetVersion
 		});
 	}
 	return postProcessMigrationFilenames(generatedFiles);
@@ -85,7 +65,7 @@ async function generateMigrationsOrSchema(databases, options) {
 async function executeMigrations(databases) {
 	if (databases.length === 0) throw new Error("No databases provided for migration");
 	const adapter = databases[0].adapter;
-	if (!adapter.createMigrationEngine) throw new Error("Adapter does not support running migrations. The adapter only supports schema generation.\nTry using 'generateMigrationsOrSchema' instead to generate schema files.");
+	if (!adapter.prepareMigrations) throw new Error("Adapter does not support running migrations. The adapter only supports schema generation.\nTry using 'generateMigrationsOrSchema' instead to generate schema files.");
 	const firstAdapterName = adapter[fragnoDatabaseAdapterNameFakeSymbol];
 	const firstAdapterVersion = adapter[fragnoDatabaseAdapterVersionFakeSymbol];
 	for (const db of databases) {
@@ -97,51 +77,33 @@ async function executeMigrations(databases) {
 	const results = [];
 	const migrationsToExecute = [];
 	const internalFragment = instantiate(internalFragmentDef).withConfig({}).withOptions({ databaseAdapter: adapter }).build();
-	let settingsSourceVersion;
-	try {
-		const result = await internalFragment.inContext(async function() {
-			return this.uow(async ({ forSchema, executeRetrieve }) => {
-				const findOp = forSchema(settingsSchema).find(SETTINGS_TABLE_NAME, (b) => b.whereIndex("unique_key", (eb) => eb("key", "=", `${SETTINGS_NAMESPACE}.version`)));
-				await executeRetrieve();
-				const [results$1] = await findOp.retrievalPhase;
-				return results$1?.[0];
-			});
-		});
-		settingsSourceVersion = result ? parseInt(result.value) : 0;
-	} catch {
-		settingsSourceVersion = 0;
-	}
-	const settingsMigrator = adapter.createMigrationEngine(settingsSchema, "");
-	const settingsTargetVersion = settingsSchema.version;
+	const settingsSourceVersion = await getSchemaVersionFromDatabase(internalFragment, SETTINGS_NAMESPACE);
+	const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
+	const settingsTargetVersion = internalSchema.version;
 	if (settingsSourceVersion < settingsTargetVersion) {
-		const settingsMigration = await settingsMigrator.prepareMigrationTo(settingsTargetVersion, {
-			fromVersion: settingsSourceVersion,
-			updateSettings: true
-		});
-		if (settingsMigration.operations.length > 0) migrationsToExecute.push({
+		if (settingsPreparedMigrations.compile(settingsSourceVersion, settingsTargetVersion, { updateVersionInMigration: true }).statements.length > 0) migrationsToExecute.push({
 			namespace: "",
 			fromVersion: settingsSourceVersion,
 			toVersion: settingsTargetVersion,
-			preparedMigration: settingsMigration
+			execute: () => settingsPreparedMigrations.execute(settingsSourceVersion, settingsTargetVersion, { updateVersionInMigration: true })
 		});
 	}
 	const sortedDatabases = [...databases].sort((a, b) => a.namespace.localeCompare(b.namespace));
 	for (const fragnoDb of sortedDatabases) {
-		const migrator = adapter.createMigrationEngine(fragnoDb.schema, fragnoDb.namespace);
-		const currentVersion = await migrator.getVersion();
+		const preparedMigrations = adapter.prepareMigrations(fragnoDb.schema, fragnoDb.namespace);
+		const currentVersion = await getSchemaVersionFromDatabase(internalFragment, fragnoDb.namespace);
 		const targetVersion = fragnoDb.schema.version;
 		if (currentVersion < targetVersion) {
-			const preparedMigration = await migrator.prepareMigrationTo(targetVersion, { updateSettings: true });
-			if (preparedMigration.operations.length > 0) migrationsToExecute.push({
+			if (preparedMigrations.compile(currentVersion, targetVersion, { updateVersionInMigration: true }).statements.length > 0) migrationsToExecute.push({
 				namespace: fragnoDb.namespace,
 				fromVersion: currentVersion,
 				toVersion: targetVersion,
-				preparedMigration
+				execute: () => preparedMigrations.execute(currentVersion, targetVersion, { updateVersionInMigration: true })
 			});
 		}
 	}
 	for (const migration of migrationsToExecute) {
-		await migration.preparedMigration.execute();
+		await migration.execute();
 		results.push({
 			namespace: migration.namespace,
 			didMigrate: true,