docs: align contract docs with canonical events and stable source references

CONTRACTS.md

@@ -186,20 +186,21 @@ These types stay as Python by design — they are app-layer concerns, not kernel
 
 ## Event Constants
 
-Rust defines event names in `crates/amplifier-core/src/events.rs`. Python defines
-them as class-level constants on `HookRegistry` in `hooks.py`. They must be
-identical strings:
+Canonical event names are defined in `crates/amplifier-core/src/events.rs` (Rust)
+and re-exported in `amplifier_core.events` (Python). The full set contains 41+
+events; the table below lists the most commonly referenced ones. Always use the
+constants from the events module rather than hard-coding strings.
 
 | Event | Value |
 |-------|-------|
+| Execution start | `"execution:start"` |
+| Execution end | `"execution:end"` |
 | Session start | `"session:start"` |
 | Session end | `"session:end"` |
-| Turn start | `"turn:start"` |
-| Turn end | `"turn:end"` |
+| LLM request | `"llm:request"` |
+| LLM response | `"llm:response"` |
 | Tool pre | `"tool:pre"` |
 | Tool post | `"tool:post"` |
-| LLM pre | `"llm:pre"` |
-| LLM post | `"llm:post"` |
 | Context compaction | `"context:compaction"` |
 
 ---

docs/HOOKS_API.md

@@ -5,7 +5,7 @@ last_modified: 2025-01-29
 related_contracts:
   - path: contracts/HOOK_CONTRACT.md
     relationship: contract_hub
-  - path: ../amplifier_core/interfaces.py#HookHandler
+  - path: ../python/amplifier_core/interfaces.py#HookHandler
     relationship: protocol_definition
     lines: 205-220
 ---

docs/contracts/CONTEXT_CONTRACT.md

@@ -4,14 +4,13 @@ module_type: context
 contract_version: 2.1.0
 last_modified: 2026-01-01
 related_files:
-  - path: amplifier_core/interfaces.py#ContextManager
+  - path: ../../python/amplifier_core/interfaces.py#ContextManager
     relationship: protocol_definition
-    lines: 148-180
   - path: ../specs/MOUNT_PLAN_SPECIFICATION.md
     relationship: configuration
   - path: ../specs/CONTRIBUTION_CHANNELS.md
     relationship: observability
-  - path: amplifier_core/testing.py#MockContextManager
+  - path: ../../python/amplifier_core/testing.py#MockContextManager
     relationship: test_utilities
 canonical_example: https://github.com/microsoft/amplifier-module-context-simple
 ---
@@ -38,7 +37,7 @@ Context managers control **what the agent remembers**:
 
 ## Protocol Definition
 
-**Source**: `amplifier_core/interfaces.py` lines 148-180
+**Source**: `amplifier_core/interfaces.py` → `class ContextManager(Protocol)`
 
 ```python
 @runtime_checkable

docs/contracts/HOOK_CONTRACT.md

@@ -4,18 +4,17 @@ module_type: hook
 contract_version: 1.0.0
 last_modified: 2025-01-29
 related_files:
-  - path: amplifier_core/interfaces.py#HookHandler
+  - path: ../../python/amplifier_core/interfaces.py#HookHandler
     relationship: protocol_definition
-    lines: 205-220
-  - path: amplifier_core/models.py#HookResult
+  - path: ../../python/amplifier_core/models.py#HookResult
     relationship: result_model
   - path: ../HOOKS_API.md
     relationship: detailed_api
   - path: ../specs/MOUNT_PLAN_SPECIFICATION.md
     relationship: configuration
   - path: ../specs/CONTRIBUTION_CHANNELS.md
     relationship: observability
-  - path: amplifier_core/testing.py#EventRecorder
+  - path: ../../python/amplifier_core/testing.py#EventRecorder
     relationship: test_utilities
 canonical_example: https://github.com/microsoft/amplifier-module-hooks-logging
 ---
@@ -52,7 +51,7 @@ This contract provides the essentials. The API reference contains full details.
 
 ## Protocol Definition
 
-**Source**: `amplifier_core/interfaces.py` lines 205-220
+**Source**: `amplifier_core/interfaces.py` → `class HookHandler(Protocol)`
 
 ```python
 @runtime_checkable

