run-dmcp 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Shawn Rushefsky (DMCP, the project this continues)
+Copyright (c) 2026 Derek Ferguson (run-dmcp)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# run-dmcp
+
+**An MCP server for LLM-run interactive fiction where the server owns what is true — including when
+it was true.**
+
+> The model classifies and narrates. The server resolves, remembers, and can say what the world
+> looked like at any point in its history. The narrator may be as florid as it likes about *the how*;
+> it can never lie about *the what*, or about *the when*.
+
+Both halves of that are deliberate reversals of the design this project continues, in which the model
+holds full adjudication discretion over a world that only ever stores *now*.
+
+## Status
+
+**0.1.0 — the foundation, not the thesis.** What ships today is the predecessor's engine plus four
+pieces of generic mechanism that were built for it and offered back to it:
+
+- **Atomicity** — `withTransaction()` wired into the multi-write operations that were running
+  non-atomically.
+- **Declarative constraints** — resources can be declared `bounded`, `monotonic` or `resolve_only`,
+  and the store enforces it rather than trusting every caller.
+- **Conserved resource sets** — a set of resources can be declared conserved, with an atomic transfer
+  that never silently clamps.
+- **On-expiry consequences** — scheduled events and timers can carry a consequence that actually
+  lands when they expire, rather than expiring into nothing.
+
+The timeline that gives this project its reason to exist — interval-versioned facts, `replay(t)`,
+irreversibility, `changes_within` — is designed and accepted but **not yet built**. See
+[docs/DESIGN.md](docs/DESIGN.md), which is the authority, and §11 for the order things land in.
+
+## Provenance
+
+This continues [DMCP](https://github.com/shawnrushefsky/dmcp) by Shawn Rushefsky (MIT), whose last
+commit was 2026-01-06. This repository carries its full history rather than a squashed root: the
+first commit here is his, from 2025-12-30.
+
+It is **not** a GitHub fork, deliberately — a repository inside another's fork network is discoverable
+only as "a fork of" and cannot own its issue tracker. The four offers listed above stand as open pull
+requests against the original and remain valid there; they are merged here because this project
+cannot wait on a repository that has not moved in seven months.
+
+MIT, and his copyright notice travels with the code. See [LICENSE](LICENSE).
+
+## The one rule that shapes everything else
+
+This engine serves more than one piece of interactive fiction. Two consumers were in the room when it
+was designed, chosen to be unlike each other: one whose world advances a turn at a time and has a
+player making uncertain decisions, and one with no player at all, whose units have *duration* and are
+entirely known in advance.
+
+Neither may become the reason the engine exists. That intention does not survive as a rule people
+remember, so it is a test: `src/__tests__/engineVocabulary.test.ts` fails CI when a specific
+consumer's language appears anywhere in the engine. Fixtures use grain, treasury and population — a
+throwaway vocabulary for exercising mechanism, never a starter set.
+
+**Core membership is "generic, with at least one real caller"** — not "needed by every consumer", and
+not "sounds general". Nothing enters the core against an imagined client.
+
+## Development
+
+```bash
+npm ci
+cd client && npm ci && cd ..
+
+npm run lint          # eslint
+npm run typecheck     # tsc --noEmit
+npm run test:run      # vitest, one shot
+npm run build         # tsc + client build
+
+npm run dev           # tsx src/index.ts
+```
+
+CI runs lint, typecheck, tests and build on every push, for both the server and the client.
+
+Local MCP inspection: `npx @modelcontextprotocol/inspector node dist/index.js`
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/__tests__/engineVocabulary.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/engineVocabulary.test.js

@@ -0,0 +1,147 @@
+// No client's vocabulary reaches the engine.
+//
+// run-dmcp exists to serve more than one piece of interactive fiction. Two
+// consumers were in the room when it was designed and they are deliberately
+// unlike each other: a geopolitical roleplay whose world advances one turn at a
+// time, and a music-video pipeline whose units have duration and no player at
+// all. Neither may become the reason the engine exists.
+//
+// That intention cannot survive as a rule people remember. The predecessor's
+// own history shows why: `resource_history` and `relationship_history` were
+// added because somebody needed them, and nothing generalised the idea, so the
+// concept of versioning existed for exactly two tables for the life of the
+// project. Good intentions do not generalise; tests do.
+//
+// So the line is a test. It runs in CI on every push, against the actual
+// tracked file list, and it fails when a specific client's language appears in
+// the engine — which is the first observable symptom of "engine with two
+// consumers" decaying into "one client's library with a second bolted on".
+//
+// WHAT THIS IS NOT: a check that the engine is free of narrative vocabulary.
+// Dice, combat, quests and factions are inherited and generic — they belong to
+// the RPG layer above the core, not to any one client. The forbidden list is
+// specifically the vocabulary of the two named consumers, plus terms that could
+// only have come from one of them.
+//
+// WHERE FIXTURES COME FROM: grain, treasury, population. A throwaway vocabulary
+// for exercising the mechanism, never a starter set anyone should build on.
+import { describe, it, expect } from "vitest";
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve, basename } from "node:path";
+const REPO_ROOT = resolve(__dirname, "..", "..");
+/**
+ * The design brief is excluded, and only it.
+ *
+ * That document's entire job is to explain where the boundary between engine
+ * and consumer falls, and it cannot do that without naming the consumers on
+ * either side of it. Excluding the explanation of a rule is not a hole in the
+ * rule. Excluding anything else would be.
+ */
+const EXCLUDED_PATHS = new Set(["docs/DESIGN.md"]);
+function scannedFiles() {
+    return execFileSync("git", ["ls-files"], { cwd: REPO_ROOT, encoding: "utf8" })
+        .split("\n")
+        .filter(Boolean)
+        .filter((f) => !EXCLUDED_PATHS.has(f))
+        .filter((f) => basename(f) !== "engineVocabulary.test.ts")
+        .filter((f) => !/package-lock\.json$/.test(f))
+        .filter((f) => !/\.(png|jpe?g|gif|webp|ico|svg|woff2?|ttf|otf|mp3|wav|onnx|pth|bin)$/i.test(f));
+}
+/**
+ * Each entry carries why, because a bare list of forbidden words is exactly the
+ * thing a future contributor deletes when it gets in their way.
+ *
+ * Note the shapes chosen. `\baccords?\b` and not `\baccord` — the latter also
+ * matches "accordance" and "according", which are ordinary English. `chunk_id`
+ * and not `chunk` — a chunked read is a legitimate generic idea. No bare
+ * `shot`: the tree already says "in one shot" and `"wide shot"` as an image
+ * framing, both of which are fine. A rule that cries wolf gets deleted, and
+ * then it is protecting nothing.
+ */
+const FORBIDDEN = [
+    {
+        pattern: /\bDEFCON\b/i,
+        what: "a consumer's escalation ladder",
+        why: "one game's bounded resource. The engine has `bounded` constraints; it has never heard of a ladder.",
+    },
+    {
+        pattern: /\bprestige\b/i,
+        what: "a consumer's conserved resource",
+        why: "the engine offers conserved resource SETS. Which resource is conserved, and among whom, is the game's.",
+    },
+    {
+        pattern: /\bflashpoints?\b/i,
+        what: "a consumer's contested location",
+        why: "the engine has entities and locations. 'Flashpoint' is a geopolitical reading of one.",
+    },
+    {
+        pattern: /\bcohesion\b/i,
+        what: "a consumer's per-location scalar",
+        why: "a resource on a location. The name belongs to the game that decided what it measures.",
+    },
+    {
+        pattern: /\bcompellence\b|\bARMED_STRIKE\b|\bPRESTIGE_CONTEST\b|\bFLASHPOINT_SEIZURE\b/,
+        what: "a consumer's mechanic names",
+        why: "mechanics are registered BY a game (design §5.2a). The engine dispatches them and never learns what they mean.",
+    },
+    {
+        pattern: /\baccords?\b/i,
+        what: "a consumer's negotiated agreement",
+        why: "the engine has facts with obligations. 'Accord' is one game's word for a bundle of them.",
+    },
+    {
+        pattern: /\bseats?\b/i,
+        what: "a consumer's player positions",
+        why: "the engine has entities and (eventually) per-entity visibility. Seats are how one game partitions them.",
+    },
+    {
+        pattern: /\bcrises\b|\bcrisis\b/i,
+        what: "a consumer's timed pressure",
+        why: "the engine has scheduled events with on-expiry consequences. What makes one a crisis is the game's fiction.",
+    },
+    {
+        pattern: /\blyrics?\b|\bchorus\b|\bverses?\b|\bstoryboards?\b/i,
+        what: "the other consumer's source material",
+        why: "the engine renders state at t. That the state was authored against a song is not its business.",
+    },
+    {
+        pattern: /\bchunk_id\b|\bchunkId\b|\bshot_id\b|\bshotId\b|\bshot lines?\b/i,
+        what: "the other consumer's unit identifiers",
+        why: "and these are the ones that must never appear, because that client's own rule is that an index " +
+            "into re-segmentable units is the wrong axis (design §5.1). The engine takes `t`, never a unit id.",
+    },
+    {
+        pattern: /\bgeopolitic(s|al)\b/i,
+        what: "the domain of one consumer",
+        why: "if the engine describes itself by one client's genre, the second client is already a guest.",
+    },
+];
+describe("no client's vocabulary reaches the engine", () => {
+    const files = scannedFiles();
+    it("scans a meaningful number of tracked files (guard against a vacuous pass)", () => {
+        expect(files.length).toBeGreaterThan(50);
+    });
+    it.each(FORBIDDEN)("contains no $what", ({ pattern, why }) => {
+        const offenders = [];
+        for (const file of files) {
+            let contents;
+            try {
+                contents = readFileSync(resolve(REPO_ROOT, file), "utf8");
+            }
+            catch {
+                continue;
+            }
+            contents.split("\n").forEach((line, i) => {
+                if (pattern.test(line))
+                    offenders.push(`${file}:${i + 1}: ${line.trim().slice(0, 100)}`);
+            });
+        }
+        expect(offenders, `${why}\n\n${offenders.join("\n")}`).toEqual([]);
+    });
+    it("keeps the design brief excluded, and nothing else", () => {
+        // If this list ever grows, the rule is being routed around rather than
+        // enforced. One exclusion, for the document that explains the rule.
+        expect([...EXCLUDED_PATHS]).toEqual(["docs/DESIGN.md"]);
+    });
+});

