@kontsedal/olas-core 0.0.1-rc.0

package/src/query/mutation.ts

@@ -0,0 +1,384 @@
+import type { DevtoolsEmitter } from '../devtools'
+import { dispatchError, type ErrorHandler } from '../errors'
+import { batch, type Signal, signal } from '../signals'
+import type { ReadSignal } from '../signals/types'
+import { isAbortError } from '../utils'
+import type { RetryDelay, RetryPolicy, Snapshot } from './types'
+
+/**
+ * How concurrent calls to `mutation.run(...)` interact:
+ * - `parallel` (default): every call runs concurrently.
+ * - `latest-wins`: a new call aborts any in-flight previous call (`AbortSignal` fires).
+ * - `serial`: calls queue and run one at a time in order.
+ *
+ * Spec §6.3.
+ */
+export type MutationConcurrency = 'parallel' | 'latest-wins' | 'serial'
+
+/**
+ * The configuration object passed to `ctx.mutation(spec)`. See spec §20.5 for
+ * the full lifecycle semantics. `onMutate` may return a `Snapshot` (from
+ * `query.setData(...)`) to enable automatic rollback on error.
+ */
+export type MutationSpec<V, R> = {
+  /**
+   * A short human-readable name. Surfaces in the devtools mutation log so the
+   * user sees `moveCard` instead of just the controller path. Strongly
+   * recommended in app code; cosmetic only — no runtime semantics depend on it.
+   */
+  name?: string
+  /** The actual write. Receives the user-supplied vars and an `AbortSignal`. */
+  mutate: (vars: V, signal: AbortSignal) => Promise<R>
+  /**
+   * Runs before `mutate`. Return a `Snapshot` from `query.setData(...)` to
+   * apply an optimistic update; the snapshot is rolled back on error.
+   */
+  onMutate?: (vars: V) => Snapshot | void
+  onSuccess?: (result: R, vars: V) => void
+  onError?: (err: unknown, vars: V, snapshot: Snapshot | undefined) => void
+  onSettled?: (result: R | undefined, err: unknown | undefined, vars: V) => void
+  concurrency?: MutationConcurrency
+  retry?: RetryPolicy
+  retryDelay?: RetryDelay
+}
+
+/**
+ * A running mutation. Created via `ctx.mutation(spec)` — the controller owns
+ * its lifetime. Each `run(vars)` returns a Promise; the four signals reflect
+ * the last-resolved run for UI binding.
+ *
+ * Spec §6, §20.5.
+ */
+/**
+ * Call signature for `mutation.run`:
+ *  - When `V` is `void` → no args. (`mutation.run()`)
+ *  - When `V` was not constrained (default-inferred as `unknown`) → optional
+ *    arg. Lets `ctx.mutation({ mutate: async () => 1 })` call `run()` *or*
+ *    `run(anything)` without a type error.
+ *  - Otherwise → arg required. (`mutation.run(vars)`)
+ *
+ * Defined as a variadic-tuple conditional so consumers see the right shape
+ * without writing `run(undefined as unknown as void)`.
+ */
+export type MutationRun<V, R> = (
+  ...args: unknown extends V ? [V?] : [V] extends [void] ? [] : [V]
+) => Promise<R>
+
+export type Mutation<V, R> = {
+  /** Trigger a run. Returns a Promise that resolves with the mutate result. */
+  run: MutationRun<V, R>
+  data: ReadSignal<R | undefined>
+  error: ReadSignal<unknown | undefined>
+  isPending: ReadSignal<boolean>
+  lastVariables: ReadSignal<V | undefined>
+  /** Clear `data` / `error` / `lastVariables` without aborting in-flight runs. */
+  reset(): void
+  /** Abort in-flight runs and tear down. Idempotent. Called by the parent controller's dispose. */
+  dispose(): void
+}
+
+type RunHandle = {
+  abort: AbortController
+  snapshot: Snapshot | undefined
+}
+
+type SerialEntry<V, R> = {
+  vars: V
+  resolve: (value: R) => void
+  reject: (err: unknown) => void
+}
+
+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 lastVariables: Signal<V | undefined> = signal(undefined)
+
+  private inflight = new Set<RunHandle>()
+  private serialQueue: Array<SerialEntry<V, R>> = []
+  private serialActive = false
+  private disposed = false
+
+  constructor(
+    private readonly spec: MutationSpec<V, R>,
+    private readonly onError: ErrorHandler | undefined,
+    private readonly controllerPath: readonly string[],
+    private readonly inflightCounter?: {
+      update(fn: (n: number) => number): void
+    },
+    private readonly devtools?: DevtoolsEmitter,
+  ) {}
+
+  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
+  private emit(event: { type: 'mutation:rollback' }): void
+  private emit(
+    event:
+      | { type: 'mutation:run'; vars: unknown }
+      | { type: 'mutation:success'; result: unknown }
+      | { type: 'mutation:error'; error: unknown }
+      | { type: 'mutation:rollback' },
+  ): void {
+    if (!__DEV__) return
+    if (this.devtools === undefined) return
+    const out: Record<string, unknown> = { ...event, path: this.controllerPath }
+    if (this.spec.name !== undefined) out.name = this.spec.name
+    this.devtools.emit(out as Parameters<DevtoolsEmitter['emit']>[0])
+  }
+
+  // Implementation-side signature accepts an optional `vars` (defaults to
+  // `undefined`) so call sites for `Mutation<void, R>` can call `.run()` with
+  // no args. The public type forces the right shape per `V`.
+  run = ((vars: V = undefined as V): Promise<R> => {
+    if (this.disposed) {
+      return Promise.reject(new Error('Mutation disposed'))
+    }
+    const mode = this.spec.concurrency ?? 'parallel'
+    switch (mode) {
+      case 'parallel':
+        return this.executeRun(vars)
+      case 'latest-wins':
+        // Spec §6.1: rollback the superseded run's snapshot BEFORE the new
+        // run's onMutate runs, so the new optimistic update doesn't stack on
+        // top of the obsolete one.
+        for (const handle of this.inflight) {
+          handle.abort.abort()
+          handle.snapshot?.rollback()
+          handle.snapshot = undefined
+        }
+        return this.executeRun(vars)
+      case 'serial':
+        return this.enqueueSerial(vars)
+    }
+  }) as MutationRun<V, R>
+
+  private enqueueSerial(vars: V): Promise<R> {
+    if (this.serialActive) {
+      return new Promise<R>((resolve, reject) => {
+        this.serialQueue.push({ vars, resolve, reject })
+      })
+    }
+    this.serialActive = true
+    return this.executeRun(vars).finally(() => this.advanceSerialQueue())
+  }
+
+  private advanceSerialQueue(): void {
+    const next = this.serialQueue.shift()
+    if (!next) {
+      this.serialActive = false
+      return
+    }
+    this.executeRun(next.vars).then(
+      (result) => {
+        next.resolve(result)
+        this.advanceSerialQueue()
+      },
+      (err) => {
+        next.reject(err)
+        this.advanceSerialQueue()
+      },
+    )
+  }
+
+  private async executeRun(vars: V): Promise<R> {
+    const abort = new AbortController()
+    let snapshot: Snapshot | undefined
+    try {
+      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,
+      })
+    }
+
+    const handle: RunHandle = { abort, snapshot }
+    this.inflight.add(handle)
+    this.inflightCounter?.update((n) => n + 1)
+    batch(() => {
+      this.isPending.set(true)
+      this.lastVariables.set(vars)
+    })
+
+    if (__DEV__) this.emit({ type: 'mutation:run', vars })
+
+    try {
+      const result = await raceAbort(this.runWithRetry(vars, abort.signal), abort.signal)
+      if (abort.signal.aborted || this.disposed) {
+        snapshot?.rollback()
+        throw new DOMException('Superseded', 'AbortError')
+      }
+      batch(() => {
+        this.data.set(result)
+        this.error.set(undefined)
+      })
+      if (__DEV__) this.emit({ type: 'mutation:success', result })
+      this.safeCall(() => this.spec.onSuccess?.(result, vars), 'mutation')
+      // Commit the optimistic snapshot so `hasPendingMutations` clears on the
+      // affected entry. Symmetric to the auto-rollback in the error path.
+      // Spec §6.4.
+      snapshot?.finalize()
+      this.safeCall(() => this.spec.onSettled?.(result, undefined, vars), 'mutation')
+      return result
+    } catch (err) {
+      if (isAbortError(err) || abort.signal.aborted) {
+        snapshot?.rollback()
+        // Reserve `error` signal for genuine failures.
+        throw err
+      }
+      this.error.set(err)
+      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
+      // single-consume, so an `onError` that already called `snapshot.rollback()`
+      // turns the auto-call into a no-op. Spec §6.4.
+      snapshot?.rollback()
+      this.safeCall(() => this.spec.onSettled?.(undefined, err, vars), 'mutation')
+      throw err
+    } finally {
+      this.inflight.delete(handle)
+      this.inflightCounter?.update((n) => Math.max(0, n - 1))
+      if (this.inflight.size === 0) {
+        this.isPending.set(false)
+      }
+    }
+  }
+
+  // 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
+  // happens first wins; subsequent calls (including the auto-call) no-op.
+  private wrapSnapshot(raw: Snapshot): Snapshot {
+    let consumed = false
+    return {
+      rollback: () => {
+        if (consumed) return
+        consumed = true
+        raw.rollback()
+        if (__DEV__) this.emit({ type: 'mutation:rollback' })
+      },
+      finalize: () => {
+        if (consumed) return
+        consumed = true
+        raw.finalize()
+      },
+    }
+  }
+
+  private async runWithRetry(vars: V, signal: AbortSignal): Promise<R> {
+    const retry = this.spec.retry ?? 0
+    const retryDelay = this.spec.retryDelay ?? 1000
+    let attempt = 0
+    while (true) {
+      try {
+        return await this.spec.mutate(vars, signal)
+      } catch (err) {
+        if (signal.aborted || isAbortError(err)) throw err
+        const shouldRetry = typeof retry === 'number' ? attempt < retry : retry(attempt, err)
+        if (!shouldRetry) throw err
+        const delay = typeof retryDelay === 'function' ? retryDelay(attempt) : retryDelay
+        await abortableSleep(delay, signal)
+        attempt += 1
+      }
+    }
+  }
+
+  private safeCall(fn: () => void, kind: 'mutation'): void {
+    try {
+      fn()
+    } catch (err) {
+      dispatchError(this.onError, err, {
+        kind,
+        controllerPath: this.controllerPath,
+      })
+    }
+  }
+
+  reset(): void {
+    if (this.disposed) return
+    for (const handle of this.inflight) handle.abort.abort()
+    this.serialQueue.length = 0
+    batch(() => {
+      this.data.set(undefined)
+      this.error.set(undefined)
+      this.lastVariables.set(undefined)
+      this.isPending.set(false)
+    })
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    for (const handle of this.inflight) handle.abort.abort()
+    for (const queued of this.serialQueue) {
+      queued.reject(new DOMException('Disposed', 'AbortError'))
+    }
+    this.serialQueue.length = 0
+  }
+}
+
+export function createMutation<V, R>(
+  spec: MutationSpec<V, R>,
+  onError: ErrorHandler | undefined,
+  controllerPath: readonly string[],
+  inflightCounter?: { update(fn: (n: number) => number): void },
+  devtools?: DevtoolsEmitter,
+): Mutation<V, R> {
+  return new MutationImpl<V, R>(spec, onError, controllerPath, inflightCounter, devtools)
+}
+
+/**
+ * Race a promise against an AbortSignal. If the signal fires before the
+ * promise settles, the returned promise rejects with AbortError — regardless
+ * of whether the underlying promise ever resolves. Protects against
+ * misbehaving mutate fns that ignore their signal.
+ */
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) {
+    return Promise.reject(new DOMException('Aborted', 'AbortError'))
+  }
+  return new Promise<T>((resolve, reject) => {
+    let settled = false
+    const onAbort = () => {
+      if (settled) return
+      settled = true
+      reject(new DOMException('Aborted', 'AbortError'))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (v) => {
+        if (settled) return
+        settled = true
+        signal.removeEventListener('abort', onAbort)
+        resolve(v)
+      },
+      (e) => {
+        if (settled) return
+        settled = true
+        signal.removeEventListener('abort', onAbort)
+        reject(e)
+      },
+    )
+  })
+}
+
+function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'))
+      return
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      reject(new DOMException('Aborted', 'AbortError'))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}

