@kontsedal/olas-core 0.0.3 → 0.0.5

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_root = require("./root-D_xAdcom.cjs");
+const require_root = require("./root-lBp7qziQ.cjs");
 //#region src/signals/readonly.ts
 /**
 * Project a Signal (or any object with a reactive `value` + `peek` + `subscribe`)
@@ -395,6 +395,7 @@ function throttled(source, ms, options) {
 	return out;
 }
 //#endregion
+exports._unregisterMutationById = require_root._unregisterMutationById;
 exports.batch = require_root.batch;
 exports.computed = require_root.computed;
 exports.createEmitter = require_root.createEmitter;
@@ -403,12 +404,14 @@ exports.debounced = debounced;
 exports.debouncedValidator = require_root.debouncedValidator;
 exports.defineController = require_root.defineController;
 exports.defineInfiniteQuery = defineInfiniteQuery;
+exports.defineMutation = require_root.defineMutation;
 exports.defineQuery = defineQuery;
 exports.defineScope = defineScope;
 exports.effect = require_root.effect;
 exports.email = email;
 exports.isAbortError = require_root.isAbortError;
 exports.isStandardSchema = isStandardSchema;
+exports.lookupRegisteredMutation = require_root.lookupRegisteredMutation;
 exports.lookupRegisteredQuery = require_root.lookupRegisteredQuery;
 exports.max = max;
 exports.maxLength = maxLength;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { $ as FormErrors, A as DebugEvent, B as QuerySpec, C as SetDataEvent, D as MutationSpec, E as MutationConcurrency, F as AsyncStatus, G as UseOptions, H as RetryDelay, I as DehydratedEntry, J as FieldArrayItemErrors, K as DeepPartial, L as DehydratedState, M as InfiniteQuerySpec, N as InfiniteQuerySubscription, O as DebugBus, P as AsyncState, Q as Form, R as LocalCache, S as RegisteredQuery, T as Mutation, U as RetryPolicy, V as QuerySubscription, W as Snapshot, X as FieldArrayValidator, Y as FieldArrayOptions, Z as FieldArrayValue, _ as defineScope, a as CollectionFactoryResult, at as Validator, b as QueryClientPlugin, c as CtrlApi, ct as Signal, d as Field, dt as EmitterErrorReporter, et as FormOptions, f as LazyChild, ft as createEmitter, g as ScopeOptions, h as Scope, i as CollectionFactoryOptions, it as ItemInitial, j as InfiniteQuery, k as DebugCacheEntry, l as CtrlProps, lt as ErrorContext, m as RootOptions, n as Collection, nt as FormValidator, o as CollectionHomogeneousOptions, ot as Computed, p as Root, q as FieldArray, r as CollectionFactoryApi, rt as FormValue, s as ControllerDef, st as ReadSignal, t as AmbientDeps, tt as FormSchema, u as Ctx, ut as Emitter, v as GcEvent, w as lookupRegisteredQuery, x as QueryClientPluginApi, y as InvalidateEvent, z as Query } from "./types-r_TVaRkD.cjs";
+import { $ as DeepPartial, A as Mutation, B as InfiniteQuerySubscription, C as QueryClientPluginApi, D as _unregisterMutationById, E as SetDataEvent, F as DebugBus, G as LocalCache, H as AsyncStatus, I as DebugCacheEntry, J as QuerySubscription, K as Query, L as DebugEvent, M as MutationDef, N as MutationSpec, O as lookupRegisteredMutation, P as defineMutation, Q as UseOptions, R as InfiniteQuery, S as QueryClientPlugin, T as RegisteredQuery, U as DehydratedEntry, V as AsyncState, W as DehydratedState, X as RetryPolicy, Y as RetryDelay, Z as Snapshot, _ as defineScope, _t as Emitter, a as CollectionFactoryResult, at as Form, b as MutationEnqueueEvent, c as CtrlApi, ct as FormSchema, d as Field, dt as ItemInitial, et as FieldArray, f as LazyChild, ft as Validator, g as ScopeOptions, gt as ErrorContext, h as Scope, ht as Signal, i as CollectionFactoryOptions, it as FieldArrayValue, j as MutationConcurrency, k as lookupRegisteredQuery, l as CtrlProps, lt as FormValidator, m as RootOptions, mt as ReadSignal, n as Collection, nt as FieldArrayOptions, o as CollectionHomogeneousOptions, ot as FormErrors, p as Root, pt as Computed, q as QuerySpec, r as CollectionFactoryApi, rt as FieldArrayValidator, s as ControllerDef, st as FormOptions, t as AmbientDeps, tt as FieldArrayItemErrors, u as Ctx, ut as FormValue, v as GcEvent, vt as EmitterErrorReporter, w as RegisteredMutation, x as MutationSettleEvent, y as InvalidateEvent, yt as createEmitter, z as InfiniteQuerySpec } from "./types-C4Vtkxbn.cjs";
 
 //#region src/signals/runtime.d.ts
 /**
@@ -245,5 +245,5 @@ declare function throttled<T>(source: ReadSignal<T>, ms: number, options?: {
  */
 declare function isAbortError(err: unknown): boolean;
 //#endregion
