@kontsedal/olas-core 0.0.1-rc.0 → 0.0.1

package/dist/testing.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_root = require("./root-Bazp5_Ik.cjs");
+const require_root = require("./root-DXV1gVbQ.cjs");
 //#region src/testing.ts
 /**
 * Construct an isolated root wrapping a single controller. The returned object

package/dist/testing.d.cts

@@ -1,4 +1,4 @@
-import { O as AsyncState, c as RootOptions, k as AsyncStatus, n as ControllerDef, o as Field, s as Root } from "./types-emq_lZd7.cjs";
+import { O as AsyncState, c as RootOptions, k as AsyncStatus, n as ControllerDef, o as Field, s as Root } from "./types-CffZ1QXt.cjs";
 
 //#region src/testing.d.ts
 /**

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { O as AsyncState, c as RootOptions, k as AsyncStatus, n as ControllerDef, o as Field, s as Root } from "./types-CAMgqCMz.mjs";
+import { O as AsyncState, c as RootOptions, k as AsyncStatus, n as ControllerDef, o as Field, s as Root } from "./types-DSlDowpE.mjs";
 
 //#region src/testing.d.ts
 /**

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { d as signal, l as computed, n as createRootWithProps } from "./root-BImHnGj1.mjs";
+import { f as signal, n as createRootWithProps, u as computed } from "./root-BCZDC5Fv.mjs";
 //#region src/testing.ts
 /**
 * Construct an isolated root wrapping a single controller. The returned object

package/dist/{types-CAMgqCMz.d.mts → types-CffZ1QXt.d.cts}

@@ -85,8 +85,24 @@ type DeepPartial<T> = T extends object ? T extends ReadonlyArray<infer U> ? Read
 type FormValidator<S extends FormSchema> = Validator<FormValue<S>>;
 type FieldArrayValidator<I> = Validator<FieldArrayValue<I>>;
 type FormOptions<S extends FormSchema> = {
+  /**
+   * Initial values for the form. A function form is **tracked** — if the
+   * function reads reactive signals (e.g. a query's `data`), the form re-seats
+   * itself when those signals change, but only while the form is not dirty
+   * (so a user mid-edit isn't clobbered by a background refetch). See
+   * `resetOnInitialChange` for opt-out. Spec §8.4.
+   */
   initial?: (() => DeepPartial<FormValue<S>> | undefined) | DeepPartial<FormValue<S>>;
   validators?: FormValidator<S>[];
+  /**
+   * When `initial` is a function and one of its tracked deps changes:
+   *  - `'when-clean'` (default) — re-seat only if the form is not dirty.
+   *  - `'never'` — never re-seat; `initial()` runs once at construction.
+   *  - `'always'` — re-seat unconditionally (dirty state is discarded).
+   *
+   * Spec §20.7.
+   */
+  resetOnInitialChange?: 'when-clean' | 'never' | 'always';
 };
 type FieldArrayOptions<I> = {
   initial?: Array<ItemInitial<I>>;
@@ -356,9 +372,7 @@ type InfiniteQuery<Args extends unknown[], TPage, _TItem> = {
   readonly __olas: 'infiniteQuery';
   invalidate(...args: Args): void;
   invalidateAll(): void;
-  setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): {
-    rollback: () => void;
-  };
+  setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): Snapshot;
   prefetch(...args: Args): Promise<TPage>;
 };
 /**
@@ -574,10 +588,44 @@ type QueryClientPluginApi = {
    */
   applyRemoteSetData(queryId: string, keyArgs: readonly unknown[], data: unknown): void;
   applyRemoteInvalidate(queryId: string, keyArgs: readonly unknown[]): void;
+  /**
+   * Apply a local-originated `setData` to the entry identified by
+   * `(queryId, keyArgs)`. The resulting plugin events fire with
+   * `isRemote: false` and `source: 'set'` — cross-tab plugins WILL
+   * rebroadcast (the write is treated as if a controller called
+   * `client.setData(...)` directly).
+   *
+   * Drops silently when the queryId is unknown, the registered query is
+   * infinite, or no local entry exists for that key. The `updater`
+   * receives the previous data (typed as `unknown` because plugins are
+   * type-erased) and returns the next.
+   *
+   * Use case: entity-normalization plugins that want to backpropagate an
+   * `entity.update(...)` patch into every query holding that entity.
+   * Mutations / optimistic updates already go through the public
+   * `client.setData` and don't need this API.
+   */
+  setEntryData(queryId: string, keyArgs: readonly unknown[], updater: (prev: unknown) => unknown): void;
   /**
    * Snapshot of currently bound entry keys for a query (by `queryId`). Empty
    * array when the query isn't registered, has no client entries, or the
    * `queryId` doesn't match any registered query.
+   *
+   * @example
+   * ```ts
+   * // Plugin sees an incoming invalidate; only echo it outward if any local
+   * // controller is actually subscribed to that key — otherwise the message
+   * // is unilateral noise.
+   * const plugin: QueryClientPlugin = {
+   *   init(api) { this.api = api },
+   *   onInvalidate(ev) {
+   *     if (ev.isRemote) return
+   *     const subscribed = this.api.subscribedKeys(ev.queryId)
+   *     if (subscribed.length === 0) return // no local subscribers → don't send
+   *     transport.send({ type: 'invalidate', queryId: ev.queryId, keyArgs: ev.keyArgs })
+   *   },
+   * }
+   * ```
    */
   subscribedKeys(queryId: string): readonly (readonly unknown[])[];
 };