package/dist/db/__tests__/connection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/db/__tests__/connection.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTestDb, destroyTestDb } from './testDb.js';
+import { withTransaction, getDatabase } from '../connection.js';
+import { createGame } from '../../tools/game.js';
+import { createResource, getResource } from '../../tools/resource.js';
+describe('withTransaction', () => {
+    let gameId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    it('commits all writes performed inside the callback when it succeeds', () => {
+        const result = withTransaction(() => {
+            const a = createResource({ gameId, ownerType: 'game', name: 'grain', value: 1 });
+            const b = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 2 });
+            return { a, b };
+        });
+        expect(getResource(result.a.id)?.value).toBe(1);
+        expect(getResource(result.b.id)?.value).toBe(2);
+    });
+    it('returns the callback return value', () => {
+        const value = withTransaction(() => 42);
+        expect(value).toBe(42);
+    });
+    it('rolls back every write in the callback when it throws, leaving no partial writes', () => {
+        const first = createResource({ gameId, ownerType: 'game', name: 'grain', value: 1 });
+        expect(() => {
+            withTransaction(() => {
+                // This write should succeed at the SQLite level...
+                createResource({ gameId, ownerType: 'game', name: 'treasury', value: 2 });
+                // ...but the transaction as a whole should never commit because of this throw.
+                throw new Error('boom');
+            });
+        }).toThrow('boom');
+        // The pre-existing resource is untouched.
+        expect(getResource(first.id)?.value).toBe(1);
+        // The resource created inside the doomed transaction must not exist.
+        const db = getDatabase();
+        const rows = db.prepare('SELECT * FROM resources WHERE name = ?').all('treasury');
+        expect(rows).toHaveLength(0);
+    });
+    it('propagates the original error when rolling back', () => {
+        class CustomError extends Error {
+        }
+        expect(() => withTransaction(() => {
+            createResource({ gameId, ownerType: 'game', name: 'grain', value: 1 });
+            throw new CustomError('custom failure');
+        })).toThrow(CustomError);
+    });
+    it('rolls back a mid-operation failure across two dependent writes (debit/credit style)', () => {
+        const from = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+        const to = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 0 });
+        const shouldFailBeforeCredit = true;
+        expect(() => {
+            withTransaction(() => {
+                const db = getDatabase();
+                db.prepare('UPDATE resources SET value = value - 10 WHERE id = ?').run(from.id);
+                // Simulate a failure that happens after the first write but before the second.
+                if (shouldFailBeforeCredit) {
+                    throw new Error('credit step failed');
+                }
+                db.prepare('UPDATE resources SET value = value + 10 WHERE id = ?').run(to.id);
+            });
+        }).toThrow('credit step failed');
+        // Neither side of the transfer should have taken effect.
+        expect(getResource(from.id)?.value).toBe(100);
+        expect(getResource(to.id)?.value).toBe(0);
+    });
+});

