Mutation→context merge primitive across the stack

The @client(merge=[context, ...]) decorator lets a mutation patch its
return value directly into the cached context bundle by matching the
mutation's Output type against each context-function's Output type
to identify the slot, then splicing server-side. Kernel runs
splice_slot on the response to apply locally — no refetch, no
invalidate-cascade.

Lands H14, H15, H16, M19, M20 from ISSUES.md.

Backends (Django + FastAPI):
  _resolve_merges() in both executors walks @client(merge=...) targets,
  resolves the per-context slot via types_match_for_merge, and emits
  {context, slot, value, params?} entries on the response. Param
  auto-scoping mirrors _resolve_invalidation's tier-1 logic.

Frontend kernel (mizan-base):
  Response handler reads the merge[] array and applies splice_slot
  for each entry — locates the cached context bundle by name+params,
  overwrites the named slot with the new value, notifies subscribers.

Core (mizan-python):
  @client decorator extended with merge= parameter. Schema export
  threads merge metadata onto the OpenAPI x-mizan-functions entries.

Examples / fixtures:
  fastapi-react-site harness exercises merge + Playwright spec covers
  the end-to-end happy path (mutation → instant UI update without
  network refetch). AFI fixture's rename_user function is the
  canonical merge target.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cores/mizan-python/src/mizan_core/client/function.py

@@ -19,6 +19,7 @@ Two styles supported:
 
 from __future__ import annotations
 
+import asyncio
 import inspect
 import warnings
 from abc import ABC, abstractmethod
@@ -165,6 +166,16 @@ class ServerFunction(ABC, Generic[TInput, TOutput]):
         """
         raise NotImplementedError(f"{self.__class__.__name__} must implement call()")
 
+    async def acall(self, input: TInput) -> TOutput:
+        """
+        Async entrypoint for dispatch on event-loop-driven adapters (FastAPI).
+
+        Default: run the sync `call` in a threadpool so it doesn't block the
+        loop. Subclasses with native-async handlers override this to await
+        the handler directly.
+        """
+        return await asyncio.to_thread(self.call, input)
+
     @classmethod
     def get_schema_export(cls) -> dict[str, Any]:
         """Export schema for TypeScript generation."""
@@ -207,17 +218,30 @@ class _FunctionWrapper(ServerFunction):
 
     def call(self, input):
         """Execute the wrapped function, unpacking input into individual args."""
-        if input is not None and self._param_names:
-            # Unpack validated model into keyword arguments
-            kwargs = {name: getattr(input, name) for name in self._param_names}
-            result = self._wrapped_fn(self.request, **kwargs)
-        else:
-            result = self._wrapped_fn(self.request)
+        return self._postprocess(self._invoke_sync(input))
 
+    async def acall(self, input):
+        """Async dispatch. Awaits async handlers directly; sync handlers run
+        in a threadpool via the super's default `acall`."""
+        if not inspect.iscoroutinefunction(self._wrapped_fn):
+            return await super().acall(input)
+        if input is not None and self._param_names:
+            kwargs = {name: getattr(input, name) for name in self._param_names}
+            result = await self._wrapped_fn(self.request, **kwargs)
+        else:
+            result = await self._wrapped_fn(self.request)
+        return self._postprocess(result)
+
+    def _invoke_sync(self, input):
+        if input is not None and self._param_names:
+            kwargs = {name: getattr(input, name) for name in self._param_names}
+            return self._wrapped_fn(self.request, **kwargs)
+        return self._wrapped_fn(self.request)
+
+    def _postprocess(self, result):
         # View path — return a framework-native response directly (no serialization)
         if is_framework_response(result):
             return result
-
         # Wrap primitive returns in the generated output model
         if self._is_primitive_output:
             return self._output_cls(result=result)
@@ -276,12 +300,18 @@ def _resolve_context(context: ContextMode) -> str | Literal[False]:
 AffectsTarget = ReactContext | str | type["ServerFunction"]
 AffectsMode = AffectsTarget | list[AffectsTarget] | None
 
