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>

backends/mizan-fastapi/src/mizan_fastapi/executor.py

@@ -12,9 +12,11 @@ from __future__ import annotations
 from enum import Enum
 from typing import Any
 
+from fastapi.encoders import jsonable_encoder
 from pydantic import BaseModel, ValidationError
 
-from mizan_core.registry import get_function
+from mizan_core.registry import get_context_groups, get_function
+from mizan_core.type_utils import types_match_for_merge
 
 
 # ─── Error taxonomy ─────────────────────────────────────────────────────────
@@ -148,15 +150,21 @@ def _resolve_function(fn_name: str) -> Any:
 
 
 def _serialize(result: Any) -> Any:
-    return result.model_dump(mode="json") if isinstance(result, BaseModel) else result
+    # jsonable_encoder walks BaseModel / list / dict recursively, so list[BaseModel]
+    # (and nested shapes) come out wire-ready without a per-shape branch here.
+    return jsonable_encoder(result)
 
 
-def execute_function(
+async def execute_function(
     request: Any,
     fn_name: str,
     input_data: dict[str, Any] | None = None,
 ) -> Any:
-    """Dispatch a registered function. Returns the serialized result, or raises MizanError."""
+    """Dispatch a registered function. Returns the serialized result, or raises MizanError.
+
+    Awaits `view.acall` — async handlers run on the loop, sync handlers run
+    in the default threadpool, both via the same entrypoint.
+    """
     view_class = _resolve_function(fn_name)
     _enforce_auth(request, view_class._meta.get("auth"))
 
@@ -164,7 +172,7 @@ def execute_function(
     validated = _validate_input(view.Input, input_data)
 
     try:
-        result = view.call(validated)
+        result = await view.acall(validated)
     except NotImplementedError as e:
         raise NotImplementedYet(str(e) or "Not implemented") from e
     except MizanError:
@@ -184,12 +192,70 @@ def compute_invalidation(view_class: Any, input_data: dict[str, Any] | None) ->
     return [_invalidation_target(target, input_data or {}) for target in affects]
 
 
+def compute_merges(view_class: Any, input_data: dict[str, Any] | None, result: Any) -> list[dict[str, Any]]:
+    """Build the `merge` list from @client(merge=...) metadata.
+
+    Each entry is `{context, slot, value, params?}` where `slot` names the
+    function inside the context bundle the value lands in. The slot is
+    resolved server-side via `types_match_for_merge` so the kernel does
+    no shape inference — the server has the schema, type-checked routing
+    lives here. Entries whose slot can't be uniquely resolved are dropped
+    with a warning; the consumer falls back to refetch via `affects`.
+    """
+    targets = getattr(view_class, "_meta", {}).get("merge") or []
+    if not targets:
+        return []
+    mutation_output = getattr(view_class, "Output", None)
+    out: list[dict[str, Any]] = []
+    for ctx_name in targets:
+        slot = _resolve_merge_slot(ctx_name, mutation_output)
+        if slot is None:
+            continue
+        entry: dict[str, Any] = {"context": ctx_name, "slot": slot, "value": result}
+        scoped = _scoped_params(ctx_name, input_data or {})
+        if scoped:
+            entry["params"] = scoped
+        out.append(entry)
+    return out
+
+
+def _resolve_merge_slot(context_name: str, mutation_output: Any) -> str | None:
+    """Find the unique function-name slot whose return type matches the mutation's output.
+
+    Returns None on no match or ambiguous match (multiple candidates).
+    """
+    if mutation_output is None:
+        return None
+    matches: list[str] = []
+    for fn_name in get_context_groups().get(context_name, []):
+        fn_cls = get_function(fn_name)
+        if fn_cls is None:
+            continue
+        fn_output = getattr(fn_cls, "Output", None)
+        if fn_output is not None and types_match_for_merge(fn_output, mutation_output):
+            matches.append(fn_name)
+    return matches[0] if len(matches) == 1 else None
+
+
+def _scoped_params(context_name: str, input_data: dict[str, Any]) -> dict[str, Any]:
+    """Match input args against the context's declared Input field names."""
+    fn_names = get_context_groups().get(context_name, [])
+    declared: set[str] = set()
+    for fn_name in fn_names:
+        fn_cls = get_function(fn_name)
+        if fn_cls is None:
+            continue
+        input_cls = getattr(fn_cls, "Input", None)
+        if input_cls and input_cls is not BaseModel and hasattr(input_cls, "model_fields"):
+            declared.update(input_cls.model_fields.keys())
+    return {k: v for k, v in input_data.items() if k in declared}
+
+
 def _invalidation_target(target: dict[str, Any], input_data: dict[str, Any]) -> Any:
     match target.get("type"):
         case "context":
             name = target["name"]
-            scope_keys = (target.get("params") or {}).keys()
-            scoped = {k: input_data[k] for k in scope_keys if k in input_data}
+            scoped = _scoped_params(name, input_data)
             return {"context": name, "params": scoped} if scoped else name
         case "function":
             return {"function": target["name"]}

backends/mizan-fastapi/src/mizan_fastapi/router.py

@@ -28,6 +28,7 @@ from .executor import (
     MizanError,
     NotFound,
     compute_invalidation,
+    compute_merges,
     execute_function,
 )
 
@@ -49,10 +50,15 @@ class CallBody(BaseModel):
 
 @router.post("/call/")
 async def function_call(body: CallBody, request: Request) -> JSONResponse:
-    """RPC dispatch — `{"fn": "...", "args": {...}}` → `{"result": ..., "invalidate": [...]}`."""
-    result = execute_function(request, body.fn, body.args)
-    invalidate = compute_invalidation(get_function(body.fn), body.args)
-    return _no_store({"result": result, "invalidate": invalidate})
+    """RPC dispatch — `{"fn": "...", "args": {...}}` → `{"result": ..., "invalidate": [...], "merge"?: [...]}`."""
+    fn_class = get_function(body.fn)
+    result = await execute_function(request, body.fn, body.args)
+    invalidate = compute_invalidation(fn_class, body.args)
+    merges = compute_merges(fn_class, body.args, result)
+    payload: dict[str, Any] = {"result": result, "invalidate": invalidate}
+    if merges:
+        payload["merge"] = merges
+    return _no_store(payload)
 
 
 @router.get("/ctx/{context_name}/")
@@ -63,7 +69,7 @@ async def context_fetch(context_name: str, request: Request) -> JSONResponse:
         raise NotFound(f"Context '{context_name}' not found")
 
     params = dict(request.query_params)
-    bundled = {fn: execute_function(request, fn, params) for fn in fn_names}
+    bundled = {fn: await execute_function(request, fn, params) for fn in fn_names}
     return _no_store(bundled)