-export { type AmbientDeps, type AsyncState, type AsyncStatus, type Collection, type CollectionFactoryApi, type CollectionFactoryOptions, type CollectionFactoryResult, type CollectionHomogeneousOptions, type Computed, type ControllerDef, type CtrlApi, type CtrlProps, type Ctx, type DebugBus, type DebugCacheEntry, type DebugEvent, type DeepPartial, type DehydratedEntry, type DehydratedState, type Emitter, type EmitterErrorReporter, type ErrorContext, type Field, type FieldArray, type FieldArrayItemErrors, type FieldArrayOptions, type FieldArrayValidator, type FieldArrayValue, type Form, type FormErrors, type FormOptions, type FormSchema, type FormValidator, type FormValue, type GcEvent, type InfiniteQuery, type InfiniteQuerySpec, type InfiniteQuerySubscription, type InvalidateEvent, type ItemInitial, type LazyChild, type LocalCache, type Mutation, type MutationConcurrency, type MutationSpec, type Query, type QueryClientPlugin, type QueryClientPluginApi, type QuerySpec, type QuerySubscription, type ReadSignal, type RegisteredQuery, type RetryDelay, type RetryPolicy, type Root, type RootOptions, type Scope, type ScopeOptions, type Selection, type SetDataEvent, type Signal, type Snapshot, type StandardSchemaV1, type UseOptions, type Validator, batch, computed, createEmitter, createRoot, debounced, debouncedValidator, defineController, defineInfiniteQuery, defineQuery, defineScope, effect, email, isAbortError, isStandardSchema, lookupRegisteredQuery, max, maxLength, min, minLength, pattern, required, selection, signal, stableHash, throttled, untracked, validator };
+export { type AmbientDeps, type AsyncState, type AsyncStatus, type Collection, type CollectionFactoryApi, type CollectionFactoryOptions, type CollectionFactoryResult, type CollectionHomogeneousOptions, type Computed, type ControllerDef, type CtrlApi, type CtrlProps, type Ctx, type DebugBus, type DebugCacheEntry, type DebugEvent, type DeepPartial, type DehydratedEntry, type DehydratedState, type Emitter, type EmitterErrorReporter, type ErrorContext, type Field, type FieldArray, type FieldArrayItemErrors, type FieldArrayOptions, type FieldArrayValidator, type FieldArrayValue, type Form, type FormErrors, type FormOptions, type FormSchema, type FormValidator, type FormValue, type GcEvent, type InfiniteQuery, type InfiniteQuerySpec, type InfiniteQuerySubscription, type InvalidateEvent, type ItemInitial, type LazyChild, type LocalCache, type Mutation, type MutationConcurrency, type MutationDef, type MutationEnqueueEvent, type MutationSettleEvent, type MutationSpec, type Query, type QueryClientPlugin, type QueryClientPluginApi, type QuerySpec, type QuerySubscription, type ReadSignal, type RegisteredMutation, type RegisteredQuery, type RetryDelay, type RetryPolicy, type Root, type RootOptions, type Scope, type ScopeOptions, type Selection, type SetDataEvent, type Signal, type Snapshot, type StandardSchemaV1, type UseOptions, type Validator, _unregisterMutationById, batch, computed, createEmitter, createRoot, debounced, debouncedValidator, defineController, defineInfiniteQuery, defineMutation, defineQuery, defineScope, effect, email, isAbortError, isStandardSchema, lookupRegisteredMutation, lookupRegisteredQuery, max, maxLength, min, minLength, pattern, required, selection, signal, stableHash, throttled, untracked, validator };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as FormErrors, A as DebugEvent, B as QuerySpec, C as SetDataEvent, D as MutationSpec, E as MutationConcurrency, F as AsyncStatus, G as UseOptions, H as RetryDelay, I as DehydratedEntry, J as FieldArrayItemErrors, K as DeepPartial, L as DehydratedState, M as InfiniteQuerySpec, N as InfiniteQuerySubscription, O as DebugBus, P as AsyncState, Q as Form, R as LocalCache, S as RegisteredQuery, T as Mutation, U as RetryPolicy, V as QuerySubscription, W as Snapshot, X as FieldArrayValidator, Y as FieldArrayOptions, Z as FieldArrayValue, _ as defineScope, a as CollectionFactoryResult, at as Validator, b as QueryClientPlugin, c as CtrlApi, ct as Signal, d as Field, dt as EmitterErrorReporter, et as FormOptions, f as LazyChild, ft as createEmitter, g as ScopeOptions, h as Scope, i as CollectionFactoryOptions, it as ItemInitial, j as InfiniteQuery, k as DebugCacheEntry, l as CtrlProps, lt as ErrorContext, m as RootOptions, n as Collection, nt as FormValidator, o as CollectionHomogeneousOptions, ot as Computed, p as Root, q as FieldArray, r as CollectionFactoryApi, rt as FormValue, s as ControllerDef, st as ReadSignal, t as AmbientDeps, tt as FormSchema, u as Ctx, ut as Emitter, v as GcEvent, w as lookupRegisteredQuery, x as QueryClientPluginApi, y as InvalidateEvent, z as Query } from "./types-CRn4UoLn.mjs";
+import { $ as DeepPartial, A as Mutation, B as InfiniteQuerySubscription, C as QueryClientPluginApi, D as _unregisterMutationById, E as SetDataEvent, F as DebugBus, G as LocalCache, H as AsyncStatus, I as DebugCacheEntry, J as QuerySubscription, K as Query, L as DebugEvent, M as MutationDef, N as MutationSpec, O as lookupRegisteredMutation, P as defineMutation, Q as UseOptions, R as InfiniteQuery, S as QueryClientPlugin, T as RegisteredQuery, U as DehydratedEntry, V as AsyncState, W as DehydratedState, X as RetryPolicy, Y as RetryDelay, Z as Snapshot, _ as defineScope, _t as Emitter, a as CollectionFactoryResult, at as Form, b as MutationEnqueueEvent, c as CtrlApi, ct as FormSchema, d as Field, dt as ItemInitial, et as FieldArray, f as LazyChild, ft as Validator, g as ScopeOptions, gt as ErrorContext, h as Scope, ht as Signal, i as CollectionFactoryOptions, it as FieldArrayValue, j as MutationConcurrency, k as lookupRegisteredQuery, l as CtrlProps, lt as FormValidator, m as RootOptions, mt as ReadSignal, n as Collection, nt as FieldArrayOptions, o as CollectionHomogeneousOptions, ot as FormErrors, p as Root, pt as Computed, q as QuerySpec, r as CollectionFactoryApi, rt as FieldArrayValidator, s as ControllerDef, st as FormOptions, t as AmbientDeps, tt as FieldArrayItemErrors, u as Ctx, ut as FormValue, v as GcEvent, vt as EmitterErrorReporter, w as RegisteredMutation, x as MutationSettleEvent, y as InvalidateEvent, yt as createEmitter, z as InfiniteQuerySpec } from "./types-BH1o6nYa.mjs";
 
 //#region src/signals/runtime.d.ts
 /**
@@ -245,5 +245,5 @@ declare function throttled<T>(source: ReadSignal<T>, ms: number, options?: {
  */
 declare function isAbortError(err: unknown): boolean;
 //#endregion
