@svadmin/core 0.50.0 → 0.52.0

package/src/infinite-query.svelte.ts

@@ -0,0 +1,228 @@
+import { createInfiniteQuery, type InfiniteData, type InfiniteQueryObserverBaseResult, type QueryObserverResult,
+  type RefetchOptions, type FetchNextPageOptions, type FetchPreviousPageOptions } from '@tanstack/svelte-query';
+import { tick } from 'svelte';
+import { Type } from '@sinclair/typebox';
+import { definedOptions } from './defined-options';
+import { getAdminOptions } from './options.svelte';
+import { useParsed } from './useParsed.svelte';
+import { captureContractContext, type ContractOptions } from './contract-context.svelte';
+import { createOvertimeTracker, createLiveSubscription, type NotificationConfig, type OvertimeOptions,
+  type LiveSubscriptionParams } from './hook-utils.svelte';
+import { HttpError, type BaseRecord, type GetListResult, type Pagination, type Sort, type Filter, type KnownResources } from './types';
+import { decodeBaseRecord, decodeListResult, rejectProviderResponse, type RecordDecoder } from './record-decoder';
+import { captureQueryProvider, snapshotListParams } from './query-snapshot';
+import type { LiveMode, LiveEvent } from './live.svelte';
+import type { QueryKey } from './query-keys';
+import { snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+import {
+  createQuerySession, createQueryResultView, pendingQueryResult, querySessionError, supersededQuerySession,
+} from './query-session.svelte';
+
+export interface UseInfiniteListOptions extends ContractOptions {
+  resource?: KnownResources;
+  pagination?: Pagination;
+  sorters?: Sort[];
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+  queryOptions?: { staleTime?: number; enabled?: boolean };
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+  liveMode?: LiveMode;
+  onLiveEvent?: (event: LiveEvent) => void;
+  overtimeOptions?: OvertimeOptions;
+}
+
+const dataSchema = Type.Object({
+  pages: Type.Array(Type.Unknown(), { minItems: 1 }),
+  pageParams: Type.Array(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }), { minItems: 1 }),
+}, { additionalProperties: false });
+const flagsSchema = Type.Object({
+  hasNextPage: Type.Boolean(), hasPreviousPage: Type.Boolean(),
+  isFetchNextPageError: Type.Boolean(), isFetchingNextPage: Type.Boolean(),
+  isFetchPreviousPageError: Type.Boolean(), isFetchingPreviousPage: Type.Boolean(),
+}, { additionalProperties: false });
+
+type Pages<T extends BaseRecord> = InfiniteData<GetListResult<T>, number>;
+type InfiniteOutcome<T> =
+  | { status: 'pending'; data: undefined; error: null; isPending: true; isError: false; isSuccess: false;
+      isLoading: boolean; isLoadingError: false; isRefetchError: false; isPlaceholderData: false;
+      isFetchNextPageError: false; isFetchPreviousPageError: false }
+  | { status: 'success'; data: T; error: null; isPending: false; isError: false; isSuccess: true;
+      isLoading: false; isLoadingError: false; isRefetchError: false; isPlaceholderData: boolean;
+      isFetchNextPageError: false; isFetchPreviousPageError: false }
+  | { status: 'error'; data: undefined; error: unknown; isPending: false; isError: true; isSuccess: false;
+      isLoading: false; isLoadingError: true; isRefetchError: false; isPlaceholderData: false;
+      isFetchNextPageError: boolean; isFetchPreviousPageError: boolean }
+  | ({ status: 'error'; data: T; error: unknown; isPending: false; isError: true; isSuccess: false;
+      isLoading: false; isLoadingError: false; isPlaceholderData: false } & (
+      | { isRefetchError: true; isFetchNextPageError: false; isFetchPreviousPageError: false }
+      | { isRefetchError: false; isFetchNextPageError: true; isFetchPreviousPageError: false }
+      | { isRefetchError: false; isFetchNextPageError: false; isFetchPreviousPageError: true }
+    ));
+
+/** The installed observer retains data on paging errors without setting isRefetchError. */
+export type InfiniteListResult<T extends BaseRecord> =
+  Omit<InfiniteQueryObserverBaseResult<Pages<T>, unknown>, keyof InfiniteOutcome<Pages<T>> | 'refetch' | 'fetchNextPage' | 'fetchPreviousPage'>
+  & InfiniteOutcome<Pages<T>> & {
+    refetch: (settings?: RefetchOptions) => Promise<InfiniteListResult<T>>;
+    fetchNextPage: (settings?: FetchNextPageOptions) => Promise<InfiniteListResult<T>>;
+    fetchPreviousPage: (settings?: FetchPreviousPageOptions) => Promise<InfiniteListResult<T>>;
+  };
+
+export function decodeInfiniteResult<T extends BaseRecord>(input: unknown, decode: RecordDecoder<T>): InfiniteData<GetListResult<T>, number> {
+  try {
+    const candidate = snapshotPlainData(input);
+    if (checkExact(dataSchema, candidate) && candidate.pages.length === candidate.pageParams.length &&
+      candidate.pageParams.every((page, index) => page === index + 1)) {
+      return { pages: candidate.pages.map(page => decodeListResult(page, decode)), pageParams: [...candidate.pageParams] };
+    }
+  } catch {
+    // Malformed pages and reflection errors cannot become a typed page collection.
+  }
+  return rejectProviderResponse();
+}
+
+export function useInfiniteList(options: UseInfiniteListOptions = {}) {
+  return createInfiniteListQuery(options, () => decodeBaseRecord);
+}
+
+export function createInfiniteListQuery<TData extends BaseRecord>(
+  options: UseInfiniteListOptions, getDecoder: () => RecordDecoder<TData>,
+) {
+  const context = captureContractContext(options);
+  const parsed = useParsed();
+  const adminOptions = getAdminOptions();
+  type Data = Pages<TData>;
+  type Result = InfiniteListResult<TData>;
+  const session = createQuerySession(context, () => {
+    const resource = options.resource ?? parsed.resource ?? '';
+    const captured = captureQueryProvider(context, {
+      resource, ...definedOptions({ dataProviderName: options.dataProviderName, contract: options.contract, meta: options.meta }),
+    });
+    const params = snapshotListParams({
+      resource, ...definedOptions({
+        pagination: { ...options.pagination, current: 1, pageSize: options.pagination?.pageSize ?? 10 },
+        sorters: options.sorters, filters: options.filters, meta: captured.meta,
+      }),
+    });
+    return {
+      resource, captured, params, decode: getDecoder(),
+      queryKey: context.queryKeys(resource, options.dataProviderName).data.infiniteList(resource, { ...params, source: captured.source }),
+      enabled: options.queryOptions?.enabled ?? true,
+      staleTime: options.queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime,
+      successNotification: options.successNotification, errorNotification: options.errorNotification,
+    };
+  });
+  type Origin = typeof session.options;
+  const raw = createInfiniteQuery<GetListResult<TData>, unknown, Data, QueryKey, number>(() => {
+    const origin = session.options;
+    return {
+      queryKey: origin.queryKey, initialPageParam: 1,
+      queryFn: ({ pageParam }) => session.run(origin, async () => {
+        if (typeof pageParam !== 'number' || !Number.isSafeInteger(pageParam) || pageParam < 1) {
+          throw new HttpError('Invalid page number', 422, undefined, { code: 'INVALID_RESOURCE_INPUT' });
+        }
+        const result = await origin.captured.provider.getList(snapshotListParams({
+          ...origin.params, pagination: { ...origin.params.pagination, current: pageParam },
+        }));
+        return decodeListResult(result, origin.decode);
+      }),
+      getNextPageParam: (_last, pages, _lastParam, pageParams) => {
+        if (!session.sessionCurrent(origin)) return undefined;
+        try {
+          const checked = decodeInfiniteResult({ pages, pageParams }, origin.decode);
+          const last = checked.pages.at(-1);
+          if (!last || last.data.length === 0 || checked.pages.reduce((total, page) => total + page.data.length, 0) >= last.total) return undefined;
+          const next = checked.pages.length + 1;
+          return Number.isSafeInteger(next) ? next : undefined;
+        } catch {
+          return undefined;
+        }
+      },
+      enabled: origin.enabled && origin.auth.available,
+      ...definedOptions({ staleTime: origin.staleTime }),
+    };
+  });
+
+  type Operations = {
+    refetch: (settings?: RefetchOptions) => Promise<Result>;
+    fetchNextPage: (settings?: FetchNextPageOptions) => Promise<Result>;
+    fetchPreviousPage: (settings?: FetchPreviousPageOptions) => Promise<Result>;
+  };
+  function pending(operations: Operations): Result {
+    return {
+      ...pendingQueryResult<Data, Operations['refetch']>(operations.refetch), ...operations,
+      hasNextPage: false, hasPreviousPage: false,
+      isFetchNextPageError: false, isFetchingNextPage: false,
+      isFetchPreviousPageError: false, isFetchingPreviousPage: false,
+    };
+  }
+  function project(origin: Origin, result: QueryObserverResult<Data, unknown>): Result {
+    async function run(request: () => Promise<QueryObserverResult<Data, unknown>>): Promise<Result> {
+      if (!session.current(origin)) return pending(operations);
+      await tick();
+      if (!session.current(origin)) return pending(operations);
+      try {
+        return project(origin, await request());
+      } catch (error) {
+        throw session.current(origin) ? querySessionError(error) : supersededQuerySession();
+      }
+    }
+    const operations: Operations = {
+      refetch: settings => run(() => raw.refetch(settings)),
+      fetchNextPage: settings => run(() => raw.fetchNextPage(settings)),
+      fetchPreviousPage: settings => run(() => raw.fetchPreviousPage(settings)),
+    };
+    if (!session.current(origin)) return pending(operations);
+    const state = session.client.getQueryState(origin.queryKey);
+    if (!state || state.data !== result.data || state.error !== result.error) return pending(operations);
+    try {
+      // Refetch's base type omits pagination fields that the installed observer returns.
+      const flags: unknown = Object.fromEntries(Object.keys(flagsSchema.properties).map(key => [key, Reflect.get(result, key)]));
+      if (!checkExact(flagsSchema, flags)) return rejectProviderResponse();
+      const failureReason = result.failureReason === null ? null : querySessionError(result.failureReason);
+      const rawData: unknown = result.data;
+      if (result.status === 'success') {
+        const data = decodeInfiniteResult(rawData, origin.decode);
+        if (!session.current(origin)) return pending(operations);
+        return { ...result, ...flags, ...operations, data, failureReason, isFetchNextPageError: false, isFetchPreviousPageError: false };
+      }
+      if (result.status === 'error') {
+        const base = { ...result, ...flags, ...operations, error: querySessionError(result.error), failureReason };
+        if (rawData === undefined) return { ...base, data: undefined, isLoadingError: true, isRefetchError: false };
+        const data = decodeInfiniteResult(rawData, origin.decode);
+        if (!session.current(origin)) return pending(operations);
+        if (flags.isFetchNextPageError) return {
+          ...base, data, isLoadingError: false, isRefetchError: false, isFetchNextPageError: true, isFetchPreviousPageError: false,
+        };
+        if (flags.isFetchPreviousPageError) return {
+          ...base, data, isLoadingError: false, isRefetchError: false, isFetchNextPageError: false, isFetchPreviousPageError: true,
+        };
+        return { ...base, data, isLoadingError: false, isRefetchError: true, isFetchNextPageError: false, isFetchPreviousPageError: false };
+      }
+      return { ...result, ...flags, ...operations, failureReason, isFetchNextPageError: false, isFetchPreviousPageError: false };
+    } catch (error) {
+      if (!session.current(origin)) return pending(operations);
+      return {
+        ...pending(operations), status: 'error', data: undefined, error: querySessionError(error),
+        isError: true, isPending: false, isLoading: false, isLoadingError: true, isRefetchError: false,
+        isSuccess: false, isPlaceholderData: false, isFetchNextPageError: false, isFetchPreviousPageError: false,
+      };
+    }
+  }
+  session.observe(origin => project(origin, raw));
+  const query = createQueryResultView(() => project(session.options, raw));
+  const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
+  createLiveSubscription((): LiveSubscriptionParams => ({
+    resource: options.resource ?? parsed.resource ?? '',
+    ...definedOptions({
+      liveProvider: context.liveProvider, liveMode: options.liveMode ?? adminOptions.liveMode,
+      contract: options.contract, onLiveEvent: options.onLiveEvent, onGlobalLiveEvent: adminOptions.onLiveEvent,
+      dataProviderName: options.dataProviderName,
+    }),
+    enabled: options.queryOptions?.enabled ?? true,
+  }));
+  return { query, get overtime() { return overtime; } };
+}

