run-dmcp 0.4.0 → 0.6.0

package/dist/register/world.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import * as worldTools from "../tools/world.js";
 import { imageGenSchema } from "../schemas/index.js";
-import { LIMITS } from "../utils/validation.js";
+import { LIMITS, validatedSchemas } from "../utils/validation.js";
 import { ANNOTATIONS } from "../utils/tool-annotations.js";
 export function registerWorldTools(server) {
     server.registerTool("create_location", {
@@ -26,7 +26,7 @@ export function registerWorldTools(server) {
     server.registerTool("get_location", {
         description: "Get location details",
         inputSchema: {
-            locationId: z.string().describe("The location ID"),
+            locationId: validatedSchemas.id.describe("The location ID"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ locationId }) => {
@@ -44,9 +44,9 @@ export function registerWorldTools(server) {
     server.registerTool("update_location", {
         description: "Update a location",
         inputSchema: {
-            locationId: z.string().describe("The location ID"),
-            name: z.string().optional().describe("New name"),
-            description: z.string().optional().describe("New description"),
+            locationId: validatedSchemas.id.describe("The location ID"),
+            name: validatedSchemas.token.optional().describe("New name"),
+            description: validatedSchemas.description.optional().describe("New description"),
             properties: z.record(z.string(), z.unknown()).optional().describe("Property updates"),
             imageGen: imageGenSchema.nullable().optional().describe("Image generation metadata (null to remove)"),
         },
@@ -66,7 +66,7 @@ export function registerWorldTools(server) {
     server.registerTool("list_locations", {
         description: "List all locations in a game",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
+            gameId: validatedSchemas.id.describe("The game ID"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ gameId }) => {
@@ -78,11 +78,11 @@ export function registerWorldTools(server) {
     server.registerTool("connect_locations", {
         description: "Create exits/paths between two locations. Call this whenever you describe how locations connect to each other - the player should be able to navigate based on database connections.",
         inputSchema: {
-            fromLocationId: z.string().describe("First location ID"),
-            toLocationId: z.string().describe("Second location ID"),
-            fromDirection: z.string().describe("Direction from first location (e.g., 'north', 'up', 'through the door')"),
-            toDirection: z.string().describe("Direction from second location back (e.g., 'south', 'down')"),
-            description: z.string().optional().describe("Description of the path"),
+            fromLocationId: validatedSchemas.id.describe("First location ID"),
+            toLocationId: validatedSchemas.id.describe("Second location ID"),
+            fromDirection: validatedSchemas.token.describe("Direction from first location (e.g., 'north', 'up', 'through the door')"),
+            toDirection: validatedSchemas.token.describe("Direction from second location back (e.g., 'south', 'down')"),
+            description: validatedSchemas.description.optional().describe("Description of the path"),
             bidirectional: z.boolean().optional().describe("Create exit in both directions (default: true)"),
         },
         annotations: ANNOTATIONS.CREATE,
@@ -108,8 +108,8 @@ export function registerWorldTools(server) {
     server.registerTool("get_location_by_name", {
         description: "Look up a location by name within a game. Supports exact, partial, and fuzzy matching. Returns the best match or an error if no reasonable match found.",
         inputSchema: {
-            gameId: z.string().describe("The game ID to search within"),
-            name: z.string().describe("Location name to search for (case-insensitive)"),
+            gameId: validatedSchemas.id.describe("The game ID to search within"),
+            name: validatedSchemas.token.describe("Location name to search for (case-insensitive)"),
         },
         annotations: ANNOTATIONS.READ_ONLY,
     }, async ({ gameId, name }) => {

package/dist/rpg/register/batch.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import * as characterTools from "../../tools/character.js";
 import * as narrativeTools from "../../tools/narrative.js";
 import * as combatTools from "../tools/combat.js";
-import { LIMITS } from "../../utils/validation.js";
+import { LIMITS, validatedSchemas } from "../../utils/validation.js";
 import { ANNOTATIONS } from "../../utils/tool-annotations.js";
 // The one multi-entity workflow tool that reaches into combat, split out of
 // src/register/batch.ts (design §8, issue #17): everything else there --
@@ -17,8 +17,8 @@ export function registerRpgBatchTools(server) {
     server.registerTool("setup_combat_encounter", {
         description: "Complete combat setup in one call: creates enemy NPCs and starts combat with all participants (enemies + players at location). Returns the ready-to-play combat state.",
         inputSchema: {
-            gameId: z.string().describe("The game ID"),
-            locationId: z.string().describe("Location where combat takes place"),
+            gameId: validatedSchemas.id.describe("The game ID"),
+            locationId: validatedSchemas.id.describe("Location where combat takes place"),
             enemies: z
                 .array(z.object({
                 name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Enemy name"),

package/dist/schemas/index.js

@@ -1,121 +1,140 @@
+// Reusable Zod schemas, shared by the register modules.
+//
+// EVERY string here is bounded, and this file is where most of the engine's
+// bounds actually live: `imageGenSchema` alone is accepted by seven tools, so
+// one unbounded leaf in it was seven unbounded declarations in the published
+// contract (issue #29 -- 698 of them, against 348 hand-written `.max()` calls
+// spread across the register modules). Bounds belong in the shared schema, not
+// at each call site, for the same reason the schema itself is shared.
+//
+// The tiers come from `validatedSchemas` (../utils/validation.ts) and nowhere
+// else: `.token` for a short descriptor, `.description` for free text a model
+// writes prose into, `.embeddedData` for inline base64. Reach for one of those
+// rather than hand-rolling `z.string().max(...)` -- inlining the bound at each
+// site is exactly how 698 of them came to be forgotten. Each access hands back
+// a FRESH schema instance, deliberately; that file's comment says why, and it
+// is the difference between publishing a declaration and publishing a `$ref`.
 import { z } from "zod";
+import { LIMITS, validatedSchemas } from "../utils/validation.js";
 // Reusable Zod schemas for image generation
 export const subjectDescriptionSchema = z.object({
     type: z.enum(["character", "location", "item", "scene"]),
-    primaryDescription: z.string(),
+    primaryDescription: validatedSchemas.description,
     physicalTraits: z.object({
-        age: z.string().optional(),
-        gender: z.string().optional(),
-        bodyType: z.string().optional(),
-        height: z.string().optional(),
-        skinTone: z.string().optional(),
-        hairColor: z.string().optional(),
-        hairStyle: z.string().optional(),
-        eyeColor: z.string().optional(),
-        facialFeatures: z.string().optional(),
-        distinguishingMarks: z.array(z.string()).optional(),
+        age: validatedSchemas.token.optional(),
+        gender: validatedSchemas.token.optional(),
+        bodyType: validatedSchemas.token.optional(),
+        height: validatedSchemas.token.optional(),
+        skinTone: validatedSchemas.token.optional(),
+        hairColor: validatedSchemas.token.optional(),
+        hairStyle: validatedSchemas.token.optional(),
+        eyeColor: validatedSchemas.token.optional(),
+        facialFeatures: validatedSchemas.description.optional(),
+        distinguishingMarks: validatedSchemas.stringArray.optional(),
     }).optional(),
     attire: z.object({
-        description: z.string(),
-        colors: z.array(z.string()).optional(),
-        materials: z.array(z.string()).optional(),
-        accessories: z.array(z.string()).optional(),
+        description: validatedSchemas.description,
+        colors: validatedSchemas.stringArray.optional(),
+        materials: validatedSchemas.stringArray.optional(),
+        accessories: validatedSchemas.stringArray.optional(),
     }).optional(),
     environment: z.object({
-        setting: z.string(),
-        timeOfDay: z.string().optional(),
-        weather: z.string().optional(),
-        lighting: z.string().optional(),
-        architecture: z.string().optional(),
-        vegetation: z.string().optional(),
-        notableFeatures: z.array(z.string()).optional(),
+        setting: validatedSchemas.description,
+        timeOfDay: validatedSchemas.token.optional(),
+        weather: validatedSchemas.token.optional(),
+        lighting: validatedSchemas.token.optional(),
+        architecture: validatedSchemas.token.optional(),
+        vegetation: validatedSchemas.token.optional(),
+        notableFeatures: validatedSchemas.stringArray.optional(),
     }).optional(),
     objectDetails: z.object({
-        material: z.string().optional(),
-        size: z.string().optional(),
-        condition: z.string().optional(),
-        glowOrEffects: z.string().optional(),
+        material: validatedSchemas.token.optional(),
+        size: validatedSchemas.token.optional(),
+        condition: validatedSchemas.token.optional(),
+        glowOrEffects: validatedSchemas.description.optional(),
     }).optional(),
-    pose: z.string().optional(),
-    expression: z.string().optional(),
-    action: z.string().optional(),
+    pose: validatedSchemas.description.optional(),
+    expression: validatedSchemas.description.optional(),
+    action: validatedSchemas.description.optional(),
 });
 export const styleDescriptionSchema = z.object({
-    artisticStyle: z.string(),
-    genre: z.string(),
-    mood: z.string(),
-    colorScheme: z.string().optional(),
-    influences: z.array(z.string()).optional(),
-    qualityTags: z.array(z.string()).optional(),
-    negativeElements: z.array(z.string()).optional(),
+    artisticStyle: validatedSchemas.description,
+    genre: validatedSchemas.token,
+    mood: validatedSchemas.token,
+    colorScheme: validatedSchemas.token.optional(),
+    influences: validatedSchemas.stringArray.optional(),
+    qualityTags: validatedSchemas.stringArray.optional(),
+    negativeElements: validatedSchemas.stringArray.optional(),
 });
 export const compositionDescriptionSchema = z.object({
-    framing: z.string(),
-    cameraAngle: z.string().optional(),
-    aspectRatio: z.string().optional(),
-    focusPoint: z.string().optional(),
-    background: z.string().optional(),
-    depth: z.string().optional(),
+    framing: validatedSchemas.description,
+    cameraAngle: validatedSchemas.token.optional(),
+    aspectRatio: validatedSchemas.token.optional(),
+    focusPoint: validatedSchemas.description.optional(),
+    background: validatedSchemas.description.optional(),
+    depth: validatedSchemas.token.optional(),
 });
 export const comfyUIPromptSchema = z.object({
-    positive: z.string(),
-    negative: z.string(),
-    checkpoint: z.string().optional(),
+    positive: validatedSchemas.description,
+    negative: validatedSchemas.description,
+    checkpoint: validatedSchemas.token.optional(),
     loras: z.array(z.object({
-        name: z.string(),
+        name: validatedSchemas.name,
         weight: z.number(),
-    })).optional(),
+    })).max(LIMITS.ARRAY_MAX).optional(),
     samplerSettings: z.object({
-        sampler: z.string().optional(),
-        scheduler: z.string().optional(),
+        sampler: validatedSchemas.token.optional(),
+        scheduler: validatedSchemas.token.optional(),
         steps: z.number().optional(),
         cfg: z.number().optional(),
     }).optional(),
 });
 export const generatedImageSchema = z.object({
-    id: z.string(),
-    tool: z.string(),
-    prompt: z.string(),
-    url: z.string().optional(),
-    base64: z.string().optional(),
+    id: validatedSchemas.id,
+    tool: validatedSchemas.token,
+    prompt: validatedSchemas.description,
+    // A URL, including a `data:` one. Over DESCRIPTION_MAX it is not an address,
+    // it is a payload, and `base64` below is the field for those.
+    url: validatedSchemas.description.optional(),
+    base64: validatedSchemas.embeddedData.optional(),
     seed: z.number().optional(),
-    timestamp: z.string(),
-    metadata: z.record(z.string(), z.unknown()).optional(),
+    timestamp: validatedSchemas.token,
+    metadata: z.record(validatedSchemas.token, z.unknown()).optional(),
 });
 export const imageGenSchema = z.object({
     subject: subjectDescriptionSchema,
     style: styleDescriptionSchema,
     composition: compositionDescriptionSchema,
     prompts: z.object({
-        generic: z.string().optional(),
-        sdxl: z.string().optional(),
-        dalle: z.string().optional(),
-        midjourney: z.string().optional(),
-        flux: z.string().optional(),
+        generic: validatedSchemas.description.optional(),
+        sdxl: validatedSchemas.description.optional(),
+        dalle: validatedSchemas.description.optional(),
+        midjourney: validatedSchemas.description.optional(),
+        flux: validatedSchemas.description.optional(),
         comfyui: comfyUIPromptSchema.optional(),
     }).optional(),
-    generations: z.array(generatedImageSchema).optional(),
+    generations: z.array(generatedImageSchema).max(LIMITS.ARRAY_MAX).optional(),
     consistency: z.object({
-        characterRef: z.string().optional(),
-        seedImage: z.string().optional(),
-        colorPalette: z.array(z.string()).optional(),
-        styleRef: z.string().optional(),
+        characterRef: validatedSchemas.description.optional(),
+        seedImage: validatedSchemas.description.optional(),
+        colorPalette: validatedSchemas.stringArray.optional(),
+        styleRef: validatedSchemas.description.optional(),
     }).optional(),
 }).describe("Image generation metadata for visual representation");
 // Voice schema for characters
 export const voiceSchema = z.object({
     pitch: z.enum(["very_low", "low", "medium", "high", "very_high"]).describe("Voice pitch"),
     speed: z.enum(["very_slow", "slow", "medium", "fast", "very_fast"]).describe("Speaking speed"),
-    tone: z.string().describe("Voice tone (e.g., 'gravelly', 'melodic', 'nasal', 'breathy')"),
-    accent: z.string().optional().describe("Accent (e.g., 'Scottish', 'French', 'Brooklyn')"),
-    quirks: z.array(z.string()).optional().describe("Speech quirks (e.g., 'stutters when nervous')"),
-    description: z.string().optional().describe("Free-form voice description for more nuance"),
+    tone: validatedSchemas.token.describe("Voice tone (e.g., 'gravelly', 'melodic', 'nasal', 'breathy')"),
+    accent: validatedSchemas.token.optional().describe("Accent (e.g., 'Scottish', 'French', 'Brooklyn')"),
+    quirks: validatedSchemas.stringArray.optional().describe("Speech quirks (e.g., 'stutters when nervous')"),
+    description: validatedSchemas.description.optional().describe("Free-form voice description for more nuance"),
 });
 // Random table entry schema
 export const tableEntrySchema = z.object({
     minRoll: z.number().optional().describe("Minimum roll to get this result (for ranged tables)"),
     maxRoll: z.number().optional().describe("Maximum roll for this result"),
     weight: z.number().optional().describe("Weight for weighted random selection"),
-    result: z.string().describe("The result text"),
-    effects: z.record(z.unknown()).optional().describe("Optional structured effects"),
+    result: validatedSchemas.description.describe("The result text"),
+    effects: z.record(validatedSchemas.token, z.unknown()).optional().describe("Optional structured effects"),
 });

package/dist/timeline/export.d.ts

@@ -80,6 +80,13 @@ export interface TimelineExportFact {
     validFromT: T;
     validToT: T | null;
     irreversible: boolean;
+    /** The one hop of causality (design §5.2c, issue #30) -- the event that
+     *  opened this fact, or null when none is recorded. Optional, not just
+     *  nullable: a v1 artifact written before issue #30 landed carries no such
+     *  field at all, and `importTimeline` treats an absent field and an
+     *  explicit `null` identically -- there was never a recorded hop for
+     *  either, so there is nothing to guess and no reason to refuse. */
+    openedByEventId?: string | null;
 }
 export interface TimelineExportEvent {
     id: string;
@@ -158,10 +165,12 @@ export declare function exportTimeline(gameId: string): TimelineExport;
  * artifact shape above) is stamped fresh at import time; it was never
  * exported and never round-trips.
  *
- * `entities` are inserted before `facts` because `facts.entity_id` is a
- * real foreign key and this database runs with `PRAGMA foreign_keys = ON`
- * (`../db/connection.ts`) -- inserting out of order would fail loudly
- * rather than silently, but there is no reason to invite the failure.
+ * `entities` are inserted before `events` and `facts` because `facts.entity_id`
+ * is a real foreign key; `events` are inserted before `facts` (issue #30) for
+ * the identical reason now that `facts.opened_by_event_id` is one too --
+ * this database runs with `PRAGMA foreign_keys = ON` (`../db/connection.ts`),
+ * so inserting out of order would fail loudly rather than silently, but
+ * there is no reason to invite the failure.
  */
 export declare function importTimeline(artifact: TimelineExport): TimelineImportResult;
 /**

package/dist/timeline/export.js

@@ -103,7 +103,7 @@ function readTimeline(gameId) {
     // scoped by joining back to entities, exactly the way replay.ts scopes
     // "what was true of them" to "who was alive."
     const factRows = db
-        .prepare(`SELECT f.id, f.entity_id, f.key, f.value, f.valid_from_t, f.valid_to_t, f.irreversible
+        .prepare(`SELECT f.id, f.entity_id, f.key, f.value, f.valid_from_t, f.valid_to_t, f.irreversible, f.opened_by_event_id
        FROM facts f
        JOIN entities e ON e.id = f.entity_id
        WHERE e.game_id = ?
@@ -137,6 +137,7 @@ function readTimeline(gameId) {
             validFromT: row.valid_from_t,
             validToT: row.valid_to_t,
             irreversible: Boolean(row.irreversible),
+            openedByEventId: row.opened_by_event_id,
         })),
         events: eventRows.map((row) => ({
             id: row.id,
@@ -266,10 +267,12 @@ function assertTargetIsEmpty(gameId) {
  * artifact shape above) is stamped fresh at import time; it was never
  * exported and never round-trips.
  *
- * `entities` are inserted before `facts` because `facts.entity_id` is a
- * real foreign key and this database runs with `PRAGMA foreign_keys = ON`
- * (`../db/connection.ts`) -- inserting out of order would fail loudly
- * rather than silently, but there is no reason to invite the failure.
+ * `entities` are inserted before `events` and `facts` because `facts.entity_id`
+ * is a real foreign key; `events` are inserted before `facts` (issue #30) for
+ * the identical reason now that `facts.opened_by_event_id` is one too --
+ * this database runs with `PRAGMA foreign_keys = ON` (`../db/connection.ts`),
+ * so inserting out of order would fail loudly rather than silently, but
+ * there is no reason to invite the failure.
  */
 export function importTimeline(artifact) {
     assertValidArtifactShape(artifact);
@@ -289,14 +292,17 @@ export function importTimeline(artifact) {
         for (const entity of artifact.entities) {
             insertEntity.run(entity.id, entity.gameId, entity.kind, entity.name, entity.createdAtT, entity.destroyedAtT);
         }
-        const insertFact = db.prepare(`INSERT INTO facts (id, entity_id, key, value, valid_from_t, valid_to_t, irreversible) VALUES (?, ?, ?, ?, ?, ?, ?)`);
-        for (const fact of artifact.facts) {
-            insertFact.run(fact.id, fact.entityId, fact.key, fact.value, fact.validFromT, fact.validToT, fact.irreversible ? 1 : 0);
-        }
+        // Events before facts (issue #30): `facts.opened_by_event_id` is a real
+        // foreign key into `events` now, on top of `facts.entity_id`'s existing
+        // one into `entities` -- see this function's doc comment.
         const insertEvent = db.prepare(`INSERT INTO events (id, game_id, at_t, kind, description, causes) VALUES (?, ?, ?, ?, ?, ?)`);
         for (const event of artifact.events) {
             insertEvent.run(event.id, event.gameId, event.atT, event.kind, event.description, event.causes);
         }
+        const insertFact = db.prepare(`INSERT INTO facts (id, entity_id, key, value, valid_from_t, valid_to_t, irreversible, opened_by_event_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const fact of artifact.facts) {
+            insertFact.run(fact.id, fact.entityId, fact.key, fact.value, fact.validFromT, fact.validToT, fact.irreversible ? 1 : 0, fact.openedByEventId ?? null);
+        }
         return {
             gameId: artifact.gameId,
             entities: artifact.entities.length,

package/dist/timeline/irreversible.js

@@ -1,7 +1,11 @@
 import { getDatabase } from "../db/connection.js";
 import { assertT } from "./t.js";
-import { openingEventId } from "./provenance.js";
-function toIrreversibleFact(row, gameId) {
+/** `gameId` is no longer used to look up the hop (issue #30: it is a stored
+ *  column on the fact row itself, never derived), but stays a parameter so
+ *  every call site here keeps naming the game it is working in -- and so a
+ *  future caller that genuinely needs to re-scope by game has somewhere to
+ *  put it without changing every signature in this file again. */
+function toIrreversibleFact(row, _gameId) {
     assertT(row.valid_from_t);
     return {
         factId: row.id,
@@ -9,7 +13,7 @@ function toIrreversibleFact(row, gameId) {
         key: row.key,
         value: row.value,
         validFromT: row.valid_from_t,
-        openedByEventId: openingEventId(gameId, row.entity_id, row.valid_from_t),
+        openedByEventId: row.opened_by_event_id,
     };
 }
 /**
@@ -44,7 +48,7 @@ export function declareIrreversible(params) {
     // order. Same tiebreak as irreversibleFactFor below, so the two functions
     // can never disagree about which row they mean.
     const open = db
-        .prepare(`SELECT id, entity_id, key, value, valid_from_t FROM facts
+        .prepare(`SELECT id, entity_id, key, value, valid_from_t, opened_by_event_id FROM facts
         WHERE entity_id = ? AND key = ? AND valid_to_t IS NULL
         ORDER BY valid_from_t DESC, id DESC
         LIMIT 1`)
@@ -73,7 +77,7 @@ export function irreversibleFactFor(entityId, key) {
     if (!entity)
         return null;
     const row = db
-        .prepare(`SELECT id, entity_id, key, value, valid_from_t FROM facts
+        .prepare(`SELECT id, entity_id, key, value, valid_from_t, opened_by_event_id FROM facts
         WHERE entity_id = ? AND key = ? AND irreversible = 1
         ORDER BY valid_from_t DESC, id DESC
         LIMIT 1`)
@@ -92,7 +96,8 @@ export function irreversibleFactFor(entityId, key) {
 export function listIrreversibleFacts(params) {
     const db = getDatabase();
     let query = `
-    SELECT f.id AS id, f.entity_id AS entity_id, f.key AS key, f.value AS value, f.valid_from_t AS valid_from_t
+    SELECT f.id AS id, f.entity_id AS entity_id, f.key AS key, f.value AS value, f.valid_from_t AS valid_from_t,
+           f.opened_by_event_id AS opened_by_event_id
     FROM facts f
     JOIN entities e ON e.id = f.entity_id
     WHERE e.game_id = ? AND f.irreversible = 1

package/dist/timeline/narration.js

@@ -1,6 +1,5 @@
 import { getDatabase } from "../db/connection.js";
 import { assertT, compareT } from "./t.js";
-import { openingEventId } from "./provenance.js";
 /**
  * The outbound half of authority (design §5.2b/§5.2c, GitHub issues #11 and
  * #12): "Here is what is true; depict it, do not argue with it." One
@@ -47,7 +46,10 @@ import { openingEventId } from "./provenance.js";
  * opened it" in this codebase, not a second copy grown for this module.
  */
 export const NARRATION_CONSTRAINT_FORMAT_VERSION = 1;
-function toConstraintFact(row, gameId) {
+/** `gameId` is unused now that the hop is a stored column (issue #30) rather
+ *  than derived per-row, but the parameter stays -- see irreversible.ts's
+ *  identical note on `toIrreversibleFact`. */
+function toConstraintFact(row, _gameId) {
     assertT(row.valid_from_t);
     if (row.valid_to_t !== null)
         assertT(row.valid_to_t);
@@ -61,7 +63,7 @@ function toConstraintFact(row, gameId) {
         irreversible: Boolean(row.irreversible),
         entityKind: row.entity_kind,
         entityName: row.entity_name,
-        openedByEventId: openingEventId(gameId, row.entity_id, row.valid_from_t),
+        openedByEventId: row.opened_by_event_id,
     };
 }
 /**
@@ -125,7 +127,7 @@ export function narrationConstraintAt(params) {
     const rows = db
         .prepare(`SELECT f.id AS id, f.entity_id AS entity_id, f.key AS key, f.value AS value,
               f.valid_from_t AS valid_from_t, f.valid_to_t AS valid_to_t, f.irreversible AS irreversible,
-              e.kind AS entity_kind, e.name AS entity_name
+              e.kind AS entity_kind, e.name AS entity_name, f.opened_by_event_id AS opened_by_event_id
          FROM facts f
          JOIN entities e ON e.id = f.entity_id
         WHERE e.game_id = ?

package/dist/timeline/projection.js

@@ -41,10 +41,16 @@ function tExpr(gidExpr) {
 /**
  * `AFTER INSERT`: ensure the game's clock row exists, advance it, insert the
  * entity, insert one fact per non-NULL column, insert a `<kind>.created`
- * event. Column names are interpolated directly (never bound as parameters)
- * because they come from this codebase's own `pragma_table_info`, never
- * from anything a caller supplied -- there is no user input anywhere in
- * this SQL (trigger-sql-skeleton trap #6).
+ * event, then (issue #30) stamp every fact this firing just opened with that
+ * event's id via `last_insert_rowid()` -- the one hop of causality (design
+ * §5.2c), recorded rather than derived later. The `opened_by_event_id IS
+ * NULL` guard is what keeps a repeated `t` on a non-`sequence` axis correct:
+ * it restricts the stamp to facts THIS firing opened, never one a previous
+ * firing at the same `t` already stamped. Column names are interpolated
+ * directly (never bound as parameters) because they come from this
+ * codebase's own `pragma_table_info`, never from anything a caller supplied
+ * -- there is no user input anywhere in this SQL (trigger-sql-skeleton
+ * trap #6).
  */
 function buildInsertTrigger(row, cols) {
     const gid = `NEW.${row.gameIdColumn}`;
@@ -72,6 +78,9 @@ ${factInserts}
       INSERT INTO events (id, game_id, at_t, kind, description, causes)
         VALUES (lower(hex(randomblob(16))), ${gid}, ${t}, '${row.kind}.created', '${row.kind} created',
                 json_object('table', '${row.table}', 'row_id', NEW.id));
+
+      UPDATE facts SET opened_by_event_id = (SELECT id FROM events WHERE rowid = last_insert_rowid())
+        WHERE entity_id = NEW.id AND valid_from_t = ${t} AND opened_by_event_id IS NULL;
     END;
   `;
 }
@@ -84,6 +93,11 @@ ${factInserts}
  * column: reversed, the open's subquery would still see the value the
  * close was about to retire and write nothing (trap #3). The five-case
  * table this produces is walked by the test suite, not re-derived here.
+ * After the `<kind>.updated` event lands, every fact this firing just opened
+ * (across every column touched) is stamped with that event's id -- see
+ * `buildInsertTrigger`'s doc comment for why the `opened_by_event_id IS
+ * NULL` guard is what keeps this correct when a non-`sequence` axis repeats
+ * a `t` across firings (issue #30).
  */
 function buildUpdateTrigger(row, cols) {
     const gid = `NEW.${row.gameIdColumn}`;
@@ -111,6 +125,9 @@ ${perColumn}
       INSERT INTO events (id, game_id, at_t, kind, description, causes)
         VALUES (lower(hex(randomblob(16))), ${gid}, ${t}, '${row.kind}.updated', '${row.kind} updated',
                 json_object('table', '${row.table}', 'row_id', NEW.id));
+
+      UPDATE facts SET opened_by_event_id = (SELECT id FROM events WHERE rowid = last_insert_rowid())
+        WHERE entity_id = NEW.id AND valid_from_t = ${t} AND opened_by_event_id IS NULL;
     END;
   `;
 }

package/dist/timeline/provenance.d.ts

@@ -32,35 +32,28 @@ export interface FactProvenance {
     openedByEventId: string | null;
 }
 /**
- * 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 declare function openingEventId(gameId: string, entityId: string, validFromT: number): string | null;