run-dmcp 0.2.0 → 0.3.0

package/README.md

@@ -12,23 +12,26 @@ holds full adjudication discretion over a world that only ever stores *now*.
 
 ## Status
 
-**0.1.1 — 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:
+**0.3.0.** The base 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` or `monotonic`, and the store
-  enforces it rather than trusting every caller. (`resolve_only` — every direct write rejected, so a
-  value can move only through an adjudicating call — exists in a downstream consumer and has not been
-  extracted here yet. It arrives with the resolve protocol; see [docs/DESIGN.md](docs/DESIGN.md) §5.2a.)
+  enforces it rather than trusting every caller. `resolve_only` — every direct write rejected, so a
+  value can move only through an adjudicating call — joined them alongside the resolve protocol, and
+  is enforced by a trigger rather than by a checker anyone has to remember to call; see
+  [docs/DESIGN.md](docs/DESIGN.md) §5.2a.
 - **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.
 
-0.1.1 adds the packaging half of that: importing the library starts nothing, the database resolves to
-the consuming application rather than into `node_modules`, and a consumer can bring up its own tables
-through the migration hook below.
+0.1.1 added the packaging half of that: importing the library starts nothing, the database resolves
+to the consuming application rather than into `node_modules`, and a consumer can bring up its own
+tables through the migration hook below. 0.3.0 adds the consuming half — the entity/property spine is
+exported as library functions, so a consumer that deletes its own vendored copy has something to
+import rather than a server to make tool calls into.
 
 The timeline that gives this project its reason to exist — interval-versioned facts, `replay(t)`,
 irreversibility, timeline export, `changes_within` — is built, and every write of world state appends
@@ -93,6 +96,27 @@ The database lands in the consuming application: `DMCP_DB_PATH` if set, else an
 `~/.local/share/dmcp`, else `./data/games.db` relative to the working directory. Never inside the
 installed package.
 
+**The spine is importable, not only callable over a transport.** Games, locations, characters,
+factions, relationships, resources, secrets, items, notes, tags, time and timers are library
+functions first and MCP tools second, so a consumer reads and writes its own world directly and only
+serves the tools it actually wants an LLM to reach. That includes the constrained-write choke point:
+a number that moves through `updateResourceValue` is checked against its declared constraints and its
+history is `facts`, queryable with `valueHistory`.
+
+```ts
+import { createGame, createResource, updateResourceValue, valueHistory } from "run-dmcp";
+
+const game = createGame({ name: "The Granary", setting: "…", style: "…" });
+const grain = createResource({ gameId: game.id, ownerType: "game", name: "grain", value: 100 });
+
+updateResourceValue({ resourceId: grain.id, mode: "delta", value: -30, reason: "the winter ration" });
+valueHistory(grain.id, "value"); // → the transitions, with the reason each one carried
+```
+
+The annotations, input limits, error envelope and logger the engine's own tools are built from are
+exported too (`ANNOTATIONS`, `LIMITS`, `errors`, `createLogger`), so a consumer's own tools can
+refuse and bound the way these do instead of re-implementing it.
+
 ## Provenance
 
 This continues [DMCP](https://github.com/shawnrushefsky/dmcp) by Shawn Rushefsky (MIT), whose last

package/dist/db/schema.js

@@ -3,6 +3,49 @@ import { createLogger } from "../utils/logger.js";
 import { initializeTimelineSchema } from "../timeline/schema.js";
 import { initializeAdjudicationSchema } from "../timeline/adjudication.js";
 const log = createLogger("schema");
+/**
+ * Run one whole-table CHECK rebuild with foreign-key enforcement suspended,
+ * and verify afterwards that nothing was left dangling.
+ *
+ * SQLite cannot ALTER a CHECK, so widening one means rebuilding the table:
+ * copy the rows aside, DROP, CREATE with the new CHECK, copy back. Two
+ * migrations in this file do that, and both need the same two guarantees.
+ *
+ * ENFORCEMENT MUST BE OFF ACROSS THE DROP. With it on, `DROP TABLE` performs
+ * an implicit per-row DELETE first, precisely so that any ON DELETE action
+ * declared against that table fires as though each row had genuinely been
+ * deleted -- which for both of these tables means cascade-emptying the tables
+ * that reference them. Suspending it is what makes the drop a schema
+ * operation instead of a silent mass deletion. It is toggled out here rather
+ * than inside `withTransaction`, because `PRAGMA foreign_keys` is a
+ * documented no-op while a transaction is pending.
+ *
+ * AND IT MUST GO BACK ON WHEN THE REBUILD THROWS, which is why the restore is
+ * in a `finally` and why this is a shared function rather than two copies.
+ * Both call sites previously restored it on the success path only.
+ * `getDatabase()` caches one connection at module scope, so a rebuild that
+ * threw handed the rest of the process a handle with foreign keys still
+ * disabled -- and a disabled foreign key does not announce itself. It means
+ * every ON DELETE CASCADE in this schema quietly stops working: deleting a
+ * game orphans its characters, resources, locations and secrets instead of
+ * taking them with it, and nothing errors. The scenario is not exotic -- a
+ * staging table left behind by a rebuild that died partway is exactly what
+ * makes the next startup's `CREATE TABLE ..._staging` throw. Covered by
+ * `src/db/__tests__/foreignKeysRestored.test.ts`.
+ */
+function rebuildWithForeignKeysSuspended(db, label, rebuild) {
+    db.pragma("foreign_keys = OFF");
+    try {
+        withTransaction(rebuild);
+        const violations = db.pragma("foreign_key_check");
+        if (violations.length > 0) {
+            throw new Error(`${label} CHECK migration left dangling foreign keys: ` + JSON.stringify(violations));
+        }
+    }
+    finally {
+        db.pragma("foreign_keys = ON");
+    }
+}
 export function initializeSchema(options) {
     const db = getDatabase();
     // ============================================================================
@@ -203,12 +246,22 @@ export function initializeSchema(options) {
     )
   `);
     // Resources table (for tracking currency, reputation, counters, etc.)
