Extension framework optimization

docs/extension-authoring.md

@@ -94,6 +94,58 @@ Subsystem-specific dataclasses may remain richer. The canonical model is the
 bridge that lets callbacks, registries, diagnostics, provenance, and future
 policy checks interact consistently.
 
+### Minimal Runnable Extension
+
+```python
+from markitect_tool.extension import (
+    ExtensionDescriptor,
+    ExtensionExecutor,
+    ExtensionRegistry,
+    ProcessingRequest,
+    ProcessingResult,
+)
+
+
+def run_example(request: ProcessingRequest) -> ProcessingResult:
+    name = request.input.get("name", "world")
+    return ProcessingResult(output=f"Hello, {name}")
+
+
+descriptor = ExtensionDescriptor(
+    id="example.hello",
+    kind="example",
+    summary="Small example extension.",
+    factory=lambda: run_example,
+)
+
+registry = ExtensionRegistry([descriptor])
+result = ExtensionExecutor(registry).execute(
+    "example.hello",
+    ProcessingRequest(operation="example.hello", input={"name": "Markitect"}),
+)
+```
+
+Use this executor boundary when callbacks, dependency checks, trace events, or
+future policy checks matter. For tiny deterministic helpers, it is still fine to
+keep the existing direct function API and expose a descriptor alongside it.
+
+### Cache-Key Rules
+
+`ProcessingRequest.cache_key` includes:
+
+- operation
+- input
+- stable context material
+- options
+- scope
+- declared capabilities
+- request metadata
+
+Stable context material includes source path, namespaces, variables, policy, and
+metadata. It does not include workspace root, caller, or live backend handles.
+This keeps cache keys portable while avoiding collisions for context-sensitive
+operations.
+
 ## Diagnostics
 
 Diagnostics should be: