@svadmin/core 0.50.0 → 0.52.0

package/src/query-invalidation.ts

@@ -0,0 +1,172 @@
+import { QueryClient } from '@tanstack/svelte-query';
+import { dataQueryMatches, parseQueryKey, type DataQueryMatcher, type QueryDescriptorData } from './query-keys';
+import { snapshotPlainData } from './plain-data';
+import { snapshotInvalidationParams } from './invalidation-contract';
+import { definedOptions } from './defined-options';
+import { HttpError } from './types';
+import { Type } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+
+export interface QueryCacheOwner {
+  readonly source: string;
+  readonly authSession: string;
+}
+export type RefreshScope = Exclude<NonNullable<ReturnType<typeof snapshotInvalidationParams>['invalidates']>, false | 'all'>[number];
+const ownerSchema = Type.Object({
+  source: Type.String({ minLength: 1 }), authSession: Type.String({ minLength: 1 }),
+}, { additionalProperties: false });
+const matcherSchema = Type.Object({
+  resource: Type.String({ minLength: 1 }),
+  provider: Type.Optional(Type.String({ minLength: 1 })),
+  contract: Type.Optional(Type.String({ minLength: 1 })),
+  tenant: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  action: Type.Optional(Type.Union([
+    Type.Literal('list'), Type.Literal('infiniteList'), Type.Literal('select'),
+    Type.Literal('selectDefaults'), Type.Literal('many'), Type.Literal('one'),
+  ])),
+  method: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+
+function invalidRefresh(): never {
+  throw new HttpError('Invalid refresh request', 422, undefined, { code: 'INVALID_REFRESH_REQUEST' });
+}
+
+/** Copy own data properties while leaving executable capabilities opaque. */
+function properties(value: unknown, allowed: readonly string[]): Map<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return invalidRefresh();
+  const prototype: unknown = Object.getPrototypeOf(value);
+  if ((prototype !== Object.prototype && prototype !== null) || Object.getOwnPropertySymbols(value).length) return invalidRefresh();
+  const result = new Map<string, unknown>();
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    if (!allowed.includes(key) || !descriptor.enumerable || !('value' in descriptor)) return invalidRefresh();
+    const field: unknown = descriptor.value;
+    result.set(key, field);
+  }
+  return result;
+}
+
+function snapshotMatcher(value: unknown): DataQueryMatcher {
+  const fields = properties(value, ['resource', 'provider', 'contract', 'tenant', 'id', 'action', 'method']);
+  const candidate = snapshotPlainData(Object.fromEntries([...fields].filter(([, value]) => value !== undefined)));
+  if (!checkExact(matcherSchema, candidate)) return invalidRefresh();
+  // Missing tenancy selects an unset tenant; it is not permission to cross tenants.
+  return Object.freeze({
+    ...candidate, provider: candidate.provider ?? 'default', tenant: candidate.tenant, contract: candidate.contract,
+    ...(fields.has('id') ? { id: candidate.id } : {}),
+    ...(fields.has('action') ? { action: candidate.action } : {}),
+    ...(fields.has('method') ? { method: candidate.method } : {}),
+  });
+}
+
+function snapshotOwner(value: unknown): QueryCacheOwner {
+  const owner = snapshotPlainData(value);
+  if (!checkExact(ownerSchema, owner)) return invalidRefresh();
+  return Object.freeze(owner);
+}
+
+function readCapturedQuery(
+  key: readonly unknown[], matcher: DataQueryMatcher, owner: QueryCacheOwner,
+): QueryDescriptorData | undefined {
+  try {
+    const descriptor = parseQueryKey(snapshotPlainData(key));
+    if (!descriptor || descriptor.kind !== 'data' || !dataQueryMatches([descriptor], matcher)) return undefined;
+    const params = descriptor.params;
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) return undefined;
+    const source: unknown = Object.getOwnPropertyDescriptor(params, 'source')?.value;
+    const session: unknown = Object.getOwnPropertyDescriptor(params, 'authSession')?.value;
+    return source === owner.source && session === owner.authSession ? descriptor : undefined;
+  } catch { return undefined; }
+}
+
+/** Untagged, malformed and accessor-backed keys never acquire an inferred owner. */
+export function readOwnedDataQuery(
+  key: readonly unknown[], matcher: DataQueryMatcher, owner: QueryCacheOwner,
+): QueryDescriptorData | undefined {
+  try {
+    return readCapturedQuery(key, snapshotMatcher(matcher), snapshotOwner(owner));
+  } catch {
+    return undefined;
+  }
+}
+
+export function refreshSuperseded(): HttpError {
+  return new HttpError('Refresh is no longer current', 409, undefined, { code: 'REFRESH_SUPERSEDED' });
+}
+function refreshFailed(): HttpError {
+  return new HttpError('Refresh failed', 500, undefined, { code: 'REFRESH_FAILED' });
+}
+
+function captureRequest(value: unknown) {
+  try {
+    const fields = properties(value, ['client', 'matcher', 'owner', 'scopes', 'id', 'current']);
+    const client = fields.get('client');
+    const callback = fields.get('current');
+    if (!(client instanceof QueryClient) || typeof callback !== 'function') return invalidRefresh();
+    const matcher = snapshotMatcher(fields.get('matcher'));
+    const owner = snapshotOwner(fields.get('owner'));
+    const params = snapshotInvalidationParams({
+      invalidates: fields.get('scopes'), ...(fields.has('id') ? { id: fields.get('id') } : {}),
+    });
+    if (!Array.isArray(params.invalidates)) return invalidRefresh();
+    let retired = false;
+    return {
+      client, matcher, owner, scopes: params.invalidates, ...definedOptions({ id: params.id }),
+      current(): boolean {
+        if (retired) return false;
+        try {
+          const result: unknown = Reflect.apply(callback, undefined, []);
+          if (result !== true) {
+            retired = true;
+            if (typeof result !== 'boolean') void Promise.resolve(result).catch(() => {});
+            return false;
+          }
+          return true;
+        } catch {
+          retired = true;
+          return false;
+        }
+      },
+    };
+  } catch { return invalidRefresh(); }
+}
+
+/** Recheck ownership for each dispatch and await every started request, including failures. */
+export async function invalidateOwnedQueries(request: {
+  client: QueryClient;
+  matcher: DataQueryMatcher;
+  owner: QueryCacheOwner;
+  scopes: readonly RefreshScope[];
+  id?: string | number;
+  current: () => boolean;
+}): Promise<void> {
+  const { client, matcher, owner, scopes, id, current } = captureRequest(request);
+  if (!current()) throw refreshSuperseded();
+  const matches = (key: readonly unknown[]) => {
+    if (!current()) return false;
+    const descriptor = readCapturedQuery(key, matcher, owner);
+    if (!descriptor) return false;
+    return scopes.some(scope => {
+      if (scope === 'resourceAll') return true;
+      if (scope === 'list') return ['list', 'infiniteList', 'select', 'selectDefaults'].includes(descriptor.action);
+      if (scope === 'many') return descriptor.action === 'many';
+      return scope === 'detail' && descriptor.action === 'one' && (id === undefined || descriptor.id === id);
+    });
+  };
+  const selected = (() => {
+    try {
+      return client.getQueryCache().findAll({ predicate: query => matches(query.queryKey) });
+    } catch {
+      throw current() ? refreshFailed() : refreshSuperseded();
+    }
+  })();
+  const tasks = selected.map(async query => {
+    if (!current()) return;
+    await client.invalidateQueries({
+      predicate: candidate => candidate === query && matches(candidate.queryKey),
+    }, { throwOnError: true });
+  });
+  const settled = await Promise.allSettled(tasks);
+  if (!current()) throw refreshSuperseded();
+  if (settled.some(result => result.status === 'rejected')) throw refreshFailed();
+}