-export { type AmbientDeps, type AsyncState, type AsyncStatus, type Collection, type CollectionFactoryApi, type CollectionFactoryOptions, type CollectionFactoryResult, type CollectionHomogeneousOptions, type Computed, type ControllerDef, type CtrlApi, type CtrlProps, type Ctx, type DebugBus, type DebugCacheEntry, type DebugEvent, type DeepPartial, type DehydratedEntry, type DehydratedState, type Emitter, type EmitterErrorReporter, type ErrorContext, type Field, type FieldArray, type FieldArrayItemErrors, type FieldArrayOptions, type FieldArrayValidator, type FieldArrayValue, type Form, type FormErrors, type FormOptions, type FormSchema, type FormValidator, type FormValue, type GcEvent, type InfiniteQuery, type InfiniteQuerySpec, type InfiniteQuerySubscription, type InvalidateEvent, type ItemInitial, type LazyChild, type LocalCache, type Mutation, type MutationConcurrency, type MutationSpec, type Query, type QueryClientPlugin, type QueryClientPluginApi, type QuerySpec, type QuerySubscription, type ReadSignal, type RegisteredQuery, type RetryDelay, type RetryPolicy, type Root, type RootOptions, type Scope, type ScopeOptions, type Selection, type SetDataEvent, type Signal, type Snapshot, type StandardSchemaV1, type UseOptions, type Validator, batch, computed, createEmitter, createRoot, debounced, debouncedValidator, defineController, defineInfiniteQuery, defineQuery, defineScope, effect, email, isAbortError, isStandardSchema, lookupRegisteredQuery, max, maxLength, min, minLength, pattern, required, selection, signal, stableHash, throttled, untracked, validator };
+export { type AmbientDeps, type AsyncState, type AsyncStatus, type Collection, type CollectionFactoryApi, type CollectionFactoryOptions, type CollectionFactoryResult, type CollectionHomogeneousOptions, type Computed, type ControllerDef, type CtrlApi, type CtrlProps, type Ctx, type DebugBus, type DebugCacheEntry, type DebugEvent, type DeepPartial, type DehydratedEntry, type DehydratedState, type Emitter, type EmitterErrorReporter, type ErrorContext, type Field, type FieldArray, type FieldArrayItemErrors, type FieldArrayOptions, type FieldArrayValidator, type FieldArrayValue, type Form, type FormErrors, type FormOptions, type FormSchema, type FormValidator, type FormValue, type GcEvent, type InfiniteQuery, type InfiniteQuerySpec, type InfiniteQuerySubscription, type InvalidateEvent, type ItemInitial, type LazyChild, type LocalCache, type Mutation, type MutationConcurrency, type MutationDef, type MutationEnqueueEvent, type MutationSettleEvent, type MutationSpec, type Query, type QueryClientPlugin, type QueryClientPluginApi, type QuerySpec, type QuerySubscription, type ReadSignal, type RegisteredMutation, type RegisteredQuery, type RetryDelay, type RetryPolicy, type Root, type RootOptions, type Scope, type ScopeOptions, type Selection, type SetDataEvent, type Signal, type Snapshot, type StandardSchemaV1, type UseOptions, type Validator, _unregisterMutationById, batch, computed, createEmitter, createRoot, debounced, debouncedValidator, defineController, defineInfiniteQuery, defineMutation, defineQuery, defineScope, effect, email, isAbortError, isStandardSchema, lookupRegisteredMutation, lookupRegisteredQuery, max, maxLength, min, minLength, pattern, required, selection, signal, stableHash, throttled, untracked, validator };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as lookupRegisteredQuery, c as isAbortError, d as effect, f as signal, i as createEmitter, l as batch, m as defineController, o as registerQueryById, p as untracked, r as debouncedValidator, s as stableHash, t as createRoot, u as computed } from "./root-Cnkb3I--.mjs";
+import { _ as defineController, a as createEmitter, c as lookupRegisteredQuery, d as isAbortError, f as batch, g as untracked, h as signal, i as debouncedValidator, l as registerQueryById, m as effect, o as _unregisterMutationById, p as computed, r as defineMutation, s as lookupRegisteredMutation, t as createRoot, u as stableHash } from "./root-DqWolle_.mjs";
 //#region src/signals/readonly.ts
 /**
 * Project a Signal (or any object with a reactive `value` + `peek` + `subscribe`)
@@ -394,6 +394,6 @@ function throttled(source, ms, options) {
 	return out;
 }
 //#endregion
-export { batch, computed, createEmitter, createRoot, debounced, debouncedValidator, defineController, defineInfiniteQuery, defineQuery, defineScope, effect, email, isAbortError, isStandardSchema, lookupRegisteredQuery, max, maxLength, min, minLength, pattern, required, selection, signal, stableHash, throttled, untracked, validator };
+export { _unregisterMutationById, batch, computed, createEmitter, createRoot, debounced, debouncedValidator, defineController, defineInfiniteQuery, defineMutation, defineQuery, defineScope, effect, email, isAbortError, isStandardSchema, lookupRegisteredMutation, lookupRegisteredQuery, max, maxLength, min, minLength, pattern, required, selection, signal, stableHash, throttled, untracked, validator };
 
 //# sourceMappingURL=index.mjs.map

package/dist/{root-Cnkb3I--.mjs → root-DqWolle_.mjs}

@@ -978,6 +978,25 @@ function registerQueryById(queryId, query) {
 function lookupRegisteredQuery(queryId) {
 	return queryRegistry.get(queryId);
 }
+const mutationRegistry = /* @__PURE__ */ new Map();
+/** Register a mutation by its `mutationId`. Internal — called from `defineMutation`. */
+function registerMutationById(mutationId, entry) {
+	mutationRegistry.set(mutationId, entry);
+}
+/**
+* Look up a registered mutation by id. Returns `undefined` when no
+* mutation with that id has been defined — typical when a queue entry
+* references a mutation whose module hasn't been imported (e.g. a
+* code-split route boundary). The plugin should leave such entries in
+* place and retry once the module loads.
+*/
+function lookupRegisteredMutation(mutationId) {
+	return mutationRegistry.get(mutationId);
+}
+/** Test-only — drop a registered mutation. Not exported from the package. */
+function _unregisterMutationById(mutationId) {
+	mutationRegistry.delete(mutationId);
+}
 //#endregion
 //#region src/query/client.ts
 const DEFAULT_GC_TIME = 5 * 6e4;