docs/contracts/ORCHESTRATOR_CONTRACT.md

@@ -4,16 +4,15 @@ module_type: orchestrator
 contract_version: 1.0.0
 last_modified: 2026-03-05
 related_files:
-  - path: amplifier_core/interfaces.py#Orchestrator
+  - path: ../../python/amplifier_core/interfaces.py#Orchestrator
     relationship: protocol_definition
-    lines: 26-55
-  - path: amplifier_core/content_models.py
+  - path: ../../python/amplifier_core/content_models.py
     relationship: event_content_types
   - path: ../specs/MOUNT_PLAN_SPECIFICATION.md
     relationship: configuration
   - path: ../specs/CONTRIBUTION_CHANNELS.md
     relationship: observability
-  - path: amplifier_core/testing.py#ScriptedOrchestrator
+  - path: ../../python/amplifier_core/testing.py#ScriptedOrchestrator
     relationship: test_utilities
 canonical_example: https://github.com/microsoft/amplifier-module-loop-basic
 ---
@@ -38,7 +37,7 @@ Orchestrators control **how** agents execute:
 
 ## Protocol Definition
 
-**Source**: `amplifier_core/interfaces.py` lines 26-52
+**Source**: `amplifier_core/interfaces.py` → `class Orchestrator(Protocol)`
 
 ```python
 @runtime_checkable
@@ -50,7 +49,7 @@ class Orchestrator(Protocol):
         providers: dict[str, Provider],
         tools: dict[str, Tool],
         hooks: HookRegistry,
-        coordinator: ModuleCoordinator | None = None,
+        **kwargs: Any,
     ) -> str:
         """
         Execute the agent loop with given prompt.
@@ -61,15 +60,20 @@ class Orchestrator(Protocol):
             providers: Available LLM providers (keyed by name)
             tools: Available tools (keyed by name)
             hooks: Hook registry for lifecycle events
-            coordinator: Module coordinator for accessing shared services
-                         (optional; passed by session.py in production)
+            **kwargs: Additional kernel-injected arguments (see note below)
 
         Returns:
             Final response string
         """
         ...
 ```
 
+> **`coordinator` injection**: The kernel (`session.py`) passes
+> `coordinator=<ModuleCoordinator>` via kwargs at runtime so orchestrators can
+> process hook results and coordinate module interactions. Implementations may
+> accept `coordinator` as an explicit keyword argument or simply absorb it
+> through `**kwargs`.
+
 ---
 
 ## Execution Flow
