run-dmcp 0.1.0 → 0.2.0

package/dist/register/mcp-resources.js

@@ -2,9 +2,24 @@ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as gameTools from "../tools/game.js";
 import * as characterTools from "../tools/character.js";
 import * as worldTools from "../tools/world.js";
-import * as questTools from "../tools/quest.js";
 import * as narrativeTools from "../tools/narrative.js";
 import * as rulesTools from "../tools/rules.js";
+// Helper to create list callback for game-scoped resources. Hoisted to
+// module scope and exported (design §8, issue #17) so that
+// src/rpg/register/mcp-resources.ts's game-quests and quest resources --
+// the two RPG-shaped entries pulled out of this file -- share this one
+// implementation rather than growing a second copy of it.
+export const createGameListCallback = (suffix, nameFormatter) => {
+    return async () => {
+        const games = gameTools.listGames();
+        return {
+            resources: games.map((g) => ({
+                uri: `dmcp://game/${g.id}${suffix}`,
+                name: nameFormatter(g),
+            })),
+        };
+    };
+};
 export function registerMcpResources(server) {
     // ============================================================================
     // STATIC RESOURCES
@@ -28,18 +43,6 @@ export function registerMcpResources(server) {
     // ============================================================================
     // GAME-SCOPED RESOURCES (templated)
     // ============================================================================
-    // Helper to create list callback for game-scoped resources
-    const createGameListCallback = (suffix, nameFormatter) => {
-        return async () => {
-            const games = gameTools.listGames();
-            return {
-                resources: games.map((g) => ({
-                    uri: `dmcp://game/${g.id}${suffix}`,
-                    name: nameFormatter(g),
-                })),
-            };
-        };
-    };
     // Game details
     server.registerResource("game", new ResourceTemplate("dmcp://game/{gameId}", {
         list: createGameListCallback("", (g) => g.name),
@@ -171,25 +174,6 @@ export function registerMcpResources(server) {
             ],
         };
     });
-    // Game quests
-    server.registerResource("game-quests", new ResourceTemplate("dmcp://game/{gameId}/quests", {
-        list: createGameListCallback("/quests", (g) => `${g.name} - Quests`),
-    }), {
-        description: "All quests in the game",
-        mimeType: "application/json",
-    }, async (uri, variables) => {
-        const gameId = variables.gameId;
-        const quests = questTools.listQuests(gameId);
-        return {
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: "application/json",
-                    text: JSON.stringify(quests, null, 2),
-                },
-            ],
-        };
-    });
     // Game history (recent narrative events)
     server.registerResource("game-history", new ResourceTemplate("dmcp://game/{gameId}/history", {
         list: createGameListCallback("/history", (g) => `${g.name} - History`),
@@ -302,34 +286,4 @@ export function registerMcpResources(server) {
             ],
         };
     });
-    // Quest by ID
-    server.registerResource("quest", new ResourceTemplate("dmcp://quest/{questId}", {
-        list: undefined, // No enumeration - access by ID only
-    }), {
-        description: "Quest details with objectives",
-        mimeType: "application/json",
-    }, async (uri, variables) => {
-        const questId = variables.questId;
-        const quest = questTools.getQuest(questId);
-        if (!quest) {
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        mimeType: "application/json",
-                        text: JSON.stringify({ error: "Quest not found" }),
-                    },
-                ],
-            };
-        }
-        return {
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: "application/json",
-                    text: JSON.stringify(quest, null, 2),
-                },
-            ],
-        };
-    });
 }

package/dist/register/render.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { StateRenderer } from "../timeline/render.js";
+/**
+ * The MCP surface for the engine's state-to-text projection (design §7,
+ * §8, GitHub issue #16) -- one tool, `render_state_at`. Registered ONLY
+ * when a caller supplies a `StateRenderer` to `createCoreMcpServer`
+ * (src/mcp-server.ts), itself built by `createStateRenderer({ vocabulary
+ * })` (timeline/render.ts) over a caller-injected, caller-owned vocabulary.
+ * An engine with no injected vocabulary has nothing to name and registers
+ * no render tool at all -- the same "injection at construction" shape
+ * `registerResolveTools` (resolve.ts) already uses for its `Resolver`, and
+ * for the identical reason: there is no global renderer anywhere in this
+ * codebase, and this file carries no vocabulary of its own, not even an
+ * example (root CLAUDE.md hard rule 3, design §7's "mechanism is core, the
+ * vocabulary is injected").
+ */
+export declare function registerRenderTools(server: McpServer, renderer: StateRenderer): void;

