Mnehmos · Aug 14, 2026 · Aug 14, 2026 · coderabbitai · Aug 14, 2026 · coderabbitai
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)]()
 [![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)]()
 [![Tests](https://img.shields.io/badge/tests-2214%20passing-brightgreen.svg)]()
-[![Tools](https://img.shields.io/badge/MCP%20tools-33-blue.svg)]()
+[![Tools](https://img.shields.io/badge/MCP%20tools-36-blue.svg)]()
-[![Tools](https://img.shields.io/badge/MCP%20tools-36-blue.svg)]()
+![Tools](https://img.shields.io/badge/MCP%20tools-36-blue.svg)
-[![Tools](https://img.shields.io/badge/MCP%20tools-36-blue.svg)]()
+![Tools](https://img.shields.io/badge/MCP%20tools-36-blue.svg)
 
 **A rules-enforced RPG backend that turns any LLM into a game master who can't cheat.**
 
@@ -46,9 +46,9 @@ You talk to an AI (Claude, GPT, etc.) in natural language. You say things like "
 
 ## v1.0 Release (January 2026)
 
-### 83% Tool Reduction: 195 → 33 Tools (29 Consolidated + 4 Meta/Event)
+### 81% Tool Reduction: 195 → 36 Tools (31 Consolidated + 5 Meta/Event)
 
-This release consolidates 195 individual tools into **29 action-based tools** plus 4 standalone meta/event tools using:
+This release consolidates 195 individual tools into **31 action-based tools** plus 5 standalone meta/event tools using:
 
 - **Action enums** - Each tool handles multiple operations via an `action` parameter
 - **Fuzzy matching** - Typo-tolerant action matching with suggestions
@@ -61,7 +61,7 @@ This release consolidates 195 individual tools into **29 action-based tools** pl
 
 | Metric | Before | After | Change |
 |--------|--------|-------|--------|
-| MCP Tools | 195 | 33 | **83.1% reduction** |
+| MCP Tools | 195 | 36 | **81.5% reduction** |
 | Tests | 1,242 | 2,214 | +78% coverage |
 | Token overhead | ~50K | ~6-8K | **85% reduction** |
 
@@ -118,7 +118,7 @@ This engine implements the **Event-Driven Agentic AI Architecture**:
 
 ---
 
-## Consolidated Tools Reference (29 Tools)
+## Consolidated Tools Reference (31 Tools)
 
 ### Character & Party
 
@@ -318,7 +318,7 @@ src/
 │   ├── migrations.ts # SQLite schema definitions
 │   └── repos/        # Repository pattern for persistence
 ├── server/
-│   ├── consolidated/ # 29 action-based tools
+│   ├── consolidated/ # 31 action-based tools
 │   ├── handlers/     # Extracted handler implementations (combat, spatial)
 │   ├── consolidated-registry.ts  # Tool registration
 │   ├── meta-tools.ts # search_tools, load_tool_schema
@@ -354,20 +354,29 @@ docs/                 # White paper and LLM spatial guide
    LLMs cannot cast spells they don't know or claim damage they didn't roll.
 
 7. **Token efficiency**
-   29 consolidated tools with action routing reduce context overhead by 85%.
+   31 consolidated tools with action routing reduce context overhead by 85%.
 
 8. **Guiding errors**
    Invalid actions return suggestions, not just failures.
 
+## Tool-surface policy
+
+The consolidated MCP contracts are the public tool surface. The older
+world-map helpers in `src/server/tools.ts` are retained in compatibility mode
+as an internal adapter because `world_map` still delegates to their validated
+world persistence and patch implementation. New public tools must be added to
+the consolidated contracts, and the adapter matrix is enforced by
+`src/server/legacy-surface-policy.ts`.
+
 ---
 
 ## Test Coverage
 
 ```bash
 npm test
-# 2214 tests passing, 7 skipped
-# 136 test files
-# Coverage across all 33 tools (29 consolidated + 4 meta/event)
+# 2252 tests passing, 7 skipped
+# 148 test files
+# Coverage across all 36 tools (31 consolidated + 5 meta/event)
 ```
 
 ---
@@ -391,7 +400,7 @@ Contributions welcome! Please:
 - [x] Corpse and loot mechanics
 - [x] NPC memory and relationships
 - [x] Improvisation engine
-- [x] Tool consolidation (195 → 33)
+- [x] Tool consolidation (195 → 36)
 - [x] Fuzzy action matching
 - [x] Preset systems (creatures, encounters, locations)
 - [ ] WebSocket real-time subscriptions

diff --git a/docs/issue-13-adr-001.md b/docs/issue-13-adr-001.md
@@ -1,7 +1,7 @@
 ## ADR-001: Unified Tool Contract Object Model
 
 ### Status
-Proposed
+Accepted
 
 ### Context
 The consolidated runtime currently keeps key contract elements in separate places:
@@ -30,10 +30,10 @@ Generate registry/search metadata from these contract objects, replacing manuall
 - Requires generator/adapter layer for current runtime registration path
 
 ### Acceptance Criteria
-- [ ] Each consolidated tool exports one contract definition
-- [ ] Registry metadata is derived from contract definitions
-- [ ] `search_tools` and `load_tool_schema` behavior remains compatible
-- [ ] Tests verify metadata/action/schema parity for all consolidated tools
+- [x] Each consolidated tool is represented by one `ToolContract` definition
+- [x] Registry metadata is derived from contract definitions
+- [x] `search_tools` and `load_tool_schema` behavior remains compatible
+- [x] Tests verify metadata/action/schema parity for all consolidated tools
 
 ### Source
 Architecture analysis: `docs/ARCHITECTURE-CODEBASE-ANALYSIS.md`
diff --git a/docs/issue-15-adr-003.md b/docs/issue-15-adr-003.md
@@ -1,7 +1,7 @@
 ## ADR-003: Domain Service/Facade Boundary
 
 ### Status
-Proposed
+Accepted (phased boundary)
 
 ### Context
 Consolidated MCP handlers currently include direct persistence access patterns (e.g., direct DB/repository calls).
@@ -15,6 +15,12 @@ Introduce **domain service/facade interfaces** between MCP handlers and reposito
 - Services coordinate domain operations and repository calls
 - Storage layer owns DB lifecycle and repository implementation details
 
+The first migration covers the inventory, world, and consolidated combat
+handlers through `src/server/domain-services.ts`. The facade is injectable via
+`runWithDomainServices`, and production resolution still uses the verified
+tenant-scoped database from storage. Remaining handlers migrate as they are
+changed; new handlers must not open databases or construct repositories.
+
 ### Consequences
 **Positive**
 - Improved separation of concerns
@@ -26,10 +32,10 @@ Introduce **domain service/facade interfaces** between MCP handlers and reposito
 - Requires phased migration to avoid regressions
 
 ### Acceptance Criteria
-- [ ] Combat, world, and inventory handlers route through service facades first
-- [ ] Handlers no longer call `getDb()` directly
-- [ ] Unit tests can mock services without DB dependency
-- [ ] Architecture docs updated with boundary contracts
+- [x] Combat, world, and inventory handlers route through service facades first
+- [x] Consolidated handlers in those domains no longer call `getDb()` directly
+- [x] Unit tests can inject a facade without changing storage globals
+- [x] Architecture docs updated with boundary contracts
 
 ### Source
 Architecture analysis: `docs/ARCHITECTURE-CODEBASE-ANALYSIS.md`
diff --git a/docs/issue-16-adr-004.md b/docs/issue-16-adr-004.md
@@ -1,18 +1,25 @@
 ## ADR-004: Legacy Tool Surface Strategy (Deprecate vs Compatibility Mode)
 
 ### Status
-Proposed
+Accepted
 
 ### Context
 The consolidated runtime path is active, while `src/server/tools.ts` remains as a legacy-style tool surface.
 
 ### Problem
 Without explicit policy, dual surfaces increase maintenance cost and risk behavior divergence.
 
-### Decision (to be made)
-Choose one explicit strategy and document it:
-1. **Deprecate/remove legacy surface** with migration notes, or
-2. **Retain compatibility mode** with explicit support guarantees and parity tests
+### Decision
+Retain **compatibility mode**. The consolidated MCP tools are the only public
+registration surface. `src/server/tools.ts` remains an internal adapter for
+the world-map implementation until that implementation is migrated behind the
+same contract, and no new public legacy tools may be added.
+
+The supported adapter matrix is the seven world-map operations listed in
+`src/server/legacy-surface-policy.ts`. Each entry maps to one
+`world_map` action and is covered by a parity test. The adapter may be removed
+only after the consolidated implementation no longer imports it and a staged
+migration note is published.
 
 ### Consequences
 **If deprecate**
@@ -24,10 +31,10 @@ Choose one explicit strategy and document it:
 - Ongoing parity testing/maintenance overhead
 
 ### Acceptance Criteria
-- [ ] ADR finalized with selected option
-- [ ] README/docs updated with the decision
-- [ ] If retained: parity test matrix for critical workflows
-- [ ] If deprecated: staged removal plan and timeline
+- [x] ADR finalized with selected option
+- [x] README/docs updated with the decision
+- [x] If retained: parity test matrix for critical workflows
+- [x] If deprecated: staged removal plan and timeline
 
 ### Source
 Architecture analysis: `docs/ARCHITECTURE-CODEBASE-ANALYSIS.md`
diff --git a/package.json b/package.json
@@ -46,7 +46,7 @@
     "url": "https://github.com/Mnehmos/rpg-mcp/issues"
   },
   "homepage": "https://github.com/Mnehmos/rpg-mcp#readme",
-  "description": "Complete tabletop RPG game engine via MCP - D&D 5e combat, procedural worldgen, NPC memory, 33 tools (29 consolidated + 4 meta/event)",
+  "description": "Complete tabletop RPG game engine via MCP - D&D 5e combat, procedural worldgen, NPC memory, 36 tools (31 consolidated + 5 meta/event)",
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^24.10.1",

diff --git a/src/engine/pubsub.ts b/src/engine/pubsub.ts
@@ -1,8 +1,12 @@
 /**
  * Simple Pub/Sub system for event streaming.
  */
+import { getTenant, type TenantContext } from '../storage/tenant-context.js';
+
 export class PubSub {
     private subscribers: Map<string, Set<(payload: any) => void>> = new Map();
+    /** Provenance is kept out of the payload so clients cannot forge it. */
+    private readonly tenantByPayload = new WeakMap<object, TenantContext>();
 
     subscribe(topic: string, callback: (payload: any) => void): () => void {
         if (!this.subscribers.has(topic)) {
@@ -23,15 +27,34 @@ export class PubSub {
     }
 
     publish(topic: string, payload: any): void {
+        const tenant = getTenant();
+        // Event consumers need the verified tenant that produced an event, but
+        // that provenance must never become model- or client-visible payload.
+        // A shallow clone gives the bridge an object identity to look up while
+        // preserving the existing event shape for subscribers.
+        const publishedPayload = tenant && payload !== null && typeof payload === 'object'
+            ? (Array.isArray(payload) ? [...payload] : { ...payload })
+            : payload;
+
+        if (tenant && publishedPayload !== null && typeof publishedPayload === 'object') {
+            this.tenantByPayload.set(publishedPayload, tenant);
+        }
+
         const subs = this.subscribers.get(topic);
         if (subs) {
             subs.forEach(callback => {
                 try {
-                    callback(payload);
+                    callback(publishedPayload);
                 } catch (error) {
                     console.error(`Error in subscriber for topic ${topic}:`, error);
                 }
             });
         }
     }
+
+    /** Return the verified producer context associated with a published payload. */
+    getTenantContext(payload: unknown): TenantContext | undefined {
+        if (payload === null || typeof payload !== 'object') return undefined;
+        return this.tenantByPayload.get(payload);
+    }
 }