-    db.exec(`
+    //
+    // `RESOURCES_DDL` is a shared constant, not a literal inlined here, for the
+    // same reason `RESOURCE_CONSTRAINTS_DDL` further down is one: the CHECK-
+    // rebuild migration immediately below needs this exact text executed in
+    // TWO places -- here, for a fresh database, and again inside the rebuild,
+    // for a database that still carries the OLD two-member CHECK. Sharing one
+    // JS string is what makes "a fresh database and a migrated database
+    // converge on byte-identical `sqlite_master.sql` for this table" true BY
+    // CONSTRUCTION rather than by two hand-written literals happening to agree
+    // today.
+    const RESOURCES_DDL = `
     CREATE TABLE IF NOT EXISTS resources (
       id TEXT PRIMARY KEY,
       game_id TEXT NOT NULL,
       owner_id TEXT,
-      owner_type TEXT NOT NULL CHECK (owner_type IN ('game', 'character')),
+      owner_type TEXT NOT NULL CHECK (owner_type IN ('game', 'character', 'faction', 'location')),
       name TEXT NOT NULL,
       description TEXT,
       category TEXT,
@@ -218,7 +271,115 @@ export function initializeSchema(options) {
       created_at TEXT NOT NULL,
       FOREIGN KEY (game_id) REFERENCES games(id) ON DELETE CASCADE
     )
-  `);
+  `;
+    db.exec(RESOURCES_DDL);
+    // Migration: widen `resources.owner_type` to admit 'faction' and
+    // 'location' alongside 'game' and 'character'. A resource owned by a
+    // faction or a location is generic mechanism -- the engine already has
+    // `factions` and `locations` tables; this just lets `resources` point at
+    // either the way it already points at a `game` or a `character` -- so it
+    // belongs here rather than behind a downstream application's own migration.
+    //
+    // SQLite cannot ALTER a CHECK constraint, so a database that already has
+    // `resources` rows under the OLD two-member CHECK needs the same full-
+    // table-rebuild recipe the `resource_constraints` CHECK-widening migration
+    // uses further down this function (see that block's comment for the
+    // detailed reasoning this one leans on): build a replacement table with
+    // the new CHECK, copy every row across, drop the old table, put the
+    // replacement in its place.
+    //
+    // DETECTION IS IDEMPOTENT AND LITERAL, not a guess: read this codebase's
+    // OWN generated DDL back out of `sqlite_master` and check whether it
+    // already contains the token 'faction' -- the same "a literal check for a
+    // token we defined in output we generated is fine" carve-out the
+    // `resource_constraints` migration's own comment cites (hard rule 4 in the
+    // downstream game's own engineering standards; this engine has no
+    // narrative-language rule of its own to point at, but the reasoning is the
+    // same: this is a substring check against SQL text THIS FUNCTION generated
+    // a few lines above, never against anything a player or a model wrote). A
+    // truly fresh database never takes the branch below: `RESOURCES_DDL`'s
+    // `CREATE TABLE IF NOT EXISTS` a few lines up already carries the widened
+    // CHECK, so by the time this runs, this database's own `resources` already
+    // contains 'faction'.
+    const resourcesDdl = db
+        .prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'resources'`)
+        .get();
+    if (resourcesDdl && !resourcesDdl.sql.includes("faction")) {
+        // DROP THE PROJECTION TRIGGERS FIRST, UNCONDITIONALLY, IF THEY EXIST.
+        // `timeline_resources_ai`/`_au`/`_ad` are defined ON `resources` itself
+        // (`AFTER INSERT/UPDATE/DELETE ON resources`), so SQLite drops them
+        // automatically the moment `DROP TABLE resources` below runs -- but
+        // dropping them here too, explicitly, costs nothing and removes any
+        // dependence on that implicit behaviour being exactly right. They are
+        // unconditionally reinstalled, generated fresh off the rebuilt table's
+        // own `pragma_table_info`, by `installProjectionTriggers()`
+        // (`src/timeline/projection.ts`), which `initializeTimelineSchema()`
+        // calls LAST in this function -- see the comment on that call for why it
+        // runs after every migration above it, this one included.
+        db.exec(`DROP TRIGGER IF EXISTS timeline_resources_ai`);
+        db.exec(`DROP TRIGGER IF EXISTS timeline_resources_au`);
+        db.exec(`DROP TRIGGER IF EXISTS timeline_resources_ad`);
+        // Enforcement has to be suspended across the drop, and put back
+        // afterwards on every path -- see `rebuildWithForeignKeysSuspended`. Here
+        // the tables that would be cascade-emptied are `resource_history` and
+        // `resource_constraint_members`, both of which declare
+        // `FOREIGN KEY (resource_id) REFERENCES resources(id) ON DELETE CASCADE`.
+        rebuildWithForeignKeysSuspended(db, "resources.owner_type", () => {
+            // 1. Copy the OLD table's rows into a staging table under a temporary
+            //    name, already carrying the widened CHECK.
+            db.exec(`
+        CREATE TABLE resources_staging (
+          id TEXT PRIMARY KEY,
+          game_id TEXT NOT NULL,
+          owner_id TEXT,
+          owner_type TEXT NOT NULL CHECK (owner_type IN ('game', 'character', 'faction', 'location')),
+          name TEXT NOT NULL,
+          description TEXT,
+          category TEXT,
+          value REAL NOT NULL DEFAULT 0,
+          min_value REAL,
+          max_value REAL,
+          created_at TEXT NOT NULL
+        )
+      `);
+            db.exec(`
+        INSERT INTO resources_staging (id, game_id, owner_id, owner_type, name, description, category, value, min_value, max_value, created_at)
+        SELECT id, game_id, owner_id, owner_type, name, description, category, value, min_value, max_value, created_at FROM resources
+      `);
+            // 2. Drop the OLD table outright -- not renamed. Renaming it out of
+            //    the way first would rewrite `resource_history` and
+            //    `resource_constraint_members`'s own stored FOREIGN KEY clauses to
+            //    point at the temporary name (RENAME TO rewrites every OTHER
+            //    table's FK text that references the renamed table, regardless of
+            //    the `foreign_keys` pragma), leaving them permanently dangling
+            //    once that temporary table is dropped a few steps later. `DROP
+            //    TABLE`, unlike `RENAME TO`, does not rewrite other tables'
+            //    references -- there is nothing to rewrite them TO -- so this
+            //    recipe never renames the table other tables' foreign keys point
+            //    at; the FINAL name is produced by a genuine `CREATE TABLE`
+            //    instead, and `resource_history`/`resource_constraint_members`'s
+            //    FK text is never touched by anything in this block.
+            db.exec(`DROP TABLE resources`);
+            // 3. Recreate under the FINAL name using the exact same DDL text the
+            //    fresh-database path executed above -- `RESOURCES_DDL` itself, not
+            //    a second hand-copied literal -- so its stored SQL matches the
+            //    fresh-database path byte for byte.
+            db.exec(RESOURCES_DDL);
+            // 4. Copy every row back across from the staging table with an
+            //    EXPLICIT column list -- never SELECT * -- and drop the staging
+            //    table. Every id was copied verbatim, so `resource_history` and
+            //    `resource_constraint_members`'s own `FOREIGN KEY (resource_id)
+            //    REFERENCES resources(id)` -- never touched by any of the steps
+            //    above -- is satisfied by the replacement table throughout,
+            //    verified for real by the `PRAGMA foreign_key_check` below, not
+            //    merely assumed here.
+            db.exec(`
+        INSERT INTO resources (id, game_id, owner_id, owner_type, name, description, category, value, min_value, max_value, created_at)
+        SELECT id, game_id, owner_id, owner_type, name, description, category, value, min_value, max_value, created_at FROM resources_staging
+      `);
+            db.exec(`DROP TABLE resources_staging`);
+        });
+    }
     // Resource history table (tracks all changes) -- FROZEN, see the trigger
     // immediately below. Kept for existing rows only; nothing writes here any
     // more.