package/dist/register/render.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("render");
+/**
+ * The MCP surface for the engine's state-to-text projection (design §7,
+ * §8, GitHub issue #16) -- one tool, `render_state_at`. Registered ONLY
+ * when a caller supplies a `StateRenderer` to `createCoreMcpServer`
+ * (src/mcp-server.ts), itself built by `createStateRenderer({ vocabulary
+ * })` (timeline/render.ts) over a caller-injected, caller-owned vocabulary.
+ * An engine with no injected vocabulary has nothing to name and registers
+ * no render tool at all -- the same "injection at construction" shape
+ * `registerResolveTools` (resolve.ts) already uses for its `Resolver`, and
+ * for the identical reason: there is no global renderer anywhere in this
+ * codebase, and this file carries no vocabulary of its own, not even an
+ * example (root CLAUDE.md hard rule 3, design §7's "mechanism is core, the
+ * vocabulary is injected").
+ */
+export function registerRenderTools(server, renderer) {
+    server.registerTool("render_state_at", {
+        description: "Render a game's world at t as positive concrete nouns, drawn only from the caller's own injected " +
+            "vocabulary -- 'the grain stores are full and the treasury coffers overflow', never 'the grain stores " +
+            "are no longer empty'. The renderer's sole source of state is replay(t): a fact that does not hold at " +
+            "t produces nothing, not a phrase about its absence. A fact that DOES hold but has no vocabulary entry " +
+            "is reported as an unnamed row rather than described or invented -- that is how a caller learns its " +
+            "vocabulary is too thin, without the engine passing judgement on it. No diff, no comparison against " +
+            "another t, and no transition/change form: state at one t, full stop.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: z
+                .number()
+                .finite()
+                .describe("An opaque ordinal on this game's declared time axis -- never a datetime, and never an index " +
+                "into units you might later re-cut."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t }) => {
+        try {
+            const rendered = renderer.render({ gameId, t });
+            return { content: [{ type: "text", text: JSON.stringify(rendered, null, 2) }] };
+        }
+        catch (error) {
+            log.error("render_state_at failed", { gameId, t, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/register/resolve.d.ts

@@ -0,0 +1,14 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Resolver } from "../timeline/resolve.js";
+/**
+ * The MCP surface for the resolve protocol (design §5.2a, issue #10) --
+ * `resolve` and `list_mechanics`. Registered ONLY when a caller supplies a
+ * non-empty `mechanics` array to `createCoreMcpServer` (src/mcp-server.ts): an
+ * engine with no mechanics has no resolve surface, and that is the correct
+ * shape rather than a resolve tool that could only ever answer
+ * "unknown-mechanic" and a list_mechanics that could only ever answer `[]`.
+ * This keeps injection at construction -- there is still no global resolver
+ * anywhere in this codebase, only the one `Resolver` instance a caller built
+ * and handed in, closed over by the two tool handlers below.
+ */
+export declare function registerResolveTools(server: McpServer, resolver: Resolver): void;

package/dist/register/resolve.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { createLogger } from "../utils/logger.js";
+import { errors, formatErrorResponse } from "../utils/errors.js";
+import { ConstraintViolationError } from "../timeline/registry.js";
+import { ResolveProtocolError } from "../timeline/resolve.js";
+const log = createLogger("resolve");
+/**
+ * The MCP surface for the resolve protocol (design §5.2a, issue #10) --
+ * `resolve` and `list_mechanics`. Registered ONLY when a caller supplies a
+ * non-empty `mechanics` array to `createCoreMcpServer` (src/mcp-server.ts): an
+ * engine with no mechanics has no resolve surface, and that is the correct
+ * shape rather than a resolve tool that could only ever answer
+ * "unknown-mechanic" and a list_mechanics that could only ever answer `[]`.
+ * This keeps injection at construction -- there is still no global resolver
+ * anywhere in this codebase, only the one `Resolver` instance a caller built
+ * and handed in, closed over by the two tool handlers below.
+ */
+export function registerResolveTools(server, resolver) {
+    server.registerTool("resolve", {
+        description: "Propose a resolution to a registered mechanic and get back its outcome. The engine enforces the " +
+            "PROTOCOL -- resolution happens before narration, writes go through the audited path, declared " +
+            "expectations are checked before dispatch -- without knowing what the mechanic itself means. " +
+            "Refuses (no window opens, nothing is written) for an unknown mechanic, a game with no timeline " +
+            "clock, or a declared expectation that does not hold at the game's current t -- the last of these " +
+            "carries one hop of causality per contradicted expectation, so a caller can tell whether the fact " +
+            "is wrong or the claim is. A constraint violated mid-adjudication (bounded, monotonic, conserved, " +
+            "resolve_only, irreversible) rolls back every change in the resolution and records no event.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            mechanic: z.string().min(1).max(200).describe("The name of a mechanic registered with this resolver"),
+            parameters: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Opaque to the engine -- handed to the mechanic verbatim, never inspected here"),
+            expects: z
+                .array(z.object({
+                entityId: z.string().max(100).describe("The entity this expectation is about"),
+                key: z.string().max(200).describe("The fact key this expectation is about"),
+                value: z.union([z.string(), z.number()]).describe("The value this proposal declares it depends on"),
+            }))
+                .optional()
+                .describe("Facts this proposal declares it depends on, verified BEFORE the mechanic is dispatched. A caller's " +
+                "own declared precondition -- the engine only reports whether it holds, never why it should."),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ gameId, mechanic, parameters, expects }) => {
+        try {
+            const outcome = resolver.resolve({ gameId, mechanic, parameters, expects });
+            return { content: [{ type: "text", text: JSON.stringify(outcome, null, 2) }] };
+        }
+        catch (error) {
+            if (error instanceof ResolveProtocolError) {
+                log.error("resolve refused", { gameId, mechanic, reason: error.reason, error: error.message });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: error.message,
+                                reason: error.reason,
+                                contradictions: error.contradictions ?? undefined,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (error instanceof ConstraintViolationError) {
+                log.error("resolve rolled back", {
+                    gameId,
+                    mechanic,
+                    constraintKind: error.constraintKind,
+                    error: error.message,
+                });
+                return formatErrorResponse(errors.constraintViolation(error.resourceId, error.message));
+            }
+            log.error("resolve failed", { gameId, mechanic, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("list_mechanics", {
+        description: "List every mechanic name registered with this resolver. The engine holds these names; it never " +
+            "reads meaning into them -- they are exactly what a caller handed to createCoreMcpServer's mechanics option.",
+        inputSchema: {},
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async () => {
+        try {
+            return { content: [{ type: "text", text: JSON.stringify(resolver.mechanics(), null, 2) }] };
+        }
+        catch (error) {
+            log.error("list_mechanics failed", { error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/register/resources.js

@@ -207,17 +207,19 @@ export function registerResourceTools(server) {
         description: "Declare a server-enforced invariant on one or more resources, so update_resource_value cannot write a value that violates it. " +
             "'bounded': the resource must already have minValue and/or maxValue set (via create_resource/update_resource) -- once declared, writes outside those bounds are REJECTED instead of the default silent clamp. " +
             "'monotonic': the resource's value may only move in one direction ('increasing' = never decreases, 'decreasing' = never increases); holding steady is always allowed. " +
-            "'conserved': declares a set of 2+ resources that must always sum to a fixed total -- the members' current values must already sum to `total` (this does not rewrite them to match). Once declared, update_resource_value REJECTS direct writes to any member (ambiguous -- it can't know where the offsetting change comes from); use transfer_resource_value to move value between two members of the set atomically instead. A resource can belong to at most one 'conserved' set at a time.",
+            "'conserved': declares a set of 2+ resources that must always sum to a fixed total -- the members' current values must already sum to `total` (this does not rewrite them to match). Once declared, update_resource_value REJECTS direct writes to any member (ambiguous -- it can't know where the offsetting change comes from); use transfer_resource_value to move value between two members of the set atomically instead. A resource can belong to at most one 'conserved' set at a time. " +
+            "'resolve_only': every DIRECT write to the given fact key is refused -- both update_resource_value and transfer_resource_value -- so it can move only through an adjudicating call. Scoped to one fact key (factKey, default 'value'); a resource can hold a separate 'resolve_only' declaration per fact key.",
         inputSchema: {
             gameId: z.string().max(100).describe("The game ID"),
-            kind: z.enum(["bounded", "monotonic", "conserved"]).describe("Constraint kind"),
-            resourceId: z.string().max(100).optional().describe("Required for 'bounded' or 'monotonic': the resource to constrain"),
+            kind: z.enum(["bounded", "monotonic", "conserved", "resolve_only"]).describe("Constraint kind"),
+            resourceId: z.string().max(100).optional().describe("Required for 'bounded', 'monotonic' or 'resolve_only': the resource to constrain"),
             resourceIds: z.array(z.string().max(100)).optional().describe("Required for 'conserved': 2 or more resource IDs that must sum to `total`"),
             direction: z.enum(["increasing", "decreasing"]).optional().describe("Required for 'monotonic': the only direction the value may move"),
             total: z.number().optional().describe("Required for 'conserved': the fixed sum the resource set must maintain"),
+            factKey: z.string().max(100).optional().describe("For 'resolve_only' only: the fact key the constraint governs, defaulting to 'value'"),
         },
         annotations: ANNOTATIONS.CREATE,
-    }, async ({ gameId, kind, resourceId, resourceIds, direction, total }) => {
+    }, async ({ gameId, kind, resourceId, resourceIds, direction, total, factKey }) => {
         try {
             let constraint;
             if (kind === "bounded") {
@@ -231,6 +233,11 @@ export function registerResourceTools(server) {
                 }
                 constraint = constraintTools.declareMonotonicConstraint({ gameId, resourceId, direction });
             }
+            else if (kind === "resolve_only") {
+                if (!resourceId)
+                    throw new Error("resourceId is required for a 'resolve_only' constraint");
+                constraint = constraintTools.declareResolveOnlyConstraint({ gameId, resourceId, factKey });
+            }
             else {
                 if (!resourceIds || total === undefined) {
                     throw new Error("resourceIds and total are required for a 'conserved' constraint");

package/dist/register/timeline.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTimelineTools(server: McpServer): void;

package/dist/register/timeline.js

@@ -0,0 +1,311 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { createLogger } from "../utils/logger.js";
+import { replay } from "../timeline/replay.js";
+import { declareTimeAxis, setStoryTime, currentStoryTime } from "../timeline/clock.js";
+import { declareIrreversible, listIrreversibleFacts } from "../timeline/irreversible.js";
+import { exportTimelineToFile, importTimelineFromFile } from "../timeline/export.js";
+import { changesWithin } from "../timeline/changes.js";
+import { narrationConstraintAt } from "../timeline/narration.js";
+const log = createLogger("timeline");
+/**
+ * The `t` every tool below takes or returns. This is the surface an
+ * implementer actually meets the invariance property at (design §14, root
+ * CLAUDE.md hard rule 6) -- the description is deliberately short, because
+ * the property itself lives in `t.ts`'s `TimeAxis` doc comment; this is
+ * where a caller is reminded of it at the moment it matters.
+ */
+const tSchema = z
+    .number()
+    .finite()
+    .describe("An opaque ordinal on this game's declared time axis -- never a datetime, and never an " +
+    "index into units you might later re-cut.");
+/**
+ * Exactly the three variants `TimeAxis` (t.ts) allows, and no index-into-
+ * units fourth one -- the schema shape itself is part of what this issue
+ * asks for. `sequence` needs no `unit`; `elapsed`/`counter` need a
+ * caller-named one so the tool description alone can't be mistaken for
+ * always meaning "seconds".
+ */
+const timeAxisSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("sequence").describe("The engine's own append ordinal, one tick per write. Default for a game that declares nothing."),
+    }),
+    z.object({
+        kind: z.literal("elapsed").describe("Time since a fixed origin."),
+        unit: z.string().min(1).max(100).describe("What the elapsed count is measured in (e.g. 'second', 'minute')."),
+    }),
+    z.object({
+        kind: z.literal("counter").describe("A count of things that happened -- turns, ticks -- not of things authored."),
+        unit: z.string().min(1).max(100).describe("What is being counted (e.g. 'turn', 'tick')."),
+    }),
+]);
+export function registerTimelineTools(server) {
+    server.registerTool("replay_world_at", {
+        description: "Replay a game's world as it stood at a given t: every entity alive then, with every fact valid then. Works at any point in the game's recorded history, not only 'now'.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: tSchema,
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t }) => {
+        try {
+            const snapshot = replay({ gameId, t });
+            return { content: [{ type: "text", text: JSON.stringify(snapshot, null, 2) }] };
+        }
+        catch (error) {
+            log.error("replay_world_at failed", { gameId, t, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("changes_within", {
+        description: "List every event and fact-interval transition a game recorded in the half-open window [t0, t1) -- t0 is in, t1 is not. The range companion to replay_world_at's point query, for callers whose units have duration. A fact that both opens and closes inside the window returns two rows, one per endpoint. Returns rows and nothing else: no verdict, no severity, no judgement about whether the window is 'clean'. What a change inside a window means is the caller's policy, not the engine's.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t0: tSchema.describe("Start of the window, inclusive. Same axis as every other t for this game."),
+            t1: tSchema.describe("End of the window, exclusive. Must be >= t0. There is no open-ended form and no start-plus-length form -- a window is two points on the axis, never a point and a duration."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t0, t1 }) => {
+        try {
+            const changeSet = changesWithin({ gameId, t0, t1 });
+            return { content: [{ type: "text", text: JSON.stringify(changeSet, null, 2) }] };
+        }
+        catch (error) {
+            log.error("changes_within failed", { gameId, t0, t1, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("get_story_time", {
+        description: "Get a game's current position on its own timeline: t, and the axis it is measured on.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId }) => {
+        try {
+            const storyTime = currentStoryTime(gameId);
+            if (!storyTime) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `timeline: game '${gameId}' has no timeline clock yet -- nothing has been declared or written for it`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(storyTime, null, 2) }] };
+        }
+        catch (error) {
+            log.error("get_story_time failed", { gameId, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("declare_time_axis", {
+        description: "Declare the axis a game's t is measured on -- fixed for the life of that game's timeline once set for real. Call this before creating anything else so the game's world starts at its own origin, not partway up the engine's default append ordinal. A game that already has a recorded t (e.g. from its own creation) has a floor there: startAt below it is refused with the floor named, never silently shifted down to fit.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            axis: timeAxisSchema.describe("The time axis. There is no variant for an index into units you might later re-cut -- only sequence, elapsed, or counter."),
+            startAt: z
+                .number()
+                .finite()
+                .optional()
+                .describe("Where this axis's t should start (or continue); defaults to 0 for a brand-new game, or to the current t otherwise. Must never be behind the current t."),
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ gameId, axis, startAt }) => {
+        try {
+            const storyTime = declareTimeAxis({ gameId, axis, startAt });
+            return { content: [{ type: "text", text: JSON.stringify(storyTime, null, 2) }] };
+        }
+        catch (error) {
+            log.error("declare_time_axis failed", {
+                gameId,
+                axis,
+                startAt,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("set_story_time", {
+        description: "Move a game's t forward on its declared axis. Only works once a non-sequence axis has been declared -- the engine's own append ordinal cannot be positioned by a caller. Never moves t backwards, including below whatever floor the axis inherited at declaration time.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: tSchema,
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ gameId, t }) => {
+        try {
+            const storyTime = setStoryTime({ gameId, t });
+            return { content: [{ type: "text", text: JSON.stringify(storyTime, null, 2) }] };
+        }
+        catch (error) {
+            log.error("set_story_time failed", { gameId, t, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("declare_fact_irreversible", {
+        description: "Mark the fact currently open for one entity and key as irreversible: from its valid_from_t onward, the engine refuses any later assertion of a different value under that key. The temporal member of the same constraint family as bounded, monotonic and conserved sets. Closing the fact, and deleting the entity, both remain legal -- ending a record is not asserting its opposite -- but reopening the key at a different value is still refused. Irreversibility cannot be withdrawn once declared. Because the flag is per-fact, a property you intend to declare irreversible must live under its own key: declaring it locks the whole value stored under that key.",
+        inputSchema: {
+            entityId: z
+                .string()
+                .max(100)
+                .describe("The entity ID -- the same id as the row it was projected from (e.g. a resource ID)"),
+            key: z
+                .string()
+                .max(200)
+                .describe("The fact key, i.e. the column name the fact was projected from (e.g. 'value')"),
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ entityId, key }) => {
+        try {
+            const fact = declareIrreversible({ entityId, key });
+            return { content: [{ type: "text", text: JSON.stringify(fact, null, 2) }] };
+        }
+        catch (error) {
+            log.error("declare_fact_irreversible failed", {
+                entityId,
+                key,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("list_irreversible_facts", {
+        description: "List every fact declared irreversible in a game, optionally narrowed to one entity. Each row carries the fact, its valid_from_t, and the event that opened it -- one hop of provenance, so a reviewer meeting a refusal can tell whether the fact is wrong or the claim is. Returns rows, never a verdict.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            entityId: z.string().max(100).optional().describe("Narrow the listing to one entity"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, entityId }) => {
+        try {
+            const facts = listIrreversibleFacts({ gameId, entityId });
+            return { content: [{ type: "text", text: JSON.stringify(facts, null, 2) }] };
+        }
+        catch (error) {
+            log.error("list_irreversible_facts failed", {
+                gameId,
+                entityId,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * Both export tools deal in a PATH and return only counts, never the
+     * artifact itself. That is design §6's point -- the deliverable is a file
+     * the client owns, not a payload passed back through a conversation -- and
+     * it is also what keeps a whole world's timeline from being pasted into
+     * the caller's context window, which is how a tool result kills the
+     * conversation that asked for it.
+     */
+    server.registerTool("export_timeline", {
+        description: "Freeze a game's entire timeline -- every entity, every fact interval, every event, and the declared time axis -- into a JSON file the caller owns. Deterministic: the same world exports byte-identically every time. Carries no media references and no live table rows by design, so the file can be re-imported anywhere and answer replay(t) identically. Returns the path and row counts, never the artifact itself.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            filePath: z.string().min(1).max(4096).describe("Absolute path to write the export file to"),
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ gameId, filePath }) => {
+        try {
+            const artifact = exportTimelineToFile({ gameId, filePath });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            filePath,
+                            gameId: artifact.gameId,
+                            formatVersion: artifact.formatVersion,
+                            entities: artifact.entities.length,
+                            facts: artifact.facts.length,
+                            events: artifact.events.length,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            log.error("export_timeline failed", { gameId, filePath, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("import_timeline", {
+        description: "Restore a frozen timeline export into this database, verbatim -- ids and every t are carried through unchanged. Refuses rather than merges if the game already has any recorded history, and refuses an artifact whose rows do not all belong to the game it names. Imports the timeline only; the live tables are not repopulated.",
+        inputSchema: {
+            filePath: z.string().min(1).max(4096).describe("Absolute path of the export file to read"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async ({ filePath }) => {
+        try {
+            const result = importTimelineFromFile(filePath);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            log.error("import_timeline failed", { filePath, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("narration_constraint_at", {
+        description: "Return what IS true for a game at t, and nothing else: every fact valid then on an entity alive then, plus every irreversible fact from valid_from_t onward even if it has since closed or its entity has been destroyed. Each fact carries one hop of causality -- the event that opened it, if any is recorded -- so a reviewer can tell whether a disputed fact or a disputed claim is the one that's wrong. This tool does not check anything and returns no verdict: it hands back the serialized constraint so a caller can run its own check (a live one now, or an offline lint over the saved JSON hours later) -- see the library-exported `contradictions` function for that half, which takes no database and is not exposed as a tool because wrapping a pure function in a tool call would defeat the point of it being callable offline.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: tSchema,
+            entityIds: z
+                .array(z.string().max(100))
+                .optional()
+                .describe("Narrow the constraint to only these entities. Omit for the whole game; an empty array narrows to nothing."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t, entityIds }) => {
+        try {
+            const constraint = narrationConstraintAt({ gameId, t, entityIds });
+            return { content: [{ type: "text", text: JSON.stringify(constraint, null, 2) }] };
+        }
+        catch (error) {
+            log.error("narration_constraint_at failed", {
+                gameId,
+                t,
+                entityIds,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+}