package/src/query/plugin.ts

@@ -0,0 +1,135 @@
+/**
+ * `QueryClientPlugin` — a slot for layered cache concerns (cross-tab sync,
+ * server-push patches, persistence-like layers) that need to observe
+ * `setData` / `invalidate` / `gc` and apply remote writes back into the
+ * cache without re-triggering their own outbound side-effects.
+ *
+ * Plugins are installed via `RootOptions.plugins[]`; lifecycle is bound to
+ * the root's `QueryClient` (`init` is called once after construction;
+ * `dispose` is called from `QueryClient.dispose`).
+ *
+ * SPEC §13.2.
+ */
+
+/**
+ * Surface the plugin gets at `init` time. Used to push remote-originated
+ * cache writes through the normal `setData`/`invalidate` paths without
+ * triggering the plugin's own outbound hooks for those writes (the inbound
+ * writes are marked `isRemote: true` and rebroadcast must be skipped).
+ *
+ * `subscribedKeys(queryId)` walks the per-root entry registry for the
+ * matching query and returns every bound entry's `keyArgs`. Cross-tab
+ * plugins use this to scope outbound traffic (e.g. only echo invalidations
+ * for queries the local tab actually has entries for).
+ */
+export type QueryClientPluginApi = {
+  /**
+   * Apply a remote snapshot. The plugin's own `onSetData` IS fired for the
+   * resulting cache write, but the event carries `isRemote: true` — plugins
+   * MUST skip rebroadcast in that case.
+   */
+  applyRemoteSetData(queryId: string, keyArgs: readonly unknown[], data: unknown): void
+  applyRemoteInvalidate(queryId: string, keyArgs: readonly 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.
+   */
+  subscribedKeys(queryId: string): readonly (readonly unknown[])[]
+}
+
+export type SetDataEvent = {
+  queryId: string
+  keyArgs: readonly unknown[]
+  data: unknown
+  /**
+   * `'data'` for regular queries, `'infinite'` for paginated queries.
+   * Cross-tab plugins skip `'infinite'` in v1 — page-array payloads are
+   * too heavy to be a safe default.
+   */
+  kind: 'data' | 'infinite'
+  /**
+   * True iff this write originated from `applyRemoteSetData`. Plugins MUST
+   * skip rebroadcast in that case — otherwise the message would echo back.
+   */
+  isRemote: boolean
+}
+
+export type InvalidateEvent = {
+  queryId: string
+  keyArgs: readonly unknown[]
+  kind: 'data' | 'infinite'
+  isRemote: boolean
+}
+
+export type GcEvent = {
+  queryId: string
+  keyArgs: readonly unknown[]
+  kind: 'data' | 'infinite'
+}
+
+/**
+ * Plugin contract. Every hook is optional. Hooks are wrapped in try/catch
+ * by `QueryClient`; thrown exceptions are routed through the root's
+ * `onError` handler with `kind: 'plugin'`.
+ */
+export type QueryClientPlugin = {
+  /**
+   * Called once after the `QueryClient` is constructed. Use it to wire up
+   * transport listeners and capture the `QueryClientPluginApi`.
+   */
+  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. */
+  dispose?(): void
+}
+
+/**
+ * Internal helper — fetch the `queryId` from a query's spec without
+ * peeking into private types. Returns `undefined` for queries that didn't
+ * declare a `queryId`; plugin events are then skipped (a plugin can't route
+ * by name without one).
+ */
+export function readQueryId(query: { readonly __spec: { queryId?: string } }): string | undefined {
+  return query.__spec.queryId
+}
+
+/**
+ * Shape of values stored in the `queryId → Query` registry. Either a
+ * regular `Query` or an `InfiniteQuery`, both branded by `__olas`.
+ */
+export type RegisteredQuery = {
+  readonly __olas: 'query' | 'infiniteQuery'
+  readonly __spec: { queryId?: string; crossTab?: boolean }
+}
+
+const queryRegistry = new Map<string, RegisteredQuery>()
+
+/**
+ * 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).
+ */
+export function registerQueryById(queryId: string, query: RegisteredQuery): void {
+  queryRegistry.set(queryId, query)
+}
+
+/**
+ * Look up a query by its declared `queryId`. Returns `undefined` when no
+ * query with that id has been defined yet (e.g. the module isn't imported
+ * in the receiving tab).
+ */
+export function lookupRegisteredQuery(queryId: string): RegisteredQuery | undefined {
+  return queryRegistry.get(queryId)
+}
+
+/**
+ * Test-only — drop a registered entry. Lets tests defining the same
+ * `queryId` across cases avoid bleed. Not exported from `@kontsedal/olas-core`.
+ */
+export function _unregisterQueryById(queryId: string): void {
+  queryRegistry.delete(queryId)
+}

package/src/query/types.ts

@@ -0,0 +1,168 @@
+import type { ReadSignal } from '../signals/types'
+
+/** Lifecycle phase of an async resource. */
+export type AsyncStatus = 'idle' | 'pending' | 'success' | 'error'
+
+/**
+ * The eight 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.
+ * - `isLoading` — true only on the first pending fetch (no `data` yet).
+ * - `isFetching` — true on any pending fetch.
+ * - `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.
+ *
+ * Actions:
+ * - `refetch()` — force a fetch; resolves with the result.
+ * - `reset()` — clear `error` + `status` without re-fetching.
+ * - `firstValue()` — resolves on the first success after subscribe.
+ */
+export type AsyncState<T> = {
+  data: ReadSignal<T | undefined>
+  error: ReadSignal<unknown | undefined>
+  status: ReadSignal<AsyncStatus>
+  isLoading: ReadSignal<boolean>
+  isFetching: ReadSignal<boolean>
+  isStale: ReadSignal<boolean>
+  lastUpdatedAt: ReadSignal<number | undefined>
+  hasPendingMutations: ReadSignal<boolean>
+
+  refetch: () => Promise<T>
+  reset: () => void
+  firstValue: () => Promise<T>
+}
+
+/**
+ * Returned by `query.setData(...)` or `localCache.setData(...)`. Used by
+ * `mutation.onMutate` for optimistic-update rollback (spec §6.4).
+ *
+ * - `rollback()` restores the previous data state (and clears the
+ *   "pending mutation" flag on the entry if no other snapshots are live).
+ * - `finalize()` commits the snapshot as the new truth — no rollback,
+ *   `hasPendingMutations` clears once all live snapshots on the entry
+ *   are finalized or rolled back. The mutation runner calls this on
+ *   success; user code rarely needs to.
+ *
+ * Both are idempotent and mutually exclusive (calling one disables the
+ * other). Safe to call after the owning entry has been disposed.
+ */
+export type Snapshot = {
+  rollback: () => void
+  finalize: () => void
+}
+
+/**
+ * A cache owned by one controller — no sharing across the tree. Returned by
+ * `ctx.cache(fetcher, options?)`. Disposed automatically with the controller.
+ */
+export type LocalCache<T> = AsyncState<T> & {
+  /** Mark stale and trigger an immediate refetch. */
+  invalidate(): void
+  /** Patch the current data. Returns a `Snapshot` for rollback. */
+  setData(updater: (prev: T | undefined) => T): Snapshot
+  /** Idempotent — also called when the owning controller disposes. */
+  dispose(): void
+}
+
+/** One entry inside a `DehydratedState`. */
+export type DehydratedEntry = {
+  key: readonly unknown[]
+  data: unknown
+  lastUpdatedAt: number
+}
+
+/**
+ * SSR-serializable snapshot of a root's `QueryClient`. Produced by
+ * `root.dehydrate()` on the server; consumed by
+ * `createRoot(def, { hydrate: state })` on the client. Spec §15, §20.9.
+ */
+export type DehydratedState = {
+  version: 1
+  entries: DehydratedEntry[]
+}
+
+/**
+ * Retry policy for queries and mutations. A number is a max-attempt count
+ * (default backoff). A function decides per-attempt (return `true` to retry).
+ */
+export type RetryPolicy = number | ((attempt: number, error: unknown) => boolean)
+
+/** Backoff in ms. A number is constant delay; a function computes per-attempt. */
+export type RetryDelay = number | ((attempt: number) => number)
+
+/**
+ * Per-fetch context: the `AbortSignal` to honor + the root's `deps`. Passed
+ * as the first argument to every `QuerySpec.fetcher` invocation so module-
+ * level queries can reach their dependencies without resorting to globals.
+ */
+export type FetchCtx = {
+  signal: AbortSignal
+  deps: import('../controller/types').AmbientDeps
+}
+
+/**
+ * Configuration passed to `defineQuery({ ... })`. The `Args` tuple is what
+ * callers pass as cache keys and to the fetcher. Spec §20.4.
+ *
+ * The fetcher's first argument is a `FetchCtx` (signal + deps); positional
+ * cache args come after. This shape lets module-scoped queries read
+ * `ctx.deps.api` etc. — no `setApiForQuery(api)` module-level capture needed.
+ */
+export type QuerySpec<Args extends unknown[], T> = {
+  key: (...args: Args) => unknown[]
+  fetcher: (ctx: FetchCtx, ...args: Args) => Promise<T>
+  staleTime?: number
+  gcTime?: number
+  refetchInterval?: number
+  refetchOnWindowFocus?: boolean
+  refetchOnReconnect?: boolean
+  keepPreviousData?: boolean
+  retry?: RetryPolicy
+  retryDelay?: RetryDelay
+  /**
+   * Stable identifier used by `QueryClientPlugin`s (e.g. `@kontsedal/olas-cross-tab`)
+   * to locate the same query across tabs / processes / persistence layers.
+   * REQUIRED for queries with `crossTab: true`. SPEC §13.2.
+   *
+   * Don't auto-derive from `fetcher.name` or argument hashing — both are
+   * fragile under minification.
+   */
+  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.
+   */
+  crossTab?: boolean
+}
+
+/**
+ * A module-scoped shared query handle. Bind a subscriber via
+ * `ctx.use(query, () => [...args])`. The same `Query` value can be used by
+ * many controllers across many roots — each root has its own cache.
+ */
+export type Query<Args extends unknown[], T> = {
+  readonly __olas: 'query'
+  /** Mark a specific keyed entry stale + trigger refetch if any subscribers. */
+  invalidate(...args: Args): void
+  /** Mark every keyed entry stale + trigger refetch on all subscribers. */
+  invalidateAll(): void
+  /** Patch the current data for a specific key. Returns a `Snapshot` for rollback. */
+  setData(...args: [...Args, updater: (prev: T | undefined) => T]): Snapshot
+  /** 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>
+
+/**
+ * Options passed to `ctx.use(query, opts)` to control the subscription
+ * (reactive key, enabled-gating). The `key` thunk reads signals — re-evaluating
+ * when they change re-keys the subscription.
+ */
+export type UseOptions<Args extends readonly unknown[]> = {
+  key?: () => Args
+  enabled?: () => boolean
+}