@@ -1342,6 +1361,26 @@ var QueryClient = class {
 			this.callPlugin(() => cb.call(plugin, event));
 		}
 	}
+	/**
+	* Fan out a `MutationEnqueueEvent` to every installed plugin. Called from
+	* `MutationImpl.executeRun` when `spec.persist === true`. Plugins use this
+	* to write the run to durable storage; the queue replays on reload. SPEC §13.3.
+	*/
+	emitMutationEnqueue(event) {
+		if (this.plugins.length === 0) return;
+		for (const plugin of this.plugins) if (plugin.onMutationEnqueue) {
+			const cb = plugin.onMutationEnqueue;
+			this.callPlugin(() => cb.call(plugin, event));
+		}
+	}
+	/** Fan out a `MutationSettleEvent` to every installed plugin. SPEC §13.3. */
+	emitMutationSettle(event) {
+		if (this.plugins.length === 0) return;
+		for (const plugin of this.plugins) if (plugin.onMutationSettle) {
+			const cb = plugin.onMutationSettle;
+			this.callPlugin(() => cb.call(plugin, event));
+		}
+	}
 	/** Resolve `queryId → live entry-map keys`. Empty array when unknown. */
 	subscribedKeysFor(queryId) {
 		const query = lookupRegisteredQuery(queryId);
@@ -2761,6 +2800,7 @@ var LocalCacheImpl = class {
 	refetch = () => this.entry.refetch();
 	reset = () => this.entry.reset();
 	firstValue = () => this.entry.firstValue();
+	promise = () => this.entry.firstValue();
 	invalidate = () => {
 		this.entry.invalidate().catch(() => {});
 	};
@@ -2783,12 +2823,52 @@ function arraysEqual(a, b) {
 }
 //#endregion
 //#region src/query/mutation.ts
+/**
+* Register a persistable mutation at module scope. Returns the spec
+* unchanged (with a `__olas: 'mutation'` brand) so consumers can pass it
+* to `ctx.mutation(...)`, optionally spreading per-controller hooks on
+* top:
+*
+* ```ts
+* // module-scope
+* export const createOrder = defineMutation({
+*   mutationId: 'order/create',
+*   mutate: async (vars: OrderInput, { signal }) => api.createOrder(vars, { signal }),
+* })
+*
+* // controller
+* const m = ctx.mutation({
+*   ...createOrder,
+*   onSuccess: () => toast('Order placed'),
+* })
+* ```
+*
+* The `mutate` function MUST NOT close over controller-instance state — on
+* replay there is no controller. Module-level dependencies (a shared `api`
+* client, etc.) are fine.
+*/
+function defineMutation(spec) {
+	if (typeof spec.mutationId !== "string" || spec.mutationId.length === 0) throw new Error("[olas] defineMutation requires a non-empty `mutationId`.");
+	const persistSpec = {
+		...spec,
+		persist: spec.persist ?? true
+	};
+	registerMutationById(spec.mutationId, {
+		mutationId: spec.mutationId,
+		mutate: spec.mutate
+	});
+	return Object.assign(persistSpec, {
+		__olas: "mutation",
+		mutationId: spec.mutationId
+	});
+}
 var MutationImpl = class {
 	spec;
 	onError;
 	controllerPath;
 	inflightCounter;
 	devtools;
+	lifecycle;
 	data = signal$1(void 0);
 	error = signal$1(void 0);
 	isPending = signal$1(false);
@@ -2797,12 +2877,21 @@ var MutationImpl = class {
 	serialQueue = [];
 	serialActive = false;
 	disposed = false;
-	constructor(spec, onError, controllerPath, inflightCounter, devtools) {
+	constructor(spec, onError, controllerPath, inflightCounter, devtools, lifecycle) {
 		this.spec = spec;
 		this.onError = onError;
 		this.controllerPath = controllerPath;
 		this.inflightCounter = inflightCounter;
 		this.devtools = devtools;
+		this.lifecycle = lifecycle;
+	}
+	/**
+	* True iff this mutation should emit persistable-lifecycle events.
+	* Validated at construction time (in `createMutation`) so any malformed
+	* `persist: true`-without-`mutationId` config surfaces early.
+	*/
+	get isPersistable() {
+		return this.spec.persist === true && this.lifecycle !== void 0;
 	}
 	emit(event) {}
 	run = ((vars = void 0) => {
@@ -2866,10 +2955,30 @@ var MutationImpl = class {
 			this.isPending.set(true);
 			this.lastVariables.set(vars);
 		});
+		const runId = this.isPersistable ? makeRunId() : "";
+		const mutationId = this.spec.mutationId;
+		if (this.isPersistable && mutationId !== void 0) try {
+			this.lifecycle?.emitEnqueue({
+				mutationId,
+				runId,
+				variables: vars,
+				attempt: 0
+			});
+		} catch (err) {
+			dispatchError(this.onError, err, {
+				kind: "plugin",
+				controllerPath: this.controllerPath
+			});
+		}
 		try {
 			const result = await raceAbort(this.runWithRetry(vars, abort.signal), abort.signal);
 			if (abort.signal.aborted || this.disposed) {
 				snapshot?.rollback();
+				if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+					mutationId,
+					runId,
+					outcome: "cancelled"
+				});
 				throw new DOMException("Superseded", "AbortError");
 			}
 			batch$1(() => {
@@ -2879,16 +2988,32 @@ var MutationImpl = class {
 			this.safeCall(() => this.spec.onSuccess?.(result, vars), "mutation");
 			snapshot?.finalize();
 			this.safeCall(() => this.spec.onSettled?.(result, void 0, vars), "mutation");
+			if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+				mutationId,
+				runId,
+				outcome: "success"
+			});
 			return result;
 		} catch (err) {
 			if (isAbortError(err) || abort.signal.aborted) {
 				snapshot?.rollback();
+				if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+					mutationId,
+					runId,
+					outcome: "cancelled"
+				});
 				throw err;
 			}
 			this.error.set(err);
 			this.safeCall(() => this.spec.onError?.(err, vars, snapshot), "mutation");
 			snapshot?.rollback();
 			this.safeCall(() => this.spec.onSettled?.(void 0, err, vars), "mutation");
+			if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+				mutationId,
+				runId,
+				outcome: "error",
+				error: err
+			});
 			throw err;
 		} finally {
 			this.inflight.delete(handle);
@@ -2896,6 +3021,16 @@ var MutationImpl = class {
 			if (this.inflight.size === 0) this.isPending.set(false);
 		}
 	}
+	safeEmitSettle(event) {
+		try {
+			this.lifecycle?.emitSettle(event);
+		} catch (err) {
+			dispatchError(this.onError, err, {
+				kind: "plugin",
+				controllerPath: this.controllerPath
+			});
+		}
+	}
 	wrapSnapshot(raw) {
 		let consumed = false;
 		return {
@@ -2959,8 +3094,24 @@ var MutationImpl = class {
 		this.serialQueue.length = 0;
 	}
 };
-function createMutation(spec, onError, controllerPath, inflightCounter, devtools) {
-	return new MutationImpl(spec, onError, controllerPath, inflightCounter, devtools);
+function createMutation(spec, onError, controllerPath, inflightCounter, devtools, lifecycle) {
+	if (spec.persist === true) {
+		if (typeof spec.mutationId !== "string" || spec.mutationId.length === 0) throw new Error("[olas] ctx.mutation({ persist: true, ... }) requires a non-empty `mutationId`.");
+	}
+	return new MutationImpl(spec, onError, controllerPath, inflightCounter, devtools, lifecycle);
+}
+/**
+* Generate a unique-enough run id for the persistable-mutation lifecycle.
+* Uses `crypto.randomUUID` where available (Node 19+, modern browsers),
+* with a timestamp+random fallback for older runtimes. Collisions only
+* affect dedup at the plugin layer, not correctness, so the fallback's
+* weakness is acceptable.
+*/
+function makeRunId() {
+	const g = globalThis;
+	if (typeof g.crypto?.randomUUID === "function") return g.crypto.randomUUID();
+	const rand = Math.random().toString(36).slice(2, 12);
+	return `${Date.now().toString(36)}-${rand}`;
 }
 /**
 * Race a promise against an AbortSignal. If the signal fires before the
@@ -3056,6 +3207,7 @@ var SubscriptionImpl = class {
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
 		return cur.entry.firstValue().then((v) => this.project(v));
 	};
+	promise = () => this.firstValue();
 	project(v) {
 		return this.select === void 0 ? v : this.select(v);
 	}
@@ -3215,6 +3367,7 @@ var InfiniteSubscriptionImpl = class {
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
 		return cur.entry.firstValue();
 	};
+	promise = () => this.firstValue();
 	fetchNextPage = () => {
 		const cur = this.current$.peek();
 		if (!cur) return Promise.resolve();
@@ -3494,7 +3647,11 @@ var ControllerInstance = class ControllerInstance {
 				return handle.subscription;
 			},
 			mutation(spec) {
-				const m = createMutation(spec, self.rootShared.onError, self.path, self.rootShared.queryClient.mutationsInflight$, self.rootShared.devtools);
+				const queryClient = self.rootShared.queryClient;
+				const m = createMutation(spec, self.rootShared.onError, self.path, queryClient.mutationsInflight$, self.rootShared.devtools, spec.persist === true ? {
+					emitEnqueue: (ev) => queryClient.emitMutationEnqueue(ev),
+					emitSettle: (ev) => queryClient.emitMutationSettle(ev)
+				} : void 0);
 				self.entries.push({
 					kind: "cleanup",
 					dispose: () => m.dispose()
@@ -4096,6 +4253,6 @@ function createRoot(def, options) {
 	return createRootWithProps(def, void 0, options);
 }
 //#endregion
-export { lookupRegisteredQuery as a, isAbortError as c, effect$1 as d, signal$1 as f, createEmitter as i, batch$1 as l, defineController as m, createRootWithProps as n, registerQueryById as o, untracked$1 as p, debouncedValidator as r, stableHash as s, createRoot as t, computed$1 as u };
+export { defineController as _, createEmitter as a, lookupRegisteredQuery as c, isAbortError as d, batch$1 as f, untracked$1 as g, signal$1 as h, debouncedValidator as i, registerQueryById as l, effect$1 as m, createRootWithProps as n, _unregisterMutationById as o, computed$1 as p, defineMutation as r, lookupRegisteredMutation as s, createRoot as t, stableHash as u };
 
-//# sourceMappingURL=root-Cnkb3I--.mjs.map
+//# sourceMappingURL=root-DqWolle_.mjs.map