@@ -596,6 +644,18 @@ type SetDataEvent = {
    * skip rebroadcast in that case — otherwise the message would echo back.
    */
   isRemote: boolean;
+  /**
+   * Origin of the write. `'set'` covers explicit `client.setData` (mutations,
+   * optimistic updates, plugin-initiated patches). `'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
+   * `isRemote === true`.
+   *
+   * Layered plugins use this to decide whether to react: cross-tab broadcasts
+   * only on `'set'`, an entity-normalization plugin observes all sources.
+   */
+  source: 'set' | 'fetch' | 'remote';
 };
 type InvalidateEvent = {
   queryId: string;
@@ -755,18 +815,30 @@ type Ctx<TDeps = AmbientDeps> = {
     deps?: Partial<TDeps>;
   }): Api;
   /**
-   * Like `child(...)` but additionally returns a `dispose()` handle so the
-   * parent can tear down this specific sub-tree early — e.g. when the user
-   * closes a details panel. The child is still disposed automatically when
-   * the parent disposes; `dispose()` is idempotent and only earlies the
-   * teardown. Useful for "openable" sub-controllers whose lifetime is driven
-   * by a user gesture rather than the parent's lifetime alone.
+   * Like `child(...)` but additionally returns a handle that lets the parent
+   * control the attached sub-tree's lifecycle independently — `dispose()`
+   * tears it down early, and `suspend()` / `resume()` freeze and thaw it.
+   * The child is still disposed automatically when the parent disposes;
+   * `dispose()` / `suspend()` / `resume()` are idempotent.
+   *
+   * `<KeepAlive controller={…}>` in `@kontsedal/olas-react` consumes the
+   * returned `{ suspend, resume }` directly — no hand-rolled `isPaused`
+   * signal needed on the child's `Api`. Useful for "openable" sub-
+   * controllers driven by a user gesture (modal, side panel, wizard).
+   *
+   * `suspend()` cascades through the attached controller's lifecycle
+   * entries: cache subscriptions pause `refetchInterval` and release the
+   * entry, effects are torn down, `onSuspend(...)` handlers fire. `resume()`
+   * re-runs effects, re-acquires cache entries (a stale entry refetches),
+   * and fires `onResume(...)`. Spec §4.1, §16.5.
    */
   attach<Props, Api>(def: ControllerDef<Props, Api>, props: Props, options?: {
     deps?: Partial<TDeps>;
   }): {
     api: Api;
     dispose: () => void;
+    suspend: () => void;
+    resume: () => void;
   };
   effect(fn: () => void | (() => void)): void;
   on<T>(emitter: Emitter<T>, handler: (value: T) => void): void;
@@ -813,4 +885,4 @@ type Root<Api> = Api & {
 };
 //#endregion
 export { Validator as $, DehydratedEntry as A, DeepPartial as B, DebugCacheEntry as C, InfiniteQuerySubscription as D, InfiniteQuerySpec as E, QuerySubscription as F, FieldArrayValue as G, FieldArrayItemErrors as H, RetryDelay as I, FormOptions as J, Form as K, RetryPolicy as L, LocalCache as M, Query as N, AsyncState as O, QuerySpec as P, ItemInitial as Q, Snapshot as R, DebugBus as S, InfiniteQuery as T, FieldArrayOptions as U, FieldArray as V, FieldArrayValidator as W, FormValidator as X, FormSchema as Y, FormValue as Z, SetDataEvent as _, Ctx as a, createEmitter as at, MutationConcurrency as b, RootOptions as c, defineScope as d, Computed as et, GcEvent as f, RegisteredQuery as g, QueryClientPluginApi as h, CtrlProps as i, Emitter as it, DehydratedState as j, AsyncStatus as k, Scope as l, QueryClientPlugin as m, ControllerDef as n, Signal as nt, Field as o, InvalidateEvent as p, FormErrors as q, CtrlApi as r, ErrorContext as rt, Root as s, AmbientDeps as t, ReadSignal as tt, ScopeOptions as u, lookupRegisteredQuery as v, DebugEvent as w, MutationSpec as x, Mutation as y, UseOptions as z };
