8000 feat(reference-engine): add mnehmos-rpg-mcp A/B backend integration by Mnehmos · Pull Request #211 · Mnehmos/rpg-mcp-live · GitHub
[go: up one dir, main page]

Skip to content

feat(reference-engine): add mnehmos-rpg-mcp A/B backend integration - #211

Merged
Mnehmos merged 4 commits into
mainfrom
feat/reference-engine-ab-integration
Aug 12, 2026
Merged

Mnehmos merged 4 commits into
mainfrom
feat/reference-engine-ab-integration

Conversation

@Mnehmos
@Mnehmos Mnehmos commented Aug 12, 2026 •
Copy link
Copy Markdown
Owner

Summary

Adds a per-campaign A/B toggle between lantern-engine and the mnehmos-rpg-mcp reference engine (deployed as a separate Railway service in the same project). This is a deliberate, disclosed override of ADR-H13 ("reference engine is not Lantern production") — see the reconciliation note added to that ADR in this PR for the reasoning and the tenant-isolation mitigation.

  • src/reference-engine-client.ts — MCP JSON-RPC transport (Streamable HTTP) to the reference engine.
  • src/reference-engine-store.ts — the tenant-isolation control point (account+campaign → reference-engine world/party/character IDs; the reference engine itself has no tenant scoping at all) and storage for LLM-authored narrative "docket" documents, with secrets excluded from every player-facing read by construction.
  • src/reference-engine-tools.ts — fetches/caches the reference engine's tool schemas as OpenRouter tool-call definitions.
  • src/reference-engine-adapter.ts — golden-path campaign/character/inventory/notes operations. Hydrates the character sheet with real SRD data (saves, skills, hit die, proficiencies, spellcasting — including Warlock's actual Pact Magic slot table) for any of the 12 D&D classes via the existing Open5e content kernel (hydrateCharacter), while keeping HP/AC/inventory authoritative from the reference engine itself, never locally recomputed.
  • src/reference-engine-dm.ts — the turn orchestrator: an LLM calls the engine's tools (never the reverse, per ADR-H37's doctrine), including two local-only tools (read_docket/write_docket) that never reach the remote engine.
  • src/server.ts — routes campaign/character/inventory/notes/turn-submission endpoints to the selected backend; new POST /api/campaigns/:id/engine-backend toggle route.
  • public/app.js/index.html — engine-backend toggle button in the campaign dossier + a backend badge on the campaign list.
  • docs/ADR-H13-reference-engine-boundary.md — reconciliation note recording the 2026-08-11 override decision.
  • docs/DEPLOYMENT.md — documents the new mnehmos-rpg-mcp service and its env vars.

Risk

  • Overrides ADR-H13's original "do not deploy the reference server" decision, knowingly. The reference engine's SQLite layer has no tenant/session scoping at all (verified by reading its storage layer), and its own session_manage.initialize will hand a caller "whichever w 8000 orld/party is first in the database" if IDs aren't passed explicitly. Mitigation: ReferenceEngineStore is the only place account+campaign IDs bind to reference-engine world/party/character IDs, and the adapter never accepts a client-supplied raw reference-engine ID — real users only ever reach the reference engine through this one adapter, never directly.
  • The reference engine has documented gameplay bugs (rejected moves that still mutate persisted state, damage overrides bypassing character math, rewards reporting success without applying — see docs/REFERENCE-ENGINE.md). Campaigns routed to it inherit those bugs. This is disclosed, not fixed by this PR.
  • Opt-in, not default: lantern-engine remains the default backend for every campaign unless explicitly switched via the new toggle route. No existing campaign or code path changes behavior.
  • No idempotency/replay on reference-backend turn submission yet (a resubmitted request re-runs the turn rather than replaying a stored result) — a known, disclosed MVP gap, not a regression (this path didn't exist before).
  • Quest Journal still shows Lantern's generic placeholder quest for reference campaigns (quest_manage isn't wired yet) — cosmetic, not misleading, flagged as a fast-follow.

Acceptance criteria

  • A campaign can be switched to the reference backend and back via POST /api/campaigns/:id/engine-backend, with lantern-engine behavior completely unchanged when not switched.
  • Character sheet fields (HP/AC/abilities/inventory) always match what the reference engine's own tools report — never a locally recomputed value, verified by a dedicated test that feeds a hostile PLAYER.md docket attempting to override them.
  • The secrets docket never appears in any player-facing API response, verified by a dedicated test.
  • Saves/skills/hit die/proficiency bonus/spellcasting are correctly derived for all 12 D&D classes (not just Lantern's 4-class fallback), verified with a real Warlock fixture (d8 hit die, Pact Magic short-rest recovery, cha-based spell save DC).
  • The turn orchestrator forces tenant-scoping fields (worldId/partyId/sessionId) regardless of what the model supplies, verified by a dedicated test.

Verification

  • 47 new unit tests across the 5 new modules (mocked reference-engine client/store).
  • tsc --noEmit clean.
  • Full suite: no new regressions (668/699 passing; the 31 pre-existing failures are all in the unrelated, already-paused narrator-collapse refactor, untouched by this PR).
  • Live-verified against the deployed mnehmos-rpg-mcp Railway service during development (MCP handshake, tool catalog, character creation, inventory, notes, session init) — including finding and fixing a real bug in that service's HTTP transport (stateless-transport-per-request reuse), separately committed there.
  • Manual browser smoke on staging after this PR deploys (create a campaign, toggle to reference backend, create a character, confirm the sheet renders correctly and HP/AC match what the reference engine reports).

🤖 Generated with Claude Code

Mnehmos and others added 2 commits August 12, 2026 08:50
Routes campaigns to either lantern-engine or the mnehmos-rpg-mcp
reference engine (deployed as a separate Railway service in this
project), per an explicit per-campaign toggle. This is a deliberate,
disclosed override of ADR-H13 (reference engine must not be on the
production request path) -- see the reconciliation note being added
alongside this change.

- reference-engine-client.ts: MCP JSON-RPC transport (Streamable HTTP)
- reference-engine-store.ts: tenant-isolation routing table + LLM-
  authored narrative "docket" documents (state/player/npcs/journal/
  secrets/campaign), with secrets excluded from every player-facing
  read by construction
- reference-engine-tools.ts: fetches and caches the reference engine's
  tool schemas, converted to OpenRouter tool-call format
- reference-engine-adapter.ts: golden-path campaign/character/
  inventory/notes operations; hydrates the character sheet with real
  SRD data (saves, skills, hit die, spellcasting incl. Warlock Pact
  Magic) for any of the 12 D&D classes via the existing content
  kernel, while keeping hp/ac/inventory authoritative from the
  reference engine itself
- reference-engine-dm.ts: the turn orchestrator -- an LLM calls the
  engine's tools (never the reverse), including two local-only tools
  (read_docket/write_docket) that never reach the remote engine
- server.ts: routes campaign/character/inventory/notes/turn-submission
  endpoints to the selected backend; new POST .../engine-backend toggle
- app.js/index.html: engine-backend toggle button + backend badge on
  the campaign list

47 new unit tests. Full suite otherwise unaffected (pre-existing,
unrelated failures in the paused narrator-collapse refactor are not
touched by this change).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@Mnehmos
Mnehmos merged commit 0f5cdbf into main Aug 12, 2026
1 check passed
@Mnehmos
Mnehmos deleted the feat/reference-engine-ab-integration branch August 12, 2026 16:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
4C00

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0