package/dist/db/__tests__/testDb.d.ts

@@ -0,0 +1,33 @@
+import type Database from "better-sqlite3";
+/**
+ * Test fixture: gives each test a clean, fully migrated, isolated SQLite
+ * database, backed by an in-memory database rather than a file on disk.
+ *
+ * Why this is needed: `getDatabase()` in `src/db/connection.ts` caches a
+ * single database handle at module scope. Without resetting it, every test
+ * in a process would share one connection and bleed state into each other.
+ *
+ * Usage:
+ *   let db: Database.Database;
+ *   beforeEach(() => {
+ *     db = createTestDb();
+ *   });
+ *   afterEach(() => {
+ *     destroyTestDb();
+ *   });
+ *
+ * Call `destroyTestDb()` in `afterEach` (not just before the next
+ * `createTestDb()`) so a failed/skipped test doesn't leak its connection
+ * into whichever test happens to run next.
+ */
+export declare function createTestDb(): Database.Database;
+/**
+ * Tears down the database created by `createTestDb()`.
+ *
+ * Deliberately does NOT delete `DMCP_DB_PATH`. `src/test-setup.ts` sets it
+ * process-wide as a safety net so that any `getDatabase()` call -- including
+ * one made outside this fixture, e.g. at module scope in a test file -- can
+ * never open the real on-disk database. Clearing it here would punch a hole
+ * in that net for every test that ran after the first teardown.
+ */
+export declare function destroyTestDb(): void;