-//# sourceMappingURL=types-CAMgqCMz.d.mts.map
+//# sourceMappingURL=types-CffZ1QXt.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types-CffZ1QXt.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":";;AAUA;;;;;;;;;KAAY,OAAA;EACV,IAAA,GAAO,CAAA,iCAAkC,KAAA,EAAO,CAAA,WAAzC;EAEP,EAAA,CAAG,OAAA,GAAU,KAAA,EAAO,CAAA,wBAFqB;EAIzC,IAAA,CAAK,OAAA,GAAU,KAAA,EAAO,CAAA,wBAFF;EAIpB,OAAA;AAAA;;;;;;;iBAqDc,aAAA,UAAA,CAAA,GAA2B,OAAO,CAAC,CAAA;;;;AA5DnD;;;;;;;;KCDY,YAAA;EACV,IAAA;EACA,cAAA;EACA,QAAA;AAAA;;;;ADFF;;;;;KEJY,UAAA;EAAA,SACD,KAAA,EAAO,CAAA,EFQO;EENvB,IAAA,IAAQ,CAAA;EFCU;;;;;EEKlB,SAAA,CAAU,OAAA,GAAU,KAAA,EAAO,CAAA;AAAA;;;;;;KAQjB,MAAA,MAAY,UAAA,CAAW,CAAA;EACjC,KAAA,EAAO,CAAA;EACP,GAAA,CAAI,KAAA,EAAO,CAAA;EACX,MAAA,CAAO,EAAA,GAAK,IAAA,EAAM,CAAA,KAAM,CAAA;AAAA;;KAId,QAAA,MAAc,UAAU,CAAC,CAAA;;;KC9BzB,SAAA,OAAgB,KAAA,EAAO,CAAA,EAAG,MAAA,EAAQ,WAAA,qBAAgC,OAAA;;;KCIlE,UAAA;EAAA,CACT,GAAA,WAAc,KAAA,QAAa,IAAA,QAAY,UAAA;AAAA;AAAA,KAG9B,SAAA,WAAoB,UAAA,kBAClB,CAAA,GAAI,CAAA,CAAE,CAAA,UAAW,KAAA,YACzB,CAAA,GACA,CAAA,CAAE,CAAA,UAAW,IAAA,aACX,SAAA,CAAU,EAAA,IACV,CAAA,CAAE,CAAA,UAAW,UAAA,YACX,eAAA,CAAgB,CAAA;AAAA,KAId,UAAA,WAAqB,UAAA,kBACnB,CAAA,IAAK,CAAA,CAAE,CAAA,UAAW,KAAA,+BAE1B,CAAA,CAAE,CAAA,UAAW,IAAA,aACX,UAAA,CAAW,EAAA,IACX,CAAA,CAAE,CAAA,UAAW,UAAA,YACX,KAAA,CAAM,oBAAA,CAAqB,CAAA;AAAA,KAIzB,eAAA,MACV,CAAA,SAAU,KAAA,YAAiB,CAAA,KAAM,CAAA,SAAU,IAAA,YAAgB,SAAA,CAAU,CAAA;AAAA,KAE3D,oBAAA,MACV,CAAA,SAAU,KAAA,mBAAwB,CAAA,SAAU,IAAA,YAAgB,UAAA,CAAW,CAAA;AAAA,KAE7D,WAAA,MACV,CAAA,SAAU,KAAA,YAAiB,CAAA,GAAI,CAAA,SAAU,IAAA,YAAgB,WAAA,CAAY,SAAA,CAAU,CAAA;AAAA,KAErE,WAAA,MAAiB,CAAA,kBACzB,CAAA,SAAU,aAAA,YACR,aAAA,CAAc,WAAA,CAAY,CAAA,mBACZ,CAAA,IAAK,WAAA,CAAY,CAAA,CAAE,CAAA,OACnC,CAAA;AAAA,KAEQ,aAAA,WAAwB,UAAA,IAAc,SAAA,CAAU,SAAA,CAAU,CAAA;AAAA,KAC1D,mBAAA,MAAyB,SAAA,CAAU,eAAA,CAAgB,CAAA;AAAA,KAEnD,WAAA,WAAsB,UAAA;EJ/BjB;;;;AAER;AAqDT;;EIhBE,OAAA,UAAiB,WAAA,CAAY,SAAA,CAAU,CAAA,kBAAmB,WAAA,CAAY,SAAA,CAAU,CAAA;EAChF,UAAA,GAAa,aAAA,CAAc,CAAA;EJeC;;;;AAAsB;;;;EINlD,oBAAA;AAAA;AAAA,KAGU,iBAAA;EACV,OAAA,GAAU,KAAA,CAAM,WAAA,CAAY,CAAA;EAC5B,UAAA,GAAa,mBAAA,CAAoB,CAAA;AAAA;;;AHzDzB;;;;ACNV;;;KE2EY,IAAA,WAAe,UAAA;EAAA,SAChB,MAAA,gBAAsB,CAAA,GAAI,CAAA,CAAE,CAAA;EAAA,SAC5B,KAAA,EAAO,UAAA,CAAW,SAAA,CAAU,CAAA;EAAA,SAC5B,MAAA,EAAQ,UAAA,CAAW,UAAA,CAAW,CAAA;EAAA,SAC9B,cAAA,EAAgB,UAAA;EAAA,SAChB,UAAA,EAAY,UAAA,CAAW,KAAA;IAAQ,IAAA;IAAc,MAAA;EAAA;EAAA,SAC7C,OAAA,EAAS,UAAA;EAAA,SACT,OAAA,EAAS,UAAA;EAAA,SACT,OAAA,EAAS,UAAA;EAAA,SACT,YAAA,EAAc,UAAA,WF3Ec;EE8ErC,GAAA,CAAI,OAAA,EAAS,WAAA,CAAY,SAAA,CAAU,CAAA;EFtEnB;;;;;;EE6EhB,gBAAA,CAAiB,OAAA,EAAS,WAAA,CAAY,SAAA,CAAU,CAAA,WF1ExB;EE4ExB,KAAA,UF5EyB;EE8EzB,cAAA,UFjFsB;EEmFtB,QAAA,IAAY,OAAA,WFlFZ;EEoFA,OAAA;AAAA;;;;;;KAQU,UAAA,WAAqB,KAAA,QAAa,IAAA;EAAA,SACnC,KAAA,EAAO,UAAA,CAAW,aAAA,CAAc,CAAA;EAAA,SAChC,KAAA,EAAO,UAAA,CAAW,eAAA,CAAgB,CAAA;EAAA,SAClC,MAAA,EAAQ,UAAA,CAAW,KAAA,CAAM,oBAAA,CAAqB,CAAA;EAAA,SAC9C,cAAA,EAAgB,UAAA;EAAA,SAChB,OAAA,EAAS,UAAA;EAAA,SACT,OAAA,EAAS,UAAA;EAAA,SACT,OAAA,EAAS,UAAA;EAAA,SACT,YAAA,EAAc,UAAA;EAAA,SACd,IAAA,EAAM,UAAA;EAEf,GAAA,CAAI,OAAA,GAAU,WAAA,CAAY,CAAA;EAC1B,MAAA,CAAO,KAAA,UAAe,OAAA,GAAU,WAAA,CAAY,CAAA;EAC5C,MAAA,CAAO,KAAA;EACP,IAAA,CAAK,IAAA,UAAc,EAAA;EACnB,EAAA,CAAG,KAAA,WAAgB,CAAA;EACnB,KAAA;EAEA,KAAA;EACA,cAAA;EACA,QAAA,IAAY,OAAA;EACZ,OAAA;AAAA;;;AJ/HF;AAAA,KKPY,WAAA;;;;;;;;;;;;;;;;;KAkBA,UAAA;EACV,IAAA,EAAM,UAAA,CAAW,CAAA;EACjB,KAAA,EAAO,UAAA;EACP,MAAA,EAAQ,UAAA,CAAW,WAAA;EACnB,SAAA,EAAW,UAAA;EACX,UAAA,EAAY,UAAA;EACZ,OAAA,EAAS,UAAA;EACT,aAAA,EAAe,UAAA;EACf,mBAAA,EAAqB,UAAA;EAErB,OAAA,QAAe,OAAA,CAAQ,CAAA;EACvB,KAAA;EACA,UAAA,QAAkB,OAAA,CAAQ,CAAA;AAAA;;;ALqCwB;;;;AC7DpD;;;;;;;;KIyCY,QAAA;EACV,QAAA;EACA,QAAQ;AAAA;AH9CV;;;;AAAA,KGqDY,UAAA,MAAgB,UAAA,CAAW,CAAA;EH5CV,mDG8C3B,UAAA,UH9C4B;EGgD5B,OAAA,CAAQ,OAAA,GAAU,IAAA,EAAM,CAAA,iBAAkB,CAAA,GAAI,QAAA,EHxDrC;EG0DT,OAAA;AAAA;;KAIU,eAAA;EACV,GAAA;EACA,IAAA;EACA,aAAA;AAAA;AHzDqC;AAQvC;;;;AARuC,KGiE3B,eAAA;EACV,OAAA;EACA,OAAA,EAAS,eAAe;AAAA;;;;;KAOd,WAAA,cAAyB,OAAA,UAAiB,KAAc;;KAGxD,UAAA,cAAwB,OAAe;;;;;;KAOvC,QAAA;EACV,MAAA,EAAQ,WAAA;EACR,IAAA,EADmB,WAC4B;AAAA;;AH3EtB;AAI3B;;;;;;KGkFY,SAAA;EACV,GAAA,MAAS,IAAA,EAAM,IAAA;EACf,OAAA,GAAU,GAAA,EAAK,QAAA,KAAa,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA;EACnD,SAAA;EACA,MAAA;EACA,eAAA;EACA,oBAAA;EACA,kBAAA;EACA,gBAAA;EACA,KAAA,GAAQ,WAAA;EACR,UAAA,GAAa,UAAA;EF1H+D;;;;;;;;EEmI5E,OAAA;EFnImF;AAAA;;;EEwInF,QAAA;AAAA;;;;;;KAQU,KAAA;EAAA,SACD,MAAA,WD5IR;EC8ID,UAAA,IAAc,IAAA,EAAM,IAAA,SD9IQ;ECgJ5B,aAAA,UDhJkD;ECkJlD,OAAA,IAAW,IAAA,MAAU,IAAA,EAAM,OAAA,GAAU,IAAA,EAAM,CAAA,iBAAkB,CAAA,IAAK,QAAA,ED/IxD;ECiJV,QAAA,IAAY,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,CAAA;AAAA;;KAIvB,iBAAA,MAAuB,UAAU,CAAC,CAAA;;;;;;KAOlC,UAAA;EACV,GAAA,SAAY,IAAI;EAChB,OAAA;AAAA;;;;;;;;;;;;KCxJU,gBAAA;EACV,SAAA,EAAW,SAAA;EACX,MAAA,EAAQ,WAAA;EACR,IAAA,EADmB,WAAA;AAAA;AAAA,KAIT,iBAAA,mDAAoE,KAAA;EAC9E,GAAA,MAAS,IAAA,EAAM,IAAA;ENNf;;;;;EMYA,OAAA,GAAU,GAAA,EAAK,gBAAA,CAAiB,SAAA,MAAe,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,KAAA;EACtE,gBAAA,EAAkB,SAAA;EAClB,gBAAA,GAAmB,QAAA,EAAU,KAAA,EAAO,QAAA,EAAU,KAAA,OAAY,SAAA;EAC1D,oBAAA,IAAwB,SAAA,EAAW,KAAA,EAAO,QAAA,EAAU,KAAA,OAAY,SAAA;EAChE,OAAA,IAAW,IAAA,EAAM,KAAA,KAAU,KAAA;EAC3B,SAAA;EACA,MAAA;EACA,eAAA;EACA,gBAAA;EACA,KAAA,GAAQ,WAAA;EACR,UAAA,GAAa,UAAA;;;;AL5Bf;;;EKmCE,OAAA;ELlCA;;;;EKuCA,QAAA;AAAA;;;AJ3CF;;KIkDY,aAAA;EAAA,SACD,MAAA;EACT,UAAA,IAAc,IAAA,EAAM,IAAA;EACpB,aAAA;EACA,OAAA,IAAW,IAAA,MAAU,IAAA,EAAM,OAAA,GAAU,IAAA,EAAM,KAAA,mBAAwB,KAAA,MAAW,QAAA;EAC9E,QAAA,IAAY,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,KAAA;AAAA;;;;;;;;;KAWvB,yBAAA,iBAA0C,UAAA,CAAW,KAAA;EAC/D,KAAA,EAAO,UAAA,CAAW,KAAA;EAClB,IAAA,EAAM,UAAA,CAAW,KAAA;EACjB,WAAA,EAAa,UAAA;EACb,eAAA,EAAiB,UAAA;EACjB,kBAAA,EAAoB,UAAA;EACpB,sBAAA,EAAwB,UAAA;EACxB,aAAA,QAAqB,OAAA;EACrB,iBAAA,QAAyB,OAAA;AAAA;;;;ANtE3B;;;;KOLY,UAAA;EACN,IAAA;EAAgC,IAAA;EAAyB,KAAA;AAAA;EACzD,IAAA;EAA8B,IAAA;AAAA;EAC9B,IAAA;EAA4B,IAAA;AAAA;EAC5B,IAAA;EAA6B,IAAA;AAAA;EAE7B,IAAA;EACA,QAAA;EACA,cAAA;AAAA;EAEA,IAAA;EAA2B,QAAA;AAAA;EAC3B,IAAA;EAA6B,QAAA;EAA8B,UAAA;AAAA;EAE3D,IAAA;EACA,QAAA;EACA,KAAA;EACA,UAAA;AAAA;EAEA,IAAA;EAA2B,QAAA;AAAA;EAC3B,IAAA;EAAkB,QAAA;AAAA;EAClB,IAAA;EAAsB,IAAA;EAAyB,IAAA;EAAe,IAAA;AAAA;EAC9D,IAAA;EAA0B,IAAA;EAAyB,IAAA;EAAe,MAAA;AAAA;EAClE,IAAA;EAAwB,IAAA;EAAyB,IAAA;EAAe,KAAA;AAAA;EAChE,IAAA;EAA2B,IAAA;EAAyB,IAAA;AAAA;EAEpD,IAAA;EACA,IAAA;EACA,KAAA;EACA,KAAA;EACA,MAAA;AAAA;;;ALnBiC;AAQvC;KKkBY,eAAA;EACV,GAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,aAAA;EACA,OAAA;EACA,UAAA;EACA,mBAAA;AAAA;;;;;;;;;;;;;KAeU,QAAA;EACV,SAAA,CAAU,OAAA,GAAU,KAAA,EAAO,UAAA;EAC3B,YAAA,IAAgB,eAAe;AAAA;;;;;;;;;;;KCnDrB,mBAAA;;;;;;KAOA,YAAA;ERPV;;;;;EQaA,IAAA,WRXO;EQaP,MAAA,GAAS,IAAA,EAAM,CAAA,EAAG,MAAA,EAAQ,WAAA,KAAgB,OAAA,CAAQ,CAAA;ERwCvB;;;;EQnC3B,QAAA,IAAY,IAAA,EAAM,CAAA,KAAM,QAAA;EACxB,SAAA,IAAa,MAAA,EAAQ,CAAA,EAAG,IAAA,EAAM,CAAA;EAC9B,OAAA,IAAW,GAAA,WAAc,IAAA,EAAM,CAAA,EAAG,QAAA,EAAU,QAAA;EAC5C,SAAA,IAAa,MAAA,EAAQ,CAAA,cAAe,GAAA,uBAA0B,IAAA,EAAM,CAAA;EACpE,WAAA,GAAc,mBAAA;EACd,KAAA,GAAQ,WAAA;EACR,UAAA,GAAa,UAAA;AAAA;;;;;;;;AP7BL;;;;ACNV;;;;;;;ADMU,KOkDE,WAAA,aACP,IAAA,kBAAsB,CAAA,IAAK,CAAA,MAAO,CAAA,yBAA0B,CAAA,MAC5D,OAAA,CAAQ,CAAA;AAAA,KAED,QAAA;EN3DD,6EM6DT,GAAA,EAAK,WAAA,CAAY,CAAA,EAAG,CAAA;EACpB,IAAA,EAAM,UAAA,CAAW,CAAA;EACjB,KAAA,EAAO,UAAA;EACP,SAAA,EAAW,UAAA;EACX,aAAA,EAAe,UAAA,CAAW,CAAA,eNzDN;EM2DpB,KAAA,UN3DqC;EM6DrC,OAAA;AAAA;;;;ARlEF;;;;;;;;;;;;;;;;;;;;;;KScY,oBAAA;ETPH;AAAA;AAqDT;;;ESxCE,kBAAA,CAAmB,OAAA,UAAiB,OAAA,sBAA6B,IAAA;EACjE,qBAAA,CAAsB,OAAA,UAAiB,OAAA;ETuCE;;;AAAS;;;;AC7DpD;;;;;;;;AAGU;;EQqCR,YAAA,CACE,OAAA,UACA,OAAA,sBACA,OAAA,GAAU,IAAA;;AP9Cd;;;;;;;;;;;;;;;;;;AASuC;AAQvC;EOoDE,cAAA,CAAe,OAAA;AAAA;AAAA,KAGL,YAAA;EACV,OAAA;EACA,OAAA;EACA,IAAA;EPvDkB;;;;;EO6DlB,IAAA;EPhEiC;;;;EOqEjC,QAAA;EPnEI;;;;;;;AACqB;AAI3B;;;EO0EE,MAAA;AAAA;AAAA,KAGU,eAAA;EACV,OAAA;EACA,OAAA;EACA,IAAA;EACA,QAAA;AAAA;AAAA,KAGU,OAAA;EACV,OAAA;EACA,OAAA;EACA,IAAA;AAAA;;;;;;KAQU,iBAAA;EN7HgB;;;;EMkI1B,IAAA,EAAM,GAAA,EAAK,oBAAA;EACX,SAAA,EAAW,KAAA,EAAO,YAAA;EAClB,YAAA,EAAc,KAAA,EAAO,eAAA;EACrB,IAAA,EAAM,KAAA,EAAO,OAAA;EAEb,OAAA;AAAA;ALlIkD;AAGpD;;;AAHoD,KKmJxC,eAAA;EAAA,SACD,MAAA;EAAA,SACA,MAAA;IAAU,OAAA;IAAkB,QAAA;EAAA;AAAA;;;;;;iBAoBvB,qBAAA,CAAsB,OAAA,WAAkB,eAAe;;;;ATpKvE;;;;KULY,KAAA;EAAA,SACD,MAAA,WVSa;EAAA,SUPb,IAAA,UVOc;EAAA,SULd,IAAA,WVCT;EAAA,SUCS,OAAA,GAAU,CAAA,EVD6B;EAAA,SUGvC,UAAA;EAAA,SAEA,GAAA,GAAM,CAAC;AAAA;AAAA,KAGN,YAAA;EACV,OAAA,GAAU,CAAC;EACX,IAAA;AAAA;;;;;AVJO;AAqDT;iBUxCgB,WAAA,GAAA,CAAe,OAAA,GAAU,YAAA,CAAa,CAAA,IAAK,KAAA,CAAM,CAAA;;;;;;;;;;;;;;;;;;UCGhD,WAAA;EAAA,CACd,GAAW;AAAA;;;;;;;KASF,KAAA,MAAW,UAAA,CAAW,CAAA;EAChC,MAAA,EAAQ,UAAA;EACR,OAAA,EAAS,UAAA;EACT,OAAA,EAAS,UAAA;EACT,OAAA,EAAS,UAAA;EACT,YAAA,EAAc,UAAA;EACd,GAAA,CAAI,KAAA,EAAO,CAAA;EVxCW;;;;;AAGd;;EU6CR,YAAA,CAAa,KAAA,EAAO,CAAA;EACpB,KAAA;EACA,WAAA;EACA,UAAA,IAAc,OAAA,WTtDM;ESwDpB,OAAA;AAAA;;;;;;KAQU,aAAA;EAAA,SACD,MAAA;EAAA,SACA,OAAA;IAAY,KAAA,EAAO,KAAA;IAAO,GAAA,EAAK,GAAG;EAAA;AAAA;;KAIjC,SAAA,MAAe,CAAA,SAAU,aAAa,qBAAqB,CAAA;ATrDvE;AAAA,KSwDY,OAAA,MAAa,CAAA,SAAU,aAAa,qBAAqB,CAAA;;;;;;;;;KAUzD,GAAA,SAAY,WAAA;EACtB,KAAA,IACE,OAAA,GAAU,MAAA,EAAQ,WAAA,KAAgB,OAAA,CAAQ,CAAA,GAC1C,OAAA;IACE,GAAA;IACA,SAAA;IACA,gBAAA;IACA,WAAA,GAAc,CAAA;EAAA,IAEf,UAAA,CAAW,CAAA;EAEd,GAAA,4BACE,MAAA,EAAQ,KAAA,CAAM,IAAA,EAAM,CAAA,GACpB,YAAA,UAAsB,IAAA,IAAQ,UAAA,CAAW,IAAA,IACxC,iBAAA,CAAkB,CAAA;EACrB,GAAA,uCACE,MAAA,EAAQ,aAAA,CAAc,IAAA,EAAM,KAAA,EAAO,KAAA,GACnC,YAAA,UAAsB,IAAA,IAAQ,UAAA,CAAW,IAAA,IACxC,yBAAA,CAA0B,KAAA,EAAO,KAAA;EAEpC,QAAA,OAAe,IAAA,EAAM,YAAA,CAAa,CAAA,EAAG,CAAA,IAAK,QAAA,CAAS,CAAA,EAAG,CAAA;EAEtD,OAAA,cAAqB,OAAA,CAAQ,CAAA;EAE7B,KAAA,IAAS,OAAA,EAAS,CAAA,EAAG,UAAA,GAAa,aAAA,CAAc,SAAA,CAAU,CAAA,KAAM,KAAA,CAAM,CAAA;EAEtE,IAAA,WAAe,UAAA,EAAY,MAAA,EAAQ,CAAA,EAAG,OAAA,GAAU,WAAA,CAAY,CAAA,IAAK,IAAA,CAAK,CAAA;EAEtE,UAAA,WAAqB,KAAA,QAAa,IAAA,OAChC,WAAA,GAAc,OAAA,GAAU,WAAA,CAAY,CAAA,MAAO,CAAA,EAC3C,OAAA,GAAU,iBAAA,CAAkB,CAAA,IAC3B,UAAA,CAAW,CAAA;EAEd,KAAA,aACE,GAAA,EAAK,aAAA,CAAc,KAAA,EAAO,GAAA,GAC1B,KAAA,EAAO,KAAA,EACP,OAAA;IAAY,IAAA,GAAO,OAAA,CAAQ,KAAA;EAAA,IAC1B,GAAA;EThGe;;;;;;;AAAkB;;;;AC9BtC;;;;;;;EQkJE,MAAA,aACE,GAAA,EAAK,aAAA,CAAc,KAAA,EAAO,GAAA,GAC1B,KAAA,EAAO,KAAA,EACP,OAAA;IAAY,IAAA,GAAO,OAAA,CAAQ,KAAA;EAAA;IACxB,GAAA,EAAK,GAAA;IAAK,OAAA;IAAqB,OAAA;IAAqB,MAAA;EAAA;EAEzD,MAAA,CAAO,EAAA;EAEP,EAAA,IAAM,OAAA,EAAS,OAAA,CAAQ,CAAA,GAAI,OAAA,GAAU,KAAA,EAAO,CAAA;EAG5C,OAAA,IAAW,KAAA,EAAO,KAAA,CAAM,CAAA,GAAI,KAAA,EAAO,CAAA;EACnC,MAAA,IAAU,KAAA,EAAO,KAAA,CAAM,CAAA,IAAK,CAAA;EAE5B,SAAA,CAAU,EAAA;EACV,SAAA,CAAU,EAAA;EACV,QAAA,CAAS,EAAA;EAAA,SAEA,IAAA,EAAM,KAAA;AAAA;;;;;;;KAYL,WAAA;EACV,IAAA,EAAM,KAAA;EACN,OAAA,IAAW,GAAA,WAAc,OAAA,EAAS,YAAA;EAClC,OAAA,GAAU,eAAA,EP3KoB;EO6K9B,oBAAA,YP5KgB;EO8KhB,kBAAA;EP9K6B;;;;;EOoL7B,OAAA,GAAU,iBAAA;AAAA;;;;;;KAQA,IAAA,QAAY,GAAA;EACtB,OAAA;EACA,OAAA,CAAQ,OAAA;IAAY,OAAA;EAAA;EACpB,MAAA;EACA,SAAA,IAAa,eAAA;EACb,WAAA,IAAe,OAAA;EAAA,SACN,OAAA,EAAS,QAAA;AAAA"}