@@ -393,15 +554,12 @@ export function initializeSchema(options) {
         // means it is unconditionally reinstalled before this function returns
         // regardless -- this is that discipline paying for itself a second time.
         db.exec(`DROP TRIGGER IF EXISTS timeline_facts_resolve_only`);
-        // PRAGMA foreign_keys is a documented no-op when toggled inside a
-        // pending transaction, so it brackets withTransaction() below rather
-        // than living inside it -- set OFF here (before BEGIN), restored ON
-        // after COMMIT. connection.ts turns it ON for every connection at
-        // open (`getDatabase()`); this block is the one place in the codebase
-        // that deliberately, temporarily, undoes that, and it is responsible
-        // for putting it back.
-        db.pragma("foreign_keys = OFF");
-        withTransaction(() => {
+        // Enforcement has to be suspended across the drop, and put back
+        // afterwards on every path -- see `rebuildWithForeignKeysSuspended`. Here
+        // the table that would be cascade-emptied is `resource_constraint_members`,
+        // which declares
+        // `FOREIGN KEY (constraint_id) REFERENCES resource_constraints(id) ON DELETE CASCADE`.
+        rebuildWithForeignKeysSuspended(db, "resource_constraints (resolve_only, issue #13)", () => {
             // EMPIRICALLY MEASURED, NOT ASSUMED (see resolveOnly.test.ts, whose
             // FK-check assertion caught a real bug in an earlier version of this
             // block): `ALTER TABLE ... RENAME TO` does not just rename the table
@@ -501,12 +659,6 @@ export function initializeSchema(options) {
             //    below, not merely assumed here.
             db.exec(`DROP TABLE resource_constraints_staging`);
         });
-        const fkViolations = db.pragma("foreign_key_check");
-        if (fkViolations.length > 0) {
-            throw new Error(`resource_constraints CHECK migration (resolve_only, issue #13) left dangling foreign keys: ` +
-                JSON.stringify(fkViolations));
-        }
-        db.pragma("foreign_keys = ON");
     }
     // Members of a resource constraint. 'bounded' and 'monotonic' constraints
     // have exactly one member (the resource they govern); 'conserved'

package/dist/http/server.js

@@ -583,7 +583,28 @@ export function createHttpServer(_port = 3456) {
                 next();
                 return;
             }
-            res.sendFile(join(CLIENT_DIST, "index.html"));
+            // `dotfiles: "allow"` is load-bearing, and its absence was a real bug.
+            //
+            // res.sendFile() with no `root` option hands the WHOLE absolute path to
+            // `send`, whose `dotfiles` default is "ignore" -- so if ANY segment of
+            // the path this package is installed under begins with a dot, `send`
+            // refuses the file with NotFoundError and the error handler below turns
+            // that into a 500. Every client-side route breaks at once, while `/`
+            // keeps working (it is served by express.static above, which only
+            // dotfile-checks the REQUEST path, not its own root). That is a
+            // spectacularly confusing failure: the app is fine, the file is there,
+            // and the deep link 500s because of where the checkout happens to live.
+            //
+            // Installing under a dot directory is ordinary -- a worktree beneath
+            // `.claude/`, a deploy under `~/.local/share`, a CI checkout in a dotted
+            // cache path -- so this is not a hypothetical.
+            //
+            // Safe, because the dotfiles guard is protecting nothing here: this path
+            // is a server-controlled constant (CLIENT_DIST plus a literal file name)
+            // and no part of it comes from the request. The guard exists to stop a
+            // user-supplied path from reaching `.env` or `.git`; there is no
+            // user-supplied path in it.
+            res.sendFile(join(CLIENT_DIST, "index.html"), { dotfiles: "allow" });
         });
     }
     else {

package/dist/index.d.ts

@@ -32,5 +32,38 @@ export { exportTimeline, importTimeline, exportTimelineToFile, importTimelineFro
 export type { TimelineExport, TimelineExportEntity, TimelineExportFact, TimelineExportEvent, TimelineExportClock, TimelineImportResult, } from "./timeline/export.js";
 export { ENTITY_KINDS } from "./timeline/kinds.js";
 export type { EntityKind } from "./timeline/kinds.js";
-export { DEFAULT_HTTP_PORT, httpPortFromEnv, webUiEnabled, setHttpPort, getWebUiBaseUrl, } from "./utils/webui.js";
+export { DEFAULT_HTTP_PORT, httpPortFromEnv, webUiEnabled, setHttpPort, getWebUiBaseUrl, getGameUrl, getCharacterUrl, getLocationUrl, } from "./utils/webui.js";
+export * from "./tools/game.js";
+export * from "./tools/world.js";
+export * from "./tools/character.js";
+export * from "./tools/faction.js";
+export * from "./tools/relationship.js";
+export * from "./tools/resource.js";
+export * from "./tools/constraint.js";
+export * from "./tools/inventory.js";
+export * from "./tools/secrets.js";
+export * from "./tools/narrative.js";
+export * from "./tools/notes.js";
+export * from "./tools/tags.js";
+export * from "./tools/time.js";
+export * from "./tools/timers.js";
+export * from "./tools/rules.js";
+export * from "./tools/pause.js";
+export * from "./tools/display.js";
+export * from "./tools/images.js";
+export * from "./tools/audio.js";
+export * from "./tools/image-prompt.js";
+export { gameEvents } from "./events/emitter.js";
+export type { GameEvent } from "./events/emitter.js";
+export { ANNOTATIONS, withAnnotations } from "./utils/tool-annotations.js";
+export { LIMITS, validatedSchemas, boundedString, boundedArray } from "./utils/validation.js";
+export { createError, formatErrorResponse, errors } from "./utils/errors.js";
+export type { AgentError } from "./utils/errors.js";
+export { createLogger } from "./utils/logger.js";
+export type { Logger } from "./utils/logger.js";
+export { verbositySchema, applyVerbosity, filterFields } from "./utils/verbosity.js";
+export type { VerbosityLevel } from "./utils/verbosity.js";
+export { safeJsonParse, safeJsonParseOrNull } from "./utils/json.js";
+export { successResponseSchema, textResultSchema, deletedResponseSchema, listResponseSchema, characterOutputSchema, characterStatusSchema, conditionModifyOutputSchema, tagModifyOutputSchema, } from "./utils/output-schemas.js";
+export { imageGenSchema, voiceSchema } from "./schemas/index.js";
 export type * from "./types/index.js";

package/dist/index.js

@@ -181,4 +181,82 @@ export { ENTITY_KINDS } from "./timeline/kinds.js";
 // ability and combat tools and is exported from "run-dmcp/rpg" instead
 // (src/rpg/index.ts), even though the file that implements it stays at
 // src/http/server.ts on disk.
-export { DEFAULT_HTTP_PORT, httpPortFromEnv, webUiEnabled, setHttpPort, getWebUiBaseUrl, } from "./utils/webui.js";
+export { DEFAULT_HTTP_PORT, httpPortFromEnv, webUiEnabled, setHttpPort, getWebUiBaseUrl, getGameUrl, getCharacterUrl, getLocationUrl, } from "./utils/webui.js";
+// ===========================================================================
+// The core's own tool modules, as library functions (design §8, §11 Phase 5).
+//
+// §8's layer table puts factions, relationships-with-history, secrets,
+// resources, locations and items in the CORE, and gives the reason: they are
+// "the client's spine. If these go up into the RPG layer, the client cannot
+// consume the package without dragging the RPG layer with it -- which defeats
+// the split." That reason is only satisfied if a consumer can actually IMPORT
+// them. Until this block, it could not: everything above is the timeline and
+// the database, and the only door to the spine was `createCoreMcpServer` --
+// the whole assembled server, which a consumer would then have to make tool
+// calls into, over a transport, to read its own tables.
+//
+// The layer ABOVE this one already got it right. src/rpg/index.ts ends with
+// six export-stars over its own tool modules, under a comment saying it is
+// using "the same shape core's index.ts uses for the timeline... a consumer
+// that wants to call combat/quest/table/status/ability/dice logic directly,
+// without going through an MCP tool call, can." The core never did
+//
+// (Those six are named here in prose rather than quoted as import lines on
+// purpose: layerBoundary.test.ts walks this file's import graph with a
+// deliberately syntactic scan for `from "<specifier>"`, and it cannot tell a
+// quoted example in a comment from a real edge. That is the guard being
+// conservative rather than clever, which is the right trade -- it fails loud
+// and names the chain. Do not teach it to strip comments; reword instead.)
+// the same for its own tools, which left the OPTIONAL layer more consumable
+// than the thing it is optional on top of. That is an oversight and not a
+// decision: §6's rule is "library functions first, MCP tools second", and the
+// narration-constraint and timeline-export blocks above both invoke it.
+//
+// This changes no behaviour and adds no dependency. Every module below is
+// ALREADY in this file's static import graph, reached through
+// ./mcp-server.js -> ./register/* -> ./tools/*, so src/__tests__/
+// layerBoundary.test.ts walks exactly the same file set before and after --
+// nothing under src/rpg/ becomes reachable, and none of the six tool modules
+// that moved up there is named here.
+export * from "./tools/game.js";
+export * from "./tools/world.js";
+export * from "./tools/character.js";
+export * from "./tools/faction.js";
+export * from "./tools/relationship.js";
+export * from "./tools/resource.js";
+export * from "./tools/constraint.js";
+export * from "./tools/inventory.js";
+export * from "./tools/secrets.js";
+export * from "./tools/narrative.js";
+export * from "./tools/notes.js";
+export * from "./tools/tags.js";
+export * from "./tools/time.js";
+export * from "./tools/timers.js";
+export * from "./tools/rules.js";
+export * from "./tools/pause.js";
+export * from "./tools/display.js";
+export * from "./tools/images.js";
+export * from "./tools/audio.js";
+export * from "./tools/image-prompt.js";
+// The event emitter the tool modules above write to. A consumer's own write
+// paths emit through the same singleton, so its tables and the engine's reach
+// one SSE subscriber rather than two competing ones.
+export { gameEvents } from "./events/emitter.js";
+// ===========================================================================
+// What a consumer needs to register tools OF ITS OWN onto the core server.
+//
+// A client keeps its own MCP surface -- that is the whole point of the split;
+// its mechanics are its own and the engine never learns their names. But a
+// tool it registers should refuse, bound and annotate the way the engine's do,
+// and today a client re-implements these or copies them and lets the copy
+// drift. Named one by one rather than star-exported: these modules contain
+// identifiers like `CREATE` and `UPDATE` that have no business in a package's
+// root namespace.
+export { ANNOTATIONS, withAnnotations } from "./utils/tool-annotations.js";
+export { LIMITS, validatedSchemas, boundedString, boundedArray } from "./utils/validation.js";
+export { createError, formatErrorResponse, errors } from "./utils/errors.js";
+export { createLogger } from "./utils/logger.js";
+export { verbositySchema, applyVerbosity, filterFields } from "./utils/verbosity.js";
+export { safeJsonParse, safeJsonParseOrNull } from "./utils/json.js";
+export { successResponseSchema, textResultSchema, deletedResponseSchema, listResponseSchema, characterOutputSchema, characterStatusSchema, conditionModifyOutputSchema, tagModifyOutputSchema, } from "./utils/output-schemas.js";
+export { imageGenSchema, voiceSchema } from "./schemas/index.js";

package/dist/mcp-server.d.ts

@@ -2,7 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Mechanic } from "./timeline/resolve.js";
 import { type RenderVocabulary } from "./timeline/render.js";
 export declare const SERVER_NAME = "dmcp";
-export declare const SERVER_VERSION = "0.2.0";
+export declare const SERVER_VERSION = "0.3.0";
 /**
  * Build an MCP server with every CORE tool, resource and prompt this engine
  * serves -- entities, facts, events, the timeline, and the entity/property

package/dist/mcp-server.js

@@ -41,7 +41,7 @@ import { registerRenderTools } from "./register/render.js";
 import { createResolver } from "./timeline/resolve.js";
 import { createStateRenderer } from "./timeline/render.js";
 export const SERVER_NAME = "dmcp";
-export const SERVER_VERSION = "0.2.0";
+export const SERVER_VERSION = "0.3.0";
 /**
  * Build an MCP server with every CORE tool, resource and prompt this engine
  * serves -- entities, facts, events, the timeline, and the entity/property

package/dist/register/resources.js

@@ -9,7 +9,7 @@ export function registerResourceTools(server) {
         description: "Create a new resource (currency, reputation, counter, etc.)",
         inputSchema: {
             gameId: z.string().max(100).describe("The game ID"),
-            ownerType: z.enum(["game", "character"]).describe("Owner type: 'game' for party/global resources, 'character' for personal resources"),
+            ownerType: z.enum(["game", "character", "faction", "location"]).describe("Owner type: 'game' for party/global resources, 'character' for personal resources, 'faction' or 'location' for resources owned by one of those entities"),
             ownerId: z.string().max(100).optional().describe("Character ID if ownerType is 'character' (omit for game-level resources)"),
             name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Resource name (e.g., 'Gold', 'Sanity', 'Thieves Guild Reputation')"),
             description: z.string().max(LIMITS.DESCRIPTION_MAX).optional().describe("Resource description"),
@@ -105,7 +105,7 @@ export function registerResourceTools(server) {
         description: "List resources in a game",
         inputSchema: {
             gameId: z.string().max(100).describe("The game ID"),
-            ownerType: z.enum(["game", "character"]).optional().describe("Filter by owner type"),
+            ownerType: z.enum(["game", "character", "faction", "location"]).optional().describe("Filter by owner type"),
             ownerId: z.string().max(100).optional().describe("Filter by owner ID (for character resources)"),
             category: z.string().max(100).optional().describe("Filter by category"),
         },

package/dist/timeline/changes.d.ts

@@ -92,6 +92,14 @@ export interface ChangeSet {
  * retroactively un-happen it. Filtering these rows by aliveness would be
  * exactly the kind of policy this module isn't allowed to have an opinion
  * on (see `ChangeSet`'s doc comment).
+ *
+ * DECISION(#18): changesWithin() returns every transition, whoever could observe it.
+ *
+ * Omniscient for the same reason and by the same decision as `replay()` --
+ * see its doc comment for the argument. Every transition in the window is
+ * returned regardless of which principal could have observed it, and a
+ * later per-principal filter arrives as one predicate on the two queries
+ * below (issue #18).
  */
 export declare function changesWithin(params: {
     gameId: string;

package/dist/timeline/changes.js

@@ -71,6 +71,14 @@ function compareChanges(a, b) {
  * retroactively un-happen it. Filtering these rows by aliveness would be
  * exactly the kind of policy this module isn't allowed to have an opinion
  * on (see `ChangeSet`'s doc comment).
+ *
+ * DECISION(#18): changesWithin() returns every transition, whoever could observe it.
+ *
+ * Omniscient for the same reason and by the same decision as `replay()` --
+ * see its doc comment for the argument. Every transition in the window is
+ * returned regardless of which principal could have observed it, and a
+ * later per-principal filter arrives as one predicate on the two queries
+ * below (issue #18).
  */
 export function changesWithin(params) {
     const { gameId, t0, t1 } = params;

package/dist/timeline/export.d.ts

@@ -28,6 +28,16 @@ import type { EntityKind } from "./kinds.js";
  * artifact contains no `file_path` anywhere and that those rows
  * contributed nothing (not even an extra entity).
  *
+ * DECISION(#18): the frozen artifact carries no per-principal projection.
+ *
+ * No visibility filtering either, and the same "requirement, not omission"
+ * applies (issue #18): the artifact is the omniscient timeline. Whether a
+ * per-principal export should exist is not a small question deferred for
+ * tidiness -- it decides whether §6's "one file a deterministic consumer
+ * depends on" becomes N files plus a rule for choosing between them. That
+ * is a decision for the caller that first needs it to own, and it cannot be
+ * made well against no caller, so it is not made here.
+ *
  * No live tables either. The live projected tables (`games`, `characters`,
  * `resources`, ...) are a projection of the timeline, not a second source
  * of truth (design §5.4's decided destination) -- a file carrying both

package/dist/timeline/export.js

@@ -28,6 +28,16 @@ import { getDatabase, withTransaction } from "../db/connection.js";
  * artifact contains no `file_path` anywhere and that those rows
  * contributed nothing (not even an extra entity).
  *
+ * DECISION(#18): the frozen artifact carries no per-principal projection.
+ *
+ * No visibility filtering either, and the same "requirement, not omission"
+ * applies (issue #18): the artifact is the omniscient timeline. Whether a
+ * per-principal export should exist is not a small question deferred for
+ * tidiness -- it decides whether §6's "one file a deterministic consumer
+ * depends on" becomes N files plus a rule for choosing between them. That
+ * is a decision for the caller that first needs it to own, and it cannot be
+ * made well against no caller, so it is not made here.
+ *
  * No live tables either. The live projected tables (`games`, `characters`,
  * `resources`, ...) are a projection of the timeline, not a second source
  * of truth (design §5.4's decided destination) -- a file carrying both

package/dist/timeline/irreversible.d.ts

@@ -1,5 +1,7 @@
 import { type FactProvenance } from "./provenance.js";
 /**
+ * DECISION(#21): contradiction is whole-value comparison under one key.
+ *
  * `irreversible` -- the temporal member of the constraint family alongside
  * `bounded`, `monotonic`, and conserved sets (design §5.3). Declared per
  * fact, not per entity or per value: `facts.irreversible` is a column on the

package/dist/timeline/replay.d.ts

@@ -57,6 +57,28 @@ export interface Snapshot {
  * large one and make every distinct entity count its own SQL text, which
  * defeats better-sqlite3's prepared-statement cache. Fixed SQL, two binds
  * of `t`, regardless of how many entities exist.
+ *
+ * DECISION(#18): replay() applies no visibility filtering, by decision rather than omission.
+ *
+ * OMNISCIENT, DELIBERATELY (issue #18). This returns every fact valid at
+ * `t`, for every entity alive at `t`, with no visibility filtering of any
+ * kind. That is a decision, not an omission: per-principal visibility is
+ * deferred until a real caller makes the requirement concrete, because the
+ * expensive half of such a feature is the principal model, and inventing a
+ * principal against an imagined client is precisely what design §13 forbids.
+ *
+ * Worth stating out loud here rather than leaving to be inferred, because
+ * the predecessor's unenforced version of the same decision is legible
+ * today for exactly one reason -- `get_secret`'s own description says "DM
+ * view - shows all info" -- and a reader who finds an unfiltered query with
+ * no such sentence cannot tell a decision from a hole.
+ *
+ * A later filter is additive and needs nothing reserved for it now: it is
+ * one predicate, added here once, because this function is the single place
+ * every reader of "what was true at `t`" goes through. Do NOT add a
+ * nullable visibility column to `facts` in anticipation -- an unpopulated
+ * one reads equally well as "visible to everyone" and "visible to no one",
+ * and both readings survive review.
  */
 export declare function replay(params: {
     gameId: string;

package/dist/timeline/replay.js

@@ -36,6 +36,28 @@ const ALIVE_AT_T = "e.created_at_t <= ? AND (e.destroyed_at_t IS NULL OR e.destr
  * large one and make every distinct entity count its own SQL text, which
  * defeats better-sqlite3's prepared-statement cache. Fixed SQL, two binds
  * of `t`, regardless of how many entities exist.
+ *
+ * DECISION(#18): replay() applies no visibility filtering, by decision rather than omission.
+ *
+ * OMNISCIENT, DELIBERATELY (issue #18). This returns every fact valid at
+ * `t`, for every entity alive at `t`, with no visibility filtering of any
+ * kind. That is a decision, not an omission: per-principal visibility is
+ * deferred until a real caller makes the requirement concrete, because the
+ * expensive half of such a feature is the principal model, and inventing a
+ * principal against an imagined client is precisely what design §13 forbids.
+ *
+ * Worth stating out loud here rather than leaving to be inferred, because
+ * the predecessor's unenforced version of the same decision is legible
+ * today for exactly one reason -- `get_secret`'s own description says "DM
+ * view - shows all info" -- and a reader who finds an unfiltered query with
+ * no such sentence cannot tell a decision from a hole.
+ *
+ * A later filter is additive and needs nothing reserved for it now: it is
+ * one predicate, added here once, because this function is the single place
+ * every reader of "what was true at `t`" goes through. Do NOT add a
+ * nullable visibility column to `facts` in anticipation -- an unpopulated
+ * one reads equally well as "visible to everyone" and "visible to no one",
+ * and both readings survive review.
  */
 export function replay(params) {
     const { gameId, t } = params;

package/dist/timeline/schema.js

@@ -53,6 +53,8 @@ export function initializeTimelineSchema() {
     // all (absence is the absence of a fact, never a fact of absence -- hard
     // rule 3). No ON DELETE CASCADE and no FK to `games`: deleting a game
     // deletes its live rows, but the timeline of that game survives.
+    // DECISION(#21): a property to be declared irreversible needs its own fact key.
+    //
     // `irreversible` is a per-fact flag, not a per-entity or per-value one --
     // so any property a future consumer wants to declare irreversible has to
     // live under its own fact key; you cannot flag half a blob.

package/dist/tools/audio.js

@@ -2,6 +2,7 @@ import { v4 as uuidv4 } from "uuid";
 import { getDatabase, getDataDir, withTransaction } from "../db/connection.js";
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync, rmSync, } from "fs";
 import { dirname, join, extname } from "path";
+import { mediaDirPath, mediaFilePath, mediaPathWithin } from "../utils/media-path.js";
 import { getCharacter } from "./character.js";
 import { getLocation } from "./world.js";
 import { getFaction } from "./faction.js";
@@ -128,10 +129,11 @@ export async function storeAudio(params) {
     else {
         throw new Error("Either url or filePath must be provided");
     }
-    // Build file path
+    // Build file path. Every segment below arrives from the caller, so the
+    // composition goes through the media-path choke point, which rejects
+    // anything that would land outside the audio directory.
     const ext = getExtension(mimeType);
-    const relativePath = join(params.gameId, `${params.entityType}s`, params.entityId, `${id}.${ext}`);
-    const fullPath = join(getAudioDir(), relativePath);
+    const { relativePath, fullPath } = mediaFilePath(getAudioDir(), [params.gameId, `${params.entityType}s`, params.entityId], `${id}.${ext}`);
     // Ensure directory exists and write file
     ensureDir(dirname(fullPath));
     writeFileSync(fullPath, audioBuffer);
@@ -192,7 +194,7 @@ export function getAudioFilePath(audioId) {
     const audio = getAudio(audioId);
     if (!audio)
         return null;
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (!existsSync(fullPath))
         return null;
     return fullPath;
@@ -201,7 +203,7 @@ export function getAudioData(audioId) {
     const audio = getAudio(audioId);
     if (!audio)
         return null;
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (!existsSync(fullPath))
         return null;
     const buffer = readFileSync(fullPath);
@@ -264,7 +266,7 @@ export function getCharacterVoiceReferences(gameId, characterId) {
     const audioDir = getAudioDir();
     const filePaths = voiceRefs
         .map((ref) => {
-        const fullPath = join(audioDir, ref.filePath);
+        const fullPath = mediaPathWithin(audioDir, ref.filePath);
         return existsSync(fullPath) ? fullPath : null;
     })
         .filter((p) => p !== null);
@@ -283,7 +285,7 @@ export function deleteAudio(audioId) {
     if (!audio)
         return false;
     // Delete file
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (existsSync(fullPath)) {
         unlinkSync(fullPath);
     }
@@ -339,8 +341,10 @@ export function updateAudioMetadata(audioId, updates) {
 // Cleanup helper - delete all audio for a game
 export function deleteGameAudio(gameId) {
     const db = getDatabase();
-    // Delete files
-    const gameDir = join(getAudioDir(), gameId);
+    // Delete files. mediaDirPath rejects before the rmSync below, which is
+    // recursive and forced: an unchecked `..` here would take the whole data
+    // directory with it.
+    const gameDir = mediaDirPath(getAudioDir(), [gameId]);
     if (existsSync(gameDir)) {
         rmSync(gameDir, { recursive: true, force: true });
     }

package/dist/tools/game.js

@@ -1,6 +1,10 @@
 import { v4 as uuidv4 } from "uuid";
 import { getDatabase } from "../db/connection.js";
 import { safeJsonParse } from "../utils/json.js";
+import { createLogger } from "../utils/logger.js";
+import { deleteGameAudio } from "./audio.js";
+import { deleteGameImages } from "./images.js";
+const log = createLogger("game");
 /**
  * Validates that a game exists and returns it, or throws an error if not found.
  * Use this in create operations to prevent orphaned records.
@@ -119,7 +123,35 @@ export function deleteGame(id) {
     const db = getDatabase();
     const stmt = db.prepare(`DELETE FROM games WHERE id = ?`);
     const result = stmt.run(id);
-    return result.changes > 0;
+    if (result.changes === 0)
+        return false;
+    // The stored_audio / stored_images rows went with the game by foreign key
+    // cascade, so nothing is left that knows the files on disk exist. Cleanup
+    // therefore runs here, after the delete has committed.
+    //
+    // A cleanup failure degrades to a log rather than an exception: the row is
+    // already gone and throwing cannot un-delete it, so it would trade a stale
+    // directory for a failed tool call and lose both. Each cleanup is attempted
+    // separately, so one failing does not skip the other.
+    try {
+        deleteGameAudio(id);
+    }
+    catch (error) {
+        log.error("Failed to remove stored audio for a deleted game; files remain on disk", {
+            gameId: id,
+            error: error.message,
+        });
+    }
+    try {
+        deleteGameImages(id);
+    }
+    catch (error) {
+        log.error("Failed to remove stored images for a deleted game; files remain on disk", {
+            gameId: id,
+            error: error.message,
+        });
+    }
+    return true;
 }
 export function updateGameLocation(gameId, locationId) {
     const db = getDatabase();

package/dist/tools/images.js

@@ -3,6 +3,7 @@ import { getDatabase, getDataDir, withTransaction } from "../db/connection.js";
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync, rmSync, } from "fs";
 import { dirname, join } from "path";
 import sharp from "sharp";
+import { mediaDirPath, mediaFilePath, mediaPathWithin } from "../utils/media-path.js";
 import { getCharacter } from "./character.js";
 import { getLocation } from "./world.js";
 import { getItem } from "./inventory.js";
@@ -122,10 +123,11 @@ export async function storeImage(params) {
     catch {
         // If sharp can't parse it, proceed without dimensions
     }
-    // Build file path
+    // Build file path. Every segment below arrives from the caller, so the
+    // composition goes through the media-path choke point, which rejects
+    // anything that would land outside the images directory.
     const ext = getExtension(mimeType);
-    const relativePath = join(params.gameId, `${params.entityType}s`, params.entityId, `${id}.${ext}`);
-    const fullPath = join(getImagesDir(), relativePath);
+    const { relativePath, fullPath } = mediaFilePath(getImagesDir(), [params.gameId, `${params.entityType}s`, params.entityId], `${id}.${ext}`);
     // Ensure directory exists and write file
     ensureDir(dirname(fullPath));
     writeFileSync(fullPath, imageBuffer);
@@ -177,7 +179,7 @@ export async function getImageData(imageId, options) {
     const image = getImage(imageId);
     if (!image)
         return null;
-    const fullPath = join(getImagesDir(), image.filePath);
+    const fullPath = mediaPathWithin(getImagesDir(), image.filePath);
     if (!existsSync(fullPath))
         return null;
     const originalBuffer = readFileSync(fullPath);
@@ -335,7 +337,7 @@ export function deleteImage(imageId) {
     if (!image)
         return false;
     // Delete file
-    const fullPath = join(getImagesDir(), image.filePath);
+    const fullPath = mediaPathWithin(getImagesDir(), image.filePath);
     if (existsSync(fullPath)) {
         unlinkSync(fullPath);
     }
@@ -380,10 +382,13 @@ export function updateImageMetadata(imageId, updates) {
         validateEntityExists(newEntityId, newEntityType);
         // If entity changed, move the file
         if (newEntityId !== current.entityId || newEntityType !== current.entityType) {
-            const oldFullPath = join(getImagesDir(), current.filePath);
+            const oldFullPath = mediaPathWithin(getImagesDir(), current.filePath);
             const ext = current.filePath.split(".").pop() || "png";
-            newFilePath = join(current.gameId, `${newEntityType}s`, newEntityId, `${imageId}.${ext}`);
-            const newFullPath = join(getImagesDir(), newFilePath);
+            // The move recomposes the path from a caller-supplied entity id and
+            // type, so it goes through the same choke point as the original write.
+            const moved = mediaFilePath(getImagesDir(), [current.gameId, `${newEntityType}s`, newEntityId], `${imageId}.${ext}`);
+            newFilePath = moved.relativePath;
+            const newFullPath = moved.fullPath;
             // Ensure new directory exists
             ensureDir(dirname(newFullPath));
             // Move the file
@@ -411,8 +416,10 @@ export function updateImageMetadata(imageId, updates) {
 // Cleanup helper - delete all images for a game
 export function deleteGameImages(gameId) {
     const db = getDatabase();
-    // Delete files
-    const sessionDir = join(getImagesDir(), gameId);
+    // Delete files. mediaDirPath rejects before the rmSync below, which is
+    // recursive and forced: an unchecked `..` here would take the whole data
+    // directory with it.
+    const sessionDir = mediaDirPath(getImagesDir(), [gameId]);
     if (existsSync(sessionDir)) {
         rmSync(sessionDir, { recursive: true, force: true });
     }

package/dist/tools/resource.d.ts

@@ -1,7 +1,7 @@
 import type { Resource, ResourceChange } from "../types/index.js";
 export declare function createResource(params: {
     gameId: string;
-    ownerType: "game" | "character";
+    ownerType: "game" | "character" | "faction" | "location";
     ownerId?: string;
     name: string;
     description?: string;
@@ -20,7 +20,7 @@ export declare function updateResource(id: string, updates: {
 }): Resource | null;
 export declare function deleteResource(id: string): boolean;
 export declare function listResources(gameId: string, filter?: {
-    ownerType?: "game" | "character";
+    ownerType?: "game" | "character" | "faction" | "location";
     ownerId?: string;
     category?: string;
 }): Resource[];

package/dist/tools/time.js

@@ -133,9 +133,24 @@ export function advanceTime(gameId, duration) {
     const consequenceFailures = [];
     for (const row of events) {
         const triggerTime = safeJsonParse(row.trigger_time, { year: 1, month: 1, day: 1, hour: 0, minute: 0 });
-        // Check if event should trigger (trigger time is between previous and new time)
-        if (compareDateTime(triggerTime, previousTime, calendarConfig) >= 0 &&
-            compareDateTime(triggerTime, newTime, calendarConfig) <= 0) {
+        // Due if the trigger time has been reached -- deliberately NOT also gated
+        // on `triggerTime >= previousTime`.
+        //
+        // That lower bound looks like the right window ("did we cross it on THIS
+        // call?") and quietly broke the retry the catch block below promises. When
+        // a consequence throws, the transaction rolls back and the row stays
+        // pending, exactly as intended -- but the clock has already moved past
+        // triggerTime by then, because it is updated unconditionally above. On
+        // every subsequent call the lower bound therefore excluded the row, and
+        // the event sat pending forever with its consequence never applied. The
+        // rollback was correct and unreachable.
+        //
+        // Without the lower bound, "pending and past due" is the whole condition,
+        // which is the same retry semantics timers already have. The `triggered =
+        // 0` filter in the query above is what keeps this exactly-once: a
+        // successful event is marked (or, if recurring, rescheduled forward) in
+        // the same transaction as its consequence, so it cannot come back.
+        if (compareDateTime(triggerTime, newTime, calendarConfig) <= 0) {
             const eventId = row.id;
             const eventName = row.name;
             const recurring = row.recurring;

package/dist/types/index.d.ts

@@ -465,7 +465,7 @@ export interface Resource {
     id: string;
     gameId: string;
     ownerId: string | null;
-    ownerType: "game" | "character";
+    ownerType: "game" | "character" | "faction" | "location";
     name: string;
     description: string;
     category: string | null;

package/dist/utils/media-path.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The one place a path beneath a media root is composed or resolved.
+ *
+ * Media file paths are built from ids that arrive over the wire -- a game id,
+ * an entity id, an entity type -- and are then handed to `writeFileSync` and,
+ * worse, to a recursive `rmSync`. `join()` resolves `..` happily, so an id
+ * carrying one walks out of the data directory before the write. The rule this
+ * breaks is the engine's: it writes nothing to the consumer's machine that the
+ * consumer did not name.
+ *
+ * The guard is here, at the composition point, rather than at each call site,
+ * because a per-site check is one forgotten site away from being no check. Two
+ * things are asserted, and both are literal checks over characters -- never an
+ * attempt to read meaning out of a value (root CLAUDE.md hard rule 4):
+ *
+ *   1. Every path segment matches an allowlist. Every id the engine mints is a
+ *      UUID and every entity type is an ASCII word, so the allowlist costs
+ *      nothing the engine actually uses.
+ *   2. The resolved result is strictly beneath the resolved root -- a
+ *      structural backstop that holds even for a path this module did not
+ *      compose, such as one read back out of a row written before this guard
+ *      existed.
+ *
+ * Rejection, never normalisation: an id containing `a/../b` is refused rather
+ * than quietly rewritten to `b`, because the rewrite would silently store one
+ * caller's media under a different id than the caller named.
+ */
+export declare class MediaPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a relative path against a media root, refusing anything that is not
+ * strictly beneath it. Use for paths read back from a row; `mediaFilePath` and
+ * `mediaDirPath` funnel through it too, so every media path in the codebase
+ * passes this check exactly once.
+ */
+export declare function mediaPathWithin(root: string, relativePath: string): string;
+/**
+ * Compose the path of a media file from segments and a leaf file name,
+ * returning both the relative path to store in the row and the full path to
+ * write to.
+ */
+export declare function mediaFilePath(root: string, segments: string[], filename: string): {
+    relativePath: string;
+    fullPath: string;
+};
+/**
+ * Compose the path of a directory beneath a media root. The caller of this one
+ * is a recursive delete, so an empty segment list -- which would resolve to the
+ * media root itself -- is refused along with everything else.
+ */
+export declare function mediaDirPath(root: string, segments: string[]): string;

package/dist/utils/media-path.js

@@ -0,0 +1,106 @@
+import { isAbsolute, join, resolve, sep } from "path";
+import { createLogger } from "./logger.js";
+const log = createLogger("media-path");
+/**
+ * The one place a path beneath a media root is composed or resolved.
+ *
+ * Media file paths are built from ids that arrive over the wire -- a game id,
+ * an entity id, an entity type -- and are then handed to `writeFileSync` and,
+ * worse, to a recursive `rmSync`. `join()` resolves `..` happily, so an id
+ * carrying one walks out of the data directory before the write. The rule this
+ * breaks is the engine's: it writes nothing to the consumer's machine that the
+ * consumer did not name.
+ *
+ * The guard is here, at the composition point, rather than at each call site,
+ * because a per-site check is one forgotten site away from being no check. Two
+ * things are asserted, and both are literal checks over characters -- never an
+ * attempt to read meaning out of a value (root CLAUDE.md hard rule 4):
+ *
+ *   1. Every path segment matches an allowlist. Every id the engine mints is a
+ *      UUID and every entity type is an ASCII word, so the allowlist costs
+ *      nothing the engine actually uses.
+ *   2. The resolved result is strictly beneath the resolved root -- a
+ *      structural backstop that holds even for a path this module did not
+ *      compose, such as one read back out of a row written before this guard
+ *      existed.
+ *
+ * Rejection, never normalisation: an id containing `a/../b` is refused rather
+ * than quietly rewritten to `b`, because the rewrite would silently store one
+ * caller's media under a different id than the caller named.
+ */
+export class MediaPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MediaPathError";
+    }
+}
+/** Directory names: ids the engine mints, plus pluralised entity types. */
+const SAFE_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** Leaf file names: a safe stem, one dot, an alphanumeric extension. */
+const SAFE_FILENAME = /^[A-Za-z0-9_-]+\.[A-Za-z0-9]+$/;
+function reject(what, value) {
+    log.warn("Refused a media path built from an unsafe value", { what, value });
+    throw new MediaPathError(`Unsafe ${what} for a media path: ${JSON.stringify(value)}. ` +
+        `Only letters, digits, underscore and hyphen are allowed; a path separator, ` +
+        `"." or ".." would escape the media directory.`);
+}
+function assertSafeSegment(value) {
+    if (typeof value !== "string" || !SAFE_SEGMENT.test(value)) {
+        reject("path segment", String(value));
+    }
+}
+/**
+ * Resolve a relative path against a media root, refusing anything that is not
+ * strictly beneath it. Use for paths read back from a row; `mediaFilePath` and
+ * `mediaDirPath` funnel through it too, so every media path in the codebase
+ * passes this check exactly once.
+ */
+export function mediaPathWithin(root, relativePath) {
+    if (typeof relativePath !== "string" || relativePath.length === 0) {
+        reject("stored path", String(relativePath));
+    }
+    if (isAbsolute(relativePath)) {
+        reject("stored path", relativePath);
+    }
+    // Split on both separators regardless of platform: a stored path composed on
+    // one and read on another must not sneak a traversal past the check.
+    for (const segment of relativePath.split(/[\\/]/)) {
+        if (segment.length === 0 || segment === "." || segment === "..") {
+            reject("stored path", relativePath);
+        }
+    }
+    const rootResolved = resolve(root);
+    const fullPath = resolve(rootResolved, relativePath);
+    // Compare with the separator appended, so a sibling directory whose name
+    // merely starts with the root's (`<root>-elsewhere`) is not mistaken for a
+    // child of it.
+    if (!fullPath.startsWith(rootResolved + sep)) {
+        reject("stored path", relativePath);
+    }
+    return fullPath;
+}
+/**
+ * Compose the path of a media file from segments and a leaf file name,
+ * returning both the relative path to store in the row and the full path to
+ * write to.
+ */
+export function mediaFilePath(root, segments, filename) {
+    segments.forEach(assertSafeSegment);
+    if (typeof filename !== "string" || !SAFE_FILENAME.test(filename)) {
+        reject("file name", String(filename));
+    }
+    const relativePath = join(...segments, filename);
+    return { relativePath, fullPath: mediaPathWithin(root, relativePath) };
+}
+/**
+ * Compose the path of a directory beneath a media root. The caller of this one
+ * is a recursive delete, so an empty segment list -- which would resolve to the
+ * media root itself -- is refused along with everything else.
+ */
+export function mediaDirPath(root, segments) {
+    if (segments.length === 0) {
+        reject("path segment", "");
+    }
+    segments.forEach(assertSafeSegment);
+    return mediaPathWithin(root, join(...segments));
+}

package/dist/utils/output-schemas.d.ts

@@ -76,17 +76,17 @@ export declare const gameMenuOutputSchema: {
         setting: string;
         id: string;
         name: string;
+        createdAt: string;
         style: string;
         updatedAt: string;
-        createdAt: string;
         webUiUrl?: string | undefined;
     }, {
         setting: string;
         id: string;
         name: string;
+        createdAt: string;
         style: string;
         updatedAt: string;
-        createdAt: string;
         webUiUrl?: string | undefined;
     }>, "many">;
     instruction: z.ZodString;
@@ -776,8 +776,8 @@ export declare const characterListOutputSchema: {
             experience: number;
             level: number;
         };
-        locationId: string | null;
         isPlayer: boolean;
+        locationId: string | null;
     }, {
         id: string;
         name: string;
@@ -788,8 +788,8 @@ export declare const characterListOutputSchema: {
             experience: number;
             level: number;
         };
-        locationId: string | null;
         isPlayer: boolean;
+        locationId: string | null;
     }>, "many">;
     count: z.ZodNumber;
 };
@@ -1138,7 +1138,7 @@ export declare const resourceOutputSchema: {
     id: z.ZodString;
     gameId: z.ZodString;
     ownerId: z.ZodNullable<z.ZodString>;
-    ownerType: z.ZodEnum<["game", "character"]>;
+    ownerType: z.ZodEnum<["game", "character", "faction", "location"]>;
     name: z.ZodString;
     description: z.ZodString;
     category: z.ZodNullable<z.ZodString>;

package/dist/utils/output-schemas.js

@@ -278,7 +278,7 @@ export const resourceOutputSchema = {
     id: z.string(),
     gameId: z.string(),
     ownerId: z.string().nullable(),
-    ownerType: z.enum(["game", "character"]),
+    ownerType: z.enum(["game", "character", "faction", "location"]),
     name: z.string(),
     description: z.string(),
     category: z.string().nullable(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-dmcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An MCP server for LLM-run interactive fiction where the server owns what is true - including when it was true. A continuation of DMCP.",
   "license": "MIT",
   "author": "Derek Ferguson",
@@ -37,11 +37,14 @@
     "test:coverage": "vitest run --coverage",
     "test:client": "cd client && npm run test",
     "test:all": "npm run test:run && npm run test:client -- run",
+    "test:acceptance": "npm run build && playwright test",
+    "test:acceptance:only": "playwright test",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write \"src/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "typecheck:e2e": "tsc --noEmit -p tsconfig.e2e.json"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -53,6 +56,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
+    "@playwright/test": "^1.62.1",
     "@types/better-sqlite3": "^7.6.11",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",