package/dist/db/__tests__/testDb.js

@@ -0,0 +1,41 @@
+import { closeDatabase, getDatabase } from "../connection.js";
+import { initializeSchema } from "../schema.js";
+/**
+ * Test fixture: gives each test a clean, fully migrated, isolated SQLite
+ * database, backed by an in-memory database rather than a file on disk.
+ *
+ * Why this is needed: `getDatabase()` in `src/db/connection.ts` caches a
+ * single database handle at module scope. Without resetting it, every test
+ * in a process would share one connection and bleed state into each other.
+ *
+ * Usage:
+ *   let db: Database.Database;
+ *   beforeEach(() => {
+ *     db = createTestDb();
+ *   });
+ *   afterEach(() => {
+ *     destroyTestDb();
+ *   });
+ *
+ * Call `destroyTestDb()` in `afterEach` (not just before the next
+ * `createTestDb()`) so a failed/skipped test doesn't leak its connection
+ * into whichever test happens to run next.
+ */
+export function createTestDb() {
+    process.env.DMCP_DB_PATH = ":memory:";
+    const db = getDatabase();
+    initializeSchema();
+    return db;
+}
+/**
+ * Tears down the database created by `createTestDb()`.
+ *
+ * Deliberately does NOT delete `DMCP_DB_PATH`. `src/test-setup.ts` sets it
+ * process-wide as a safety net so that any `getDatabase()` call -- including
+ * one made outside this fixture, e.g. at module scope in a test file -- can
+ * never open the real on-disk database. Clearing it here would punch a hole
+ * in that net for every test that ran after the first teardown.
+ */
+export function destroyTestDb() {
+    closeDatabase();
+}

package/dist/db/connection.d.ts

@@ -0,0 +1,22 @@
+import Database from "better-sqlite3";
+export declare function getDatabase(): Database.Database;
+export declare function closeDatabase(): void;
+/**
+ * Execute multiple operations atomically within a single SQLite transaction.
+ *
+ * better-sqlite3 transactions are synchronous: `fn` must not be `async` and
+ * must not contain `await`. Pass a plain function that only performs
+ * synchronous statement executions. If `fn` throws, better-sqlite3 rolls
+ * back everything it did and the original error propagates -- no partial
+ * writes are left behind. If `fn` returns normally, the transaction commits
+ * and its return value is passed through.
+ */
+export declare function withTransaction<T>(fn: () => T): T;
+/**
+ * Get the current database path (useful for debugging/logging).
+ */
+export declare function getDatabasePath(): string;
+/**
+ * Get the current data directory (for images and other media).
+ */
+export declare function getDataDir(): string;

package/dist/db/connection.js