package/dist/{types-emq_lZd7.d.cts → types-DSlDowpE.d.mts}

@@ -85,8 +85,24 @@ type DeepPartial<T> = T extends object ? T extends ReadonlyArray<infer U> ? Read
 type FormValidator<S extends FormSchema> = Validator<FormValue<S>>;
 type FieldArrayValidator<I> = Validator<FieldArrayValue<I>>;
 type FormOptions<S extends FormSchema> = {
+  /**
+   * Initial values for the form. A function form is **tracked** — if the
+   * function reads reactive signals (e.g. a query's `data`), the form re-seats
+   * itself when those signals change, but only while the form is not dirty
+   * (so a user mid-edit isn't clobbered by a background refetch). See
+   * `resetOnInitialChange` for opt-out. Spec §8.4.
+   */
   initial?: (() => DeepPartial<FormValue<S>> | undefined) | DeepPartial<FormValue<S>>;
   validators?: FormValidator<S>[];
+  /**
+   * When `initial` is a function and one of its tracked deps changes:
+   *  - `'when-clean'` (default) — re-seat only if the form is not dirty.
+   *  - `'never'` — never re-seat; `initial()` runs once at construction.
+   *  - `'always'` — re-seat unconditionally (dirty state is discarded).
+   *
+   * Spec §20.7.
+   */
+  resetOnInitialChange?: 'when-clean' | 'never' | 'always';
 };
 type FieldArrayOptions<I> = {
   initial?: Array<ItemInitial<I>>;
@@ -356,9 +372,7 @@ type InfiniteQuery<Args extends unknown[], TPage, _TItem> = {
   readonly __olas: 'infiniteQuery';
   invalidate(...args: Args): void;
   invalidateAll(): void;
-  setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): {
-    rollback: () => void;
-  };
+  setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): Snapshot;
   prefetch(...args: Args): Promise<TPage>;
 };
 /**
@@ -574,10 +588,44 @@ type QueryClientPluginApi = {
    */
   applyRemoteSetData(queryId: string, keyArgs: readonly unknown[], data: unknown): void;
   applyRemoteInvalidate(queryId: string, keyArgs: readonly unknown[]): void;