package/src/query-keys.ts

@@ -1,127 +1,238 @@
-export const NAMESPACE = 'svadmin';
-export const VERSION = 2;
-
-export type QueryKind = 'data' | 'task' | 'access' | 'custom';
-export type QueryDataAction = 'list' | 'infiniteList' | 'one' | 'many' | 'select' | 'selectDefaults';
-export type QueryTaskAction = 'list' | 'one';
-type TenantId = string | number;
-
-type BaseDescriptor = {
-  readonly namespace: typeof NAMESPACE;
-  readonly version: typeof VERSION;
-  readonly provider: string;
-  readonly tenant?: TenantId;
-  readonly resource?: string;
-  readonly id?: string | number;
-  readonly params?: unknown;
-  readonly method?: string;
-};
+import { Type,type Static } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { definedOptions } from './defined-options';
+import { snapshotPlainData, type JsonValue } from './plain-data';
+import { HttpError } from './types';
+
+export const NAMESPACE='svadmin';
+export const VERSION=2;
 
-export type QueryDescriptorData = BaseDescriptor & { readonly kind: 'data'; readonly action: QueryDataAction };
-export type QueryDescriptorTask = BaseDescriptor & { readonly kind: 'task'; readonly action: QueryTaskAction };
-export type QueryDescriptorAccess = BaseDescriptor & { readonly kind: 'access'; readonly action?: 'can' };
-export type QueryDescriptorCustom = BaseDescriptor & { readonly kind: 'custom'; readonly action?: string };
-export type QueryDescriptor = QueryDescriptorData | QueryDescriptorTask | QueryDescriptorAccess | QueryDescriptorCustom;
-export type QueryKey = readonly [descriptor: QueryDescriptor];
-
-export type QueryKeysContext = { readonly provider?: string; readonly tenant?: TenantId; readonly resource?: string; readonly action?: string; readonly id?: string | number; readonly params?: unknown; readonly method?: string };
-export type QueryMatcher = { readonly provider?: string; readonly tenant?: TenantId; readonly resource?: string; readonly action?: string; readonly id?: string | number; readonly method?: string; readonly kind?: QueryKind };
-export type DataQueryMatcher = Omit<QueryMatcher, 'kind'> & { readonly resource: string };
-export type QueryKeysBuilder = {
-  data: { list(resource: string, params?: unknown): QueryKey; infiniteList(resource: string, params?: unknown): QueryKey; one(resource: string, id: string | number, params?: unknown): QueryKey; many(resource: string, params: unknown): QueryKey; select(resource: string, params?: unknown): QueryKey; selectDefaults(resource: string, params?: unknown): QueryKey; };
-  task: { list(params?: unknown): QueryKey; one(id: string | number): QueryKey };
-  access: { can(resource?: string, params?: unknown): QueryKey };
-  custom: { call(resource: string, id: string | number, method?: string, params?: unknown): QueryKey };
+const baseProperties={
+  namespace: Type.Literal(NAMESPACE),
+  version: Type.Literal(VERSION),
+  provider: Type.String({ minLength: 1 }),
+  contract: Type.Optional(Type.String({ minLength: 1 })),
+  tenant: Type.Optional(Type.Union([Type.String(),Type.Number()])),
+  resource: Type.Optional(Type.String()),
+  id: Type.Optional(Type.Union([Type.String(),Type.Number()])),
+  params: Type.Optional(Type.Unknown()),
+  method: Type.Optional(Type.String()),
+};
+const identity=Type.Union([Type.String(),Type.Number()]);
+const dataBase={
+  ...baseProperties,
+  kind: Type.Literal('data'),
+  resource: Type.String(),
 };
+const dataSchema=Type.Union([Type.Object({
+  ...dataBase,action: Type.Literal('one'),id: identity,
+},{ additionalProperties: false }),Type.Object({
+  ...dataBase,
+  action: Type.Union([
+    Type.Literal('list'),Type.Literal('infiniteList'),
+    Type.Literal('many'),Type.Literal('select'),Type.Literal('selectDefaults'),
+  ]),
+},{ additionalProperties: false })]);
+const taskSchema=Type.Union([Type.Object({
+  ...baseProperties,
+  kind: Type.Literal('task'),action: Type.Literal('one'),id: identity,
+},{ additionalProperties: false }),Type.Object({
+  ...baseProperties,kind: Type.Literal('task'),action: Type.Literal('list'),
+},{ additionalProperties: false })]);
+const accessSchema=Type.Object({
+  ...baseProperties,kind: Type.Literal('access'),action: Type.Optional(Type.Literal('can')),
+},{ additionalProperties: false });
+const customSchema=Type.Object({
+  ...baseProperties,kind: Type.Literal('custom'),action: Type.Optional(Type.String()),
+  resource: Type.String(),id: identity,
+},{ additionalProperties: false });
+const keySchema=Type.Tuple([Type.Union([dataSchema,taskSchema,accessSchema,customSchema])]);
+
+export type QueryDescriptorData=Readonly<Static<typeof dataSchema>>;
+export type QueryDescriptorTask=Readonly<Static<typeof taskSchema>>;
+export type QueryDescriptorAccess=Readonly<Static<typeof accessSchema>>;
+export type QueryDescriptorCustom=Readonly<Static<typeof customSchema>>;
+export type QueryDescriptor=QueryDescriptorData|QueryDescriptorTask|QueryDescriptorAccess|QueryDescriptorCustom;
+export type QueryKey=readonly [descriptor: QueryDescriptor];
+export type QueryKind=QueryDescriptor['kind'];
+export type QueryDataAction=QueryDescriptorData['action'];
+export type QueryTaskAction=QueryDescriptorTask['action'];
+
+export type QueryKeysContext=Partial<Pick<QueryDescriptorCustom,'provider'|'contract'|'tenant'|'resource'|'id'|'params'|'method'>>;
+
+// An absent matcher field is a wildcard; explicit undefined matches an unset field.
+// The provider is special: explicit undefined selects the default provider.
+export type QueryMatcher={
+  readonly [K in keyof Omit<QueryDescriptorCustom,'namespace'|'version'|'params'|'kind'>]?: QueryDescriptorCustom[K]|undefined;
+}&{ readonly kind?: QueryKind };
+export type DataQueryMatcher=Omit<QueryMatcher,'kind'|'resource'>&{ readonly resource: string };
+export type QueryKeysBuilder=Readonly<{
+  data: Readonly<{
+    list(resource: string,params?: unknown): QueryKey;
+    infiniteList(resource: string,params?: unknown): QueryKey;
+    one(resource: string,id: string|number,params?: unknown): QueryKey;
+    many(resource: string,params: unknown): QueryKey;
+    select(resource: string,params?: unknown): QueryKey;
+    selectDefaults(resource: string,params?: unknown): QueryKey;
+  }>;
+  task: Readonly<{ list(params?: unknown): QueryKey; one(id: string|number): QueryKey }>;
+  access: Readonly<{ can(resource?: string,params?: unknown): QueryKey }>;
+  custom: Readonly<{ call(resource: string,id: string|number,method?: string,params?: unknown): QueryKey }>;
+}>;
+
+const contextSchema=Type.Object({
+  provider: Type.Optional(baseProperties.provider),contract: baseProperties.contract,tenant: baseProperties.tenant,
+  resource: baseProperties.resource,id: baseProperties.id,params: baseProperties.params,method: baseProperties.method,
+},{ additionalProperties: false });
+const matcherSchema=Type.Object({
+  provider: Type.Optional(baseProperties.provider),contract: baseProperties.contract,tenant: baseProperties.tenant,
+  resource: baseProperties.resource,id: baseProperties.id,method: baseProperties.method,
+  action: Type.Optional(Type.String()),
+  kind: Type.Optional(Type.Union([Type.Literal('data'),Type.Literal('task'),Type.Literal('access'),Type.Literal('custom')])),
+},{ additionalProperties: false });
+
+function invalidKey(): never {
+  throw new HttpError('Invalid query key',422,undefined,{ code: 'INVALID_QUERY_KEY' });
+}
+
+function ownFields(value: unknown, allowed: readonly string[]): [string,unknown][] {
+  if(typeof value!=='object'||value===null||Array.isArray(value)) return invalidKey();
+  const prototype: unknown=Object.getPrototypeOf(value);
+  if((prototype!==Object.prototype&&prototype!==null)||Object.getOwnPropertySymbols(value).length) return invalidKey();
+  return Object.entries(Object.getOwnPropertyDescriptors(value)).map(([key,descriptor]) => {
+    if(!allowed.includes(key)||!descriptor.enumerable||!('value' in descriptor)) return invalidKey();
+    const field: unknown=descriptor.value;
+    return [key,field];
+  });
+}
 
-function withDefaultProvider(value: string | undefined): string { return value === undefined ? 'default' : value; }
-function assertProvider(provider: string): void { if (!provider.length) throw new Error('provider must be a non-empty string'); }
-
-function makeDescriptor(value: { kind: 'data'; provider?: string; tenant?: TenantId; resource?: string; action: QueryDataAction; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorData;
-function makeDescriptor(value: { kind: 'task'; provider?: string; tenant?: TenantId; resource?: string; action: QueryTaskAction; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorTask;
-function makeDescriptor(value: { kind: 'access'; provider?: string; tenant?: TenantId; resource?: string; action?: 'can'; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorAccess;
-function makeDescriptor(value: { kind: 'custom'; provider?: string; tenant?: TenantId; resource?: string; id?: string | number; action?: string; params?: unknown; method?: string; }): QueryDescriptorCustom;
-function makeDescriptor(value: { kind: QueryKind; provider?: string; tenant?: TenantId; resource?: string; action?: string; id?: string | number; params?: unknown; method?: string; }): QueryDescriptor {
-  const provider = withDefaultProvider(value.provider);
-  assertProvider(provider);
-
-  const base = { namespace: NAMESPACE, version: VERSION, provider, tenant: value.tenant, resource: value.resource, id: value.id, params: value.params, method: value.method } as const;
-  if (value.kind === 'data') return { ...base, kind: 'data', action: value.action } as QueryDescriptorData;
-  if (value.kind === 'task') return { ...base, kind: 'task', action: value.action as QueryTaskAction } as QueryDescriptorTask;
-  if (value.kind === 'access') return { ...base, kind: 'access', action: value.action as 'can' | undefined } as QueryDescriptorAccess;
-  return { ...base, kind: 'custom', action: value.action } as QueryDescriptorCustom;
+function freezeData(value: JsonValue): void {
+  if(typeof value!=='object'||value===null) return;
+  for(const field of Object.values(value)) freezeData(field);
+  Object.freeze(value);
 }
 
-export function keys(context: QueryKeysContext = {}): QueryKeysBuilder {
-  const base = { provider: withDefaultProvider(context.provider), tenant: context.tenant, resource: context.resource, id: context.id, params: context.params, method: context.method };
-  return {
-    data: {
-      list: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'list', id: base.id, params, method: base.method })],
-      infiniteList: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'infiniteList', id: base.id, params, method: base.method })],
-      one: (resource, id, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'one', id, params, method: base.method })],
-      many: (resource, params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'many', params, method: base.method })],
-      select: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'select', id: base.id, params, method: base.method })],
-      selectDefaults: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'selectDefaults', id: base.id, params, method: base.method })],
-    },
-    task: {
-      list: (params = base.params) => [makeDescriptor({ kind: 'task', provider: base.provider, tenant: base.tenant, resource: base.resource, action: 'list', id: base.id, params, method: base.method })],
-      one: (id) => [makeDescriptor({ kind: 'task', provider: base.provider, tenant: base.tenant, resource: base.resource, action: 'one', id, method: base.method })],
-    },
-    access: { can: (resource = base.resource, params = base.params) => [makeDescriptor({ kind: 'access', provider: base.provider, tenant: base.tenant, resource, action: 'can', id: base.id, params, method: base.method })] },
-    custom: { call: (resource, id, method, params) => [makeDescriptor({ kind: 'custom', provider: base.provider, tenant: base.tenant, resource, id, method, params, action: 'call' })] },
+function snapshotKey(value: unknown): QueryKey|undefined {
+  try {
+    const candidate=snapshotPlainData(value);
+    freezeData(candidate);
+    return checkExact(keySchema,candidate)? candidate:undefined;
+  } catch { return undefined; }
+}
+
+function build(descriptor: Record<string,unknown>): QueryKey {
+  const key=snapshotKey([definedOptions(descriptor)]);
+  return key??invalidKey();
+}
+
+function snapshotContext(value: unknown): QueryKeysContext {
+  try {
+    const fields=ownFields(value,['provider','contract','tenant','resource','id','params','method']);
+    const candidate=snapshotPlainData(Object.fromEntries(fields.filter(([key,value]) => key!=='params'||value!==undefined)));
+    freezeData(candidate);
+    if(checkExact(contextSchema,candidate)) return candidate;
+  } catch { /* Never expose rejected key data or reflection errors. */ }
+  return invalidKey();
+}
+
+function snapshotMatcher(value: unknown): QueryMatcher|undefined {
+  try {
+    const fields=ownFields(value,['provider','contract','tenant','resource','id','action','method','kind']);
+    if(fields.some(([key,value]) => key==='kind'&&value===undefined)) return undefined;
+    const candidate=snapshotPlainData(Object.fromEntries(fields.filter(([,value]) => value!==undefined)));
+    if(!checkExact(matcherSchema,candidate)) return undefined;
+    const explicitUndefined=Object.fromEntries<undefined>(fields.filter(([,value]) => value===undefined).map(([key]) => [key,undefined]));
+    return Object.freeze({ ...candidate,...explicitUndefined });
+  } catch { return undefined; }
+}
+
+export function keys(context: QueryKeysContext={}): QueryKeysBuilder {
+  const captured=snapshotContext(context);
+  const provider=captured.provider??'default';
+  const base=definedOptions({
+    namespace: NAMESPACE,version: VERSION,provider,
+    contract: captured.contract,tenant: captured.tenant,resource: captured.resource,
+    id: captured.id,params: captured.params,method: captured.method,
+  });
+  const result: QueryKeysBuilder={
+    data: Object.freeze({
+      list: (resource,params=base.params) => build({ ...base,kind: 'data',action: 'list',resource,params }),
+      infiniteList: (resource,params=base.params) => build({ ...base,kind: 'data',action: 'infiniteList',resource,params }),
+      one: (resource,id,params=base.params) => build({ ...base,kind: 'data',action: 'one',resource,id,params }),
+      many: (resource,params) => build({
+        ...base,
+        kind: 'data',
+        action: 'many',
+        resource,
+        id: undefined,
+        params,
+      }),
+      select: (resource,params=base.params) => build({ ...base,kind: 'data',action: 'select',resource,params }),
+      selectDefaults: (resource,params=base.params) => build({ ...base,kind: 'data',action: 'selectDefaults',resource,params }),
+    }),
+    task: Object.freeze({
+      list: (params=base.params) => build({ ...base,kind: 'task',action: 'list',params }),
+      one: id => build({
+        ...base,
+        kind: 'task',
+        action: 'one',
+        id,
+        params: undefined,
+      }),
+    }),
+    access: Object.freeze({
+      can: (resource=base.resource,params=base.params) => build({
+        ...base,
+        kind: 'access',
+        action: 'can',
+        resource,
+        params,
+      })
+    }),
+    custom: Object.freeze({
+      call: (resource,id,method,params) => build({
+        ...base,
+        kind: 'custom',
+        action: 'call',
+        resource,
+        id,
+        method,
+        params,
+      })
+    }),
   };
+  return Object.freeze(result);
 }
 
-export const queryKeys: QueryKeysBuilder = {
-  data: {
-    list: (resource, params) => keys().data.list(resource, params),
-    infiniteList: (resource, params) => keys().data.infiniteList(resource, params),
-    one: (resource, id, params) => keys().data.one(resource, id, params),
-    many: (resource, params) => keys().data.many(resource, params),
-    select: (resource, params) => keys().data.select(resource, params),
-    selectDefaults: (resource, params) => keys().data.selectDefaults(resource, params),
-  },
-  task: { list: (params) => keys().task.list(params), one: (id) => keys().task.one(id) },
-  access: { can: (resource, params) => keys().access.can(resource, params) },
-  custom: { call: (resource, id, method, params) => keys().custom.call(resource, id, method, params) },
-};
+export const queryKeys: QueryKeysBuilder=keys();
 
-export function parseQueryKey(value: unknown): QueryDescriptor | undefined {
-  if (!Array.isArray(value) || value.length !== 1) return;
-  const candidate = value[0];
-  if (!candidate || typeof candidate !== 'object') return;
-  const descriptor = candidate as QueryDescriptor;
-  if (descriptor.namespace !== NAMESPACE || descriptor.version !== VERSION || typeof descriptor.provider !== 'string' || !descriptor.provider.length) return;
-  if (descriptor.tenant !== undefined && typeof descriptor.tenant !== 'string' && typeof descriptor.tenant !== 'number') return;
-  if (descriptor.resource !== undefined && typeof descriptor.resource !== 'string') return;
-  if (descriptor.id !== undefined && typeof descriptor.id !== 'string' && typeof descriptor.id !== 'number') return;
-  if (descriptor.method !== undefined && typeof descriptor.method !== 'string') return;
-  if (descriptor.kind === 'data' && ['list', 'infiniteList', 'one', 'many', 'select', 'selectDefaults'].includes(descriptor.action)) return descriptor;
-  if (descriptor.kind === 'task' && ['list', 'one'].includes(descriptor.action)) return descriptor;
-  if (descriptor.kind === 'access' && (descriptor.action === undefined || descriptor.action === 'can')) return descriptor;
-  if (descriptor.kind === 'custom' && (descriptor.action === undefined || typeof descriptor.action === 'string')) return descriptor;
+export function parseQueryKey(value: unknown): QueryDescriptor|undefined {
+  return snapshotKey(value)?.[0];
 }
 
-export function isQueryKey(value: unknown): value is QueryKey { return parseQueryKey(value) !== undefined; }
+/** Inspect validity without granting a type to the original mutable or proxy-backed value. */
+export function isQueryKey(value: unknown): boolean { return parseQueryKey(value)!==undefined; }
+
+function matchField(descriptor: QueryDescriptor,matcher: QueryMatcher,key: keyof QueryMatcher): boolean {
+  return !Object.hasOwn(matcher,key)||descriptor[key]===matcher[key];
+}
 
-function has(value: QueryMatcher, key: keyof QueryMatcher): boolean { return Object.prototype.hasOwnProperty.call(value, key); }
-function matchField(descriptor: QueryDescriptor, matcher: QueryMatcher, key: keyof QueryMatcher): boolean {
-  if (!has(matcher, key)) return true;
-  if (matcher[key] === undefined) return !(key in descriptor) || (descriptor as Record<string, unknown>)[key] === undefined;
-  return (descriptor as Record<string, unknown>)[key] === matcher[key];
+function matches(queryKey: readonly unknown[],matcher: QueryMatcher): boolean {
+  const parsed=parseQueryKey(queryKey);
+  if(!parsed||parsed.contract!==matcher.contract) return false;
+  if(matcher.kind!==undefined&&matcher.kind!==parsed.kind) return false;
+  if(Object.hasOwn(matcher,'provider')&&parsed.provider!==(matcher.provider??'default')) return false;
+  return matchField(parsed,matcher,'tenant')&&matchField(parsed,matcher,'resource')
+    &&matchField(parsed,matcher,'action')&&matchField(parsed,matcher,'id')&&matchField(parsed,matcher,'method');
 }
 
-export function queryKeyMatches(queryKey: readonly unknown[], matcher: QueryMatcher = {}): boolean {
-  const parsed = parseQueryKey(queryKey);
-  if (!parsed) return false;
-  if (matcher.kind !== undefined && matcher.kind !== parsed.kind) return false;
-  if (has(matcher, 'provider')) {
-    if (matcher.provider === undefined) return parsed.provider === 'default';
-    if (matcher.provider !== parsed.provider) return false;
-  }
-  return matchField(parsed, matcher, 'tenant') && matchField(parsed, matcher, 'resource') && matchField(parsed, matcher, 'action') && matchField(parsed, matcher, 'id') && matchField(parsed, matcher, 'method');
+export function queryKeyMatches(queryKey: readonly unknown[],matcher: QueryMatcher={}): boolean {
+  const captured=snapshotMatcher(matcher);
+  return captured!==undefined&&matches(queryKey,captured);
 }
 
-export function dataQueryMatches(queryKey: readonly unknown[], matcher: DataQueryMatcher): boolean {
-  return queryKeyMatches(queryKey, { ...matcher, kind: 'data' });
+export function dataQueryMatches(queryKey: readonly unknown[],matcher: DataQueryMatcher): boolean {
+  const captured=snapshotMatcher(matcher);
+  return captured!==undefined&&!Object.hasOwn(captured,'kind')&&typeof captured.resource==='string'&&
+    matches(queryKey,{ ...captured,kind: 'data' });
 }