@@ -0,0 +1,107 @@
+import Database from "better-sqlite3";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { mkdirSync, existsSync } from "fs";
+import { homedir } from "os";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("db");
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Resolve database path with the following priority:
+ * 1. DMCP_DB_PATH environment variable (absolute path)
+ * 2. XDG_DATA_HOME/dmcp/games.db (Linux/macOS standard)
+ * 3. Fallback to ./data/games.db (relative to project)
+ */
+function resolveDataPath() {
+    // Priority 1: Explicit environment variable
+    if (process.env.DMCP_DB_PATH) {
+        const dbPath = process.env.DMCP_DB_PATH;
+        const dataDir = dirname(dbPath);
+        log.info("Using database path from DMCP_DB_PATH", { dbPath });
+        return { dataDir, dbPath };
+    }
+    // Priority 2: XDG Base Directory spec
+    const xdgDataHome = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+    const xdgDataDir = join(xdgDataHome, "dmcp");
+    const xdgDbPath = join(xdgDataDir, "games.db");
+    // Use XDG path if it exists or if we're not in a development context
+    if (existsSync(xdgDataDir) || !existsSync(join(__dirname, "..", "..", "package.json"))) {
+        log.info("Using XDG data directory", { dbPath: xdgDbPath });
+        return { dataDir: xdgDataDir, dbPath: xdgDbPath };
+    }
+    // Priority 3: Fallback to project-relative path (development)
+    const fallbackDataDir = join(__dirname, "..", "..", "data");
+    const fallbackDbPath = join(fallbackDataDir, "games.db");
+    log.debug("Using project-relative data directory", { dbPath: fallbackDbPath });
+    return { dataDir: fallbackDataDir, dbPath: fallbackDbPath };
+}
+// Resolved lazily (on first getDatabase() call after startup, or after every
+// closeDatabase()) rather than once at module-import time. This makes
+// DMCP_DB_PATH re-readable at any point before the first real connection is
+// opened -- in particular it lets tests point each database at a fresh
+// in-memory instance without fighting ES module caching.
+let db = null;
+let DATA_DIR;
+let DB_PATH;
+function ensurePathsResolved() {
+    if (DATA_DIR === undefined || DB_PATH === undefined) {
+        const resolved = resolveDataPath();
+        DATA_DIR = resolved.dataDir;
+        DB_PATH = resolved.dbPath;
+    }
+    return { dataDir: DATA_DIR, dbPath: DB_PATH };
+}
+export function getDatabase() {
+    if (!db) {
+        const { dataDir, dbPath } = ensurePathsResolved();
+        // In-memory databases have no directory or file to create on disk.
+        if (dbPath !== ":memory:" && !existsSync(dataDir)) {
+            mkdirSync(dataDir, { recursive: true });
+            log.info("Created data directory", { path: dataDir });
+        }
+        db = new Database(dbPath);
+        db.pragma("journal_mode = WAL");
+        db.pragma("foreign_keys = ON");
+        log.info("Database connection established", { path: dbPath });
+    }
+    return db;
+}
+export function closeDatabase() {
+    if (db) {
+        db.close();
+        db = null;
+        log.info("Database connection closed");
+    }
+    // Forget the resolved paths too, so a subsequent getDatabase() call
+    // re-reads DMCP_DB_PATH instead of reusing a stale value. This is what
+    // lets tests swap DMCP_DB_PATH between runs and get an isolated database.
+    DATA_DIR = undefined;
+    DB_PATH = undefined;
+}
+/**
+ * Execute multiple operations atomically within a single SQLite transaction.
+ *
+ * better-sqlite3 transactions are synchronous: `fn` must not be `async` and
+ * must not contain `await`. Pass a plain function that only performs
+ * synchronous statement executions. If `fn` throws, better-sqlite3 rolls
+ * back everything it did and the original error propagates -- no partial
+ * writes are left behind. If `fn` returns normally, the transaction commits
+ * and its return value is passed through.
+ */
+export function withTransaction(fn) {
+    const database = getDatabase();
+    return database.transaction(fn)();
+}
+/**
+ * Get the current database path (useful for debugging/logging).
+ */
+export function getDatabasePath() {
+    return ensurePathsResolved().dbPath;
+}
+/**
+ * Get the current data directory (for images and other media).
+ */
+export function getDataDir() {
+    return ensurePathsResolved().dataDir;
+}

package/dist/db/schema.d.ts

@@ -0,0 +1 @@
+export declare function initializeSchema(): void;