run-dmcp 0.8.0 → 0.9.0

package/dist/db/schema.js

@@ -1270,6 +1270,67 @@ export function initializeSchema(options) {
       SELECT RAISE(ABORT, 'timeline: ''' || NEW.key || ''' on this entity is resolve_only-constrained; direct writes are refused -- this value can only change through the adjudicating call that opens the resolution window');
     END;
   `);
+    // Issue #42: a `create` leg of a resolution may declare `bounded`/
+    // `resolve_only`/`monotonic` constraints on the entity it makes, applied
+    // by resolve() inside the SAME transaction as the create -- so a later
+    // leg of the same resolution is already held to them. Two additions to
+    // `resource_constraints`:
+    //
+    //   - min_value/max_value: 'bounded' only, carried on the constraint's own
+    //     row. declareBoundedConstraint() (src/tools/constraint.ts) has no
+    //     need for this -- it enforces whatever `bounds` a caller passes at
+    //     write time against an EXISTING resource's own min_value/max_value
+    //     columns -- but a constraint declared in the same breath as the
+    //     entity it governs is recorded here instead, opaquely: the engine
+    //     stores these bounds and does not interpret them (issue #42's own
+    //     scope note), the same "one column, several kinds, mostly null"
+    //     shape `direction` (monotonic) and `total` (conserved) already use.
+    //   - caused_by_event_id: which `resolution.recorded` event's resolve()
+    //     call declared this constraint -- design §5.2c's one hop of
+    //     causality, recorded rather than derived later. NULL for a
+    //     constraint declared the ordinary way, through
+    //     declareBoundedConstraint/declareMonotonicConstraint/
+    //     declareConservedConstraint/declareResolveOnlyConstraint, none of
+    //     which run inside a resolution and so have no event to point at.
+    //
+    // Idempotent ALTERs, the same idiom RESOURCE_CONSTRAINTS_ADD_FACT_KEY_DDL
+    // uses above -- no CHECK constraint changes here, so no table rebuild is
+    // needed. Placed here, after initializeTimelineSchema() (a few lines up)
+    // rather than beside RESOURCE_CONSTRAINTS_DDL earlier in this function,
+    // so a fresh database's `resource_constraints` picks these up right after
+    // the tables issue #42's writer touches (`events`) already exist.
+    //
+    // `caused_by_event_id` carries NO `REFERENCES events(id)` -- deliberately,
+    // unlike `facts.opened_by_event_id` a few lines up. That column is always
+    // written NULL-then-UPDATEd once its target event already exists (see
+    // this function's own comment on it and projection.ts's insert trigger);
+    // resolve()'s create-leg constraints (src/timeline/resolve.ts, issue #42)
+    // declare a constraint and stamp the resolution's event id in the SAME
+    // statement, before that event row exists (the event is written only
+    // after every change in the resolution has landed, so its own `t` can be
+    // read post-write -- see resolve.ts step 7). An immediate FK here would
+    // refuse every such INSERT. `events.causes` already carries this same
+    // "one hop of provenance, unenforced by a foreign key" shape for every
+    // other event-to-event reference in this codebase (resolution_id, row_id,
+    // fact_id) -- this column follows it rather than being the one exception.
+    try {
+        db.exec(`ALTER TABLE resource_constraints ADD COLUMN min_value REAL`);
+    }
+    catch {
+        // Column already exists.
+    }
+    try {
+        db.exec(`ALTER TABLE resource_constraints ADD COLUMN max_value REAL`);
+    }
+    catch {
+        // Column already exists.
+    }
+    try {
+        db.exec(`ALTER TABLE resource_constraints ADD COLUMN caused_by_event_id TEXT`);
+    }
+    catch {
+        // Column already exists.
+    }
 }
 function runConsumerMigrations(db, migrations) {
     if (!migrations || migrations.length === 0) {

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export { writeConstrainedValue, transferConstrainedValue, valueHistory, } from "
 export type { ValueTransition } from "./timeline/constrained.js";
 export { ConstraintViolationError, constraintsFor, conservedConstraintFor } from "./timeline/registry.js";
 export { createResolver, ResolveProtocolError } from "./timeline/resolve.js";
-export type { Mechanic, Resolver, Proposal, Expectation, AdjudicationInput, Adjudication, IntendedChange, IntendedWrite, IntendedTransfer, IntendedSet, IntendedCreate, IntendedDestroy, EntityRef, Outcome, ResolveRefusalReason, } from "./timeline/resolve.js";
+export type { Mechanic, Resolver, Proposal, Expectation, AdjudicationInput, Adjudication, IntendedChange, IntendedWrite, IntendedTransfer, IntendedSet, IntendedCreate, CreateConstraint, IntendedDestroy, EntityRef, Outcome, ResolveRefusalReason, } from "./timeline/resolve.js";
 export { createStateRenderer } from "./timeline/render.js";
 export type { RenderVocabulary, VocabularyEntry, StateRenderer, RenderedState, RenderedNoun, UnnamedFact, } from "./timeline/render.js";
 export { createTurnReader } from "./reader/turnReader.js";

package/dist/mcp-server.d.ts

@@ -6,7 +6,7 @@ export declare const SERVER_NAME = "dmcp";
  *  the published package version by src/__tests__/serverVersion.test.ts --
  *  this said "0.3.0" for the whole of 0.4.0, because a release bumps
  *  package.json and nothing was watching this. */
-export declare const SERVER_VERSION = "0.8.0";
+export declare const SERVER_VERSION = "0.9.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

@@ -45,7 +45,7 @@ export const SERVER_NAME = "dmcp";
  *  the published package version by src/__tests__/serverVersion.test.ts --
  *  this said "0.3.0" for the whole of 0.4.0, because a release bumps
  *  package.json and nothing was watching this. */
-export const SERVER_VERSION = "0.8.0";
+export const SERVER_VERSION = "0.9.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/timeline/registry.d.ts

@@ -19,10 +19,23 @@ import type { IrreversibleFact } from "./irreversible.js";
  * the read side here breaks that cycle before the choke point exists to hit
  * it.
  *
- * Everything that WRITES `resource_constraints` -- insertConstraint() and
- * the declare*() functions, and all the validation that goes with them --
- * stays in src/tools/constraint.ts, which imports the accessors below
- * rather than duplicating the query against resource_constraint_members.
+ * Everything that WRITES `resource_constraints` used to stay entirely in
+ * src/tools/constraint.ts -- insertConstraint() and the declare*()
+ * functions, and all the validation that goes with them. Issue #42 moved
+ * the one raw INSERT (insertConstraintRow() below) down here, because
+ * resolve() (src/timeline/resolve.ts) now also has to write this exact row,
+ * from INSIDE its own transaction, when a `create` leg declares
+ * `bounded`/`resolve_only`/`monotonic` on the entity it makes. Reaching
+ * from src/timeline/ back into src/tools/constraint.ts to get there would
+ * close the identical cycle this module's own doc comment (above) describes
+ * for the choke point: tools/resource.ts already imports tools/constraint.ts
+ * (indirectly, via getResource), and tools/constraint.ts would then import
+ * timeline/resolve.ts's writer, closing tools/* -> timeline/* -> tools/*.
+ * src/tools/constraint.ts's declare*() functions keep every piece of
+ * business validation they always had (game exists, resource exists, no
+ * duplicate, minValue/maxValue already set for 'bounded') and call
+ * insertConstraintRow() only once every check has passed -- they are not
+ * merged away, only pointed at the one place the row is actually written.
  */
 /** Absolute tolerance for floating-point sum comparisons on 'conserved'
  * constraints. IEEE 754 doubles cannot represent values like 0.1 exactly,
@@ -67,11 +80,36 @@ export interface ConstraintRow {
     total: number | null;
     fact_key: string;
     created_at: string;
+    min_value: number | null;
+    max_value: number | null;
+    caused_by_event_id: string | null;
 }
 /** The resource ids belonging to a constraint, in insertion order. Exported
  * alongside ConstraintRow/rowToConstraint for the same reason. */
 export declare function memberIdsFor(constraintId: string): string[];
 export declare function rowToConstraint(row: ConstraintRow): ResourceConstraint;
+/**
+ * The one INSERT for `resource_constraints` (+ its members) -- see this
+ * module's own doc comment on why it lives here rather than in
+ * src/tools/constraint.ts. Every declare*Constraint() function there calls
+ * this only after its own business validation passes; resolve()'s create-leg
+ * declarations (src/timeline/resolve.ts, issue #42) call it directly, from
+ * inside their own transaction, after the leaner pre-transaction check that
+ * module runs (a declared key must be a live column -- see
+ * assertCreateConstraintKeysValid there). Either way this is the only
+ * `INSERT INTO resource_constraints` in the codebase.
+ */
+export declare function insertConstraintRow(params: {
+    gameId: string;
+    kind: ConstraintKind;
+    resourceIds: readonly string[];
+    direction?: MonotonicDirection | null;
+    total?: number | null;
+    factKey?: string;
+    minValue?: number | null;
+    maxValue?: number | null;
+    causedByEventId?: string | null;
+}): ResourceConstraint;
 /**
  * Every constraint governing `(entityId, factKey)`, ordered by
  * `created_at`. This is the whole point of Phase 3 step 1: a constraint

package/dist/timeline/registry.js

@@ -1,3 +1,4 @@
+import { v4 as uuidv4 } from "uuid";
 import { getDatabase } from "../db/connection.js";
 /**
  * The read side of the resource-constraint registry (design §5.3 / §5.4
@@ -18,10 +19,23 @@ import { getDatabase } from "../db/connection.js";
  * the read side here breaks that cycle before the choke point exists to hit
  * it.
  *
- * Everything that WRITES `resource_constraints` -- insertConstraint() and
- * the declare*() functions, and all the validation that goes with them --
- * stays in src/tools/constraint.ts, which imports the accessors below
- * rather than duplicating the query against resource_constraint_members.
+ * Everything that WRITES `resource_constraints` used to stay entirely in
+ * src/tools/constraint.ts -- insertConstraint() and the declare*()
+ * functions, and all the validation that goes with them. Issue #42 moved
+ * the one raw INSERT (insertConstraintRow() below) down here, because
+ * resolve() (src/timeline/resolve.ts) now also has to write this exact row,
+ * from INSIDE its own transaction, when a `create` leg declares
+ * `bounded`/`resolve_only`/`monotonic` on the entity it makes. Reaching
+ * from src/timeline/ back into src/tools/constraint.ts to get there would
+ * close the identical cycle this module's own doc comment (above) describes
+ * for the choke point: tools/resource.ts already imports tools/constraint.ts
+ * (indirectly, via getResource), and tools/constraint.ts would then import
+ * timeline/resolve.ts's writer, closing tools/* -> timeline/* -> tools/*.
+ * src/tools/constraint.ts's declare*() functions keep every piece of
+ * business validation they always had (game exists, resource exists, no
+ * duplicate, minValue/maxValue already set for 'bounded') and call
+ * insertConstraintRow() only once every check has passed -- they are not
+ * merged away, only pointed at the one place the row is actually written.
  */
 /** Absolute tolerance for floating-point sum comparisons on 'conserved'
  * constraints. IEEE 754 doubles cannot represent values like 0.1 exactly,
@@ -70,6 +84,50 @@ export function rowToConstraint(row) {
         total: row.total,
         factKey: row.fact_key,
         createdAt: row.created_at,
+        minValue: row.min_value,
+        maxValue: row.max_value,
+        causedByEventId: row.caused_by_event_id,
+    };
+}
+/**
+ * The one INSERT for `resource_constraints` (+ its members) -- see this
+ * module's own doc comment on why it lives here rather than in
+ * src/tools/constraint.ts. Every declare*Constraint() function there calls
+ * this only after its own business validation passes; resolve()'s create-leg
+ * declarations (src/timeline/resolve.ts, issue #42) call it directly, from
+ * inside their own transaction, after the leaner pre-transaction check that
+ * module runs (a declared key must be a live column -- see
+ * assertCreateConstraintKeysValid there). Either way this is the only
+ * `INSERT INTO resource_constraints` in the codebase.
+ */
+export function insertConstraintRow(params) {
+    const db = getDatabase();
+    const id = uuidv4();
+    const createdAt = new Date().toISOString();
+    const direction = params.direction ?? null;
+    const total = params.total ?? null;
+    const factKey = params.factKey ?? "value";
+    const minValue = params.minValue ?? null;
+    const maxValue = params.maxValue ?? null;
+    const causedByEventId = params.causedByEventId ?? null;
+    db.prepare(`INSERT INTO resource_constraints (id, game_id, kind, direction, total, fact_key, created_at, min_value, max_value, caused_by_event_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, params.gameId, params.kind, direction, total, factKey, createdAt, minValue, maxValue, causedByEventId);
+    const memberStmt = db.prepare(`INSERT INTO resource_constraint_members (constraint_id, resource_id) VALUES (?, ?)`);
+    for (const resourceId of params.resourceIds) {
+        memberStmt.run(id, resourceId);
+    }
+    return {
+        id,
+        gameId: params.gameId,
+        kind: params.kind,
+        resourceIds: [...params.resourceIds],
+        direction,
+        total,
+        factKey,
+        createdAt,
+        minValue,
+        maxValue,
+        causedByEventId,
     };
 }
 /**

package/dist/timeline/resolve.d.ts

@@ -204,13 +204,54 @@ export interface IntendedSet {
         ref: string;
     };
 }
+/**
+ * One constraint a `create` leg declares on the entity it makes (issue #42),
+ * applied by `resolve()` step 5 INSIDE the same transaction as the create --
+ * so a later leg of the same resolution is already held to it, and the
+ * whole resolution rolls back together if it is not (see
+ * assertCreateConstraintKeysValid and the `declareCreateConstraints` call in
+ * `resolveProposal` below). Vocabulary matches the existing constraint
+ * family exactly (declareBoundedConstraint/declareMonotonicConstraint/
+ * declareResolveOnlyConstraint, src/tools/constraint.ts) -- `conserved` is
+ * deliberately absent: it is a statement about several EXISTING entities
+ * summing to a total, not about one being created, so a single `create` leg
+ * has nothing to attach it to.
+ *
+ * The engine interprets neither `key` nor any bound below -- it only
+ * confirms, before any write, that `key` names a live column of the
+ * entity's own table (assertCreateConstraintKeysValid). `direction`'s
+ * vocabulary here ('up'/'down') is this field's own; declareCreateConstraints
+ * translates it to the registry's stored 'increasing'/'decreasing' the same
+ * way `entityKind` is translated to a table name -- a structural lookup, not
+ * an interpretation of what either word means (root CLAUDE.md hard rule 4).
+ */
+export type CreateConstraint = {
+    kind: "bounded";
+    key: string;
+    minValue: number | null;
+    maxValue: number | null;
+} | {
+    kind: "resolve_only";
+    key: string;
+} | {
+    kind: "monotonic";
+    key: string;
+    direction: "up" | "down";
+};
 /** One intended entity coming into existence (issue #34): a row in the
  *  projected table for `entityKind`, with `columns` restricted to that
  *  table's live columns and the game column filled by the engine from the
  *  proposal. `ref` is the label later legs of this same resolution use for
  *  it; the engine allocates the id and reports it in `Outcome.created`.
  *  The engine never learns what the entity is for or what it was made
- *  from -- "derived from" is the caller's to record. */
+ *  from -- "derived from" is the caller's to record.
+ *
+ *  `constraints` (issue #42) is optional and, unlike `columns`, is never a
+ *  column write -- it declares `resource_constraints` rows governing the
+ *  entity this leg creates, the same rows declareBoundedConstraint/
+ *  declareMonotonicConstraint/declareResolveOnlyConstraint would declare
+ *  after the fact, but inside the resolution's own transaction instead of a
+ *  second write path after `resolve()` returns. */
 export interface IntendedCreate {
     kind: "create";
     ref: string;
@@ -218,6 +259,7 @@ export interface IntendedCreate {
     columns: Readonly<Record<string, string | number | null | {
         ref: string;
     }>>;
+    constraints?: readonly CreateConstraint[];
 }
 /** One intended entity ending (issue #34): its live row deleted, its facts
  *  closed by the projection trigger. See `destroyProjectedEntity`
@@ -293,7 +335,10 @@ export type ResolveRefusalReason = "unknown-mechanic" | "no-clock" | "expectatio
  | "unresolved-ref"
 /** Two `create` legs of one resolution chose the same `ref` (issue #34).
  *  Refused before any write. */
- | "duplicate-ref";
+ | "duplicate-ref"
+/** A `create` leg's `constraints` names a `key` that is not a live column
+ *  of the entity it creates (issue #42). Refused before any write. */
+ | "invalid-constraint-key";
 /**
  * Refused before dispatch, before any write, or (never, by construction --
  * see step 5 above) mid-apply. `reason` is the discriminant a caller

package/dist/timeline/resolve.js

@@ -3,6 +3,8 @@ import { getDatabase, withTransaction } from "../db/connection.js";
 import { currentStoryTime } from "./clock.js";
 import { narrationConstraintAt, contradictions } from "./narration.js";
 import { withAdjudicationOpen } from "./adjudication.js";
+import { PROJECTED_TABLES, liveColumns } from "./projection.js";
+import { insertConstraintRow } from "./registry.js";
 import { writeConstrainedValue, transferConstrainedValue, setProjectedValue, createProjectedEntity, destroyProjectedEntity, } from "./constrained.js";
 /**
  * Refused before dispatch, before any write, or (never, by construction --
@@ -126,6 +128,85 @@ function assertRefsResolvable(mechanicName, changes) {
         }
     });
 }
+/**
+ * Step 5's second precondition (issue #42), checked in the same voice and
+ * at the same point as assertRefsResolvable above: every `constraints`
+ * entry on every `create` leg names a `key` that is a live column of the
+ * projected table for that leg's `entityKind` -- decidable from the schema
+ * alone, with no database write and no dependency on the entity actually
+ * existing yet, because the live column set is a property of the KIND, not
+ * of any one row of it. A bad key refuses with no transaction opened and no
+ * write attempted, naming the key.
+ */
+function assertCreateConstraintKeysValid(mechanicName, changes) {
+    const db = getDatabase();
+    changes.forEach((change, index) => {
+        if (change.kind !== "create" || !change.constraints || change.constraints.length === 0)
+            return;
+        const projected = PROJECTED_TABLES.find((p) => p.kind === change.entityKind);
+        // An entityKind with no projected table is createProjectedEntity's own
+        // refusal to make, inside the transaction -- nothing to validate a
+        // constraint key against here.
+        if (!projected)
+            return;
+        const cols = liveColumns(db, projected.table);
+        for (const constraint of change.constraints) {
+            if (!cols.includes(constraint.key)) {
+                throw new ResolveProtocolError("invalid-constraint-key", `resolve: leg ${index + 1} of mechanic '${mechanicName}' declares a '${constraint.kind}' constraint on key ` +
+                    `'${constraint.key}' for the entity it creates under ref '${change.ref}', and '${constraint.key}' is not a ` +
+                    `live column of '${projected.table}' -- refused before any write.`);
+            }
+        }
+    });
+}
+/**
+ * Translates every `CreateConstraint` (issue #42) a `create` leg declared
+ * into a `resource_constraints` row, through insertConstraintRow
+ * (registry.ts) -- the same primitive every declare*Constraint()
+ * (src/tools/constraint.ts) call now shares, so this is never a second
+ * write path for that table. Called from INSIDE the resolution's own
+ * transaction (resolveProposal below), immediately after the entity it
+ * governs is created, so `entityId` is real and `eventId` is the id the
+ * resolution's own `resolution.recorded` event will carry.
+ */
+function declareCreateConstraints(params) {
+    for (const constraint of params.constraints) {
+        if (constraint.kind === "bounded") {
+            insertConstraintRow({
+                gameId: params.gameId,
+                kind: "bounded",
+                resourceIds: [params.entityId],
+                factKey: constraint.key,
+                minValue: constraint.minValue,
+                maxValue: constraint.maxValue,
+                causedByEventId: params.eventId,
+            });
+        }
+        else if (constraint.kind === "resolve_only") {
+            insertConstraintRow({
+                gameId: params.gameId,
+                kind: "resolve_only",
+                resourceIds: [params.entityId],
+                factKey: constraint.key,
+                causedByEventId: params.eventId,
+            });
+        }
+        else {
+            insertConstraintRow({
+                gameId: params.gameId,
+                kind: "monotonic",
+                resourceIds: [params.entityId],
+                factKey: constraint.key,
+                // This field's own vocabulary ('up'/'down') is translated to the
+                // registry's stored 'increasing'/'decreasing' -- a structural
+                // lookup, not an interpretation of what either word means (see
+                // CreateConstraint's own doc comment).
+                direction: constraint.direction === "up" ? "increasing" : "decreasing",
+                causedByEventId: params.eventId,
+            });
+        }
+    }
+}
 function deref(value, refs) {
     if (typeof value === "string")
         return value;
@@ -246,8 +327,10 @@ function resolveProposal(mechanicsByName, proposal) {
     });
     const resolutionId = uuidv4();
     const changes = adjudication.changes ?? [];
-    // 5's precondition: every ref resolves, before the transaction opens.
+    // 5's preconditions: every ref resolves, and every create leg's declared
+    // constraint keys are live columns -- both before the transaction opens.
     assertRefsResolvable(mechanicName, changes);
+    assertCreateConstraintKeysValid(mechanicName, changes);
     // 5 & 6. Apply every intended change through the one choke point, and
     // record one event -- both inside ONE transaction with the adjudication
     // window nested inside it (adjudication.ts's own doc comment asks for
@@ -262,14 +345,31 @@ function resolveProposal(mechanicsByName, proposal) {
         const created = [];
         const destroyed = [];
         const refs = new Map();
+        // Generated here, before any change is applied, rather than after the
+        // loop below (as it used to be) -- issue #42's create-leg constraint
+        // declarations (below) need to stamp the SAME event id this
+        // resolution's own `resolution.recorded` event is about to carry, and
+        // that event cannot be written until every change has landed (step 7's
+        // t comes from AFTER the writes). uuidv4() needs nothing from the
+        // database, so generating it early costs nothing and lets both sides
+        // agree on one id.
+        const eventId = uuidv4();
         for (const change of changes) {
             const applied = applyChange(change, gameId, refs);
             if ("transitions" in applied)
                 transitions.push(...applied.transitions);
             else if ("set" in applied)
                 sets.push(applied.set);
-            else if ("created" in applied)
+            else if ("created" in applied) {
                 created.push(applied.created);
+                // Issue #42: a create leg's declared constraints are applied
+                // immediately, inside this same transaction, once the entity they
+                // govern has a real id -- so a later leg of this same resolution
+                // (still to come in this loop) is already held to them.
+                if (change.kind === "create" && change.constraints && change.constraints.length > 0) {
+                    declareCreateConstraints({ gameId, entityId: applied.created.entityId, constraints: change.constraints, eventId });
+                }
+            }
             else
                 destroyed.push(applied.destroyed);
         }
@@ -286,7 +386,6 @@ function resolveProposal(mechanicsByName, proposal) {
             // function has no business assuming that silently forever.
             throw new Error(`resolve: game '${gameId}' lost its timeline clock mid-resolution -- cannot record the outcome event`);
         }
-        const eventId = uuidv4();
         const causes = {
             source: "resolve",
             resolution_id: resolutionId,

package/dist/tools/constraint.js

@@ -1,8 +1,7 @@
-import { v4 as uuidv4 } from "uuid";
 import { getDatabase } from "../db/connection.js";
 import { validateGameExists } from "./game.js";
 import { getResource } from "./resource.js";
-import { ConstraintViolationError, CONSERVED_SUM_EPSILON, constraintsFor, allConstraintsForEntity, rowToConstraint, } from "../timeline/registry.js";
+import { ConstraintViolationError, CONSERVED_SUM_EPSILON, constraintsFor, allConstraintsForEntity, insertConstraintRow, rowToConstraint, } from "../timeline/registry.js";
 // Re-exported so every existing importer (src/tools/resource.ts,
 // src/register/resources.ts) keeps working unchanged -- these two now live
 // in src/timeline/registry.js; see the paragraph below on why.
@@ -72,25 +71,16 @@ export { ConstraintViolationError, CONSERVED_SUM_EPSILON };
  * adjudication window is open (src/timeline/adjudication.ts), not anything
  * about the intended value itself.
  */
+// The raw INSERT this used to perform directly now lives in
+// insertConstraintRow (src/timeline/registry.js) -- see that module's own
+// doc comment for why (issue #42: resolve() needs to write the identical
+// row from inside its own transaction, and src/timeline/ cannot reach back
+// into src/tools/ to get here without closing a cycle). This wrapper keeps
+// every call site below unchanged; declared constraints from this file
+// always carry a null causedByEventId, because none of these run inside a
+// resolution.
 function insertConstraint(gameId, kind, resourceIds, direction, total, factKey = "value") {
-    const db = getDatabase();
-    const id = uuidv4();
-    const now = new Date().toISOString();
-    db.prepare(`INSERT INTO resource_constraints (id, game_id, kind, direction, total, fact_key, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, gameId, kind, direction, total, factKey, now);
-    const memberStmt = db.prepare(`INSERT INTO resource_constraint_members (constraint_id, resource_id) VALUES (?, ?)`);
-    for (const resourceId of resourceIds) {
-        memberStmt.run(id, resourceId);
-    }
-    return {
-        id,
-        gameId,
-        kind,
-        resourceIds,
-        direction,
-        total,
-        factKey,
-        createdAt: now,
-    };
+    return insertConstraintRow({ gameId, kind, resourceIds, direction, total, factKey });
 }
 /**
  * Declare a 'bounded' constraint: the resource's value must stay within its

package/dist/types/index.d.ts

@@ -512,6 +512,9 @@ export interface ResourceConstraint {
     total: number | null;
     factKey: string;
     createdAt: string;
+    minValue: number | null;
+    maxValue: number | null;
+    causedByEventId: string | null;
 }
 export interface GameDateTime {
     year: number;

package/package.json

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