@kontsedal/olas-core 0.0.3 → 0.0.5

package/dist/{types-r_TVaRkD.d.cts → types-C4Vtkxbn.d.cts}

@@ -251,6 +251,13 @@ type AsyncState<T> = {
   refetch: () => Promise<T>;
   reset: () => void;
   firstValue: () => Promise<T>;
+  /**
+   * Alias of `firstValue()` — clearer name for Suspense / `React.use(...)`
+   * use cases. Resolves with `data` on first success (short-circuits if
+   * already settled), rejects with `error` on the first failure. Use this
+   * to suspend a React tree until the query lands its first value.
+   */
+  promise: () => Promise<T>;
 };
 /**
  * Returned by `query.setData(...)` or `localCache.setData(...)`. Used by
@@ -580,7 +587,67 @@ type MutationSpec<V, R> = {
   concurrency?: MutationConcurrency;
   retry?: RetryPolicy;
   retryDelay?: RetryDelay;
+  /**
+   * Stable identifier used by the mutation-queue plugin
+   * (`@kontsedal/olas-mutation-queue`) to route persistable runs across a
+   * page reload. REQUIRED when `persist: true`. Recommended even without
+   * `persist` if you want devtools to group runs across mutation instances
+   * — same shape as `defineQuery({ queryId })`.
+   *
+   * Don't auto-derive from `name` or function identity; both are fragile
+   * under minification.
+   */
+  mutationId?: string;
+  /**
+   * Opt this mutation into durable persistence. When `true`, the runner
+   * emits `onMutationEnqueue` to plugins before the user's `mutate` runs
+   * and `onMutationSettle` after retries exhaust. Requires `mutationId`.
+   * SPEC §13.3.
+   */
+  persist?: boolean;
+};
+/**
+ * Module-scope handle for a persistable mutation. Returned by
+ * `defineMutation(...)`. Pass it to `ctx.mutation(...)` (spread or as-is)
+ * so per-controller lifecycle hooks (`onSuccess` / `onError` / ...) can be
+ * layered on top.
+ *
+ * Registering at module import time means the mutation-queue plugin can
+ * replay pending runs from durable storage during `init` — before any
+ * controller reconstructs.
+ */
+type MutationDef<V, R> = MutationSpec<V, R> & {
+  readonly __olas: 'mutation';
+  readonly mutationId: string;
 };
+/**
+ * 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.
+ */
+declare function defineMutation<V, R>(spec: MutationSpec<V, R> & {
+  mutationId: string;
+  persist?: boolean;
+}): MutationDef<V, R>;
 /**
  * A running mutation. Created via `ctx.mutation(spec)` — the controller owns
  * its lifetime. Each `run(vars)` returns a Promise; the four signals reflect
@@ -722,6 +789,33 @@ type GcEvent = {
   keyArgs: readonly unknown[];
   kind: 'data' | 'infinite';
 };
+/**
+ * Emitted when a persistable mutation (`spec.persist === true`) starts
+ * executing — before the user's `mutate` is invoked. Plugins use this to
+ * persist the variables to durable storage; if the page reloads mid-run,
+ * the queue replays from these entries.
+ *
+ * `runId` is unique per execution (a single `mutation.run(...)` call OR a
+ * replay attempt). `attempt` counts retry passes within a single runId.
+ */
+type MutationEnqueueEvent = {
+  mutationId: string;
+  runId: string;
+  variables: unknown;
+  attempt: number;
+};
+/**
+ * Emitted after a persistable mutation settles. Plugins use this to drop
+ * the run from the durable queue (on `'success'` or `'error'` after retries
+ * exhaust), or to leave it pending (on `'cancelled'` — e.g. parent dispose
+ * mid-flight).
+ */
+type MutationSettleEvent = {
+  mutationId: string;
+  runId: string;
+  outcome: 'success' | 'error' | 'cancelled'; /** Only present on `'error'` — the final thrown value after retries. */
+  error?: unknown;
+};
 /**
  * Plugin contract. Every hook is optional. Hooks are wrapped in try/catch
  * by `QueryClient`; thrown exceptions are routed through the root's
@@ -730,12 +824,23 @@ type GcEvent = {
 type QueryClientPlugin = {
   /**
    * Called once after the `QueryClient` is constructed. Use it to wire up
-   * transport listeners and capture the `QueryClientPluginApi`.
+   * transport listeners and capture the `QueryClientPluginApi`. SPEC §13.2.
+   *
+   * Persistable-mutation replay typically happens HERE — module-scope
+   * `defineMutation(...)` calls have already registered their handlers by
+   * the time `createRoot(...)` runs, so `init` can walk durable storage
+   * and re-invoke registered mutates for any pending entries.
    */
   init?(api: QueryClientPluginApi): void;
   onSetData?(event: SetDataEvent): void;
   onInvalidate?(event: InvalidateEvent): void;