+  /**
+   * Apply a local-originated `setData` to the entry identified by
+   * `(queryId, keyArgs)`. The resulting plugin events fire with
+   * `isRemote: false` and `source: 'set'` — cross-tab plugins WILL
+   * rebroadcast (the write is treated as if a controller called
+   * `client.setData(...)` directly).
+   *
+   * Drops silently when the queryId is unknown, the registered query is
+   * infinite, or no local entry exists for that key. The `updater`
+   * receives the previous data (typed as `unknown` because plugins are
+   * type-erased) and returns the next.
+   *
+   * Use case: entity-normalization plugins that want to backpropagate an
+   * `entity.update(...)` patch into every query holding that entity.
+   * Mutations / optimistic updates already go through the public
+   * `client.setData` and don't need this API.
+   */
+  setEntryData(queryId: string, keyArgs: readonly unknown[], updater: (prev: unknown) => unknown): void;
   /**
    * Snapshot of currently bound entry keys for a query (by `queryId`). Empty
    * array when the query isn't registered, has no client entries, or the
    * `queryId` doesn't match any registered query.
+   *
+   * @example
+   * ```ts
+   * // Plugin sees an incoming invalidate; only echo it outward if any local
+   * // controller is actually subscribed to that key — otherwise the message
+   * // is unilateral noise.
+   * const plugin: QueryClientPlugin = {
+   *   init(api) { this.api = api },
+   *   onInvalidate(ev) {
+   *     if (ev.isRemote) return
+   *     const subscribed = this.api.subscribedKeys(ev.queryId)
+   *     if (subscribed.length === 0) return // no local subscribers → don't send
+   *     transport.send({ type: 'invalidate', queryId: ev.queryId, keyArgs: ev.keyArgs })
+   *   },
+   * }
+   * ```
    */
   subscribedKeys(queryId: string): readonly (readonly unknown[])[];
 };