+# Merge parameter type — targets a context by name, kernel splices the return
+# value into the cached entry rather than triggering a refetch.
+MergeTarget = ReactContext | str
+MergeMode = MergeTarget | list[MergeTarget] | None
+
 
 def client(
     fn: Callable = None,
     *,
     context: ContextMode = False,
     affects: AffectsMode = None,
+    merge: MergeMode = None,
     private: bool = False,
     route: str | None = None,
     methods: list[str] | None = None,
@@ -303,6 +333,12 @@ def client(
             Mutually exclusive with context=.
             Scoping is automatic via argument name matching.
 
+        merge: Declare which contexts the mutation's return value merges into.
+            The kernel splices the return value into the cached entry rather
+            than triggering a refetch — fits high-frequency UI (slider drags,
+            color pickers) where the server already knows the exact change.
+            Mutually exclusive with context=. Composes with affects=.
+
         private: If True, the function is not client-callable.
             - Not exposed as an RPC endpoint
             - No generated TypeScript
@@ -352,6 +388,13 @@ def client(
                 "A function cannot be both a context reader and a mutation."
             )
 
+    # Validate merge parameter
+    if merge is not None and resolved_context is not False:
+        raise ValueError(
+            "context= and merge= are mutually exclusive. "
+            "A function cannot be both a context reader and a mutation."
+        )
+
     # Validate auth parameter
     if auth is not None:
         if isinstance(auth, str) and auth not in _VALID_AUTH_STRINGS:
@@ -362,7 +405,7 @@ def client(
 
     def decorator(fn: Callable) -> type[ServerFunction]:
         return _create_server_function(
-            fn, context=resolved_context, affects=affects,
+            fn, context=resolved_context, affects=affects, merge=merge,
             private=private, route=route, methods=methods,
             websocket=websocket, auth=auth, rev=rev, cache=cache,
         )
@@ -370,13 +413,32 @@ def client(
     # Support both @client and @client(...)
     if fn is not None:
         return _create_server_function(
-            fn, context=resolved_context, affects=affects,
+            fn, context=resolved_context, affects=affects, merge=merge,
             private=private, route=route, methods=methods,
             websocket=websocket, auth=auth, rev=rev, cache=cache,
         )
     return decorator
 
 
+def _normalize_merge(merge: MergeMode) -> list[str] | None:
+    """Normalize merge param to a list of context name strings."""
+    if merge is None:
+        return None
+    items = merge if isinstance(merge, list) else [merge]
+    result: list[str] = []
+    for item in items:
+        if isinstance(item, ReactContext):
+            result.append(item.name)
+        elif isinstance(item, str):
+            result.append(item)
+        else:
+            raise ValueError(
+                f"merge items must be ReactContext instances or context name strings. "
+                f"Got {type(item).__name__}."
+            )
+    return result
+
+
 def _normalize_affects(affects: AffectsMode) -> list[dict[str, str]] | None:
     """Normalize the affects parameter into a list of target descriptors."""
     if affects is None:
@@ -410,6 +472,7 @@ def _create_server_function(
     *,
     context: str | Literal[False] = False,
     affects: str | type["ServerFunction"] | list[str | type["ServerFunction"]] | None = None,
+    merge: MergeMode = None,
     private: bool = False,
     route: str | None = None,
     methods: list[str] | None = None,
@@ -468,25 +531,9 @@ def _create_server_function(
         is_primitive_output = False
     else:
         # RPC path — resolve output type
-        import types
+        from mizan_core.type_utils import is_structured_output
 
-        def is_basemodel_type(t: Any) -> bool:
-            """Check if type is a BaseModel subclass, handling Optional/Union."""
-            if isinstance(t, type) and issubclass(t, BaseModel):
-                return True
-            origin = get_origin(t)
-            if origin is Union or isinstance(t, types.UnionType):
-                args = get_args(t)
-                for arg in args:
-                    if (
-                        arg is not type(None)
-                        and isinstance(arg, type)
-                        and issubclass(arg, BaseModel)
-                    ):
-                        return True
-            return False
-
-        if is_basemodel_type(output_type):
+        if is_structured_output(output_type):
             output_cls = output_type
             is_primitive_output = False
         else:
@@ -538,6 +585,11 @@ def _create_server_function(
     if normalized_affects:
         meta["affects"] = normalized_affects
 
+    # Merge: contexts to splice the return value into (vs refetch)
+    normalized_merge = _normalize_merge(merge)
+    if normalized_merge:
+        meta["merge"] = normalized_merge
+
     # WebSocket: enable WebSocket transport
     if websocket:
         meta["websocket"] = True