-  onGc?(event: GcEvent): void; /** Called from `QueryClient.dispose`. Tear down transports / listeners here. */
+  onGc?(event: GcEvent): void;
+  /**
+   * Fired when a persistable mutation (`spec.persist === true`) starts
+   * executing. SPEC §13.3.
+   */
+  onMutationEnqueue?(event: MutationEnqueueEvent): void; /** Fired after a persistable mutation settles. SPEC §13.3. */
+  onMutationSettle?(event: MutationSettleEvent): void; /** Called from `QueryClient.dispose`. Tear down transports / listeners here. */
   dispose?(): void;
 };
 /**
@@ -755,6 +860,33 @@ type RegisteredQuery = {
  * in the receiving tab).
  */
 declare function lookupRegisteredQuery(queryId: string): RegisteredQuery | undefined;
+/**
+ * Shape stored in the `mutationId → handler` registry. Only the `mutate`
+ * function and the id are needed for replay — lifecycle hooks like
+ * `onSuccess` / `onError` are per-controller and can't be safely replayed
+ * across page reloads (the controller doesn't exist yet).
+ */
+type RegisteredMutation = {
+  readonly mutationId: string;
+  /**
+   * Replay-safe `mutate`. Matches `MutationSpec.mutate` 1:1 — receives the
+   * variables and an `AbortSignal`. The mutation-queue plugin invokes this
+   * directly on replay, so the implementation MUST NOT close over
+   * controller-instance state. Module-level deps (a shared `api` client,
+   * etc.) are fine.
+   */
+  readonly mutate: (vars: unknown, signal: AbortSignal) => Promise<unknown>;
+};
+/**
+ * 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.
+ */
+declare function lookupRegisteredMutation(mutationId: string): RegisteredMutation | undefined;
+/** Test-only — drop a registered mutation. Not exported from the package. */
+declare function _unregisterMutationById(mutationId: string): void;
 //#endregion
 //#region src/scope.d.ts
 /**
@@ -941,13 +1073,13 @@ type Ctx<TDeps = AmbientDeps> = {
     keepPreviousData?: boolean;
     initialData?: T | undefined;
   }): LocalCache<T>;
-  use<Args extends unknown[], T>(source: Query<Args, T>, keyOrOptions?: (() => Args) | UseOptions<Args>): QuerySubscription<T>;
-  use<Args extends unknown[], TPage, TItem>(source: InfiniteQuery<Args, TPage, TItem>, keyOrOptions?: (() => Args) | UseOptions<Args>): InfiniteQuerySubscription<TPage, TItem>;
   use<Args extends unknown[], T, U>(source: Query<Args, T>, options: {
-    key?: () => Args;
+    key?: () => readonly [...Args];
     enabled?: () => boolean;
     select: (data: T) => U;
   }): QuerySubscription<U>;
+  use<Args extends unknown[], T>(source: Query<Args, T>, keyOrOptions?: (() => readonly [...Args]) | UseOptions<Args>): QuerySubscription<T>;
+  use<Args extends unknown[], TPage, TItem>(source: InfiniteQuery<Args, TPage, TItem>, keyOrOptions?: (() => readonly [...Args]) | UseOptions<Args>): InfiniteQuerySubscription<TPage, TItem>;
   mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R>;
   emitter<T = void>(): Emitter<T>;
   field<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T>;
@@ -1072,5 +1204,5 @@ type Root<Api> = Api & {
   readonly __debug: DebugBus;
 };
 //#endregion
-export { FormErrors as $, DebugEvent as A, QuerySpec as B, SetDataEvent as C, MutationSpec as D, MutationConcurrency as E, AsyncStatus as F, UseOptions as G, RetryDelay as H, DehydratedEntry as I, FieldArrayItemErrors as J, DeepPartial as K, DehydratedState as L, InfiniteQuerySpec as M, InfiniteQuerySubscription as N, DebugBus as O, AsyncState as P, Form as Q, LocalCache as R, RegisteredQuery as S, Mutation as T, RetryPolicy as U, QuerySubscription as V, Snapshot as W, FieldArrayValidator as X, FieldArrayOptions as Y, FieldArrayValue as Z, defineScope as _, CollectionFactoryResult as a, Validator as at, QueryClientPlugin as b, CtrlApi as c, Signal as ct, Field as d, EmitterErrorReporter as dt, FormOptions as et, LazyChild as f, createEmitter as ft, ScopeOptions as g, Scope as h, CollectionFactoryOptions as i, ItemInitial as it, InfiniteQuery as j, DebugCacheEntry as k, CtrlProps as l, ErrorContext as lt, RootOptions as m, Collection as n, FormValidator as nt, CollectionHomogeneousOptions as o, Computed as ot, Root as p, FieldArray as q, CollectionFactoryApi as r, FormValue as rt, ControllerDef as s, ReadSignal as st, AmbientDeps as t, FormSchema as tt, Ctx as u, Emitter as ut, GcEvent as v, lookupRegisteredQuery as w, QueryClientPluginApi as x, InvalidateEvent as y, Query as z };
-//# sourceMappingURL=types-r_TVaRkD.d.cts.map
+export { DeepPartial as $, Mutation as A, InfiniteQuerySubscription as B, QueryClientPluginApi as C, _unregisterMutationById as D, SetDataEvent as E, DebugBus as F, LocalCache as G, AsyncStatus as H, DebugCacheEntry as I, QuerySubscription as J, Query as K, DebugEvent as L, MutationDef as M, MutationSpec as N, lookupRegisteredMutation as O, defineMutation as P, UseOptions as Q, InfiniteQuery as R, QueryClientPlugin as S, RegisteredQuery as T, DehydratedEntry as U, AsyncState as V, DehydratedState as W, RetryPolicy as X, RetryDelay as Y, Snapshot as Z, defineScope as _, Emitter as _t, CollectionFactoryResult as a, Form as at, MutationEnqueueEvent as b, CtrlApi as c, FormSchema as ct, Field as d, ItemInitial as dt, FieldArray as et, LazyChild as f, Validator as ft, ScopeOptions as g, ErrorContext as gt, Scope as h, Signal as ht, CollectionFactoryOptions as i, FieldArrayValue as it, MutationConcurrency as j, lookupRegisteredQuery as k, CtrlProps as l, FormValidator as lt, RootOptions as m, ReadSignal as mt, Collection as n, FieldArrayOptions as nt, CollectionHomogeneousOptions as o, FormErrors as ot, Root as p, Computed as pt, QuerySpec as q, CollectionFactoryApi as r, FieldArrayValidator as rt, ControllerDef as s, FormOptions as st, AmbientDeps as t, FieldArrayItemErrors as tt, Ctx as u, FormValue as ut, GcEvent as v, EmitterErrorReporter as vt, RegisteredMutation as w, MutationSettleEvent as x, InvalidateEvent as y, createEmitter as yt, InfiniteQuerySpec as z };
+//# sourceMappingURL=types-C4Vtkxbn.d.cts.map

package/dist/types-C4Vtkxbn.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-C4Vtkxbn.d.cts","names":[],"sources":["../src/emitter.ts","../src/errors.ts","../src/signals/types.ts","../src/forms/types.ts","../src/forms/form-types.ts","../src/query/types.ts","../src/query/infinite.ts","../src/devtools.ts","../src/query/mutation.ts","../src/query/plugin.ts","../src/scope.ts","../src/controller/types.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontsedal/olas-core",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Olas core — controller-tree state management with signals, queries, mutations, and forms. Framework-agnostic.",
   "keywords": [
     "olas",

package/src/controller/instance.ts

@@ -340,12 +340,22 @@ export class ControllerInstance {
       },
 
       mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R> {
+        const queryClient = self.rootShared.queryClient
         const m = createMutation<V, R>(
           spec,
           self.rootShared.onError,
           self.path,
-          self.rootShared.queryClient.mutationsInflight$,
+          queryClient.mutationsInflight$,
           self.rootShared.devtools,
+          // Lifecycle hooks for persistable mutations — only wired when
+          // `spec.persist === true`. `createMutation` validates the
+          // `mutationId` requirement before construction.
+          spec.persist === true
+            ? {
+                emitEnqueue: (ev) => queryClient.emitMutationEnqueue(ev),
+                emitSettle: (ev) => queryClient.emitMutationSettle(ev),
+              }
+            : undefined,
         )
         self.entries.push({ kind: 'cleanup', dispose: () => m.dispose() })
         return m

package/src/controller/types.ts

@@ -185,21 +185,25 @@ export type Ctx<TDeps = AmbientDeps> = {
     },
   ): LocalCache<T>
 
+  // Select-projecting overload — picked when the options object has a
+  // required `select` field. `key`'s return is `readonly [...Args]` so
+  // callers writing `() => [id] as const` flow through cleanly.
+  use<Args extends unknown[], T, U>(
+    source: Query<Args, T>,
+    options: {
+      key?: () => readonly [...Args]
+      enabled?: () => boolean
+      select: (data: T) => U
+    },
+  ): QuerySubscription<U>
   use<Args extends unknown[], T>(
     source: Query<Args, T>,
-    keyOrOptions?: (() => Args) | UseOptions<Args>,
+    keyOrOptions?: (() => readonly [...Args]) | UseOptions<Args>,
   ): QuerySubscription<T>
   use<Args extends unknown[], TPage, TItem>(
     source: InfiniteQuery<Args, TPage, TItem>,
-    keyOrOptions?: (() => Args) | UseOptions<Args>,
+    keyOrOptions?: (() => readonly [...Args]) | UseOptions<Args>,
   ): InfiniteQuerySubscription<TPage, TItem>
-  // Overload — `select` projects T → U; the returned subscription's `data`
-  // is `U | undefined`. The required `select` field is the discriminator
-  // that picks this overload over the plain-key one above.
-  use<Args extends unknown[], T, U>(
-    source: Query<Args, T>,
-    options: { key?: () => Args; enabled?: () => boolean; select: (data: T) => U },
-  ): QuerySubscription<U>
 
   mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R>
 

package/src/index.ts

@@ -68,18 +68,27 @@ export { stableHash } from './query/keys'
 export type {
   Mutation,
   MutationConcurrency,
+  MutationDef,
   MutationSpec,
 } from './query/mutation'
-// Query-client plugins (§13.2)
+export { defineMutation } from './query/mutation'
+// Query-client plugins (§13.2 / §13.3)
 export type {
   GcEvent,
   InvalidateEvent,
+  MutationEnqueueEvent,
+  MutationSettleEvent,
   QueryClientPlugin,
   QueryClientPluginApi,
+  RegisteredMutation,
   RegisteredQuery,
   SetDataEvent,
 } from './query/plugin'
-export { lookupRegisteredQuery } from './query/plugin'
+export {
+  _unregisterMutationById,
+  lookupRegisteredMutation,
+  lookupRegisteredQuery,
+} from './query/plugin'
 // Query primitives
 export type {
   AsyncState,

package/src/query/client.ts

@@ -520,6 +520,42 @@ export class QueryClient {
     }
   }
 
+  /**
+   * 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: {
+    mutationId: string
+    runId: string
+    variables: unknown
+    attempt: number
+  }): void {
+    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: {
+    mutationId: string
+    runId: string
+    outcome: 'success' | 'error' | 'cancelled'
+    error?: unknown
+  }): void {
+    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. */
   private subscribedKeysFor(queryId: string): readonly (readonly unknown[])[] {
     // Defer the registry lookup to avoid an eager circular import — `define.ts`

package/src/query/local.ts

@@ -83,6 +83,7 @@ class LocalCacheImpl<T> implements LocalCache<T> {
   refetch = (): Promise<T> => this.entry.refetch()
   reset = (): void => this.entry.reset()
   firstValue = (): Promise<T> => this.entry.firstValue()
+  promise = (): Promise<T> => this.entry.firstValue()
   invalidate = (): void => {
     this.entry.invalidate().catch(() => {})
   }

package/src/query/mutation.ts

@@ -3,6 +3,7 @@ import { dispatchError, type ErrorHandler } from '../errors'
 import { batch, type Signal, signal } from '../signals'
 import type { ReadSignal } from '../signals/types'
 import { abortableSleep, isAbortError } from '../utils'
+import { registerMutationById } from './plugin'
 import type { RetryDelay, RetryPolicy, Snapshot } from './types'
 
 /**
@@ -40,6 +41,83 @@ export type MutationSpec<V, R> = {
   concurrency?: MutationConcurrency
   retry?: RetryPolicy
   retryDelay?: RetryDelay
+  /**
+   * Stable identifier used by the mutation-queue plugin
+   * (`@kontsedal/olas-mutation-queue`) to route persistable runs across a
+   * page reload. REQUIRED when `persist: true`. Recommended even without
+   * `persist` if you want devtools to group runs across mutation instances
+   * — same shape as `defineQuery({ queryId })`.
+   *
+   * Don't auto-derive from `name` or function identity; both are fragile
+   * under minification.
+   */
+  mutationId?: string
+  /**
+   * Opt this mutation into durable persistence. When `true`, the runner
+   * emits `onMutationEnqueue` to plugins before the user's `mutate` runs
+   * and `onMutationSettle` after retries exhaust. Requires `mutationId`.
+   * SPEC §13.3.
+   */
+  persist?: boolean
+}
+
+/**
+ * Module-scope handle for a persistable mutation. Returned by
+ * `defineMutation(...)`. Pass it to `ctx.mutation(...)` (spread or as-is)
+ * so per-controller lifecycle hooks (`onSuccess` / `onError` / ...) can be
+ * layered on top.
+ *
+ * Registering at module import time means the mutation-queue plugin can
+ * replay pending runs from durable storage during `init` — before any
+ * controller reconstructs.
+ */
+export type MutationDef<V, R> = MutationSpec<V, R> & {
+  readonly __olas: 'mutation'
+  readonly mutationId: string
+}
+
+/**
+ * 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.
+ */
+export function defineMutation<V, R>(
+  spec: MutationSpec<V, R> & { mutationId: string; persist?: boolean },
+): MutationDef<V, R> {
+  if (typeof spec.mutationId !== 'string' || spec.mutationId.length === 0) {
+    throw new Error('[olas] defineMutation requires a non-empty `mutationId`.')
+  }
+  // Default `persist: true` for defined mutations — that's the whole point
+  // of using the module-scope helper. Consumers who want a non-persistable
+  // module-scope handle can override with `persist: false`.
+  const persistSpec: MutationSpec<V, R> = { ...spec, persist: spec.persist ?? true }
+  registerMutationById(spec.mutationId, {
+    mutationId: spec.mutationId,
+    mutate: spec.mutate as (vars: unknown, signal: AbortSignal) => Promise<unknown>,
+  })
+  return Object.assign(persistSpec, {
+    __olas: 'mutation' as const,
+    mutationId: spec.mutationId,
+  })
 }
 
 /**
@@ -88,6 +166,26 @@ type SerialEntry<V, R> = {
   reject: (err: unknown) => void
 }
 
+/**
+ * Hooks for emitting persistable-mutation lifecycle events back to the
+ * `QueryClient`. Wired from `createMutation` when `spec.persist === true`.
+ * Internal — not part of any public surface.
+ */
+export type MutationLifecycleHooks = {
+  emitEnqueue(event: {
+    mutationId: string
+    runId: string
+    variables: unknown
+    attempt: number
+  }): void
+  emitSettle(event: {
+    mutationId: string
+    runId: string
+    outcome: 'success' | 'error' | 'cancelled'
+    error?: unknown
+  }): void
+}
+
 class MutationImpl<V, R> implements Mutation<V, R> {
   readonly data: Signal<R | undefined> = signal(undefined)
   readonly error: Signal<unknown | undefined> = signal(undefined)
@@ -107,8 +205,18 @@ class MutationImpl<V, R> implements Mutation<V, R> {
       update(fn: (n: number) => number): void
     },
     private readonly devtools?: DevtoolsEmitter,
+    private readonly lifecycle?: MutationLifecycleHooks,
   ) {}
 
+  /**
+   * 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.
+   */
+  private get isPersistable(): boolean {
+    return this.spec.persist === true && this.lifecycle !== undefined
+  }
+
   private emit(event: { type: 'mutation:run'; vars: unknown }): void
   private emit(event: { type: 'mutation:success'; result: unknown }): void
   private emit(event: { type: 'mutation:error'; error: unknown }): void
@@ -204,10 +312,30 @@ class MutationImpl<V, R> implements Mutation<V, R> {
 
     if (__DEV__) this.emit({ type: 'mutation:run', vars })
 
+    // Persistable mutations emit an enqueue event BEFORE the user's `mutate`
+    // runs. If the page reloads mid-mutation, the queue plugin replays from
+    // this entry. `runId` is unique per `executeRun` invocation; retries
+    // within `runWithRetry` reuse it via `attempt` bumps inside that loop.
+    const runId = this.isPersistable ? makeRunId() : ''
+    const mutationId = this.spec.mutationId
+    if (this.isPersistable && mutationId !== undefined) {
+      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 !== undefined) {
+          this.safeEmitSettle({ mutationId, runId, outcome: 'cancelled' })
+        }
         throw new DOMException('Superseded', 'AbortError')
       }
       batch(() => {
@@ -221,10 +349,16 @@ class MutationImpl<V, R> implements Mutation<V, R> {
       // Spec §6.4.
       snapshot?.finalize()
       this.safeCall(() => this.spec.onSettled?.(result, undefined, vars), 'mutation')
+      if (this.isPersistable && mutationId !== undefined) {
+        this.safeEmitSettle({ mutationId, runId, outcome: 'success' })
+      }
       return result
     } catch (err) {
       if (isAbortError(err) || abort.signal.aborted) {
         snapshot?.rollback()
+        if (this.isPersistable && mutationId !== undefined) {
+          this.safeEmitSettle({ mutationId, runId, outcome: 'cancelled' })
+        }
         // Reserve `error` signal for genuine failures.
         throw err
       }
@@ -236,6 +370,9 @@ class MutationImpl<V, R> implements Mutation<V, R> {
       // turns the auto-call into a no-op. Spec §6.4.
       snapshot?.rollback()
       this.safeCall(() => this.spec.onSettled?.(undefined, err, vars), 'mutation')
+      if (this.isPersistable && mutationId !== undefined) {
+        this.safeEmitSettle({ mutationId, runId, outcome: 'error', error: err })
+      }
       throw err
     } finally {
       this.inflight.delete(handle)
@@ -246,6 +383,22 @@ class MutationImpl<V, R> implements Mutation<V, R> {
     }
   }
 
+  private safeEmitSettle(event: {
+    mutationId: string
+    runId: string
+    outcome: 'success' | 'error' | 'cancelled'
+    error?: unknown
+  }): void {
+    try {
+      this.lifecycle?.emitSettle(event)
+    } catch (err) {
+      dispatchError(this.onError, err, {
+        kind: 'plugin',
+        controllerPath: this.controllerPath,
+      })
+    }
+  }
+
   // Wrap so any rollback / finalize path runs the raw operation at most
   // once. The mutation auto-finalizes on success and auto-rolls-back on
   // error; user code may also call rollback() from onError. Whichever
@@ -334,8 +487,32 @@ export function createMutation<V, R>(
   controllerPath: readonly string[],
   inflightCounter?: { update(fn: (n: number) => number): void },
   devtools?: DevtoolsEmitter,
+  lifecycle?: MutationLifecycleHooks,
 ): Mutation<V, R> {
-  return new MutationImpl<V, R>(spec, onError, controllerPath, inflightCounter, devtools)
+  // Validate persistable-mutation config at construction time so misconfig
+  // surfaces synchronously rather than on first `run()`.
+  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<V, R>(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(): string {
+  const g = globalThis as { crypto?: { randomUUID?: () => string } }
+  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}`
 }
 
 /**