@@ -200,7 +204,7 @@ async def execute(self, prompt, context, providers, tools, hooks):
 - `execution:end` MUST be emitted on **ALL exit paths** — normal completion, error, and cancellation
 
 ```python
-async def execute(self, prompt, context, providers, tools, hooks, coordinator=None):
+async def execute(self, prompt, context, providers, tools, hooks, **kwargs):
     # REQUIRED: Emit at the very start of execute()
     await hooks.emit("execution:start", {"prompt": prompt})
 
@@ -369,7 +373,7 @@ Additional examples:
 
 ### Required
 
-- [ ] Implements `execute(prompt, context, providers, tools, hooks, coordinator=None) -> str`
+- [ ] Implements `execute(prompt, context, providers, tools, hooks, **kwargs) -> str`
 - [ ] `mount()` function with entry point in pyproject.toml
 - [ ] **Emits `execution:start` with `{prompt}` at the very beginning of `execute()`**
 - [ ] **Emits `execution:end` with `{response, status}` on ALL exit paths (success, error, cancellation)**

docs/contracts/PROVIDER_CONTRACT.md

@@ -4,22 +4,21 @@ module_type: provider
 contract_version: 1.0.0
 last_modified: 2025-01-29
 related_files:
-  - path: amplifier_core/interfaces.py#Provider
+  - path: ../../python/amplifier_core/interfaces.py#Provider
     relationship: protocol_definition
-    lines: 54-119
-  - path: amplifier_core/message_models.py
+  - path: ../../python/amplifier_core/message_models.py
     relationship: request_response_models
-  - path: amplifier_core/content_models.py
+  - path: ../../python/amplifier_core/content_models.py
     relationship: event_content_types
-  - path: amplifier_core/models.py#ProviderInfo
+  - path: ../../python/amplifier_core/models.py#ProviderInfo
     relationship: metadata_models
   - path: ../specs/PROVIDER_SPECIFICATION.md
     relationship: detailed_spec
   - path: ../specs/MOUNT_PLAN_SPECIFICATION.md
     relationship: configuration
   - path: ../specs/CONTRIBUTION_CHANNELS.md
     relationship: observability
-  - path: amplifier_core/testing.py
+  - path: ../../python/amplifier_core/testing.py
     relationship: test_utilities
 canonical_example: https://github.com/microsoft/amplifier-module-provider-anthropic
 ---
@@ -46,7 +45,7 @@ This contract document provides the quick-reference essentials. The specificatio
 
 ## Protocol Definition
 
-**Source**: `amplifier_core/interfaces.py` lines 54-119
+**Source**: `amplifier_core/interfaces.py` → `class Provider(Protocol)`
 
 ```python
 @runtime_checkable

docs/contracts/TOOL_CONTRACT.md

@@ -4,16 +4,15 @@ module_type: tool
 contract_version: 1.0.0
 last_modified: 2025-01-29
 related_files:
-  - path: amplifier_core/interfaces.py#Tool
+  - path: ../../python/amplifier_core/interfaces.py#Tool
     relationship: protocol_definition
-    lines: 121-146
-  - path: amplifier_core/models.py#ToolResult
+  - path: ../../python/amplifier_core/models.py#ToolResult
     relationship: result_model
-  - path: amplifier_core/message_models.py#ToolCall
+  - path: ../../python/amplifier_core/message_models.py#ToolCall
     relationship: invocation_model
   - path: ../specs/MOUNT_PLAN_SPECIFICATION.md
     relationship: configuration
-  - path: amplifier_core/testing.py#MockTool
+  - path: ../../python/amplifier_core/testing.py#MockTool
     relationship: test_utilities
 canonical_example: https://github.com/microsoft/amplifier-module-tool-filesystem
 ---
@@ -37,7 +36,7 @@ Tools extend agent capabilities beyond pure conversation:
 
 ## Protocol Definition
 
-**Source**: `amplifier_core/interfaces.py` lines 121-146
+**Source**: `amplifier_core/interfaces.py` → `class Tool(Protocol)`
 
 ```python
 @runtime_checkable

python/amplifier_core/interfaces.py

@@ -3,11 +3,11 @@
 Uses Protocol classes for structural subtyping (no inheritance required).
 
 Related contracts (for module developers):
-  - docs/contracts/PROVIDER_CONTRACT.md (Provider, lines 54-119)
-  - docs/contracts/TOOL_CONTRACT.md (Tool, lines 121-146)
-  - docs/contracts/HOOK_CONTRACT.md (HookHandler, lines 173-189)
-  - docs/contracts/ORCHESTRATOR_CONTRACT.md (Orchestrator, lines 26-52)
-  - docs/contracts/CONTEXT_CONTRACT.md (ContextManager, lines 148-180)
+  - docs/contracts/ORCHESTRATOR_CONTRACT.md  (Orchestrator)
+  - docs/contracts/PROVIDER_CONTRACT.md      (Provider)
+  - docs/contracts/TOOL_CONTRACT.md          (Tool)
+  - docs/contracts/CONTEXT_CONTRACT.md       (ContextManager)
+  - docs/contracts/HOOK_CONTRACT.md          (HookHandler)
 """
 
 from typing import TYPE_CHECKING