@astrale-os/shell-react 0.3.2-beta → 0.3.2-beta.1

package/dist/graph/query-definition.hook.d.ts

@@ -1,4 +1,5 @@
 import type { QueryDefinition } from '@astrale-os/sdk/query';
+import type { Domain } from '@astrale-os/sdk/schema';
 import type { GraphResource } from './resource.js';
 export interface QueryResourceOptions {
     readonly keepPrevious?: boolean;
@@ -6,4 +7,4 @@ export interface QueryResourceOptions {
     readonly refreshWhen?: 'always' | 'visible';
 }
 /** Execute one named SDK Query definition exclusively through the current GraphStore. */
-export declare function useQuery<Input, Output>(definition: QueryDefinition<Input, Output> | null, input: Input, options?: QueryResourceOptions): GraphResource<Output>;
+export declare function useQuery<DomainValue extends Domain, Input, Output>(definition: QueryDefinition<DomainValue, Input, Output> | null, input: Input, options?: QueryResourceOptions): GraphResource<Output>;

package/dist/graph/query-definition.hook.js

@@ -1,9 +1,11 @@
 import { executeQuery } from '@astrale-os/sdk/query';
 import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useExecutionDomain } from '../schema/domain.context.js';
 import { retainRefreshScheduler } from './resource.js';
 import { useGraphStore } from './store.js';
 class DefinitionObserver {
     store;
+    domain;
     definition;
     input;
     listeners = new Set();
@@ -14,8 +16,9 @@ class DefinitionObserver {
     pending = null;
     started = false;
     rerunQueued = false;
-    constructor(store, definition, input) {
+    constructor(store, domain, definition, input) {
         this.store = store;
+        this.domain = domain;
         this.definition = definition;
         this.input = input;
     }
@@ -50,7 +53,7 @@ class DefinitionObserver {
             touched.push(Object.freeze({ ast, options }));
             return this.store.read(ast, { ...options, freshness });
         };
-        const running = executeQuery({ query: execute }, this.definition, this.input)
+        const running = executeQuery({ query: execute }, this.domain, this.definition, this.input)
             .then((data) => {
             if (!this.started || generation !== this.generation)
                 return;
@@ -114,14 +117,15 @@ class DefinitionObserver {
 /** Execute one named SDK Query definition exclusively through the current GraphStore. */
 export function useQuery(definition, input, options = {}) {
     const store = useGraphStore();
+    const domain = useExecutionDomain();
     const inputIdentity = stableIdentity(input);
-    const observer = useMemo(() => (definition === null ? null : new DefinitionObserver(store, definition, input)), [store, definition, inputIdentity]);
+    const observer = useMemo(() => (definition === null ? null : new DefinitionObserver(store, domain, definition, input)), [store, domain, definition, inputIdentity]);
     const idle = useMemo(() => Object.freeze({ state: 'idle' }), []);
     const subscribe = useCallback((listener) => observer?.subscribe(listener) ?? (() => { }), [observer]);
     const snapshot = useCallback(() => observer?.getSnapshot() ?? idle, [observer, idle]);
     const current = useSyncExternalStore(subscribe, snapshot, snapshot);
     useEffect(() => observer?.start(), [observer]);
-    const identity = definition === null ? 'idle' : `${definition.id}\u0000${inputIdentity}`;
+    const identity = definition === null ? 'idle' : `${definitionIdentity(definition)}\u0000${inputIdentity}`;
     useEffect(() => {
         if (observer === null || options.refreshInterval === undefined)
             return;
@@ -148,6 +152,16 @@ export function useQuery(definition, input, options = {}) {
         more: Object.freeze({ has: false, pending: false, load: () => Promise.resolve() }),
     }), [current, previous, observer]);
 }
+const definitionIdentities = new WeakMap();
+let nextDefinitionIdentity = 1;
+function definitionIdentity(definition) {
+    const retained = definitionIdentities.get(definition);
+    if (retained !== undefined)
+        return retained;
+    const created = nextDefinitionIdentity++;
+    definitionIdentities.set(definition, created);
+    return created;
+}
 function dedupeShapes(input) {
     const seen = new Set();
     return Object.freeze(input.filter(({ ast, options }) => {

package/dist/index.d.ts

@@ -5,8 +5,8 @@ export { ActAs, useAuth, useCan, useSelf } from './auth/index.js';
 export type { ActAsProps, PolicyObject } from './auth/index.js';
 export { ClientError, NodeUnavailableError, ProtocolError, ResponseError, StaleRouteError, TransportError, isClientError, isNodeUnavailableError, useCall, useGraphStore, useQuery, useStream, } from './graph/index.js';
 export type { CallOptions, GraphResource, GraphResourceState, GraphStore, QueryResourceOptions, StreamHandle, StreamOptions, } from './graph/index.js';
-export { RelationUnavailableError, queryRefresh, useAction, useDomain, useDomains, useDynamicDomain, useDynamicObject, useKernel, useMutation, useObject, useRelation, } from './schema/index.js';
-export type { ActionOptions, ActionRefresh, DomainAction, MutationOptions, QueryRefresh, RelationOptions, RelationResource, RelationUnavailable, RichReadOptions, } from './schema/index.js';
+export { DomainProvider, RelationUnavailableError, queryRefresh, useAction, useDomain, useDomains, useDynamicDomain, useDynamicObject, useKernel, useMutation, useObject, useRelation, } from './schema/index.js';
+export type { ActionOptions, ActionRefresh, DomainProviderProps, DomainAction, MutationOptions, QueryRefresh, RelationOptions, RelationResource, RelationUnavailable, RichReadOptions, } from './schema/index.js';
 export { Link, NavigationScope, NavScope, NodeLink, pathParam, ViewLink, defineNavigation, enumParam, location, memoryAdapter, urlAdapter, useAncestors, useLocation, useNavigate, useNavigation, useNavScope, } from './navigation/index.js';
 export type { LinkProps, LocationDefinition, MissingPolicy, NavAdapter, NavLocation, NavScopeHandle, NavScopeProps, NavSnapshot, NavTarget, NavigationDefinition, NavigationParam, NavigationParams, NavigationRoutes, NavigationTarget, NodeLinkProps, Navigate, SerializedLocation, ViewLinkProps, } from './navigation/index.js';
 export { SelectionScope, useSelection } from './selection/index.js';

package/dist/index.js

@@ -5,7 +5,7 @@ export { ActAs, useAuth, useCan, useSelf } from './auth/index.js';
 // One Store path and named SDK definitions. Raw Query/Mutation builders are intentionally absent.
 export { ClientError, NodeUnavailableError, ProtocolError, ResponseError, StaleRouteError, TransportError, isClientError, isNodeUnavailableError, useCall, useGraphStore, useQuery, useStream, } from './graph/index.js';
 // Rich exact Domain bindings.
-export { RelationUnavailableError, queryRefresh, useAction, useDomain, useDomains, useDynamicDomain, useDynamicObject, useKernel, useMutation, useObject, useRelation, } from './schema/index.js';
+export { DomainProvider, RelationUnavailableError, queryRefresh, useAction, useDomain, useDomains, useDynamicDomain, useDynamicObject, useKernel, useMutation, useObject, useRelation, } from './schema/index.js';
 // Typed navigation and selection.
 export { Link, NavigationScope, NavScope, NodeLink, pathParam, ViewLink, defineNavigation, enumParam, location, memoryAdapter, urlAdapter, useAncestors, useLocation, useNavigate, useNavigation, useNavScope, } from './navigation/index.js';
 export { SelectionScope, useSelection } from './selection/index.js';

package/dist/schema/action.hook.d.ts

@@ -1,6 +1,7 @@
 import type { BoundNodeFor } from '@astrale-os/sdk/client';
 import type { SessionRequestOptions } from '@astrale-os/sdk/client/session';
-import type { QueryAST } from '@astrale-os/sdk/query';
+import type { QueryAST, QueryDefinition } from '@astrale-os/sdk/query';
+import type { Domain } from '@astrale-os/sdk/schema';
 import type { CallableInputOf, CallableResultOf, MethodOwnerKeyOf, MethodInheritance, ResolvedFunction, ResolvedMethod } from '@astrale-os/sdk/schema';
 type ExecutableInheritance = Exclude<MethodInheritance, 'abstract'>;
 type InstanceMethod = ResolvedMethod<unknown, unknown, false, ExecutableInheritance>;
@@ -10,23 +11,15 @@ type MethodReceiver<C extends InstanceMethod> = BoundNodeFor<MethodOwnerKeyOf<C>
 declare const QUERY_REFRESH: unique symbol;
 export interface QueryRefresh {
     readonly id: string;
-    readonly [QUERY_REFRESH]: () => {
+    readonly [QUERY_REFRESH]: (domain: Domain) => {
         readonly ast: QueryAST;
         readonly page: Readonly<{
             readonly size: number;
         }>;
     };
 }
-type RefreshableQuery<Input, Query extends QueryAST> = {
-    readonly id: string;
-    readonly page: Readonly<{
-        readonly size: number;
-    }>;
-    prepare?(input: Input): Input;
-    build(input: Input): Query;
-};
 /** Pair one exact named Query definition with its admitted input for targeted invalidation. */
-export declare function queryRefresh<Input, Query extends QueryAST>(definition: RefreshableQuery<Input, Query>, input: Input): QueryRefresh;
+export declare function queryRefresh<DomainValue extends Domain, Input, Output>(definition: QueryDefinition<DomainValue, Input, Output>, input: Input): QueryRefresh;
 export type ActionRefresh = 'all' | 'none' | {
     readonly queries: readonly QueryRefresh[];
 };

package/dist/schema/action.hook.js

@@ -1,18 +1,26 @@
 import { reference } from '@astrale-os/sdk/client/session';
 import { Path } from '@astrale-os/sdk/graph/path';
+import { realizeQuery } from '@astrale-os/sdk/query';
 import { useCallback, useMemo, useRef } from 'react';
 import { useSessionKernel } from '../auth/session-kernel.js';
 import { useAction as useAsyncAction } from '../graph/action.js';
 import { useGraphStore } from '../graph/store.js';
 import { bindingFor } from './domain.hook.js';
 const QUERY_REFRESH = Symbol('shell-react.query-refresh');
+const queryRefreshIdentities = new WeakMap();
+let nextQueryRefreshIdentity = 0;
 /** Pair one exact named Query definition with its admitted input for targeted invalidation. */
 export function queryRefresh(definition, input) {
+    const id = queryRefreshIdentity(definition);
     return Object.freeze({
-        id: definition.id,
-        [QUERY_REFRESH]: () => {
-            const prepared = definition.prepare?.(input) ?? input;
-            return Object.freeze({ ast: definition.build(prepared), page: definition.page });
+        id,
+        [QUERY_REFRESH]: (domain) => {
+            const realized = realizeQuery(definition, domain);
+            if (realized.kind !== 'single') {
+                throw new TypeError('Targeted refresh requires a single Query recipe.');
+            }
+            const prepared = realized.prepare?.(input) ?? input;
+            return Object.freeze({ ast: realized.build(prepared), page: realized.page });
         },
     });
 }
@@ -40,7 +48,7 @@ export function useAction(callable, options = {}) {
                 store.invalidate();
             else if (refresh !== 'none') {
                 refresh.queries.forEach((query) => {
-                    const target = query[QUERY_REFRESH]();
+                    const target = query[QUERY_REFRESH](bindingRef.current.domain);
                     store.invalidate(target.ast, { page: target.page });
                 });
             }
@@ -75,3 +83,11 @@ function isInstanceMethod(callable) {
 function receiverPath(receiver) {
     return Path.id(receiver.id);
 }
+function queryRefreshIdentity(definition) {
+    const current = queryRefreshIdentities.get(definition);
+    if (current !== undefined)
+        return current;
+    const created = `query-${++nextQueryRefreshIdentity}`;
+    queryRefreshIdentities.set(definition, created);
+    return created;
+}

package/dist/schema/domain.context.d.ts

@@ -0,0 +1,10 @@
+import type { Domain } from '@astrale-os/sdk/schema';
+import type { schema } from '@astrale-os/sdk/schema';
+import type { ReactElement, ReactNode } from 'react';
+export interface DomainProviderProps<Schema extends schema.DomainSchema> {
+    readonly schema: Schema;
+    readonly children: ReactNode;
+}
+/** Resolve one exact installed Domain for every projected recipe in the React subtree. */
+export declare function DomainProvider<const Schema extends schema.DomainSchema>(props: DomainProviderProps<Schema>): ReactElement;
+export declare function useExecutionDomain<DomainValue extends Domain>(): DomainValue;

package/dist/schema/domain.context.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+import { useDomain } from './domain.hook.js';
+const DomainContext = createContext(null);
+DomainContext.displayName = 'AstraleDomainContext';
+/** Resolve one exact installed Domain for every projected recipe in the React subtree. */
+export function DomainProvider(props) {
+    const binding = useDomain(props.schema);
+    return _jsx(DomainContext.Provider, { value: binding.domain, children: props.children });
+}
+export function useExecutionDomain() {
+    const domain = useContext(DomainContext);
+    if (domain === null) {
+        throw new Error('Projected Query and Mutation hooks require a surrounding DomainProvider.');
+    }
+    return domain;
+}

package/dist/schema/index.d.ts

@@ -1,5 +1,7 @@
 export { useKernel } from './kernel.hook.js';
 export { useDomain, useDomains, useDynamicDomain } from './domain.hook.js';
+export { DomainProvider } from './domain.context.js';
+export type { DomainProviderProps } from './domain.context.js';
 export { queryRefresh, useAction } from './action.hook.js';
 export type { ActionOptions, ActionRefresh, DomainAction, QueryRefresh } from './action.hook.js';
 export { useMutation } from './mutation.hook.js';

package/dist/schema/index.js

@@ -1,5 +1,6 @@
 export { useKernel } from './kernel.hook.js';
 export { useDomain, useDomains, useDynamicDomain } from './domain.hook.js';
+export { DomainProvider } from './domain.context.js';
 export { queryRefresh, useAction } from './action.hook.js';
 export { useMutation } from './mutation.hook.js';
 export { useDynamicObject, useObject } from './object.hook.js';

package/dist/schema/mutation.hook.d.ts

@@ -1,8 +1,9 @@
 import type { Mutation } from '@astrale-os/sdk/mutation';
+import type { Domain } from '@astrale-os/sdk/schema';
 import type { DomainAction } from './action.hook.js';
 export interface MutationOptions {
     readonly optimistic?: boolean;
     readonly onError?: (error: unknown) => void;
 }
 /** Execute one named SDK Mutation definition through GraphStore optimism/invalidation. */
-export declare function useMutation<Input, Output>(definition: Mutation<Input, Output>, options?: MutationOptions): DomainAction<[Input], Output>;
+export declare function useMutation<DomainValue extends Domain, Input, Output>(definition: Mutation<DomainValue, Input, Output>, options?: MutationOptions): DomainAction<[Input], Output>;

package/dist/schema/mutation.hook.js

@@ -2,9 +2,11 @@ import { executeMutation } from '@astrale-os/sdk/mutation';
 import { useCallback, useMemo, useRef } from 'react';
 import { useAction as useAsyncAction } from '../graph/action.js';
 import { useGraphStore } from '../graph/store.js';
+import { useExecutionDomain } from './domain.context.js';
 /** Execute one named SDK Mutation definition through GraphStore optimism/invalidation. */
 export function useMutation(definition, options = {}) {
     const store = useGraphStore();
+    const domain = useExecutionDomain();
     const definitionRef = useRef(definition);
     definitionRef.current = definition;
     const optionsRef = useRef(options);
@@ -12,16 +14,17 @@ export function useMutation(definition, options = {}) {
     const run = useCallback(async (input) => {
         try {
             return await executeMutation({
-                mutate: (ast) => store.mutate(ast, {
+                mutate: (ast, graphOptions) => store.mutate(ast, {
+                    ...graphOptions,
                     optimistic: optionsRef.current.optimistic ?? true,
                 }),
-            }, definitionRef.current, input);
+            }, domain, definitionRef.current, input);
         }
         catch (error) {
             optionsRef.current.onError?.(error);
             throw error;
         }
-    }, [store]);
+    }, [store, domain]);
     const action = useAsyncAction(run);
     return useMemo(() => project(action), [action]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/shell-react",
-  "version": "0.3.2-beta",
+  "version": "0.3.2-beta.1",
   "description": "Astrale shell-react — the React face of the shell (provider, hooks, view components)",
   "license": "Apache-2.0",
   "repository": {
@@ -26,12 +26,12 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "@astrale-os/shell": ">=0.4.2-beta <1.0.0",
     "jose": "^6.2.8",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@astrale-os/sdk": "0.5.0-beta.22",
-    "@astrale-os/shell": "0.4.2-beta",
+    "@astrale-os/sdk": "0.5.0-beta.32",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.3.0",
     "@types/node": "^26.2.0",
@@ -46,8 +46,7 @@
     "vitest": "4.1.10"
   },
   "peerDependencies": {
-    "@astrale-os/sdk": ">=0.5.0-beta.22 <1.0.0",
-    "@astrale-os/shell": ">=0.4.2-beta <1.0.0",
+    "@astrale-os/sdk": ">=0.5.0-beta.32 <1.0.0",
     "react": ">=18",
     "react-dom": ">=18"
   },
@@ -57,7 +56,6 @@
     "clean": "rm -rf dist *.tsbuildinfo",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
-    "test:watch": "vitest",
-    "preinstall": "node -e \"try{require('./.check-workspace.cjs')}catch{}\""
+    "test:watch": "vitest"
   }
 }

package/src/graph/query-definition.hook.ts

@@ -1,12 +1,14 @@
 import type { QueryPageRequest } from '@astrale-os/sdk/client'
 import type { GraphStore, StoreQueryResponse, StoreSnapshot } from '@astrale-os/sdk/client/store'
 import type { QueryAST, QueryDefinition } from '@astrale-os/sdk/query'
+import type { Domain } from '@astrale-os/sdk/schema'
 
 import { executeQuery } from '@astrale-os/sdk/query'
 import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
 
 import type { GraphResource, GraphResourceState } from './resource.js'
 
+import { useExecutionDomain } from '../schema/domain.context.js'
 import { retainRefreshScheduler } from './resource.js'
 import { useGraphStore } from './store.js'
 
@@ -18,7 +20,10 @@ export interface QueryResourceOptions {
 
 interface TouchedShape {
   readonly ast: QueryAST
-  readonly options: { readonly page: QueryPageRequest }
+  readonly options: {
+    readonly page: QueryPageRequest
+    readonly expected?: Domain['closure']
+  }
 }
 
 interface DefinitionSnapshot<Output> {
@@ -27,7 +32,7 @@ interface DefinitionSnapshot<Output> {
   readonly error?: unknown
 }
 
-class DefinitionObserver<Input, Output> {
+class DefinitionObserver<DomainValue extends Domain, Input, Output> {
   private readonly listeners = new Set<() => void>()
   private subscriptions: readonly (() => void)[] = Object.freeze([])
   private touched: readonly TouchedShape[] = Object.freeze([])
@@ -39,7 +44,8 @@ class DefinitionObserver<Input, Output> {
 
   constructor(
     private readonly store: GraphStore,
-    private readonly definition: QueryDefinition<Input, Output>,
+    private readonly domain: DomainValue,
+    private readonly definition: QueryDefinition<DomainValue, Input, Output>,
     private readonly input: Input,
   ) {}
 
@@ -75,12 +81,12 @@ class DefinitionObserver<Input, Output> {
     })
     const execute = async <Ast extends QueryAST>(
       ast: Ast,
-      options: { readonly page: QueryPageRequest },
+      options: { readonly page: QueryPageRequest; readonly expected?: Domain['closure'] },
     ): Promise<StoreQueryResponse<Ast>> => {
       touched.push(Object.freeze({ ast, options }))
       return this.store.read(ast, { ...options, freshness })
     }
-    const running = executeQuery({ query: execute }, this.definition, this.input)
+    const running = executeQuery({ query: execute }, this.domain, this.definition, this.input)
       .then((data) => {
         if (!this.started || generation !== this.generation) return
         this.touched = dedupeShapes(touched)
@@ -148,16 +154,17 @@ class DefinitionObserver<Input, Output> {
 }
 
 /** Execute one named SDK Query definition exclusively through the current GraphStore. */
-export function useQuery<Input, Output>(
-  definition: QueryDefinition<Input, Output> | null,
+export function useQuery<DomainValue extends Domain, Input, Output>(
+  definition: QueryDefinition<DomainValue, Input, Output> | null,
   input: Input,
   options: QueryResourceOptions = {},
 ): GraphResource<Output> {
   const store = useGraphStore()
+  const domain = useExecutionDomain<DomainValue>()
   const inputIdentity = stableIdentity(input)
   const observer = useMemo(
-    () => (definition === null ? null : new DefinitionObserver(store, definition, input)),
-    [store, definition, inputIdentity],
+    () => (definition === null ? null : new DefinitionObserver(store, domain, definition, input)),
+    [store, domain, definition, inputIdentity],
   )
   const idle = useMemo<DefinitionSnapshot<Output>>(() => Object.freeze({ state: 'idle' }), [])
   const subscribe = useCallback(
@@ -168,7 +175,8 @@ export function useQuery<Input, Output>(
   const current = useSyncExternalStore(subscribe, snapshot, snapshot)
   useEffect(() => observer?.start(), [observer])
 
-  const identity = definition === null ? 'idle' : `${definition.id}\u0000${inputIdentity}`
+  const identity =
+    definition === null ? 'idle' : `${definitionIdentity(definition)}\u0000${inputIdentity}`
   useEffect(() => {
     if (observer === null || options.refreshInterval === undefined) return
     return retainRefreshScheduler(
@@ -210,6 +218,17 @@ export function useQuery<Input, Output>(
   )
 }
 
+const definitionIdentities = new WeakMap<object, number>()
+let nextDefinitionIdentity = 1
+
+function definitionIdentity(definition: object): number {
+  const retained = definitionIdentities.get(definition)
+  if (retained !== undefined) return retained
+  const created = nextDefinitionIdentity++
+  definitionIdentities.set(definition, created)
+  return created
+}
+
 function dedupeShapes(input: readonly TouchedShape[]): readonly TouchedShape[] {
   const seen = new Set<string>()
   return Object.freeze(

package/src/index.ts

@@ -39,6 +39,7 @@ export type {
 
 // Rich exact Domain bindings.
 export {
+  DomainProvider,
   RelationUnavailableError,
   queryRefresh,
   useAction,
@@ -54,6 +55,7 @@ export {
 export type {
   ActionOptions,
   ActionRefresh,
+  DomainProviderProps,
   DomainAction,
   MutationOptions,
   QueryRefresh,

package/src/schema/action.hook.ts

@@ -1,7 +1,8 @@
 import type { BoundNodeFor } from '@astrale-os/sdk/client'
 import type { SessionRequestOptions } from '@astrale-os/sdk/client/session'
 import type { NodeId } from '@astrale-os/sdk/graph/node'
-import type { QueryAST } from '@astrale-os/sdk/query'
+import type { QueryAST, QueryDefinition } from '@astrale-os/sdk/query'
+import type { Domain } from '@astrale-os/sdk/schema'
 import type {
   CallableInputOf,
   CallableResultOf,
@@ -13,6 +14,7 @@ import type {
 
 import { reference } from '@astrale-os/sdk/client/session'
 import { Path } from '@astrale-os/sdk/graph/path'
+import { realizeQuery } from '@astrale-os/sdk/query'
 import { useCallback, useMemo, useRef } from 'react'
 
 import type { Action as AsyncAction } from '../graph/action.js'
@@ -33,29 +35,30 @@ const QUERY_REFRESH = Symbol('shell-react.query-refresh')
 
 export interface QueryRefresh {
   readonly id: string
-  readonly [QUERY_REFRESH]: () => {
+  readonly [QUERY_REFRESH]: (domain: Domain) => {
     readonly ast: QueryAST
     readonly page: Readonly<{ readonly size: number }>
   }
 }
 
-type RefreshableQuery<Input, Query extends QueryAST> = {
-  readonly id: string
-  readonly page: Readonly<{ readonly size: number }>
-  prepare?(input: Input): Input
-  build(input: Input): Query
-}
+const queryRefreshIdentities = new WeakMap<object, string>()
+let nextQueryRefreshIdentity = 0
 
 /** Pair one exact named Query definition with its admitted input for targeted invalidation. */
-export function queryRefresh<Input, Query extends QueryAST>(
-  definition: RefreshableQuery<Input, Query>,
+export function queryRefresh<DomainValue extends Domain, Input, Output>(
+  definition: QueryDefinition<DomainValue, Input, Output>,
   input: Input,
 ): QueryRefresh {
+  const id = queryRefreshIdentity(definition)
   return Object.freeze({
-    id: definition.id,
-    [QUERY_REFRESH]: () => {
-      const prepared = definition.prepare?.(input) ?? input
-      return Object.freeze({ ast: definition.build(prepared), page: definition.page })
+    id,
+    [QUERY_REFRESH]: (domain: Domain) => {
+      const realized = realizeQuery(definition, domain as DomainValue)
+      if (realized.kind !== 'single') {
+        throw new TypeError('Targeted refresh requires a single Query recipe.')
+      }
+      const prepared = realized.prepare?.(input) ?? input
+      return Object.freeze({ ast: realized.build(prepared), page: realized.page })
     },
   })
 }
@@ -120,7 +123,7 @@ export function useAction<C extends Callable>(
         if (refresh === 'all') store.invalidate()
         else if (refresh !== 'none') {
           refresh.queries.forEach((query) => {
-            const target = query[QUERY_REFRESH]()
+            const target = query[QUERY_REFRESH](bindingRef.current.domain)
             store.invalidate(target.ast, { page: target.page })
           })
         }
@@ -161,3 +164,11 @@ function isInstanceMethod(callable: Callable): callable is InstanceMethod {
 function receiverPath(receiver: Receiver): Path {
   return Path.id(receiver.id)
 }
+
+function queryRefreshIdentity(definition: object): string {
+  const current = queryRefreshIdentities.get(definition)
+  if (current !== undefined) return current
+  const created = `query-${++nextQueryRefreshIdentity}`
+  queryRefreshIdentities.set(definition, created)
+  return created
+}

package/src/schema/domain.context.tsx

@@ -0,0 +1,31 @@
+import type { Domain } from '@astrale-os/sdk/schema'
+import type { schema } from '@astrale-os/sdk/schema'
+import type { ReactElement, ReactNode } from 'react'
+
+import { createContext, useContext } from 'react'
+
+import { useDomain } from './domain.hook.js'
+
+const DomainContext = createContext<Domain | null>(null)
+DomainContext.displayName = 'AstraleDomainContext'
+
+export interface DomainProviderProps<Schema extends schema.DomainSchema> {
+  readonly schema: Schema
+  readonly children: ReactNode
+}
+
+/** Resolve one exact installed Domain for every projected recipe in the React subtree. */
+export function DomainProvider<const Schema extends schema.DomainSchema>(
+  props: DomainProviderProps<Schema>,
+): ReactElement {
+  const binding = useDomain(props.schema)
+  return <DomainContext.Provider value={binding.domain}>{props.children}</DomainContext.Provider>
+}
+
+export function useExecutionDomain<DomainValue extends Domain>(): DomainValue {
+  const domain = useContext(DomainContext)
+  if (domain === null) {
+    throw new Error('Projected Query and Mutation hooks require a surrounding DomainProvider.')
+  }
+  return domain as DomainValue
+}

package/src/schema/index.ts

@@ -1,5 +1,7 @@
 export { useKernel } from './kernel.hook.js'
 export { useDomain, useDomains, useDynamicDomain } from './domain.hook.js'
+export { DomainProvider } from './domain.context.js'
+export type { DomainProviderProps } from './domain.context.js'
 export { queryRefresh, useAction } from './action.hook.js'
 export type { ActionOptions, ActionRefresh, DomainAction, QueryRefresh } from './action.hook.js'
 export { useMutation } from './mutation.hook.js'

package/src/schema/mutation.hook.ts

@@ -1,4 +1,5 @@
 import type { Mutation } from '@astrale-os/sdk/mutation'
+import type { Domain } from '@astrale-os/sdk/schema'
 
 import { executeMutation } from '@astrale-os/sdk/mutation'
 import { useCallback, useMemo, useRef } from 'react'
@@ -8,6 +9,7 @@ import type { DomainAction } from './action.hook.js'
 
 import { useAction as useAsyncAction } from '../graph/action.js'
 import { useGraphStore } from '../graph/store.js'
+import { useExecutionDomain } from './domain.context.js'
 
 export interface MutationOptions {
   readonly optimistic?: boolean
@@ -15,11 +17,12 @@ export interface MutationOptions {
 }
 
 /** Execute one named SDK Mutation definition through GraphStore optimism/invalidation. */
-export function useMutation<Input, Output>(
-  definition: Mutation<Input, Output>,
+export function useMutation<DomainValue extends Domain, Input, Output>(
+  definition: Mutation<DomainValue, Input, Output>,
   options: MutationOptions = {},
 ): DomainAction<[Input], Output> {
   const store = useGraphStore()
+  const domain = useExecutionDomain<DomainValue>()
   const definitionRef = useRef(definition)
   definitionRef.current = definition
   const optionsRef = useRef(options)
@@ -29,11 +32,13 @@ export function useMutation<Input, Output>(
       try {
         return await executeMutation(
           {
-            mutate: (ast) =>
+            mutate: (ast, graphOptions) =>
               store.mutate(ast, {
+                ...graphOptions,
                 optimistic: optionsRef.current.optimistic ?? true,
               }),
           },
+          domain,
           definitionRef.current,
           input,
         )
@@ -42,7 +47,7 @@ export function useMutation<Input, Output>(
         throw error
       }
     },
-    [store],
+    [store, domain],
   )
   const action = useAsyncAction(run)
   return useMemo(() => project(action), [action])