run-dmcp 0.4.0 → 0.6.0

package/dist/timeline/provenance.js

@@ -1,45 +1,41 @@
 import { getDatabase } from "../db/connection.js";
 /**
- * The one hop of causality (design §5.2c): the event of `gameId` whose
- * `at_t` equals the fact's `valid_from_t` and whose `causes` JSON names this
- * entity as the row it was written for. `causes` is produced entirely by
- * this codebase's own projection triggers (`json_object('table', ...,
- * 'row_id', NEW.id)` in projection.ts) -- matching `$.row_id` here is a
- * literal comparison against a token we defined in output we generated, not
- * an attempt to understand what any event "means" (hard rule 4). Ordered
- * deterministically (`at_t`, then `id`) and only the first row is taken --
- * one hop, never a chain, never a trace of how the engine got here.
+ * The one hop of causality (design §5.2c), READ rather than derived (issue
+ * #30). `facts.opened_by_event_id` is stamped by the projection triggers'
+ * `_ai`/`_au` bodies (projection.ts) at the moment a fact opens, in the same
+ * firing, via `last_insert_rowid()` against the event they just inserted --
+ * so this is a direct column lookup now, not a search over `events` keyed by
+ * `(at_t, causes.row_id)` with a random-hex tiebreak among rows sharing a
+ * `t`. That derivation is gone, along with the failure modes it carried: it
+ * could return null for an event whose `causes` was not valid JSON, and it
+ * broke ties among same-`t` events arbitrarily.
  *
- * The `CASE WHEN json_valid(causes)` wrapper is load-bearing, not defensive
- * decoration. `events.causes` has no CHECK constraint, and SQLite's
- * `json_extract` RAISES "malformed JSON" rather than returning NULL when it
- * meets a value that is not JSON -- and that error belongs to the whole
- * query, not to the offending row, so a single bad row anywhere in this
- * game's events would make every function that calls this throw, including
- * ones that have nothing to do with that event. That is reachable in
- * practice: timeline import (export.ts) carries `causes` through verbatim
- * by design, because an importer that rewrote a recorded cause would be
- * inventing history. A hop of provenance must never be able to fail the
- * write it annotates, so a row we cannot read simply does not match.
- * Written as CASE rather than `json_valid(causes) AND json_extract(...)`
- * because SQLite does not guarantee the evaluation order of AND operands --
- * the planner may reorder them, and then the guard is decoration that
- * happens to work today.
+ * Both internal callers of this shape (`irreversible.ts`, `narration.ts`)
+ * no longer call this function at all -- each already queries its own fact
+ * row and now selects `opened_by_event_id` directly as part of that same
+ * query, which is strictly cheaper than a second round trip through here.
  *
- * Moved here verbatim (SQL, doc comment and all) from `irreversible.ts`'s
- * former module-private `findOpenedByEventId` -- this is the ONE owner of
- * §5.2c's hop now; `irreversible.ts` and `narration.ts` both call this
- * rather than each keeping a copy of the query.
+ * This function is kept, and re-pointed at the stored column rather than
+ * removed, because it is part of this package's published library surface
+ * (`src/index.ts` re-exports it) -- issue #30 did not ask for a public API
+ * removal, and removing an exported function silently would be exactly the
+ * kind of undocumented break root CLAUDE.md's "what we declare is what we
+ * mean" section warns against. A caller that already holds
+ * `(gameId, entityId, validFromT)` rather than a fact id can still use it;
+ * it now does less work to answer the same question.
  */
 export function openingEventId(gameId, entityId, validFromT) {
     const db = getDatabase();
     const row = db
-        .prepare(`SELECT id FROM events
-        WHERE game_id = ?
-          AND at_t = ?
-          AND json_extract(CASE WHEN json_valid(causes) THEN causes END, '$.row_id') = ?
-        ORDER BY at_t, id
+        .prepare(`SELECT f.opened_by_event_id AS id
+         FROM facts f
+         JOIN entities e ON e.id = f.entity_id
+        WHERE e.game_id = ?
+          AND f.entity_id = ?
+          AND f.valid_from_t = ?
+          AND f.opened_by_event_id IS NOT NULL
+        ORDER BY f.id
         LIMIT 1`)
-        .get(gameId, validFromT, entityId);
+        .get(gameId, entityId, validFromT);
     return row?.id ?? null;
 }

package/dist/timeline/schema.js

@@ -84,6 +84,23 @@ export function initializeTimelineSchema() {
       causes TEXT
     )
   `);
+    // facts.opened_by_event_id -- issue #30: the one hop of causality (design
+    // §5.2c) recorded at the moment it is true, instead of derived at read
+    // time by searching `events` for a row whose `at_t`/`causes.row_id` happen
+    // to match (the query this replaces lived in provenance.ts, and could
+    // return null for a bad `causes` JSON blob, or pick the wrong event of
+    // several sharing one `t` by an arbitrary hex-id tiebreak). Idempotent
+    // ALTER, ordered after `events` exists -- legal under SQLite's ADD COLUMN
+    // restrictions because the implicit default is NULL, and a database that
+    // already has this column (every run after the first) just throws here,
+    // caught and ignored, same idiom as every other migration in this
+    // codebase (root CLAUDE.md).
+    try {
+        db.exec("ALTER TABLE facts ADD COLUMN opened_by_event_id TEXT REFERENCES events(id)");
+    }
+    catch {
+        // Column already exists.
+    }
     // timeline_clock -- one row per game, tracking the declared axis and its
     // current position. A game that never declares an axis still needs one
     // of these once its first entity/fact/event is written, with axis_kind
@@ -152,6 +169,16 @@ export function initializeTimelineSchema() {
     // change. declareIrreversible() (irreversible.ts) relies on that last
     // case to make re-declaring idempotent with a single UPDATE and no
     // separate "already set" check.
+    // Third one-way latch (issue #30): NULL -> value, once, exactly like
+    // `valid_to_t` above -- once the projection trigger has stamped
+    // `opened_by_event_id`, nothing may rewrite it, but the stamp itself (the
+    // trigger's own UPDATE, immediately after the fact's INSERT -- see
+    // projection.ts) must be allowed through. This clause is load-bearing, not
+    // hygiene: probed against better-sqlite3 at this project's own pragma
+    // settings, the append-only guard fires on trigger-initiated UPDATEs too.
+    // Without it, the projection trigger's own stamp would abort the write it
+    // annotates; with it, a stamped edge can never be rewritten -- a re-stamp
+    // raises ABORT.
     db.exec(`
     DROP TRIGGER IF EXISTS timeline_facts_immutable;
     CREATE TRIGGER timeline_facts_immutable
@@ -164,8 +191,9 @@ export function initializeTimelineSchema() {
       OR (NEW.irreversible IS NOT OLD.irreversible
           AND (OLD.irreversible IS NOT 0 OR NEW.irreversible IS NOT 1))
       OR (OLD.valid_to_t IS NOT NULL AND NEW.valid_to_t IS NOT OLD.valid_to_t)
+      OR (OLD.opened_by_event_id IS NOT NULL AND NEW.opened_by_event_id IS NOT OLD.opened_by_event_id)
     BEGIN
-      SELECT RAISE(ABORT, 'timeline: facts are append-only; valid_from_t cannot be rewritten, valid_to_t may only be closed once, and irreversible may only move 0 -> 1');
+      SELECT RAISE(ABORT, 'timeline: facts are append-only; valid_from_t cannot be rewritten, valid_to_t may only be closed once, irreversible may only move 0 -> 1, and opened_by_event_id may only be stamped once');
     END;
   `);
     db.exec(`

package/dist/utils/validation.d.ts

@@ -1,24 +1,53 @@
 import { z } from "zod";
 /**
  * Common input length limits for security and performance.
- * These prevent DoS attacks via extremely large inputs.
+ *
+ * These prevent DoS attacks via extremely large inputs -- and they are also
+ * the engine's PUBLISHED CONTRACT. A `.max()` here lands in the tool's
+ * `input_schema` and `tools/list` hands it to every client before the first
+ * call, so a consumer can read what a field takes instead of hard-coding a
+ * copy of these numbers. One does. Leaving a string parameter unbounded is
+ * therefore not a missing safety net but an active statement that the field
+ * takes anything; `src/__tests__/schemaBounds.test.ts` fails on any that is
+ * (issue #29).
  */
 export declare const LIMITS: {
     readonly NAME_MAX: 200;
     readonly DESCRIPTION_MAX: 5000;
     readonly CONTENT_MAX: 50000;
     readonly NARRATIVE_MAX: 200000;
+    readonly EMBEDDED_DATA_MAX: 2000000;
     readonly ARRAY_MAX: 100;
     readonly MAX_DEPTH: 10;
 };
 /**
- * Pre-built Zod schemas with length limits
+ * Pre-built Zod schemas with length limits.
+ *
+ * EVERY PROPERTY HERE IS A GETTER, AND HANDS BACK A FRESH INSTANCE.
+ *
+ * That is not a style: `zod-to-json-schema` (which the MCP SDK runs over
+ * every `inputSchema` on its way to `tools/list`) de-duplicates by object
+ * IDENTITY. Reuse one instance twice inside a single tool and the second
+ * occurrence is published as
+ *
+ *     { "$ref": "#/properties/imageGen/properties/subject/properties/..." }
+ *
+ * -- a pointer into a sibling property, in place of the declaration a
+ * consumer came to read. Sharing these as plain constants put 648 of those
+ * into the contract, where there had been none; a fresh instance per access
+ * puts the declaration back at every site. `src/__tests__/schemaBounds.test.ts`
+ * fails on any `$ref` in a published schema, which is what caught it.
+ *
+ * The cost is a schema object built per access. They are read at server
+ * construction, not per call.
  */
 export declare const validatedSchemas: {
     readonly name: z.ZodString;
+    readonly token: z.ZodString;
     readonly description: z.ZodString;
     readonly content: z.ZodString;
     readonly narrative: z.ZodString;
+    readonly embeddedData: z.ZodString;
     readonly id: z.ZodString;
     readonly tag: z.ZodString;
     readonly stringArray: z.ZodArray<z.ZodString, "many">;

package/dist/utils/validation.js

@@ -1,7 +1,15 @@
 import { z } from "zod";
 /**
  * Common input length limits for security and performance.
- * These prevent DoS attacks via extremely large inputs.
+ *
+ * These prevent DoS attacks via extremely large inputs -- and they are also
+ * the engine's PUBLISHED CONTRACT. A `.max()` here lands in the tool's
+ * `input_schema` and `tools/list` hands it to every client before the first
+ * call, so a consumer can read what a field takes instead of hard-coding a
+ * copy of these numbers. One does. Leaving a string parameter unbounded is
+ * therefore not a missing safety net but an active statement that the field
+ * takes anything; `src/__tests__/schemaBounds.test.ts` fails on any that is
+ * (issue #29).
  */
 export const LIMITS = {
     // Short text fields (names, titles)
@@ -12,31 +20,80 @@ export const LIMITS = {
     CONTENT_MAX: 50000,
     // Very long text fields (story exports, narrative)
     NARRATIVE_MAX: 200000,
+    // Inline binary carried as a data URI or bare base64 -- an image, not prose.
+    // Deliberately generous rather than a prose tier: the fields that take one
+    // (`imageGen.generations[].base64`) accepted anything before they were
+    // bounded, and a real inline PNG is hundreds of kilobytes.
+    EMBEDDED_DATA_MAX: 2000000,
     // Array limits
     ARRAY_MAX: 100,
     // JSON object depth limit (for nested structures)
     MAX_DEPTH: 10,
 };
 /**
- * Pre-built Zod schemas with length limits
+ * Pre-built Zod schemas with length limits.
+ *
+ * EVERY PROPERTY HERE IS A GETTER, AND HANDS BACK A FRESH INSTANCE.
+ *
+ * That is not a style: `zod-to-json-schema` (which the MCP SDK runs over
+ * every `inputSchema` on its way to `tools/list`) de-duplicates by object
+ * IDENTITY. Reuse one instance twice inside a single tool and the second
+ * occurrence is published as
+ *
+ *     { "$ref": "#/properties/imageGen/properties/subject/properties/..." }
+ *
+ * -- a pointer into a sibling property, in place of the declaration a
+ * consumer came to read. Sharing these as plain constants put 648 of those
+ * into the contract, where there had been none; a fresh instance per access
+ * puts the declaration back at every site. `src/__tests__/schemaBounds.test.ts`
+ * fails on any `$ref` in a published schema, which is what caught it.
+ *
+ * The cost is a schema object built per access. They are read at server
+ * construction, not per call.
  */
 export const validatedSchemas = {
     // Name fields (character names, location names, etc.)
-    name: z.string().min(1).max(LIMITS.NAME_MAX),
+    get name() {
+        return z.string().min(1).max(LIMITS.NAME_MAX);
+    },
+    // Short free text with a ceiling and NO floor -- a colour, a direction, an
+    // aspect ratio, a sampler. Same length as `name`, without `.min(1)`: bounding
+    // a field that accepts "" today must not also start rejecting it.
+    get token() {
+        return z.string().max(LIMITS.NAME_MAX);
+    },
     // Description fields
-    description: z.string().max(LIMITS.DESCRIPTION_MAX),
+    get description() {
+        return z.string().max(LIMITS.DESCRIPTION_MAX);
+    },
     // Content fields (notes, large text)
-    content: z.string().max(LIMITS.CONTENT_MAX),
+    get content() {
+        return z.string().max(LIMITS.CONTENT_MAX);
+    },
     // Narrative content (very large text allowed)
-    narrative: z.string().max(LIMITS.NARRATIVE_MAX),
+    get narrative() {
+        return z.string().max(LIMITS.NARRATIVE_MAX);
+    },
+    // Inline binary carried as base64 or a data URI -- an image, not prose.
+    get embeddedData() {
+        return z.string().max(LIMITS.EMBEDDED_DATA_MAX);
+    },
     // ID fields (UUIDs are 36 characters)
-    id: z.string().max(100),
+    get id() {
+        return z.string().max(100);
+    },
     // Tag/category strings
-    tag: z.string().min(1).max(100),
+    get tag() {
+        return z.string().min(1).max(100);
+    },
     // Array of strings with limits
-    stringArray: z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX),
+    get stringArray() {
+        return z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX);
+    },
     // Array of tags
-    tagArray: z.array(z.string().min(1).max(100)).max(LIMITS.ARRAY_MAX),
+    get tagArray() {
+        return z.array(z.string().min(1).max(100)).max(LIMITS.ARRAY_MAX);
+    },
 };
 /**
  * Helper to create a bounded string schema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-dmcp",
-  "version": "0.4.0",
+  "version": "0.6.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",