package/src/invalidation-contract.ts

@@ -0,0 +1,26 @@
+import { Type } from '@sinclair/typebox';
+import { snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+import { HttpError } from './types';
+
+const schema = Type.Object({
+  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  invalidates: Type.Optional(Type.Union([
+    Type.Literal(false), Type.Literal('all'),
+    Type.Array(Type.Union([
+      Type.Literal('list'), Type.Literal('many'),
+      Type.Literal('detail'), Type.Literal('resourceAll'),
+    ])),
+  ])),
+}, { additionalProperties: false });
+
+/** Invalid input must not broaden the cache scope or execute submitted accessors. */
+export function snapshotInvalidationParams(value: unknown) {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(schema, candidate)) return candidate;
+  } catch {
+    // Do not expose cache input values or reflection failures.
+  }
+  throw new HttpError('Invalid refresh input', 422, undefined, { code: 'INVALID_RESOURCE_INPUT' });
+}

package/src/live-sse.ts

@@ -1,15 +1,8 @@
-/**
- * SSE (Server-Sent Events) LiveProvider
- *
- * Connects to an SSE endpoint and dispatches LiveEvents to subscribers.
- * The server should emit events as JSON matching the LiveEvent shape:
- *   data: { "type": "INSERT", "resource": "posts", "payload": {...} }
- *
- * Optionally, named SSE events can be used:
- *   event: posts
- *   data: { "type": "INSERT", "payload": {...} }
- */
-import type { LiveProvider, LiveEvent } from './live.svelte';
+import type { LiveProvider } from './live.svelte';
+import { createLiveSubscribers, decodeLiveMessage, notifyLiveObserver, readLiveOptions, captureLiveObserver } from './live-transport';
+import { Type } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
 
 export interface SSELiveProviderOptions {
   url: string;
@@ -18,137 +11,108 @@ export interface SSELiveProviderOptions {
   onError?: (event: Event) => void;
 }
 
-export function createSSELiveProvider(options: SSELiveProviderOptions): LiveProvider & { disconnect: () => void; getStatus: () => 'connecting' | 'connected' | 'disconnected' } {
-  const { url, eventSourceInit } = options;
+const initSchema = Type.Object({ withCredentials: Type.Optional(Type.Boolean()) }, { additionalProperties: false });
+function checkedInit(value: unknown) {
+  if (value === undefined) return undefined;
+  try {
+    const init = snapshotPlainData(value);
+    if (checkExact(initSchema, init)) return init;
+  } catch { /* Configuration reflection cannot leak into connection callbacks. */ }
+  throw new TypeError('Invalid SSE initialization');
+}
+
+function configuration(options: unknown) {
+  const input = readLiveOptions(options, ['url', 'eventSourceInit', 'onOpen', 'onError']);
+  const url = input['url'];
+  if (typeof url !== 'string' || !url) throw new TypeError('Invalid SSE live options');
+  const eventSourceInit = checkedInit(input['eventSourceInit']);
+  const onOpen = captureLiveObserver(input['onOpen']);
+  const onError = captureLiveObserver(input['onError']);
+  return { url, eventSourceInit, onOpen, onError };
+}
 
-  type Callback = (event: LiveEvent) => void;
-  const subscribers = new Map<string, Set<Callback>>();
-  let eventSource: EventSource | null = null;
+/**
+ * Named events may omit resource, but must include type and payload.
+ * Reserved message/open/error resources use default full-envelope messages.
+ * Per-subscription liveParams are unsupported and rejected.
+ */
+export function createSSELiveProvider(options: SSELiveProviderOptions): LiveProvider & {
+  disconnect: () => void; getStatus: () => 'connecting' | 'connected' | 'disconnected';
+} {
+  const { url, eventSourceInit, onOpen, onError } = configuration(options);
+  const subscribers = createLiveSubscribers();
+  let source: EventSource | null = null;
   let status: 'connecting' | 'connected' | 'disconnected' = 'disconnected';
   const namedListeners = new Map<string, EventListener>();
 
-  function connect() {
-    if (eventSource) return;
-    if (typeof EventSource === 'undefined') return;
-
-    status = 'connecting';
-    eventSource = new EventSource(url, eventSourceInit);
-
-    eventSource.onopen = () => {
-      status = 'connected';
-      options.onOpen?.();
-    };
-
-    eventSource.onmessage = (msgEvent) => {
-      dispatchEvent(msgEvent.data);
-    };
-
-    eventSource.onerror = (event) => {
-      if (eventSource?.readyState === EventSource.CLOSED) {
-        status = 'disconnected';
-      }
-      options.onError?.(event);
-    };
-
-    for (const resource of subscribers.keys()) {
-      if (resource !== '*') {
-        addNamedListener(resource);
-      }
-    }
-  }
-
   function addNamedListener(resource: string) {
-    if (!eventSource || namedListeners.has(resource)) return;
-    const listener = ((event: MessageEvent) => {
-      try {
-        const parsed = JSON.parse(event.data);
-        const liveEvent: LiveEvent = {
-          type: parsed.type,
-          resource: parsed.resource ?? resource,
-          payload: parsed.payload ?? parsed,
-        };
-        notifySubscribers(liveEvent);
-      } catch {
-        // ignore non-JSON
-      }
-    }) as EventListener;
+    const connection = source;
+    if (!connection || ['*', 'message', 'open', 'error'].includes(resource) || namedListeners.has(resource)) return;
+    const current = () => source === connection;
+    const listener: EventListener = event => {
+      if (!current() || namedListeners.get(resource) !== listener || !(event instanceof MessageEvent)) return;
+      const data: unknown = event.data;
+      const decoded = decodeLiveMessage(data, resource);
+      if (decoded) subscribers.notify(decoded, current);
+    };
     namedListeners.set(resource, listener);
-    eventSource.addEventListener(resource, listener);
-  }
-
-  function removeNamedListener(resource: string) {
-    const listener = namedListeners.get(resource);
-    if (!listener) return;
-    if (eventSource) {
-      eventSource.removeEventListener(resource, listener);
-    }
-    namedListeners.delete(resource);
-  }
-
-  function dispatchEvent(data: string) {
-    try {
-      const event: LiveEvent = JSON.parse(data);
-      if (event.type && event.resource) {
-        notifySubscribers(event);
-      }
-    } catch {
-      // ignore non-JSON
-    }
-  }
-
-  function notifySubscribers(event: LiveEvent) {
-    const callbacks = subscribers.get(event.resource);
-    if (callbacks) {
-      for (const cb of callbacks) cb(event);
-    }
-    const wildcardCallbacks = subscribers.get('*');
-    if (wildcardCallbacks) {
-      for (const cb of wildcardCallbacks) cb(event);
-    }
+    connection.addEventListener(resource, listener);
   }
-
   function disconnect() {
-    if (eventSource) {
-      eventSource.close();
-      eventSource = null;
-    }
+    const previous = source;
+    source = null;
     status = 'disconnected';
+    if (previous) {
+      for (const [resource, listener] of namedListeners) previous.removeEventListener(resource, listener);
+      previous.close();
+    }
     namedListeners.clear();
   }
-
+  function connect() {
+    if (source || subscribers.empty || typeof EventSource === 'undefined') return;
+    status = 'connecting';
+    let connection: EventSource;
+    try { connection = new EventSource(url, eventSourceInit); }
+    catch { status = 'disconnected'; return; }
+    source = connection;
+    const current = () => source === connection;
+    connection.onopen = event => {
+      if (!current() || event instanceof MessageEvent) return;
+      status = 'connected';
+      notifyLiveObserver(onOpen, undefined);
+    };
+    connection.onmessage = message => {
+      if (!current()) return;
+      const data: unknown = message.data;
+      const event = decodeLiveMessage(data);
+      if (event) subscribers.notify(event, current);
+    };
+    connection.onerror = event => {
+      if (!current() || event instanceof MessageEvent) return;
+      if (connection.readyState === EventSource.CLOSED) disconnect();
+      else status = 'connecting';
+      notifyLiveObserver(onError, event);
+    };
+    for (const channel of subscribers.channels()) addNamedListener(channel.resource);
+  }
   return {
-    subscribe({ resource, callback }) {
-      let isNewResource = false;
-      if (!subscribers.has(resource)) {
-        subscribers.set(resource, new Set());
-        isNewResource = true;
-      }
-      subscribers.get(resource)?.add(callback);
-
-      if (!eventSource && typeof EventSource !== 'undefined') {
-        connect();
-      }
-      if (eventSource && resource !== '*' && isNewResource) {
-        addNamedListener(resource);
-      }
-
+    subscribe(params) {
+      const entry = subscribers.add(params, false);
+      if (!source) connect();
+      else if (entry.first) addNamedListener(entry.resource);
+      let active = true;
       return () => {
-        const callbacks = subscribers.get(resource);
-        if (callbacks) {
-          callbacks.delete(callback);
-          if (callbacks.size === 0) {
-            subscribers.delete(resource);
-            removeNamedListener(resource);
-          }
+        if (!active) return;
+        active = false;
+        if (entry.remove()) {
+          const listener = namedListeners.get(entry.resource);
+          if (source && listener) source.removeEventListener(entry.resource, listener);
+          namedListeners.delete(entry.resource);
         }
-        if (subscribers.size === 0) disconnect();
+        if (subscribers.empty) disconnect();
       };
     },
-
     disconnect,
-
-    getStatus() {
-      return status;
-    },
+    getStatus: () => status,
   };
 }

package/src/live-subscription.svelte.ts

@@ -0,0 +1,130 @@
+import { untrack } from 'svelte';
+import type { QueryClient } from '@tanstack/svelte-query';
+import { Type } from '@sinclair/typebox';
+import { captureAdminContext } from './context.svelte';
+import { contractKey, type ResourceContract } from './resource-contract';
+import { captureQueryProvider } from './query-snapshot';
+import { decodeBaseRecord } from './record-decoder';
+import { invalidateOwnedQueries } from './query-invalidation';
+import { snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+import { definedOptions } from './defined-options';
+import { captureLiveObserver, notifyLiveObserver, snapshotLiveEvent } from './live-transport';
+import type { LiveEvent, LiveMode, LiveProvider } from './live.svelte';
+import { captureAuthLiveScope } from './auth-hooks.svelte';
+
+export interface LiveSubscriptionParams {
+  resource: string;
+  liveProvider?: LiveProvider;
+  liveMode?: LiveMode;
+  onLiveEvent?: (event: LiveEvent) => void;
+  /** @internal Keeps the application-wide observer independent from the local observer. */
+  onGlobalLiveEvent?: (event: LiveEvent) => void;
+  liveParams?: Record<string, unknown>;
+  enabled?: boolean;
+  dataProviderName?: string;
+  contract?: ResourceContract;
+}
+
+const configSchema = Type.Object({
+  resource: Type.String({ minLength: 1 }),
+  liveMode: Type.Union([Type.Literal('auto'), Type.Literal('manual'), Type.Literal('off')]),
+  enabled: Type.Boolean(),
+  dataProviderName: Type.Optional(Type.String({ minLength: 1 })),
+  liveParams: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+}, { additionalProperties: false });
+
+/** One subscription owns its event copies, cleanup and exact cache source. */
+export function createCheckedLiveSubscription(paramsFn: () => LiveSubscriptionParams, client?: QueryClient): void {
+  const context = captureAdminContext();
+  const state = $derived.by(() => {
+    try {
+      const params = paramsFn();
+      const candidate: unknown = snapshotPlainData(definedOptions({
+        resource: params.resource, liveMode: params.liveMode === undefined ? 'off' : params.liveMode,
+        enabled: params.enabled === undefined ? true : params.enabled,
+        dataProviderName: params.dataProviderName, liveParams: params.liveParams,
+      }));
+      if (!checkExact(configSchema, candidate) || !candidate.enabled || candidate.liveMode === 'off') return undefined;
+      const authScope = captureAuthLiveScope(context.authProvider);
+      if (!authScope.available) return undefined;
+      const provider = params.liveProvider;
+      const subscribe = provider?.subscribe;
+      if (!provider || typeof subscribe !== 'function') return undefined;
+      const definition = context.resources.find(resource => resource.name === candidate.resource || resource.identifier === candidate.resource);
+      const contract = params.contract ?? definition?.contract;
+      const contractId = contract === undefined ? undefined : contractKey(contract);
+      if (contract && contract.name !== candidate.resource) return undefined;
+      const providerName = candidate.dataProviderName ?? definition?.provider?.dataProviderName ?? definition?.meta?.dataProviderName ?? 'default';
+      if (typeof providerName !== 'string' || !providerName) return undefined;
+      if (candidate.liveMode === 'auto' && (!client || candidate.resource === '*')) return undefined;
+      const captured = candidate.liveMode === 'auto'
+        ? captureQueryProvider(context, { resource: candidate.resource, dataProviderName: providerName }) : undefined;
+      return {
+        ...candidate, provider, subscribe, contractId, providerName, source: captured?.source, authScope,
+        tenant: context.tenantCacheKey?.__svadminTenant, auth: context.authProvider, router: context.routerProvider,
+        onEvent: captureLiveObserver(params.onLiveEvent), onGlobal: captureLiveObserver(params.onGlobalLiveEvent),
+      };
+    } catch { return undefined; }
+  });
+  $effect(() => {
+    const observed = state;
+    if (!observed) return;
+    const scope = observed;
+    let active = true;
+    let ready = false;
+    let pending: LiveEvent[] = [];
+    const current = () => active && state === scope && scope.authScope.isCurrent();
+    function deliver(event: LiveEvent) {
+      if (!current()) return;
+      const local = snapshotLiveEvent(event);
+      if (!local) return;
+      notifyLiveObserver(scope.onEvent, local);
+      if (!current()) return;
+      const global = snapshotLiveEvent(event);
+      if (!global) return;
+      notifyLiveObserver(scope.onGlobal, global);
+      if (!current() || scope.liveMode !== 'auto' || !client || scope.source === undefined) return;
+      const matcher = { provider: scope.providerName, tenant: scope.tenant, contract: scope.contractId, resource: scope.resource };
+      const owner = { source: scope.source, authSession: scope.authScope.cacheKey };
+      notifyLiveObserver(() => invalidateOwnedQueries({ client, matcher, owner, scopes: ['resourceAll'], current }), undefined);
+    }
+    const callback = (value: unknown) => untrack(() => {
+      if (!current()) return;
+      const event = snapshotLiveEvent(value);
+      if (!event || (scope.resource !== '*' && scope.resource !== event.resource)) return;
+      if (ready) deliver(event);
+      else pending.push(event);
+    });
+    let cleanup: unknown;
+    try {
+      cleanup = untrack(() => scope.subscribe.call(scope.provider, {
+        resource: scope.resource,
+        ...definedOptions({ liveParams: scope.liveParams === undefined ? undefined : decodeBaseRecord(snapshotPlainData(scope.liveParams)) }),
+        callback,
+      }));
+    } catch {
+      active = false;
+      pending = [];
+      return;
+    }
+    if (typeof cleanup !== 'function') {
+      active = false;
+      pending = [];
+      // A malformed asynchronous cleanup is quarantined, but still released when available.
+      notifyLiveObserver(async () => {
+        const late: unknown = await cleanup;
+        if (typeof late === 'function') await late();
+      }, undefined);
+      return;
+    }
+    const release = cleanup;
+    ready = true;
+    untrack(() => { for (const event of pending) deliver(event); });
+    pending = [];
+    return () => {
+      active = false;
+      notifyLiveObserver(() => release(), undefined);
+    };
+  });
+}