@@ -596,6 +644,18 @@ type SetDataEvent = {
    * skip rebroadcast in that case — otherwise the message would echo back.
    */
   isRemote: boolean;
+  /**
+   * Origin of the write. `'set'` covers explicit `client.setData` (mutations,
+   * optimistic updates, plugin-initiated patches). `'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
+   * `isRemote === true`.
+   *
+   * Layered plugins use this to decide whether to react: cross-tab broadcasts
+   * only on `'set'`, an entity-normalization plugin observes all sources.
+   */
+  source: 'set' | 'fetch' | 'remote';
 };
 type InvalidateEvent = {
   queryId: string;
@@ -755,18 +815,30 @@ type Ctx<TDeps = AmbientDeps> = {
     deps?: Partial<TDeps>;
   }): Api;
   /**
-   * Like `child(...)` but additionally returns a `dispose()` handle so the
-   * parent can tear down this specific sub-tree early — e.g. when the user
-   * closes a details panel. The child is still disposed automatically when
-   * the parent disposes; `dispose()` is idempotent and only earlies the
-   * teardown. Useful for "openable" sub-controllers whose lifetime is driven
-   * by a user gesture rather than the parent's lifetime alone.
+   * Like `child(...)` but additionally returns a handle that lets the parent
+   * control the attached sub-tree's lifecycle independently — `dispose()`
+   * tears it down early, and `suspend()` / `resume()` freeze and thaw it.
+   * The child is still disposed automatically when the parent disposes;
+   * `dispose()` / `suspend()` / `resume()` are idempotent.
+   *
+   * `<KeepAlive controller={…}>` in `@kontsedal/olas-react` consumes the
+   * returned `{ suspend, resume }` directly — no hand-rolled `isPaused`
+   * signal needed on the child's `Api`. Useful for "openable" sub-
+   * controllers driven by a user gesture (modal, side panel, wizard).
+   *
+   * `suspend()` cascades through the attached controller's lifecycle
+   * entries: cache subscriptions pause `refetchInterval` and release the
+   * entry, effects are torn down, `onSuspend(...)` handlers fire. `resume()`
+   * re-runs effects, re-acquires cache entries (a stale entry refetches),
+   * and fires `onResume(...)`. Spec §4.1, §16.5.
    */
   attach<Props, Api>(def: ControllerDef<Props, Api>, props: Props, options?: {
     deps?: Partial<TDeps>;
   }): {
     api: Api;
     dispose: () => void;
+    suspend: () => void;
+    resume: () => void;
   };
   effect(fn: () => void | (() => void)): void;
   on<T>(emitter: Emitter<T>, handler: (value: T) => void): void;
