@kontsedal/olas-core 0.0.6 → 0.1.0

package/src/query/mutation.ts

@@ -4,7 +4,7 @@ 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'
+import type { AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
 
 /**
  * How concurrent calls to `mutation.run(...)` interact:
@@ -148,8 +148,17 @@ export type Mutation<V, R> = {
   data: ReadSignal<R | undefined>
   error: ReadSignal<unknown | undefined>
   isPending: ReadSignal<boolean>
+  /**
+   * Outcome of the latest run: `'idle'` (never run / reset), `'pending'`
+   * (in flight), `'success'`, `'error'`. Distinct from `isPending` (which
+   * stays true while ANY run is in flight, for parallel mode) and from `data`
+   * — a `void` mutation still reports `status: 'success'` after it resolves.
+   * A superseded `latest-wins` run does NOT flip status to `'error'`; the
+   * superseder owns the final status.
+   */
+  status: ReadSignal<AsyncStatus>
   lastVariables: ReadSignal<V | undefined>
-  /** Clear `data` / `error` / `lastVariables` without aborting in-flight runs. */
+  /** Clear `data` / `error` / `lastVariables` / `status` without aborting in-flight runs. */
   reset(): void
   /** Abort in-flight runs and tear down. Idempotent. Called by the parent controller's dispose. */
   dispose(): void
@@ -190,6 +199,7 @@ class MutationImpl<V, R> implements Mutation<V, R> {
   readonly data: Signal<R | undefined> = signal(undefined)
   readonly error: Signal<unknown | undefined> = signal(undefined)
   readonly isPending: Signal<boolean> = signal(false)
+  readonly status: Signal<AsyncStatus> = signal<AsyncStatus>('idle')
   readonly lastVariables: Signal<V | undefined> = signal(undefined)
 
   private inflight = new Set<RunHandle>()
@@ -296,10 +306,17 @@ class MutationImpl<V, R> implements Mutation<V, R> {
       const raw = this.spec.onMutate?.(vars) ?? undefined
       snapshot = raw === undefined ? undefined : this.wrapSnapshot(raw)
     } catch (err) {
-      dispatchError(this.onError, err, {
-        kind: 'mutation',
-        controllerPath: this.controllerPath,
-      })
+      // onMutate threw — the optimistic setup failed, so running `mutate`
+      // against a half-applied state is unsafe. Abort the whole run: surface
+      // via the error signal, the mutation's onError/onSettled, and the
+      // rejected run promise (mirrors the mutate-failure path). No snapshot
+      // exists yet, so nothing to roll back; `mutate` is never called. T3.9.
+      this.error.set(err)
+      this.status.set('error')
+      if (__DEV__) this.emit({ type: 'mutation:error', error: err })
+      this.safeCall(() => this.spec.onError?.(err, vars, undefined), 'mutation')
+      this.safeCall(() => this.spec.onSettled?.(undefined, err, vars), 'mutation')
+      throw err
     }
 
     const handle: RunHandle = { abort, snapshot }
@@ -307,6 +324,7 @@ class MutationImpl<V, R> implements Mutation<V, R> {
     this.inflightCounter?.update((n) => n + 1)
     batch(() => {
       this.isPending.set(true)
+      this.status.set('pending')
       this.lastVariables.set(vars)
     })
 
@@ -341,6 +359,7 @@ class MutationImpl<V, R> implements Mutation<V, R> {
       batch(() => {
         this.data.set(result)
         this.error.set(undefined)
+        this.status.set('success')
       })
       if (__DEV__) this.emit({ type: 'mutation:success', result })
       this.safeCall(() => this.spec.onSuccess?.(result, vars), 'mutation')
@@ -363,6 +382,7 @@ class MutationImpl<V, R> implements Mutation<V, R> {
         throw err
       }
       this.error.set(err)
+      this.status.set('error')
       if (__DEV__) this.emit({ type: 'mutation:error', error: err })
       this.safeCall(() => this.spec.onError?.(err, vars, snapshot), 'mutation')
       // Auto-rollback after the user's onError. The wrapped snapshot is
@@ -467,6 +487,7 @@ class MutationImpl<V, R> implements Mutation<V, R> {
       this.error.set(undefined)
       this.lastVariables.set(undefined)
       this.isPending.set(false)
+      this.status.set('idle')
     })
   }
 

package/src/query/plugin.ts

@@ -93,7 +93,9 @@ export type SetDataEvent = {
   isRemote: boolean
   /**
    * Origin of the write. `'set'` covers explicit `client.setData` (mutations,
-   * optimistic updates, plugin-initiated patches). `'fetch'` fires when the
+   * optimistic updates AND their `snapshot.rollback()`, plugin-initiated
+   * patches) — a rollback re-broadcasts the restored value so peers drop the
+   * failed optimistic state (T3.6). `'fetch'` fires when the
    * query fetcher resolved successfully and wrote the result into the entry
    * — emitted after the data signal is settled. `'remote'` is the
    * `applyRemoteSetData` path (cross-tab / server-push); equivalent to
@@ -154,6 +156,13 @@ export type MutationSettleEvent = {
  * `onError` handler with `kind: 'plugin'`.
  */
 export type QueryClientPlugin = {
+  /**
+   * Optional human-readable identifier surfaced in `ErrorContext.pluginName`
+   * when this plugin's callback throws. Without it, `pluginName` is left
+   * `undefined`. Recommended for shipped plugins so Sentry/OTel adapters
+   * can attribute errors back to the right package.
+   */
+  readonly name?: string
   /**
    * Called once after the `QueryClient` is constructed. Use it to wire up
    * transport listeners and capture the `QueryClientPluginApi`. SPEC §13.2.
@@ -197,15 +206,45 @@ export type RegisteredQuery = {
   readonly __spec: { queryId?: string; crossTab?: boolean }
 }
 
-const queryRegistry = new Map<string, RegisteredQuery>()
+/**
+ * Back a module-level registry on `globalThis` under a shared `Symbol.for`
+ * key. Guards the dual-package hazard: if a consumer ends up with both the ESM
+ * and CJS build of `@kontsedal/olas-core` (common with mixed bundler configs),
+ * each copy would otherwise own a SEPARATE registry `Map` — a mutation
+ * registered via the ESM copy would be invisible to the mutation-queue plugin
+ * loaded against the CJS copy, and cross-tab query lookups would miss. Sharing
+ * one Map on `globalThis` makes both copies agree. T3.9.
+ */
+function globalRegistry<V>(key: symbol): Map<string, V> {
+  const store = globalThis as unknown as Record<symbol, Map<string, V> | undefined>
+  const existing = store[key]
+  if (existing) return existing
+  const created = new Map<string, V>()
+  store[key] = created
+  return created
+}
+
+const queryRegistry = globalRegistry<RegisteredQuery>(Symbol.for('olas.queryRegistry'))
 
 /**
  * Register a query by its `queryId`. Internal — called from `defineQuery` /
  * `defineInfiniteQuery`. Replaces any previous registration with the same
  * id (matches Olas's "full root rebuild" HMR story; a mid-flight remote
- * message routed against the old `Query` simply misses).
+ * message routed against the old `Query` simply misses). Dev-warns when a
+ * *different* query overwrites an existing id — a genuine collision, since
+ * cross-tab / persistence route by `queryId` (expected during HMR).
  */
 export function registerQueryById(queryId: string, query: RegisteredQuery): void {
+  if (__DEV__) {
+    const existing = queryRegistry.get(queryId)
+    if (existing !== undefined && existing !== query) {
+      console.warn(
+        `[olas] duplicate queryId "${queryId}": a different query is replacing an existing ` +
+          'registration. `queryId` must be unique per query (cross-tab / persistence route by it). ' +
+          'Expected during HMR; a collision bug otherwise.',
+      )
+    }
+  }
   queryRegistry.set(queryId, query)
 }
 
@@ -251,7 +290,7 @@ export type RegisteredMutation = {
   readonly mutate: (vars: unknown, signal: AbortSignal) => Promise<unknown>
 }
 
-const mutationRegistry = new Map<string, RegisteredMutation>()
+const mutationRegistry = globalRegistry<RegisteredMutation>(Symbol.for('olas.mutationRegistry'))
 
 /** Register a mutation by its `mutationId`. Internal — called from `defineMutation`. */
 export function registerMutationById(mutationId: string, entry: RegisteredMutation): void {

package/src/query/types.ts

@@ -4,7 +4,7 @@ import type { ReadSignal } from '../signals/types'
 export type AsyncStatus = 'idle' | 'pending' | 'success' | 'error'
 
 /**
- * The eight reactive signals + three actions a subscriber sees for any async
+ * The nine reactive signals + three actions a subscriber sees for any async
  * resource (`LocalCache<T>` or a `Query` subscription). Spec §20.4.
  *
  * - `data` / `error` / `status` — current outcome.
@@ -13,6 +13,7 @@ export type AsyncStatus = 'idle' | 'pending' | 'success' | 'error'
  * - `isStale` — true when `staleTime` has elapsed since `lastUpdatedAt`.
  * - `lastUpdatedAt` — epoch ms of last success.
  * - `hasPendingMutations` — at least one mutation has a snapshot on this entry.
+ * - `isPaused` — a fetch is parked waiting for network reconnect.
  *
  * Actions:
  * - `refetch()` — force a fetch; resolves with the result.
@@ -28,6 +29,15 @@ export type AsyncState<T> = {
   isStale: ReadSignal<boolean>
   lastUpdatedAt: ReadSignal<number | undefined>
   hasPendingMutations: ReadSignal<boolean>
+  /**
+   * True while a fetch is parked waiting for network reconnect — either an
+   * `online`-mode fetch deferred because `navigator.onLine` was `false`, or an
+   * `offlineFirst` fetch that hit a network error while offline and is waiting
+   * to retry on reconnect. Distinct from `isFetching` (nothing is in flight
+   * while parked) and from `status` (stays `idle` / last-success, never
+   * flips to `error` for the parked attempt). Spec §5.5.
+   */
+  isPaused: ReadSignal<boolean>
 
   refetch: () => Promise<T>
   reset: () => void
@@ -75,6 +85,13 @@ export type LocalCache<T> = AsyncState<T> & {
 
 /** One entry inside a `DehydratedState`. */
 export type DehydratedEntry = {
+  /**
+   * Stable query identity — `spec.queryId` when set, else an auto-assigned
+   * registration id. Namespaces the hydration buffer so a subscriber of query
+   * B can't adopt query A's payload just because their `key()` outputs hash
+   * the same (spec §15).
+   */
+  id: string
   key: readonly unknown[]
   data: unknown
   lastUpdatedAt: number
@@ -117,6 +134,26 @@ export type FetchCtx = {
  * cache args come after. This shape lets module-scoped queries read
  * `ctx.deps.api` etc. — no `setApiForQuery(api)` module-level capture needed.
  */
+/**
+ * How a query behaves with respect to the network reachability signal.
+ *
+ * - `online` (default) — pause fetches while `navigator.onLine` is `false`;
+ *   automatically resume when reconnect fires (via `subscribeReconnect`).
+ *   Inflight fetches are NOT aborted on offline; a `bindEntry` / `acquire`
+ *   that lands while offline simply defers the initial fetch. The deferred
+ *   entry reports `isPaused: true` until reconnect.
+ * - `always` — never gate on connectivity; fetcher runs whenever requested.
+ *   Useful for queries against `localhost` / IPC / a service worker that
+ *   doesn't surface through `navigator.onLine`.
+ * - `offlineFirst` — start the fetch regardless; if it rejects with a
+ *   network-shaped error (a `fetch` `TypeError`; `AbortError` excluded) while
+ *   `navigator.onLine` is `false`, park the entry (`isPaused: true`, status
+ *   stays `idle` / last-success) and retry on reconnect rather than surfacing
+ *   the error. Matches TanStack's `offlineFirst` policy for app-shell-first
+ *   PWAs.
+ */
+export type NetworkMode = 'online' | 'always' | 'offlineFirst'
+
 export type QuerySpec<Args extends unknown[], T> = {
   key: (...args: Args) => unknown[]
   fetcher: (ctx: FetchCtx, ...args: Args) => Promise<T>
@@ -128,6 +165,20 @@ export type QuerySpec<Args extends unknown[], T> = {
   keepPreviousData?: boolean
   retry?: RetryPolicy
   retryDelay?: RetryDelay
+  /**
+   * Network-mode policy. Defaults to `'online'`. See `NetworkMode` for the
+   * three policies. Override per-query for special cases (e.g. `'always'`
+   * for `localhost` queries that don't surface through `navigator.onLine`).
+   */
+  networkMode?: NetworkMode
+  /**
+   * Whether to run `structuralShare(prev, next)` after a successful fetch.
+   * Defaults to `true`. Set `false` for queries returning large payloads
+   * (e.g. a 100k-row table) where the O(payload) deep walk on every poll
+   * is more expensive than re-rendering. With `false`, `applySuccess`
+   * writes the fetcher's result directly.
+   */
+  structuralShare?: boolean
   /**
    * Stable identifier used by `QueryClientPlugin`s (e.g. `@kontsedal/olas-cross-tab`)
    * to locate the same query across tabs / processes / persistence layers.
@@ -138,10 +189,17 @@ export type QuerySpec<Args extends unknown[], T> = {
    */
   queryId?: string
   /**
-   * Opt this query into cross-tab cache sync (`@kontsedal/olas-cross-tab`). No effect
-   * without a `queryId` and without a plugin installed. SPEC §13.2.
+   * Opt this query into cross-tab cache sync (`@kontsedal/olas-cross-tab`).
+   * No effect without a `queryId` and without a plugin installed. SPEC §13.2.
+   *
+   * - `true` (legacy) — equivalent to `'data'`.
+   * - `'data'` — propagate explicit `setData`/`invalidate` writes.
+   *
+   * The `'infinite'` / `'both'` values were removed (T6.4): peers can't apply
+   * infinite-query page arrays cross-tab, so those broadcasts were channel
+   * noise. Infinite cross-tab is tracked in `BACKLOG.md`.
    */
-  crossTab?: boolean
+  crossTab?: boolean | 'data'
 }
 
 /**
@@ -157,12 +215,24 @@ export type Query<Args extends unknown[], T> = {
   invalidateAll(): void
   /** Patch the current data for a specific key. Returns a `Snapshot` for rollback. */
   setData(...args: [...Args, updater: (prev: T | undefined) => T]): Snapshot
+  /**
+   * Cancel the in-flight fetch for a specific key (if any). Aborts + supersedes
+   * it, restores a settled status (`'success'` if data exists, else `'idle'`),
+   * and does NOT touch data. Use before an optimistic `setData` so an
+   * outgoing refetch's stale response can't clobber it (spec §5, §6.4).
+   */
+  cancel(...args: Args): void
+  /** Cancel in-flight fetches for every keyed entry of this query. */
+  cancelAll(): void
   /** Eagerly fetch into the cache without subscribing. */
   prefetch(...args: Args): Promise<T>
 }
 
-/** What `ctx.use(query, ...)` returns. Alias of `AsyncState<T>`. */
-export type QuerySubscription<T> = AsyncState<T>
+/** What `ctx.use(query, ...)` returns — `AsyncState<T>` plus `cancel()`. */
+export type QuerySubscription<T> = AsyncState<T> & {
+  /** Cancel this subscription's in-flight fetch (if any). See `Query.cancel`. */
+  cancel: () => void
+}
 
 /**
  * Options passed to `ctx.use(query, opts)` to control the subscription

package/src/query/use.ts

@@ -1,5 +1,6 @@
 import { computed, effect, type Signal, signal, untracked } from '../signals'
 import type { ReadSignal } from '../signals/types'
+import { isAbortError } from '../utils'
 import type { ClientEntry, InfiniteClientEntry, QueryClient } from './client'
 import type { InfiniteQuery, InfiniteQuerySpec, InfiniteQuerySubscription } from './infinite'
 import type {
@@ -27,6 +28,7 @@ class SubscriptionImpl<T, U = T> implements QuerySubscription<U> {
   readonly isStale: ReadSignal<boolean>
   readonly lastUpdatedAt: ReadSignal<number | undefined>
   readonly hasPendingMutations: ReadSignal<boolean>
+  readonly isPaused: ReadSignal<boolean>
 
   constructor(
     private readonly keepPreviousData: boolean,
@@ -66,6 +68,7 @@ class SubscriptionImpl<T, U = T> implements QuerySubscription<U> {
     this.hasPendingMutations = computed(
       () => this.current$.value?.entry.hasPendingMutations.value ?? false,
     )
+    this.isPaused = computed(() => this.current$.value?.entry.isPaused.value ?? false)
   }
 
   attach(entry: ClientEntry<T>): void {
@@ -85,13 +88,26 @@ class SubscriptionImpl<T, U = T> implements QuerySubscription<U> {
   refetch = (): Promise<U> => {
     const cur = this.current$.peek()
     if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
-    return cur.entry.refetch().then((v) => this.project(v))
+    return cur.entry.refetch().then(
+      (v) => this.project(v),
+      (err) => {
+        // A supersede (newer refetch / key change) aborts this fetch. Don't
+        // surface the spurious AbortError — resolve with the superseding
+        // fetch's eventual outcome instead (T3.9). Real errors still reject.
+        if (isAbortError(err)) return this.firstValue()
+        throw err
+      },
+    )
   }
 
   reset = (): void => {
     this.current$.peek()?.entry.reset()
   }
 
+  cancel = (): void => {
+    this.current$.peek()?.entry.cancel()
+  }
+
   firstValue = (): Promise<U> => {
     const cur = this.current$.peek()
     if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
@@ -143,8 +159,19 @@ export function createUse<Args extends unknown[], T, U = T>(
   let suspended = false
 
   const effectDispose = effect(() => {
-    if (suspended) return
+    // Read tracked signals (enabled, then key when enabled) BEFORE the
+    // `suspended` early-return, so the effect keeps its dependency set while
+    // suspended. Otherwise a key/enabled change during suspension re-runs the
+    // effect, it reads nothing, its deps go empty, and it stays inert forever
+    // — resume() then only rebinds to the key as of suspend time, silently
+    // dropping every later change (T2.1). Key is read only when enabled,
+    // preserving the `enabled`-guards-`key` pattern (the key thunk may deref
+    // state that only exists once enabled).
     const isEnabled = enabledFn ? enabledFn() : true
+    const args = isEnabled ? ((keyFn ? keyFn() : ([] as unknown as Args)) as Args) : undefined
+
+    if (suspended) return
+
     if (!isEnabled) {
       untracked(() => {
         if (currentEntry) {
@@ -156,10 +183,8 @@ export function createUse<Args extends unknown[], T, U = T>(
       return
     }
 
-    const args = (keyFn ? keyFn() : ([] as unknown as Args)) as Args
-
     untracked(() => {
-      const entry = client.bindEntry<Args, T>(query, args)
+      const entry = client.bindEntry<Args, T>(query, args as Args)
       if (currentEntry === entry) return
       if (currentEntry) currentEntry.release()
       entry.acquire()
@@ -247,6 +272,7 @@ class InfiniteSubscriptionImpl<TPage, TItem> implements InfiniteQuerySubscriptio
   readonly isStale: ReadSignal<boolean>
   readonly lastUpdatedAt: ReadSignal<number | undefined>
   readonly hasPendingMutations: ReadSignal<boolean>
+  readonly isPaused: ReadSignal<boolean>
   readonly hasNextPage: ReadSignal<boolean>
   readonly hasPreviousPage: ReadSignal<boolean>
   readonly isFetchingNextPage: ReadSignal<boolean>
@@ -288,6 +314,7 @@ class InfiniteSubscriptionImpl<TPage, TItem> implements InfiniteQuerySubscriptio
     this.hasPendingMutations = computed(
       () => this.current$.value?.entry.hasPendingMutations.value ?? false,
     )
+    this.isPaused = computed(() => this.current$.value?.entry.isPaused.value ?? false)
     this.hasNextPage = computed(() => this.current$.value?.entry.hasNextPage.value ?? false)
     this.hasPreviousPage = computed(() => this.current$.value?.entry.hasPreviousPage.value ?? false)
     this.isFetchingNextPage = computed(
@@ -315,13 +342,24 @@ class InfiniteSubscriptionImpl<TPage, TItem> implements InfiniteQuerySubscriptio
   refetch = (): Promise<TPage[]> => {
     const cur = this.current$.peek()
     if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
-    return cur.entry.refetch().then(() => cur.entry.pages.peek())
+    return cur.entry.refetch().then(
+      () => cur.entry.pages.peek(),
+      (err) => {
+        // Supersede → resolve with the superseder's outcome, not AbortError (T3.9).
+        if (isAbortError(err)) return this.firstValue()
+        throw err
+      },
+    )
   }
 
   reset = (): void => {
     this.current$.peek()?.entry.reset()
   }
 
+  cancel = (): void => {
+    this.current$.peek()?.entry.cancel()
+  }
+
   firstValue = (): Promise<TPage[]> => {
     const cur = this.current$.peek()
     if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
@@ -365,8 +403,15 @@ export function createInfiniteUse<Args extends unknown[], TPage, TItem>(
   let suspended = false
 
   const effectDispose = effect(() => {
-    if (suspended) return
+    // See the regular-query variant above: read enabled + key (when enabled)
+    // BEFORE the `suspended` early-return so the effect keeps its deps through
+    // suspension; otherwise a key change during suspend empties them and the
+    // subscription goes inert after resume (T2.1).
     const isEnabled = enabledFn ? enabledFn() : true
+    const args = isEnabled ? ((keyFn ? keyFn() : ([] as unknown as Args)) as Args) : undefined
+
+    if (suspended) return
+
     if (!isEnabled) {
       untracked(() => {
         if (currentEntry) {
@@ -378,10 +423,8 @@ export function createInfiniteUse<Args extends unknown[], TPage, TItem>(
       return
     }
 
-    const args = (keyFn ? keyFn() : ([] as unknown as Args)) as Args
-
     untracked(() => {
-      const entry = client.bindInfiniteEntry<Args, TPage, TItem>(query, args)
+      const entry = client.bindInfiniteEntry<Args, TPage, TItem>(query, args as Args)
       if (currentEntry === entry) return
       if (currentEntry) currentEntry.release()
       entry.acquire()

package/src/selection.ts

@@ -24,7 +24,7 @@ export type Selection<T = unknown> = {
   handleClick(
     id: string,
     mods: { shift?: boolean; meta?: boolean },
-    ordered: readonly string[],
+    ordered: readonly string[] | ReadonlyMap<string, number>,
   ): void
 }
 
@@ -69,6 +69,9 @@ export function selection<T = unknown>(options?: { initial?: readonly string[] }
     const next = new Set(prev)
     next.delete(id)
     ids.set(next)
+    // Clear the anchor if we just removed it — a subsequent shift-click
+    // would otherwise range from an id that's no longer in the selection.
+    if (anchor === id) anchor = null
   }
 
   const toggle = (id: string): void => {
@@ -100,24 +103,58 @@ export function selection<T = unknown>(options?: { initial?: readonly string[] }
   const handleClick = (
     id: string,
     mods: { shift?: boolean; meta?: boolean },
-    ordered: readonly string[],
+    ordered: readonly string[] | ReadonlyMap<string, number>,
   ): void => {
     if (mods.shift && anchor !== null) {
-      const anchorIdx = ordered.indexOf(anchor)
-      const targetIdx = ordered.indexOf(id)
-      if (anchorIdx === -1 || targetIdx === -1) {
-        // anchor or target not visible — fall back to plain select
-        ids.set(new Set([id]))
-        anchor = id
-        preShiftSelection = null
-        return
+      // Accept either a positional array (back-compat, O(n) lookup) OR a
+      // precomputed `Map<id, index>` for O(1) shift-click on large lists
+      // (a 100k-row virtualized table doesn't want to scan the array twice
+      // per click). The caller decides which to pass — `Map` is cheap to
+      // build once when the row list changes.
+      let anchorIdx: number
+      let targetIdx: number
+      let slice: readonly string[]
+      if (Array.isArray(ordered)) {
+        const arr = ordered as readonly string[]
+        anchorIdx = arr.indexOf(anchor)
+        targetIdx = arr.indexOf(id)
+        if (anchorIdx === -1 || targetIdx === -1) {
+          ids.set(new Set([id]))
+          anchor = id
+          preShiftSelection = null
+          return
+        }
+        const [lo, hi] = anchorIdx < targetIdx ? [anchorIdx, targetIdx] : [targetIdx, anchorIdx]
+        slice = arr.slice(lo, hi + 1)
+      } else {
+        const map = ordered as ReadonlyMap<string, number>
+        anchorIdx = map.get(anchor) ?? -1
+        targetIdx = map.get(id) ?? -1
+        if (anchorIdx === -1 || targetIdx === -1) {
+          ids.set(new Set([id]))
+          anchor = id
+          preShiftSelection = null
+          return
+        }
+        const [lo, hi] = anchorIdx < targetIdx ? [anchorIdx, targetIdx] : [targetIdx, anchorIdx]
+        // The Map gives O(1) index lookup. To materialise the range we
+        // still need keys at [lo, hi]; iterate the insertion-ordered Map
+        // once and bail when we've collected enough. The 0..hi prefix is
+        // O(hi) — bounded by the range length, not the full list.
+        const keys: string[] = []
+        let i = 0
+        for (const k of map.keys()) {
+          if (i >= lo && i <= hi) keys.push(k)
+          if (i >= hi) break
+          i += 1
+        }
+        slice = keys
       }
       if (preShiftSelection === null) {
         preShiftSelection = ids.peek()
       }
-      const [lo, hi] = anchorIdx < targetIdx ? [anchorIdx, targetIdx] : [targetIdx, anchorIdx]
       const next = new Set(preShiftSelection)
-      for (const k of ordered.slice(lo, hi + 1)) next.add(k)
+      for (const k of slice) next.add(k)
       ids.set(next)
       // Anchor stays — subsequent shift-clicks extend from the same origin.
       return

package/src/signals/readonly.ts

@@ -18,5 +18,8 @@ export function readOnly<T>(source: ReadSignal<T>): ReadSignal<T> {
     subscribe(handler: (value: T) => void) {
       return source.subscribe(handler)
     },
+    subscribeChanges(handler: (value: T) => void) {
+      return source.subscribeChanges(handler)
+    },
   })
 }

package/src/signals/runtime.ts

@@ -33,6 +33,10 @@ class SignalImpl<T> implements Signal<T> {
     return this.inner.subscribe(handler)
   }
 
+  subscribeChanges(handler: (value: T) => void): () => void {
+    return subscribeChangesImpl(this.inner, handler)
+  }
+
   set(value: T): void {
     this.inner.value = value
   }
@@ -60,6 +64,29 @@ class ComputedImpl<T> implements Computed<T> {
   subscribe(handler: (value: T) => void): () => void {
     return this.inner.subscribe(handler)
   }
+
+  subscribeChanges(handler: (value: T) => void): () => void {
+    return subscribeChangesImpl(this.inner, handler)
+  }
+}
+
+/**
+ * Shared skip-initial wrapper around `signal.subscribe`. Preact fires the
+ * subscribe callback synchronously with the current value (the "initial
+ * fire"); the wrapper swallows it and forwards every subsequent change.
+ */
+function subscribeChangesImpl<T>(
+  inner: PreactSignal<T> | PreactReadonlySignal<T>,
+  handler: (value: T) => void,
+): () => void {
+  let initial = true
+  return inner.subscribe((value) => {
+    if (initial) {
+      initial = false
+      return
+    }
+    handler(value)
+  })
 }
 
 /**

package/src/signals/types.ts

@@ -14,6 +14,16 @@ export type ReadSignal<T> = {
    * unsubscribe function.
    */
   subscribe(handler: (value: T) => void): () => void
+  /**
+   * Same as `subscribe`, but does NOT fire the synchronous "current value"
+   * callback on subscribe — only fires on subsequent changes. Useful for
+   * "react to user changes" semantics where the initial fire would be a
+   * spurious notification (the most common consumer pattern — `useField`,
+   * `usePersisted`, and the React adapter all hand-rolled this).
+   *
+   * Returns the unsubscribe function.
+   */
+  subscribeChanges(handler: (value: T) => void): () => void
 }
 
 /**

package/src/testing.ts

@@ -3,6 +3,11 @@ import type { ControllerDef, Field, Root, RootOptions } from './controller/types
 import type { AsyncState, AsyncStatus } from './query/types'
 import { computed, type ReadSignal, type Signal, signal } from './signals'
 
+// Test-only registry teardown — lives on the `@kontsedal/olas-core/testing`
+// sub-path, NOT the public entry (T3.9). Lets tests reusing a `mutationId`
+// across cases avoid registry bleed.
+export { _unregisterMutationById } from './query/plugin'
+
 /**
  * Construct an isolated root wrapping a single controller. The returned object
  * is the controller's api plus the standard Root lifecycle controls
@@ -76,6 +81,7 @@ export function fakeField<T>(
     },
     peek: () => value$.peek(),
     subscribe: (handler) => value$.subscribe(handler),
+    subscribeChanges: (handler) => value$.subscribeChanges(handler),
     errors: errors$,
     isValid: isValid$,
     isDirty: dirty$,
@@ -108,6 +114,7 @@ export function fakeAsyncState<T>(
     isStale: boolean
     lastUpdatedAt: number | undefined
     hasPendingMutations: boolean
+    isPaused: boolean
     refetch: () => Promise<T>
     reset: () => void
     firstValue: () => Promise<T>
@@ -124,6 +131,7 @@ export function fakeAsyncState<T>(
   const isStale$: ReadSignal<boolean> = signal(overrides?.isStale ?? false)
   const lastUpdatedAt$: ReadSignal<number | undefined> = signal(overrides?.lastUpdatedAt)
   const hasPendingMutations$: ReadSignal<boolean> = signal(overrides?.hasPendingMutations ?? false)
+  const isPaused$: ReadSignal<boolean> = signal(overrides?.isPaused ?? false)
 
   const refetch = overrides?.refetch ?? (async () => data$.peek() as T)
   const reset = overrides?.reset ?? (() => {})
@@ -139,6 +147,7 @@ export function fakeAsyncState<T>(
     isStale: isStale$,
     lastUpdatedAt: lastUpdatedAt$,
     hasPendingMutations: hasPendingMutations$,
+    isPaused: isPaused$,
     refetch,
     reset,
     firstValue,