@@ -813,4 +885,4 @@ type Root<Api> = Api & {
 };
 //#endregion
 export { Validator as $, DehydratedEntry as A, DeepPartial as B, DebugCacheEntry as C, InfiniteQuerySubscription as D, InfiniteQuerySpec as E, QuerySubscription as F, FieldArrayValue as G, FieldArrayItemErrors as H, RetryDelay as I, FormOptions as J, Form as K, RetryPolicy as L, LocalCache as M, Query as N, AsyncState as O, QuerySpec as P, ItemInitial as Q, Snapshot as R, DebugBus as S, InfiniteQuery as T, FieldArrayOptions as U, FieldArray as V, FieldArrayValidator as W, FormValidator as X, FormSchema as Y, FormValue as Z, SetDataEvent as _, Ctx as a, createEmitter as at, MutationConcurrency as b, RootOptions as c, defineScope as d, Computed as et, GcEvent as f, RegisteredQuery as g, QueryClientPluginApi as h, CtrlProps as i, Emitter as it, DehydratedState as j, AsyncStatus as k, Scope as l, QueryClientPlugin as m, ControllerDef as n, Signal as nt, Field as o, InvalidateEvent as p, FormErrors as q, CtrlApi as r, ErrorContext as rt, Root as s, AmbientDeps as t, ReadSignal as tt, ScopeOptions as u, lookupRegisteredQuery as v, DebugEvent as w, MutationSpec as x, Mutation as y, UseOptions as z };
-//# sourceMappingURL=types-emq_lZd7.d.cts.map
+//# sourceMappingURL=types-DSlDowpE.d.mts.map

package/dist/types-DSlDowpE.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-DSlDowpE.d.mts","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,8 +1,31 @@
 {
   "name": "@kontsedal/olas-core",
-  "version": "0.0.1-rc.0",
-  "description": "Olas core — controller tree, signals, queries, mutations, forms",
+  "version": "0.0.1",
+  "description": "Olas core — controller-tree state management with signals, queries, mutations, and forms. Framework-agnostic.",
+  "keywords": [
+    "olas",
+    "controller-tree",
+    "signals",
+    "reactive",
+    "state-management",
+    "query-cache",
+    "mutation",
+    "optimistic-updates",
+    "forms",
+    "ssr",
+    "framework-agnostic"
+  ],
   "license": "MIT",
+  "author": "Bohdan Kontsedal <kontsedalbohdan@gmail.com>",
+  "homepage": "https://github.com/Kontsedal/olas/tree/main/packages/core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kontsedal/olas.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/Kontsedal/olas/issues"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -40,6 +63,9 @@
   "devDependencies": {
     "@preact/signals-core": "^1.14.2"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit"

package/src/controller/instance.ts

@@ -2,7 +2,12 @@ import type { DevtoolsEmitter } from '../devtools'
 import { createEmitter, type Emitter } from '../emitter'
 import { dispatchError, type ErrorHandler } from '../errors'
 import { bindFieldDevtoolsOwner, createField } from '../forms/field'
-import { bindTreeToDevtools, createFieldArray, createForm } from '../forms/form'
+import {
+  bindTreeToDevtools,
+  bindTreeValidatorErrorReporter,
+  createFieldArray,
+  createForm,
+} from '../forms/form'
 import type {
   FieldArray,
   FieldArrayOptions,
@@ -36,6 +41,17 @@ type LifecycleEntry =
       dispose: (() => void) | null
     }
   | { kind: 'cleanup'; dispose: () => void }
+  | {
+      /**
+       * Cache subscription via `ctx.use`. Suspend/resume call the
+       * `suspend`/`resume` hooks so the underlying entry's `refetchInterval`
+       * and event listeners pause for the duration. Spec §4.1.
+       */
+      kind: 'subscription-cache'
+      dispose: () => void
+      suspend: () => void
+      resume: () => void
+    }
   | { kind: 'child'; instance: ControllerInstance }
   | { kind: 'onDispose'; fn: () => void }
   | { kind: 'onSuspend'; fn: () => void }
@@ -109,7 +125,6 @@ export class ControllerInstance {
 
   dispose(): void {
     if (this.state === 'disposed') return
-    const wasSuspended = this.state === 'suspended'
     this.state = 'disposed'
 
     for (let i = this.entries.length - 1; i >= 0; i--) {
@@ -130,8 +145,6 @@ export class ControllerInstance {
     if (__DEV__) {
       this.rootShared.devtools.emit({ type: 'controller:disposed', path: this.path })
     }
-    // Silence "unused" — `wasSuspended` may inform future logic; intentionally a no-op for now.
-    void wasSuspended
   }
 
   private disposeEntry(entry: LifecycleEntry): void {
@@ -143,6 +156,9 @@ export class ControllerInstance {
       case 'cleanup':
         entry.dispose()
         break
+      case 'subscription-cache':
+        entry.dispose()
+        break
       case 'child':
         entry.instance.dispose()
         break
@@ -172,6 +188,11 @@ export class ControllerInstance {
             entry.dispose?.()
             entry.dispose = null
             break
+          case 'subscription-cache':
+            // Pause `refetchInterval` + focus/online listeners + release the
+            // entry from this subscriber. Spec §4.1.
+            entry.suspend()
+            break
           case 'child':
             entry.instance.suspend()
             break
@@ -204,6 +225,11 @@ export class ControllerInstance {
           case 'effect':
             entry.dispose = standaloneEffect(entry.factory)
             break
+          case 'subscription-cache':
+            // Re-acquire the entry, restart `refetchInterval`, and re-check
+            // staleness (a stale entry refetches on resume — spec §4.1).
+            entry.resume()
+            break
           case 'child':
             entry.instance.resume()
             break
@@ -255,7 +281,12 @@ export class ControllerInstance {
           }
         }
         entry.factory = wrapped
-        entry.dispose = standaloneEffect(wrapped)
+        // If we're suspended, register the entry but defer activation to
+        // `resume()` — otherwise the resume loop would overwrite a live
+        // `dispose` ref (the just-activated effect), leaking it.
+        if (self.state !== 'suspended') {
+          entry.dispose = standaloneEffect(wrapped)
+        }
         self.entries.push(entry)
       },
 
@@ -271,21 +302,31 @@ export class ControllerInstance {
       use(query: any, keyOrOptions?: any): any {
         const brand = (query as { __olas?: string }).__olas
         if (brand === 'infiniteQuery') {
-          const { subscription, dispose: d } = createInfiniteUse(
+          const handle = createInfiniteUse(
             self.rootShared.queryClient,
             query as InfiniteQuery<unknown[], unknown, unknown>,
             keyOrOptions,
           )
-          self.entries.push({ kind: 'cleanup', dispose: d })
-          return subscription
+          self.entries.push({
+            kind: 'subscription-cache',
+            dispose: handle.dispose,
+            suspend: handle.suspend,
+            resume: handle.resume,
+          })
+          return handle.subscription
         }
-        const { subscription, dispose: d } = createUse(
+        const handle = createUse(
           self.rootShared.queryClient,
           query as Query<unknown[], unknown>,
           keyOrOptions,
         )
-        self.entries.push({ kind: 'cleanup', dispose: d })
-        return subscription
+        self.entries.push({
+          kind: 'subscription-cache',
+          dispose: handle.dispose,
+          suspend: handle.suspend,
+          resume: handle.resume,
+        })
+        return handle.subscription
       },
 
       mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R> {
@@ -307,7 +348,17 @@ export class ControllerInstance {
       },
 
       field<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T> {
-        const f = createField(initial, validators)
+        // Pass the reporter at construct time so the FIRST validator pass
+        // (which runs synchronously in the FieldImpl constructor's
+        // validator-effect) is covered.
+        const f = createField(initial, validators, {
+          onValidatorError: (err) => {
+            dispatchError(self.rootShared.onError, err, {
+              kind: 'effect',
+              controllerPath: self.path,
+            })
+          },
+        })
         self.entries.push({ kind: 'cleanup', dispose: () => f.dispose() })
         // Standalone fields (not inside a form) still publish field:validated
         // events. Use the controller path with field name "(field)" — the
@@ -321,7 +372,13 @@ export class ControllerInstance {
       },
 
       form<S extends FormSchema>(schema: S, options?: FormOptions<S>): Form<S> {
-        const f = createForm(schema, options)
+        const reporter = (err: unknown): void => {
+          dispatchError(self.rootShared.onError, err, {
+            kind: 'effect',
+            controllerPath: self.path,
+          })
+        }
+        const f = createForm(schema, options, { onValidatorError: reporter })
         self.entries.push({ kind: 'cleanup', dispose: () => f.dispose() })
         // Make every leaf field publish `field:validated` to the devtools bus
         // with its key path inside the form. See spec §20.9.
@@ -332,6 +389,12 @@ export class ControllerInstance {
           self.rootShared.devtools,
         )
         self.entries.push({ kind: 'cleanup', dispose: stop })
+        // Bind the reporter onto every leaf in the tree too (the form itself
+        // got it via the constructor option; nested forms/arrays inside the
+        // schema didn't, since they were constructed by the caller before
+        // ctx.form ran). Idempotent — leaves that already got the reporter
+        // via ctx.field get the same one set again.
+        bindTreeValidatorErrorReporter(f as unknown as Form<FormSchema>, reporter)
         return f
       },
 
@@ -339,7 +402,13 @@ export class ControllerInstance {
         itemFactory: (initial?: ItemInitial<I>) => I,
         options?: FieldArrayOptions<I>,
       ): FieldArray<I> {
-        const fa = createFieldArray<I>(itemFactory, options)
+        const reporter = (err: unknown): void => {
+          dispatchError(self.rootShared.onError, err, {
+            kind: 'effect',
+            controllerPath: self.path,
+          })
+        }
+        const fa = createFieldArray<I>(itemFactory, options, { onValidatorError: reporter })
         self.entries.push({ kind: 'cleanup', dispose: () => fa.dispose() })
         const stop = bindTreeToDevtools(
           fa as unknown as FieldArray<Field<unknown> | Form<FormSchema>>,
@@ -348,6 +417,10 @@ export class ControllerInstance {
           self.rootShared.devtools,
         )
         self.entries.push({ kind: 'cleanup', dispose: stop })
+        bindTreeValidatorErrorReporter(
+          fa as unknown as FieldArray<Field<unknown> | Form<FormSchema>>,
+          reporter,
+        )
         return fa
       },
 
@@ -407,7 +480,7 @@ export class ControllerInstance {
         def: ControllerDef<Props, Api>,
         props: Props,
         options?: { deps?: Partial<Record<string, unknown>> },
-      ): { api: Api; dispose: () => void } {
+      ): { api: Api; dispose: () => void; suspend: () => void; resume: () => void } {
         const segment = self.makeChildSegment(getFactory(def), getName(def))
         const override = options?.deps
         const childDeps = override !== undefined ? { ...self.deps, ...override } : self.deps
@@ -432,6 +505,33 @@ export class ControllerInstance {
               })
             }
           },
+          // Suspend / resume cascade through the child instance's lifecycle
+          // entries (same code path as `root.suspend()`); the child's state
+          // machine handles the no-op cases (suspending a disposed child,
+          // resuming an active child) on its own — no need to track an
+          // extra flag here.
+          suspend: () => {
+            if (disposed) return
+            try {
+              childInstance.suspend()
+            } catch (err) {
+              dispatchError(self.rootShared.onError, err, {
+                kind: 'effect',
+                controllerPath: self.path,
+              })
+            }
+          },
+          resume: () => {
+            if (disposed) return
+            try {
+              childInstance.resume()
+            } catch (err) {
+              dispatchError(self.rootShared.onError, err, {
+                kind: 'effect',
+                controllerPath: self.path,
+              })
+            }
+          },
         }
       },